| name | agent-orchestration |
| description | Use when orchestrating multi-agent or long-running work — spawning sub-agents, fanning out parallel tasks, delegating subtasks, running build-then-review loops, or deciding which model tier should do a piece of work. |
Agent Orchestration
How to structure work across multiple agents/models so it's correct, cheap, and
parallel-safe. Apply whenever you're delegating, fanning out, or looping —
independent of whether it's "milestone" work.
1. Route by task complexity, not by default
A frontier orchestrator model is several × the cost of a mid model per unit of
real work. So pick the tier per task:
| Tier | Use for |
|---|
| Orchestrator (frontier, e.g. Fable 5 / Opus) | Plan across steps, delegate, synthesize, distill rules from evidence. Reserve for where the planning earns the price. Also the fallback for any request a guarded model's classifier blocks. |
| Hard-bounded subtasks (Opus) | Architecture decisions, complex debugging, deep code review delegated by the orchestrator. |
| High-volume workers (Sonnet) | Lint passes, simple refactors, test scaffolding, doc updates — the bulk of fan-out. |
| Graders / classifiers (Haiku) | Independent-context verifier sub-agents and cheap classifiers — low cost, fresh window. |
Most work should NOT run on the most expensive tier. In Claude Code's Workflow/
Agent tools, set the model per agent() call accordingly (and default fan-out
workers down, graders to the cheapest tier).
2. Verifier ≠ author (structural, not effort)
A model grading its own output sees its own reasoning trail and rationalizes
toward it. A separate agent sees only the artifact + the rubric, and catches
more. So:
- The agent that wrote the code is not the agent that grades it. Spawn a
fresh-context verifier (cheap tier is fine).
- Order is fixed: deterministic checks (tests / linters / builds) → adversarial
verifier → human gate on anything irreversible.
- For verification, prefer N independent skeptics prompted to refute over one
agent asked "is this right?"
3. The three orchestration primitives
- Loops — goal/rubric → run → independent grader checks → not-met restarts →
exit when the grader passes (with a hard max-iterations). The gate must run a
checkable rubric, not just reviewer vibes.
- Dynamic workflows — write a small harness on the fly:
fan-out-and- synthesize (N pieces, each its own clean context), adversarial-verify (fresh
verifier per maker), loop-until-done (spawn until no new findings / no
errors). Once the plan is written, follow it deterministically.
- Worktree isolation — the moment >1 agent edits files, they collide. Run
parallel mutating agents in separate git worktrees (Claude Code:
isolation: "worktree" on subagents). Don't rely on scope honesty for parallel writers.
4. The compound stack (why orchestration pays off over time)
Build bottom-up; leverage compounds upward:
- Primitives — the model, sub-agents, worktrees, tools.
- Orchestration — goals, dynamic workflows, scheduled routines.
- Memory — state files, skills, written lessons (see the
compounding-memory skill).
- Self-improvement — eval loops + rule distillation that write graded
lessons back to layer 3.
The model is stateless and stays the same; the environment around it gets
sharper. The arc that's easy to skip and most valuable: close the loop —
write the graded lesson back to memory.
Concrete templates
Copy-pasteable patterns for all of the above — model-tier routing, verifier-≠-
author refute votes, fan-out→verify pipelines, worktree isolation, loop-until-dry,
and a read-only verifier subagent — live in references/orchestration-templates.md.
See PROVENANCE.md for sources.
