Documentation
Core concepts, contracts, and protocols that power the multi-agent framework.
Contents
Nervous System Architecture
The framework organizes AI capabilities into four biological layers, each with distinct responsibilities and MCP tool integrations.
Central Layer: The Brain
High-level cognition and executive function
Goal decomposition, planning, strategic decisions. The Orchestrator coordinates multi-step tasks while Architect and Planner handle system design and task structuring.
Somatic Layer: The Body
Voluntary motor control and action execution
Deliberate actions requiring cognitive attention. The OODA MCP provides 62+ tools for file operations, screen capture, keyboard/mouse automation, and browser control.
Autonomic Layer: The Subconscious
Background processes that maintain state without conscious attention
Memory persistence, agent coordination, semantic retrieval. The Synch MCP handles cross-session context while Index Foundry provides RAG pipelines for semantic memory.
Reflex Layer: The Spinal Cord
Immediate, pre-cognitive responses
Schema validation that rejects bad inputs before they reach the brain. The Trace MCP catches contract violations at edit time, not runtime.
In combat, soldiers don't think—they react. In code, the reflex layer validates tool inputs, enforces contracts, and rejects malformed requests—all without consuming cognitive resources.
Runs and Steps
All agents operate as part of a structured runtime. Each unit of work is organized into runs and steps.
Run Structure
{
"run_id": "uuid-v7",
"objective": "Implement user authentication",
"status": "running", // pending | running | completed | failed | blocked
"steps": [
{ "type": "reasoning", "content": "Analyzing requirements..." },
{ "type": "tool", "name": "read_file", "params": {...} },
{ "type": "delegate", "to": "code", "task": {...} }
]
}reasoning
Internal planning and analysis steps
tool
Real tool invocation (file ops, MCP, etc.)
delegate
Assign work to another agent mode
Boomerang Protocol
Any agent receiving a delegated task returns a structured payload to the orchestrator.
Return Payload Schema
{
"type": "task-completed", // or escalation | review-approved | review-rejected
"task_id": "task-001",
"run_id": "run-uuid",
"from": "code",
"to": "orchestrator",
"status": "success", // success | failed | blocked
"files_changed": ["src/auth.ts", "tests/auth.test.ts"],
"tests_run": ["npm test -- auth"],
"summary": "Implemented JWT authentication with refresh tokens",
"notes": "Consider adding rate limiting in future iteration"
}Escalation
When blocked, use type: "escalation" and describe what blocked you, what you attempted, and concrete options for resolution.
Role Contracts
Each agent role has specific responsibilities and constraints.
🔄 Orchestrator
MUST
- • Interpret user goals and constraints
- • Create and maintain Task Maps
- • Decompose work into atomic subtasks
- • Assign workspace_path and file_patterns
- • Consume boomerang payloads
MUST NOT
- • Directly edit project files
- • Run destructive commands
- • Bypass contracts
💻 Worker (Code, Red/Green/Blue Phase)
MUST
- • Operate within assigned workspace_path
- • Respect file_patterns constraints
- • Implement exactly the subtask objective
- • Add/update tests when appropriate
- • Return boomerang payloads
MUST NOT
- • Modify files outside scope
- • Ignore acceptance criteria
- • Silently expand scope
👁️ Reviewer
MUST
- • Be read-only
- • Review only relevant changes
- • Return review-approved or review-rejected
- • Provide structured feedback
MUST NOT
- • Edit files
- • Provide vague approvals
TDD Workflow
The framework enforces Test-Driven Development through three distinct phases:
Red Phase
Tests must fail with clear messages
- • Write test specifications before implementation
- • Define expected behavior through assertions
- • Create test fixtures and mocks
- • Verify tests fail for the right reasons
Green Phase
Write minimal code focused on correctness
- • Implement just enough to pass tests
- • No premature optimization
- • All red phase tests must turn green
- • Quick iterations toward passing state
Blue Phase
Improve quality while maintaining passing tests
- • Refactor for readability and maintainability
- • Optimize performance where needed
- • Polish output formatting
- • Tests must remain green throughout
Parallel Execution
Parallelism is allowed only when safe by construction through workspace and file isolation.
Safety Rules
- Non-overlapping workspace_path: Tasks with different workspace roots can run in parallel
- Disjoint file_patterns: Tasks with non-conflicting file patterns in the same workspace can run in parallel
- Any doubt = conflict: Serialize or rescope to eliminate potential race conditions
// Example: Parallel-safe task assignment
{
"tasks": [
{
"task_id": "frontend-auth",
"mode": "code",
"workspace_path": "src/components/",
"file_patterns": ["Auth*.tsx", "Login*.tsx"]
},
{
"task_id": "backend-auth",
"mode": "code",
"workspace_path": "src/api/",
"file_patterns": ["auth*.ts", "jwt*.ts"]
}
]
// These can run in parallel - different workspace_path values
}Task Maps
Planner generates Task Maps that define the complete scope of work with dependencies.
Task Map Structure
{
"objective": "Implement user authentication system",
"tasks": [
{
"task_id": "auth-001",
"title": "Design auth schema",
"mode": "architect",
"deps": [],
"acceptance_criteria": [
"ADR documenting auth approach",
"Database schema for users table",
"API contract for auth endpoints"
]
},
{
"task_id": "auth-002",
"title": "Write auth tests",
"mode": "red-phase",
"deps": ["auth-001"],
"workspace_path": "tests/",
"file_patterns": ["auth.test.ts"]
},
{
"task_id": "auth-003",
"title": "Implement auth",
"mode": "green-phase",
"deps": ["auth-002"],
"workspace_path": "src/",
"file_patterns": ["auth/*.ts"]
}
]
}