← Back to Learning Hub

Agent Communication & Data Flow

Hub-and-spoke architecture — the Orchestrator routes typed JSON documents between all specialist agents

INPUT LAYER — User Stories · API/CLI · Existing Codebase · Config AGENT CORE LLM ROUTER → Claude | GPT | Open-Source | Specialized Models PERSISTENCE — State DB · Git Repo · Artifact Store · Memory Store · Sandbox Orchestrator (State Machine · Context Assembler) REASONING Story Analyzer REASONING Planner REASONING Code Generator REASONING Test Generator REASONING Code Reviewer EXECUTION Build Runner EXECUTION Test Runner EXECUTION Deploy Engine EXECUTION Monitor / Verifier EXECUTION Feedback Loop SERVICE Codebase Intelligence MULTI-AGENT Coordination Mgr GUARDRAIL Policy Engine UserStory + Config ① UserStory StorySpec ↩ ② StorySpec Plan ↩ ③ Task + Context Patch ↩ ④ Task + AcceptanceCriteria TestSuite ↩ ⑤ Patch + StorySpec + Conventions ReviewReport ↩ ⑥ build command BuildResult ↩ ⑦ test command TestReport ↩ ⑧ deploy ↩ ⑨ verify VerifyReport ↩ ⑩ story outcome Lessons → Memory Store query context files + types + conventions ↩ lock request / publish changes lock granted / peer events ↩ action approval request allow / deny / escalate ↩ LLM calls via Router Sandbox / Git / Artifacts State DB read/write RETRY: TestReport.fail → re-invoke Code Generator

Agent Types

Orchestrator — hub, state machine, context assembler
Reasoning Agent — calls an LLM via the Router
Execution Agent — runs tools in the Sandbox
Service — shared read-only data layer
Guardrail — policy validation on every action

Arrow Meanings

Orchestrator → Agent (dispatched task)
Agent → Orchestrator (structured result)
Retry / Failure loop
Multi-agent coordination (locks, events)
Persistence read/write (State DB, Memory)

Key Principle

Hub-and-spoke: agents never call each other directly. Every message passes through the Orchestrator, which assembles context, validates schemas, enforces retry policy, and records state transitions.

Complete Data Flow — One Story, Start to Finish

Phase 1: Intake & Analysis

1
Input Layer → Orchestrator — A UserStory arrives (from backlog API, CLI, or UI). The Orchestrator creates a row in the State DB with status RECEIVED and loads Config/Constraints.
2
Orchestrator → Story Analyzer — Sends raw story text. The Analyzer calls the LLM Router, which picks the best model. Returns a typed StorySpec containing: acceptance criteria, dependency map, complexity score, ambiguity flags. State becomes ANALYZING → PLANNING.

Phase 2: Planning

3
Orchestrator → Codebase Intelligence — Queries the index for directory structure, convention profile, and files likely impacted. Receives ProjectProfile + relevant file skeletons.
4
Orchestrator → Planner — Sends StorySpec + ProjectProfile. The Planner returns a Plan JSON: ordered task list with depends_on edges, target files, token budgets, testing strategy, deploy strategy.

Phase 3: Code Generation (iterative)

5
Orchestrator → Code Generator — For each task in the plan (parallelized when depends_on allows), sends: task description, target file content, direct dependencies, type definitions, sibling patterns, convention profile. Receives a Patch (unified diff). State: CODING.
6
Orchestrator → Test Generator — Runs in parallel with coding for independent tasks. Sends acceptance criteria + generated code. Receives a TestSuite (test file content).
7
Orchestrator → Code Reviewer — Sends the full patch diff + StorySpec + conventions. Reviewer uses a different LLM for independence. Returns ReviewReport: list of findings tagged blocking / suggestion / nit. State: REVIEWING.
↺
Retry on review issues — If blocking findings exist, the Orchestrator packages them with the original task and sends back to Code Generator. Each retry carries all previous attempts + failure modes as progressive context.

Phase 4: Build & Test

