agent-orchestration

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:

1. Primitives — the model, sub-agents, worktrees, tools.
2. Orchestration — goals, dynamic workflows, scheduled routines.
3. Memory — state files, skills, written lessons (see the compounding-memory skill).
4. 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.