# Software Requirements Specification (SRS)_ Biomimetic Agentic Orchestration Layer

**Date:** 2026-04-14  
**Status:** Draft  
**System Name:** `Project Velocity Colony Orchestration Layer`

## 1. Introduction

### 1.1 Purpose

This SRS defines the functional and non-functional requirements for a biomimetic agentic orchestration layer that integrates:

- a forked Open Multi Agent runtime as execution kernel
- Project Velocity Nemoclaw-derived policy and governance concepts
- Project Velocity root domain systems including Oracle, CRM, Catalyst, and Sentinel

### 1.2 Scope

The system accepts a high-level goal and coordinates a colony of specialized agents to produce a reviewed, auditable final output or domain writeback.

The system is intended to become the orchestration layer for Project Velocity domain workflows.

### 1.3 Intended Audience

This document is intended for:

- product and systems architects
- backend and orchestration engineers
- AI infrastructure engineers
- QA and validation engineers
- internal operators defining mission classes

## 2. References

Primary references used for this SRS:

- `.Agent Context/Tech/Tools Understanding.md`
- `.Agent Context/Tech/README-Open Multi-Agent.md`
- `.Agent Context/Sprint 1/nemoclaw_setup_truth.md`
- public Open Multi Agent repository `https://github.com/JackChen-me/open-multi-agent`
- current root Project Velocity code under `backend/oracle`, `backend/services`, `backend/api`, and Sentinel routes

## 3. System Overview

The system consists of:

- mission intake and normalization
- planner
- prompt master
- research subsystem
- librarian subsystem
- worker execution layer
- aggregation and review layer
- governance and policy layer
- domain adapters

The system must preserve the current Project Velocity ownership boundaries and must not replace the root backend.

## 4. Architectural Constraints

The system shall use a modular architecture.

The system shall not depend on leaked or provenance-unclear upstream code.

The system shall support mixed model providers.

The system shall keep policy enforcement external to worker prompts wherever possible.

The system shall preserve Oracle v1, FastAPI root ownership, and Sentinel ownership.

## 5. Functional Requirements

### FR-1 Mission Intake

The system shall accept a goal payload containing:

- source surface
- user prompt
- desired output type
- risk or sensitivity hint when available

### FR-2 Mission Normalization

The system shall normalize the goal into a canonical mission envelope with:

- mission identifier
- normalized objective
- risk classification
- time budget
- token budget
- requested outputs

### FR-3 Task Planning

The system shall decompose the mission into a directed acyclic graph of tasks.

Each task shall include:

- unique task identifier
- role type
- objective
- dependency list
- success criteria
- required capabilities

### FR-4 Prompt Package Generation

The system shall generate a prompt package per task using:

- prompt templates
- examples where configured
- task metadata
- mission constraints
- tool scope

### FR-5 External Research

The system shall support a research role capable of:

- executing search queries
- browsing webpages
- returning evidence packets with citation metadata

### FR-6 Internal Retrieval and Routing

The system shall support a librarian role capable of:

- identifying relevant internal data sources
- issuing scoped access passes
- returning cached previews and data pointers

### FR-7 Worker Provisioning

The system shall spawn worker tasks with:

- prompt package
- task objective
- tool permissions
- librarian pass
- research artifacts when applicable

### FR-8 Parallel Execution

The system shall execute independent tasks in parallel, subject to concurrency limits and policy constraints.

### FR-9 Aggregation

The system shall aggregate worker outputs into a structured aggregation packet.

### FR-10 Review

The system shall execute one bounded review pass over the aggregation packet before final delivery.

### FR-11 Final Delivery

The system shall deliver a final output packet to:

- the originating user-facing surface
- or a root domain subsystem

### FR-12 Governance

The system shall evaluate policy constraints before executing:

- sensitive tools
- external network calls
- filesystem writes where applicable
- domain writebacks

### FR-13 Audit Logging

The system shall emit mission-level and task-level audit records for:

- planning
- prompt package selection
- tool use
- model use
- writeback attempts
- review findings

### FR-14 Domain Adapters

The system shall expose adapter boundaries for:

- Oracle
- CRM
- Catalyst
- Sentinel

### FR-15 Artifact Persistence

The system shall persist mission and artifact records in a store controlled by Project Velocity rather than relying solely on in-memory framework state.

### FR-16 Prompt Registry

The system shall maintain a prompt registry with:

- prompt template identifiers
- versioning
- example sets
- role associations

