agent-fanout

# Agent Fan-Out and Teams Orchestrate multiple subagents or teammates to explore, implement, review, and validate in parallel. This skill makes every judgment call explicit: when to fan out, how many agents, which model, what to put in each prompt, how to supervise, and how to combine results. ## When to fan out (decision table) | Situation | Action | | --- | --- | | Single bounded question ("where is X defined?") | No fan-out. Search directly or use one read-only explorer. | | Open-ended audit/review of a system with 2+ independent subsystems | One read-only explorer per subsystem, in parallel. | | Multiple root-caused issues, each fixable independently | One implementer per issue, each in its own git worktree. | | One pull request (PR) ready for review | One review panel (2-5 reviewers, see Review panels below). | | Sequential work where step N needs step N-1's output | Do NOT parallelize. Run one agent at a time or do it inline. | | Task needs secrets, deploy rights, or user-only credentials | Do NOT delegate. Keep it in the main session (mark the task "owner: lead"). | Do not fan out for work you can finish inline in a few minutes; a subagent costs setup, supervision, and synthesis time. ## Hard limits (compute BEFORE launching) 1. Before any fan-out, compute the worst case: `finders x max findings per finder x verifiers per finding + implementers + reviewers`. Write the number down in your plan. 2. **Budget: 10-20 agents per run for routine work; hard cap 40.** If the math exceeds the routine budget, say so and justify it; if it exceeds 40, cut scope before launching: fewer lenses, findings capped per agent (`maxItems`-style limits in the prompt), one verification vote instead of three. Going past 40 requires explicit user approval in the same conversation. If the user's own configuration states a stricter cap, the stricter number wins. 3. Prefer waves of 10 or fewer concurrent agents. Finish and synthesize a wave before launching the next. 4. Every phase plan states its own agent budget and routing up front (for example "Sol lead + Terra phase planner + Luna implementer/reviewer, ~4 agents total"). 5. If you hit a rate limit: stop spawning, schedule one backoff wait, resume staggered. Narrate as a status update, not a question. Evidence for the cap: an uncapped review-verify fan-out in a real session reached ~130 agents, rate-limited the account, and disrupted the live product under review. Compute the count first. ## Roles and model routing Keep the lead/orchestrator on the strongest available reasoning tier. The lead owns requirements, architecture, irreversible decisions, supervision, load-bearing verification, and final synthesis. Delegate bounded plan elaboration to the intermediate tier only after the architecture is fixed. Delegate implementation to the worker tier only after the brief names exact files, decisions, tests, and gates. Worker agents perform near lead quality only when three controls are present: a full lifecycle brief with exact values and named tests, mechanical gates (lint, typecheck, tests, and zero new diagnostics), and lead verification of the result. If any control is missing, keep the work on the lead or intermediate tier. ### Ecosystem routing Use an exact alias only when the current runtime exposes it. Otherwise apply the capability class in the final column. | Ecosystem | Lead / architect / observer / synthesizer | Phase-plan elaborator | Implementer / focused reviewer / validator | Capability fallback | | --- | --- | --- | --- | --- | | Claude Code | Fable when available, otherwise Opus or `best` | Opus for unresolved design; Sonnet after architecture approval | Sonnet | strongest / balanced / worker | | OpenAI Codex | Sol (`gpt-5.6-sol`) | Terra (`gpt-5.6-terra`) | Luna (`gpt-5.6-luna`) | strongest / intermediate / clear-repeatable worker | | GitHub Copilot CLI | strongest available model | balanced reasoning model | cost-efficient coding model | strongest / intermediate / worker | | Other systems | strongest available model | intermediate model | fastest model that passes the gates | strongest / intermediate / worker | Codex Luna is appropriate only for clear, repeatable implementation from a detailed plan. Escalate a worker to Terra or Sol when the task exposes an unresolved architecture choice, repeatedly fails a gate for a non-mechanical reason, or touches data integrity, encryption, concurrency, authorization, or another high-risk invariant. On Claude, use the same escalation rule from Sonnet to Opus/Fable. | Role | Agent type | Default tier | Notes | | --- | --- | --- | --- | | Lead/orchestrator | main session | strongest | Preserve requirements, approve architecture, supervise, verify, and synthesize. | | Explorer/scout | read-only explorer | intermediate or worker | One-shot for bounded facts; the lead re-verifies the keystone fact. | | Architect | plan agent | strongest | Owns macro design and open judgment calls. | | Phase planner | plan agent | intermediate | Expands an approved architecture into worker-executable actions; escalates unresolved design. | | Implementer | general-purpose | worker | One per issue and worktree, named; receives the full lifecycle contract. | | Reviewer | review agent | worker | One fresh panel per PR; use intermediate/strongest for high-risk invariants. | | Validator | general-purpose | worker | Runs named checks; classify first what needs human hardware. | | Integration reviewer | review agent | worker | Reviews only cross-phase integration at the end. | Review panels shrink as the code stabilizes: 4-5 lenses while new types and invariants are being invented, 2-3 once they settle, 1 integration-scoped reviewer for the final merge. ## Mechanics (the plumbing) Read `references/fanout-mechanics.md` for tool-by-tool instructions: spawning (agent tool parameters, naming, model selection, background execution), messaging (follow-ups, corrections, stand-downs), task boards, worktree commands, and what to do on platforms without subagent support (run the same role prompts sequentially in fresh contexts). If you have never spawned an agent in the current tool, read that file first. ## Briefing rules (what goes in every prompt) Read `references/fanout-prompts.md` for the full templates. Non-negotiable elements for every delegated prompt: 1. **Shared CONTEXT block**, authored once, pasted into every prompt of the wave: one-line project description, repo/package map, largest files with line counts, and a negative list (already-fixed items not to re-report, known gaps to extend rather than rediscover). 2. **Scope boundary**: exact worktree/branch (literal commands), files owned by concurrent siblings ("agent X is editing files A and B; do not touch them"), and read-only vs edit rights. 3. **DECIDED POLICY lines**: pre-resolve every foreseeable ambiguity at spawn time so parallel agents cannot diverge ("DECIDED POLICY (lead decision, note it in the PR body): ..."). 4. **Numbered deliverables** with exact values (constants, thresholds, type signatures), never "reasonable defaults". 5. **Gates**: the exact verification commands to run and the numeric bar ("zero new lint/type diagnostics vs the measured baseline", "all tests green"). 6. **How-far boundary**: commit / push / PR / merge, and an explicit DO NOT beyond it (usually "Do NOT merge"). 7. **Report contract**: a closing "Report:" line dictating the final message's exact contents, and the instruction to send the full report as message text (report files may be blocked for subagents; idle does not mean delivered). 8. **Secrets rule**: "NEVER read or print .env or any secrets file." 9. **No perfect agent type available?** Reuse the closest adjacent one and override its default framing explicitly in the prompt: state what this task is and is NOT ("this is a technical disclosure, NOT a journal manuscript; do not score on journal criteria; instead assess ..."), so the agent does not fall back to its default domain. 10. **GitHub body formatting**: semantic line breaks remain the default for prose source, except in GitHub issue and pull-request bodies. Keep each GitHub paragraph on one source line, separate paragraphs with blank lines, and do not insert sentence- or clause-level newlines inside a paragraph. ## Supervision protocol - **Canary first**: before launching N parallel instances of an unvalidated action, run one and watch it complete. - **Staleness threshold**: pick a number when you spawn (default 30-60 min for implementers). If an agent shows no commits, file writes, or messages within it, check filesystem evidence (file mtimes, expected deliverable paths). Do not treat "no report yet" as "still working". - **Escalation ladder**: (1) nudge with the exact expected deliverable, (2) narrow the ask ("send what you have now, quote line numbers"), (3) state the consequence ("if you do not reply shortly I will take over"), (4) stop the agent and finish the work in the main session. - **Idle without report**: send the standard nudge (template in references). If an idle ping arrives after the report already landed, acknowledge and do not double-nudge. - **Zombies**: track which agents are stood down or superseded; if one resurfaces, discard its late output explicitly instead of acting on it. - **Agent hard-fails** (API error, crash): say so, and proceed on the coverage that completed. Never silently drop a failed lane and never block everything on it. If the dead agent left partial output on disk, brief the replacement with an inventory of those files; do not re-run the original prompt blind. - **Lead keeps its hands off the code**: once delegation is underway, direct edits to project source by the lead are a smell. Prefer widening an existing agent's mandate or spawning a new one; it keeps every change reviewable under a scoped brief and preserves the lead's context for coordination. The exception is taking over from a stalled or stopped agent. - **Upstream changes**: after merging anything into a shared branch, message every in-flight worker naming exactly what changed and 1-2 acceptable reconciliation strategies, before they open PRs. - **Correction broadcast**: if a claim you gave earlier turns out wrong and reached in-flight agents, send each one a named correction quoting the wrong claim, the disproving evidence, and their specific rework. Leave a marker in project docs where the wrong path was taken. - **Remove finished agents**: after harvesting an agent's final report and confirming no follow-up is needed, close/remove its thread. Keep an agent available only when it has a named recurring role and a concrete next task; "might reuse later" is not sufficient. ## Synthesis rules (after a wave returns) 1. Merge N reports into ONE consolidated, prioritized list, bucketed by severity (Critical / Important / Moderate / Suggestion). 2. Every finding is either accepted (dispatched with an exact fix) or rejected with a one-sentence rationale recorded in an "EXPLICITLY REJECTED" section. No silent drops. 3. When two agents disagree on a fact, reproduce it yourself with a minimal check (grep, script, source read). Never average or pick by confidence. 4. Reproduce any headline numeric claim that gates a merge yourself before standing the worker down; state your number next to theirs. 5. Treat a subagent's causal explanation as a hypothesis: spot-check the most load-bearing fact against the evidence its own report cites before relaying it or acting on it. 6. "PR open" and "PR reviewed with findings addressed" are two separately verified states. A task completes on its own stated criterion (usually merge), not on the nearest milestone. ## Done The fan-out is complete when: every spawned agent is completed, stood down, or stopped with its output accounted for; every non-reusable agent thread is closed/removed; every finding is dispatched or rejected with a reason; every claimed result you relied on has been independently spot-checked; worktrees and other artifacts created for the wave are cleaned up; and the state file / task board reflects final status.