8
Orchestrator → Policy Engine — Before running builds, checks the action is allowed. Policy returns allow. (For deploy actions it may return escalate → human approval gate.)
9
Orchestrator → Build Runner — Sends structured tool call (npm run build). Build Runner executes in the Sandbox, returns BuildResult with exit code, stdout/stderr, parsed errors. State: TESTING.
10
Orchestrator → Test Runner — Sends npm run test -- --coverage. Returns TestReport: pass/fail counts, coverage percentage, structured failure objects with suite name, test name, error message, stack trace.
↺
Retry on test failure — Orchestrator classifies the error (syntax / type / logic / integration / flaky — see Error Taxonomy). Packages error context + the original task and re-dispatches to Code Generator. Max retries: configurable (default 10). State cycles TESTING → CODING → REVIEWING → TESTING.

Phase 5: Deploy & Verify

11
Orchestrator → Deploy Engine — Sends deploy command (staging first). Deploy Engine runs in Sandbox, pushes to target environment via adapter. Returns DeployReport. State: DEPLOYING.
12
Orchestrator → Monitor / Verifier — Sends acceptance criteria + deploy URL. Verifier runs smoke tests, checks health endpoints, monitors error rates. Returns VerifyReport (pass/fail + evidence). State: VERIFYING.
↺
Retry on verify failure — If post-deploy checks fail, Orchestrator triggers rollback via Deploy Engine, then re-enters CODING with the failure context.

Phase 6: Learn & Close

13
Orchestrator → Feedback Loop — Sends full story outcome (which patterns worked, error types encountered, fix strategies, performance metrics). Feedback Loop writes lessons to Memory Store for RAG retrieval in future stories. State: DONE.

Multi-Agent: Parallel Stories & Cross-Orchestrator Coordination

When multiple stories run concurrently, each gets its own Orchestrator instance running the same state machine. The Coordination Manager sits between them and prevents conflicts through four mechanisms:

A
File Locking — Before entering CODING, each Orchestrator requests advisory locks on target files from the Coordination Manager. Higher-priority stories win ties; lower-priority ones wait or pick non-conflicting tasks from their plan.
B
Shared Context Bus — After each CODING step, the Orchestrator publishes an event (file diffs, new exports, API changes). Other Orchestrators subscribed to overlapping dependencies pull the update into their local context before their next Code Generator call — so they never generate against stale code.
C
Contract-First Interfaces — When an Architect Agent defines an API contract (interface, schema), multiple Implementer Agents can code against the contract independently without seeing each other's implementations.
D
Sequential Merge Queue — PRs merge one at a time through a queue that runs the full test suite after each merge. If a merge causes regressions, it's reverted and the owning Orchestrator is notified to fix the conflict.

Typed Message Reference — What Flows on Each Arrow

Orchestrator → Reasoning Agents

UserStory → Story Analyzer
StorySpec + ProjectProfile → Planner
Task + FileContext + Types + Conventions → Code Generator
Task + AcceptanceCriteria + Code → Test Generator
Patch + StorySpec + Conventions → Code Reviewer

Reasoning Agents → Orchestrator

StorySpec ← Story Analyzer
Plan (task list + deps + strategy) ← Planner
Patch (unified diff) ← Code Generator
TestSuite (test file content) ← Test Generator
ReviewReport (blocking/suggestion/nit) ← Code Reviewer

Orchestrator → Execution Agents

ToolCall (command, working_dir, timeout, env) → Build Runner
ToolCall (test command + flags) → Test Runner
DeployCommand (strategy, target env) → Deploy Engine
VerifyRequest (criteria, deploy URL) → Monitor/Verifier
StoryOutcome (full history) → Feedback Loop

Execution Agents → Orchestrator

BuildResult (exit code, stdout, parsed errors) ← Build Runner
TestReport (pass/fail, coverage, failures) ← Test Runner
DeployReport (status, URL, rollback plan) ← Deploy Engine
VerifyReport (pass/fail, evidence) ← Monitor/Verifier
LessonsWritten (confirmation) ← Feedback Loop