### FR-17 Quorum and Approval Hooks

The system shall support configurable approval paths for high-risk missions, including:

- single human approval
- automatic review approval
- dual-agent review agreement

### FR-18 Failure Handling

The system shall handle:

- task failure
- task timeout
- policy rejection
- low-confidence evidence
- partial mission completion

and shall still return a structured final mission status.

## 6. External Interfaces

### 6.1 Mission Intake Interface

Recommended interface:

- internal HTTP or RPC endpoint from FastAPI to colony runtime
- JSON mission envelope request and response

### 6.2 Domain Adapter Interfaces

Each adapter should support:

- mission submission
- progress event subscription
- artifact retrieval
- writeback execution or rejection

### 6.3 Tool Interface

Tools shall expose:

- tool identifier
- input schema
- policy class
- timeout behavior
- result schema

### 6.4 Research Interface

Research outputs shall include:

- source URI
- title when available
- snippet
- summary
- retrieval timestamp
- confidence

### 6.5 Librarian Interface

Librarian passes shall include:

- allowed resource families
- recommended paths or queries
- cache pointers
- expiration metadata

## 7. Data Model

The following persistent entities are required:

- `missions`
- `mission_tasks`
- `prompt_packages`
- `research_artifacts`
- `library_passes`
- `worker_results`
- `aggregation_packets`
- `review_packets`
- `policy_decisions`
- `tool_invocations`
- `pheromone_signals`

Each entity shall include:

- a primary identifier
- timestamps
- provenance metadata
- mission linkage

## 8. Non-Functional Requirements

### 8.1 Reliability

The system shall degrade gracefully on partial task failure and shall produce a final mission state instead of hanging indefinitely.

### 8.2 Scalability

The system shall support configurable concurrency, multi-model execution, and task fan-out without requiring per-mission custom orchestration code.

### 8.3 Security

The system shall use external policy controls for sensitive tool and network operations.

### 8.4 Privacy

The system shall classify mission and data sensitivity and route high-sensitivity work to approved model paths only.

### 8.5 Observability

The system shall emit structured traces for:

- LLM calls
- tool calls
- task durations
- mission durations
- policy decisions
- writebacks

### 8.6 Fault Tolerance

The system should support resumable mission persistence in a later phase. Sprint 1 may use simpler persistence, but the schema and API boundaries shall not block future recovery features.

### 8.7 Licensing

The system shall use only code and artifacts with clear legal provenance.

Open Multi Agent may be forked and redistributed under MIT with attribution and license preservation.

Any direct vendor Nemoclaw code incorporation shall require explicit license verification. Until then, the design shall prefer Project Velocity-owned implementations inspired by Nemoclaw concepts.

## 9. Evaluation and Testing Strategy

The system shall be validated through:

- unit tests for planners, prompt packaging, policy checks, and adapters
- integration tests for full mission execution
- golden tests for prompt package generation
- replay tests for research and librarian flows
- failure injection tests
- performance tests on fan-out missions
- security tests for blocked tools and blocked egress

Acceptance should be measured per mission class, not only at framework level.

## 10. Migration and Fork Plan

### 10.1 Fork Strategy

The fork shall preserve upstream attribution and license files from Open Multi Agent.

The fork should remain isolated under a dedicated service or package boundary so upstream changes can still be reviewed selectively.

### 10.2 Compatibility Strategy

The fork should preserve the useful Open Multi Agent primitives:

- agent config model
- orchestrator model
- task queue model
- tool abstraction
- MCP connectivity

The fork should add Project Velocity-specific layers without tightly coupling them into upstream core classes unless necessary.

### 10.3 Contribution Strategy

The fork should define:

- contribution guidelines
- interface boundaries
- extension points for new ant roles
- prompt registry contribution rules

## 11. Open Questions

The following items require explicit decisions before implementation hardens:

- exact runtime boundary between TypeScript colony service and Python backend
- persistence backend for mission artifacts
- policy engine ownership split between Nemoclaw-derived logic and colony review logic
- how much of research browsing should be headless first versus GUI capable
- whether high-risk missions use human approval by default

## 12. Acceptance Criteria

The SRS is satisfied when an initial implementation can:

- accept a mission
- plan a task DAG
- generate prompt packages
- route internal and external context
- execute workers in parallel
- aggregate and review results
- expose audit traces
- enforce policy boundaries
- integrate with at least Oracle and CRM through explicit adapters