Project 15 — Multi-Agent Orchestrator

Enforces: orchestrator-workers, self-contained briefs, result synthesis, and a verification pass (from mcp-advanced-topics / agentic-patterns) Surface: code or Claude Code · Time: ~90 min · Difficulty: 🔴 advanced

Why this project

Orchestrator-workers is the dominant pattern for non-trivial agents: a central agent that dynamically decomposes a goal (the subtasks aren't predetermined), spawns focused workers, and integrates their results — then verifies before delivering, because a worker's summary describes intent, not necessarily reality. This project makes you build the whole loop, including the trust check most people skip.

What you'll build

An orchestrator-workers system for a real research-or-build goal: an orchestrator that decomposes the task, spawns worker subagents with self-contained briefs, synthesizes their outputs into one deliverable, and runs a verification pass over the result before it ships.

Steps

Choose a decomposable goal — Something that genuinely splits into independent parts: "Audit this repo's error handling across the API, the worker queue, and the CLI, and produce one prioritized report." Three independent surfaces → three workers.
Build the orchestrator — Either in Claude Code (a .claude/agents/orchestrator.md that delegates to workers) or in code via the Agent SDK / Messages API loop. Its job: plan, delegate, synthesize, verify — not to do the work itself.

Spawn workers with self-contained briefs — Each worker gets everything in its prompt: the surface to audit, the exact paths, the output schema, and the constraint. No "based on the above." Workers are read-only specialists (Haiku is fine); reserve the larger model for the orchestrator.

Worker brief (one per surface):
  • Scope: src/api/  (ONLY this directory)
  • Find: unhandled exceptions, swallowed errors, missing retries/timeouts.
  • Return: a list of {file:line, issue, severity (low/med/high), fix-sketch}.
  • Tag every finding with its source path. Do not propose code changes.

Run workers in parallel — Independent surfaces run concurrently. Each returns its own structured findings; the orchestrator collects the summaries, not the full traces (context isolation keeps the orchestrator lean).
Synthesize — The orchestrator merges findings, de-duplicates overlaps, and produces one prioritized report ordered by severity, preserving each finding's source tag (provenance threads through).
Verification pass — Add a distinct verifier step (separate subagent or an evaluator loop): spot-check a sample of findings against the actual code. Mark each as confirmed / not-reproducible / needs-human. This closes the trust trap — never ship a worker's word unverified.
Bound the system — Set an iteration cap on any loop and a fixed worker count so the run can't sprawl in cost or latency.

Acceptance criteria — you're done when

An orchestrator decomposes the goal into subtasks it chose (not a hardcoded list).
Each worker runs from a self-contained brief with an explicit output schema and a path scope.
Independent workers run in parallel and return isolated, structured summaries.
The orchestrator synthesizes one prioritized deliverable with source provenance on every item.
A distinct verification pass spot-checks findings and labels confidence; unverifiable items are flagged, not shipped.
The system has an iteration cap and a bounded worker count.
You journaled where synthesis or verification caught a worker error in learning-journal-template.

Stretch goals

Add an evaluator-optimizer loop: the verifier returns feedback and the synthesizer revises until clean (cap the iterations).
Use worktree isolation so a write-capable worker can apply a fix without colliding with others.
Add a routing step so trivial goals skip orchestration entirely — the smallest pattern that works.

Self-assessment rubric

Level	Signal
🟢 Got it	You design orchestrator-workers cleanly: specialized workers, generalized orchestrator, provenance preserved, results verified before delivery.
🟡 Almost	The system produces a result, but you trust worker summaries without a verification pass, or briefs leak shared state.
🔴 Revisit	Workers wander on vague briefs or the orchestrator does the work itself. Re-read agentic-patterns (orchestrator-workers) and subagents.