| name | orchestration |
| description | Multi-agent orchestration discipline — when to spawn subagents vs agent teams vs staying solo, how to write bounded task prompts, effort budgets by complexity, and coordination anti-patterns. Use before fanning work out to agents for research, implementation, reviews, or migrations. |
Orchestration
How a lead agent decomposes work across other agents without losing correctness, context, or budget. Companion skills: fable-mindset (how each agent should think), loop-engineering (recurring autonomous runs).
Decision Tree — solo, subagent, or team
- Stay solo when the task is under ~3 steps, the file/symbol is already known, or the question is conceptual. Spawning costs more than doing.
- Subagent(s) when only the result matters: isolated context, one invocation, condensed report back to the lead. Cheapest multi-agent shape — default.
- Agent team only when workers must talk to each other — challenge hypotheses, share discoveries mid-flight, claim tasks from a shared queue. Token cost scales linearly with team size; pay it only when cross-worker discussion is the point.
Effort Budget by Complexity
Declare the budget in the agent's prompt — over-spawn is the #1 documented failure (50 subagents on a simple query).
- Simple fact-find → 1 agent, 3–10 tool calls
- Comparison / two-sided question → 2–4 agents, 10–15 calls each
- Complex research / broad audit → 10+ agents with explicitly divided scopes
- Parallel sweet spot: 3–5 subagents at a time; each doing 3+ tool calls in parallel internally
The Bounded Task Prompt
Every delegated task states, explicitly:
- Objective — one concrete outcome, not a theme
- Output format — structure and a hard size cap (condensed 1,000–2,000 tokens; never raw dumps)
- Tool guidance — which tools to use and for what; agents theorize when tools aren't imposed
- Boundaries — what is out of scope, when to stop, what NOT to do
Vague boundaries produce duplicated work and silent gaps between agents. Vague tool descriptions cascade: one team measured −40% completion time just from rewriting them.
Lead Discipline
- Delegate, then wait. The lead doing a worker's task while the worker runs is a documented failure mode — results collide and context forks.
- Broad then narrow. Start agents on wide scopes, narrow in follow-up rounds; over-specified first queries miss the target.
- Tier the models. Strong lead + cheaper workers beats strong-everything: Anthropic measured Opus lead + Sonnet workers at +90.2% over Opus solo on research evals. Pick worker models by task difficulty, not by habit.
- Think between results. Evaluate after each agent report and adjust the plan; don't queue blind follow-ups.
- Async over blocking. One slow subagent must not stall the rest — background agents, collect as they land.
Parallel Safety
- One file / one scope per concurrent worker — parallel writes to the same file are silent overwrites.
- Agents that mutate files in parallel get worktree isolation, no exceptions.
- Before spawning N workers, list the files each will touch; overlap → re-partition or serialize.
Verification Layer
- Generator never grades its own homework. A fresh-context verifier beats self-critique — the generator re-reading its own work inherits its own blind spots.
- Verification criteria must be explicit before the loop starts; generator-verifier cycles with vague criteria oscillate forever.
- Cap the feedback loop: max iterations declared up front.
Anti-Patterns
- Over-spawn — agents without an effort budget multiply; declare call/agent caps in the prompt.
- Infinite source-hunt — research agents chasing nonexistent evidence; give explicit "stop after N empty searches" limits.
- Lead-does-the-work — see Lead Discipline; wait for the fan-out you paid for.
- Raw-dump returns — subagent returns 20k tokens of file contents; enforce the size cap in the prompt.
- Aggressive compaction — summarizing away context mid-orchestration loses critical details invisibly; keep load-bearing facts in files, not context.
- Sequential anchoring — one agent's early hypothesis steering everyone; for genuinely open questions, run adversarial/competing investigations.
