Swarm Orchestration

Advanced execution layer for multi-worker runs after agent or team selection.

Coordinate multiple workers without polluting the main thread. Use this skill after agents-subagents has already selected the right agent, member, team, or debate pattern. This skill is for choosing the orchestration surface, freezing task ownership before fan-out, and requiring structured outputs that the lead agent can validate and merge safely.

Terminology (Aug 2026)

"Swarm" is community vocabulary — it appears nowhere in Anthropic documentation. Use the official primitive names when writing configs, prompts, or docs; keep "swarm" only as informal shorthand for the whole category.

Informal	Official primitive	Status (Aug 2026)
"swarm of subagents"	Subagents	GA. Background behavior is mode-dependent; background: true forces background but false is not a documented foreground pin. Recursive spawn currently defaults to three layers below the main session
"swarm with peer chat"	Agent teams	Experimental, env-gated CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Behavior churns weekly — re-verify before relying
"scripted swarm"	Dynamic workflows	Shipped 2026-05. JS in .claude/workflows/; ≤1000 agents/run, 16 concurrent. The repeatable-orchestration artifact
"swarm across terminals"	Cross-session messaging	Aug 2026, macOS/Linux. Sessions message each other without a team — lighter than teams for passing findings

Quick Reference

Situation	Default pattern	Why
1-2 tasks or shared-file edits	Stay in the main conversation	Parallelism adds coordination overhead without payoff
Focused worker that only needs to report back	Claude Code subagent or Codex worker	Isolated context, simple coordination
Workers must talk to each other	Claude Code agent team	Shared task list plus direct messaging
Read-heavy scans, tests, triage, summarization	Parallel workers	Keeps noisy intermediate output off the lead thread
One coordinator should retain user ownership	Manager / agents-as-tools	Lead keeps control of decisions and final answer
Specialist should take over the conversation	Handoff	Ownership moves to the specialist agent
Work of unknown extent — discovery is the task	Loop until K empty rounds	A fixed task list cannot be enumerated up front
Loop Engineering: recurring discovery or evaluation	Loop-until-dry or budget-bounded loop	Define convergence, termination, and state checkpoints
Many items, known stages, high intermediate volume	Scripted workflow (Claude Code)	Script holds control flow; lead context holds only the result

Navigation

• references/loop-orchestration.md - Bounded iteration vs retry, loop-until-dry, convergence detection, termination predicates, dedup-target rule
• ../ai-coding-agents-tasks/references/loop-and-graph-runtime-surfaces.md - Loop Engineering and Graph Engineering runtime comparison: task queues, cyclic graphs, and workflows
• references/scripted-workflows.md - Script-held deterministic control flow (Claude Code Workflows): agent/parallel/pipeline, barrier-vs-pipeline, resume and caching
• references/platform-patterns.md - Platform guidance for Claude Code subagents, Codex subagents, Codex multi-agents, and OpenAI Agents SDK
• references/output-contracts.md - Task schema, worker report schema, and merge contract
• references/operational-guardrails.md - Safety, stop conditions, observability, and verification gates
• references/cost-discipline.md - Fan-out cost patterns, session lifecycle, loops/schedules audit, orchestration-layer config
• references/orchestration-maintenance-runbook.md - How to audit, maintain, and refresh swarm discipline over time
• references/runtime-smoke-tests.md - 3 shell-runnable checks for wave dispatch, per-worker budget breach, and wave-boundary checkpoints
• references/execution-surfaces.md - Single thread, worker fan-out, agent team, manager, and handoff selection
• references/noninteractive-and-blueprints.md - CI-safe dispatch patterns and deterministic-plus-agentic blueprint flows
• references/recipe-wave-dispatch.md - Self-contained 3-worker shell example: copy, paste, run, verify
• references/typical-scenarios.md - Scenario library: common jobs mapped to surface, pattern, worker shape, and the trap to avoid
• agents-subagents - Subagent design, tool scoping, and interruption recovery
• ../agents-hooks/SKILL.md - Hook guardrails and verification automation
• ../agents-mcp/SKILL.md - MCP server scoping for workers
• ../agents-skills/SKILL.md - Skill packaging for worker preloads
• ../agents-memory/SKILL.md - Project memory for shared conventions
• ../ai-coding-agents-permissions/SKILL.md - Approval routing, allow or ask modes, and worker permission handoff
• ../ai-coding-agents-tasks/SKILL.md - Background task runtimes, teammate queues, and task ownership
• ../dev-workflow-planning/SKILL.md - Create the plan before fan-out
• ../ai-agents/references/autonomous-loop-patterns.md - Shape C autonomous loops: PRD-driven drivers, circuit breakers, drift detection (framework-neutral)
• ../ai-agents/references/context-graph-patterns.md - Graph-structured agent state: node/edge schema, traversal, conflict resolution
• data/sources.json - Curated official docs, research, and secondary references

Maintainer note: eight URLs here are intentionally duplicated from ../agents-subagents/data/sources.json (Claude Code subagents, Agent Teams, Codex Multi-Agents, Codex Subagents, both OpenAI Agents SDK pages, OpenAI prompt-caching guide, Karpathy coding notes). Each skill frames those sources for a different reader. When a URL rotates, update both files in the same commit.

When To Use / Not To Use

Use	Do Not Use
agents-subagents already chose the team; now needs execution planning	Still deciding which agent, team, or debate mode fits
3+ bounded tasks with clear ownership or dependencies	Tasks share the same file or unresolved interface
Requirements, decisions, synthesis must stay in one lead context	Main blocker is product ambiguity, not execution bandwidth
Exploration, tests, logs, or review can run in parallel	Workers would need the same context and make the same decisions
Loop Engineering needs a bounded multi-pass orchestration contract	One pass or a simple queue already meets the goal
Verification must be explicit, not implied by worker confidence	Work is small enough that orchestration cost exceeds execution cost

Relationship To Agents-Subagents

agents-subagents is the entry point. It selects the mode and prepares the first launch prompt. This skill takes over when the plan needs multi-wave execution, worker dependencies, verifier passes, or merge/conflict control.

Operating Principles

• Lead owns requirements, decisions, approvals, and final synthesis — not execution.
• Default to read-heavy parallelism; parallel writes are higher-risk.
• Freeze shared interfaces before dispatching edit-capable workers.
• Give every worker exclusive owned_files and explicit do_not_touch boundaries.
• Pass distilled dependency outputs, not raw logs or long transcripts.
• Require structured worker reports — the lead validates and merges deterministically.
• Re-plan when conflict resolution costs more than the fan-out saved.
• Fresh context per worker: each worker brief contains only its task, plan section, file ownership, and interface contracts — not the lead's full history. Prevents context rot; gives each worker a full window.
• State in files: task graph, progress, decisions, and dependency outputs live in structured files (frontmatter MD / JSON / YAML). Any new lead session resumes by reading files, not memory.
• Checkpoint long runs: snapshot task state, reports, and decisions to checkpoints/ at each wave boundary.
• Budget per worker: explicit token/time/tool caps at dispatch. Budget-conservation invariant: child budgets are strict subsets of the parent's remaining budget. Workers that breach their budget stop and escalate — they do not continue. (Ye & Tan, Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems, arXiv:2601.08815, 2026)
• Telemetry per worker: assign a run id or span id; log inputs, outputs, status, tokens, and duration to one structured location.
• Durable approval channels: route approvals through mailbox/poller with request IDs, not ephemeral callbacks.
• Minimum toolset per worker: use tools, disallowedTools, and skills fields to give each worker only what it needs.
• Memory opt-in: prefer clean-context workers + file-backed checkpoints. Enable memory only when the role genuinely benefits from cross-run priors; never default it for verifiers or reviewers. Prefer file tools over schema-constrained memory APIs. (Lance Martin, 2026-04-24; ../ai-context-layer/references/filesystem-as-memory.md)

For context rotation and state handoff patterns, see ../ai-agents/references/context-rotation-and-state.md.

Explicit Fan-Out Is The Durable Default

Claude Opus 4.7 (GA 2026-04-16) shipped a lasting behavior change: it spawns fewer subagents by default than 4.6, favoring single-response completion over implicit parallelism. Fan-out workflows that previously worked without being asked — read-heavy scans, multi-file refactors, review waves, cross-repo audits — now silently serialize unless the lead is told to fan out explicitly. Opus 4.8 (current as of this writing) inherits the same conservative default; treat "assume no auto-parallelism" as the standing assumption for whatever frontier model is current, and re-verify against release notes each time the lead model changes.

Anthropic's source guidance is to give the model explicit fan-out instructions; it does not prescribe where the instruction must live. Our repo convention is to install the canonical phrasing once in AGENTS.md / CLAUDE.md (not duplicated per launch prompt):

Spawn multiple subagents in the same turn when fanning out across items or reading multiple files. Do not spawn a subagent for work you can complete in a single response.

Full guidance and source links live in agents-subagents. Judgment call for the lead: after any model swap, run one throwaway fan-out task and watch whether it parallelizes on its own — cheaper than discovering silent serialization mid-migration.

Named Patterns

Name the pattern explicitly when proposing a design. Full detail: ../agents-subagents/references/harness-patterns.md.

Pattern	When to use
Orchestrator-worker	Default for dependency-aware fan-out; lead plans + synthesizes, workers execute on owned files
Evaluator-optimizer	Quality hard to verify deterministically; generator retries until evaluator gate passes
Self-consistency / voting	High-stakes decisions; N workers produce output, judge picks best or majority wins. Costs ~N× generation plus a judge pass — only pays off when independent attempts actually disagree; if N drafts converge on the same answer, the cheapest draft would have done, so pilot with N=2 before committing to N≥3
Manager vs handoff	Manager: lead keeps user ownership, specialists are tools. Handoff: ownership moves to specialist
Reflection / self-correction	Dedicated evaluator is overkill; worker runs a second critique pass on its own output
Hierarchical swarm	Portfolio-wide migrations; top-level lead coordinates sub-leads. Max depth 2; enforce interface contracts. Errors compound across levels — a sub-lead's misread of its brief propagates to every worker beneath it uncaught, so put verification at each level, not just the top
Debate-before-dispatch	2–4 perspective agents argue tradeoffs before interfaces freeze; output becomes part of each worker brief. For contested high-stakes decisions where linear rounds stall, extend it into a Graph of Debates — see §Pre-Dispatch: Collaborative Debate
Planner → Generator → Evaluator / Blueprint	Owned by agents-subagents — deterministic nodes alternating with agentic nodes
Loop-until-dry / budget-bounded loop	Work of unknown extent where enumerating the task list is the job; terminates on K empty rounds or budget, never a fixed count. references/loop-orchestration.md
Scripted workflow	Control flow is knowable in advance and intermediate volume is high; a script holds the loops and branching so the lead's context holds only the final answer. Claude Code only. references/scripted-workflows.md

Typical Scenarios

Each common job maps to one dispatch shape. Load references/typical-scenarios.md for the full table (surface + pattern, worker count/tiering, waves, Claude Code vs Codex mapping, key trap), three deep walkthroughs, and a do-not-swarm list.

Job	Default shape
Framework migration / large refactor	Scout (read) → freeze → edit waves ≤3, worktree isolation
Cross-repo / portfolio audit	Broad read-only fan-out (fast tier), one merge
Test / flaky-test triage	Read fan-out + 1 verifier; reject "done" with no repro
PR / code-review board	One worker per dimension; adversarially verify findings
Security / compliance sweep	Finders → independent refuting verifier → human gate (mandatory)
Dependency-chain feature (schema→API→UI)	Strict waves; pass contract_summary, not logs
Deep research / competitive intel	Isolated research streams → lead synthesis
Multi-domain doc generation	Large-scale write swarm, phased, exact paths per worker
Evaluator-optimizer content loop	Generator + evaluator, retry cap 2–3, then escalate
CI / batch migration (non-interactive)	Blueprint: deterministic ↔ agentic nodes, script-level retry
Scheduled / loop swarm	Smallest viable, cheap tier, explicit stop condition

Orchestration Choice

Use the simplest surface that preserves ownership and coordination:

• single thread when the work is small or the interfaces are still unstable
• isolated workers when the lead only needs results back
• Claude Code agent teams when workers must talk to each other directly
• manager vs handoff depending on whether the lead keeps user ownership

Load references/execution-surfaces.md when you need:

• the detailed single-thread vs worker vs team decision
• Claude team communication patterns
• task-list and SendMessage coordination rules
• manager vs handoff guidance for OpenAI-style systems

Framework quick-pick (June 2026):

Framework	Default topology	Notes
Claude Code (Anthropic)	Subagents + Agent Teams	Subagents for isolated workers; Agent Teams when workers need direct comms
OpenAI Agents SDK	Manager / Handoff	April 2026 overhaul: native sandbox, sub-agent patterns, first-class MCP
LangGraph (LangChain)	DAG-based supervisor	Graph primitives; strongest for explicit state; MCP native support
Microsoft Agent Framework	Supervisor / hierarchical	v1.0 GA April 2026; merges AutoGen + Semantic Kernel — AutoGen now in maintenance
CrewAI	Orchestrator-worker (crew/task)	Event-driven Flows (shipped 2024, matured through 2025-2026) sit alongside crew/task; verifier-critic via task chains
AutoGen / AG2	GroupChat (peer)	Maintenance mode; migrate to Microsoft Agent Framework for new projects

Verify current GA status before committing to a framework — this space rotated significantly in early 2026. (uvik.net/blog/agentic-ai-frameworks, June 2026)

Pre-Dispatch: Collaborative Debate

Before fan-out on high-complexity work, run a collaborative debate step: 2–3 specialized personas (e.g., architect + developer + QA) argue tradeoffs in one session before interfaces freeze. Output is a decision log that becomes part of each worker brief. Reduces mid-execution rework from conflicting assumptions.

Use when: architecture affects multiple workers; tradeoffs are unclear; early disagreement is cheaper than late integration failure. Skip for routine parallel work with stable interfaces.

• Templates: ../agents-subagents/assets/templates/
• Full pattern (Claude Code, Codex, Agent Teams): ../agents-subagents/references/agent-patterns.md §"Pattern 5: Debate Team"
• Step-by-step setup: ../agents-subagents/references/debate-quickstart.md
• Wider method landscape: ../ai-agents/references/agent-delivery-methods.md

Extension: Graph of Debates (when linear rounds aren't enough)

The default debate step is a chain: personas take turns, the last round is the conclusion. That shape fails when a decision is genuinely contested — one strand of argument gets buried under later rounds, and whoever speaks last effectively wins. Graph of Debates (GoD) is the non-linear extension of the same step, not a competing pattern: the same 2–4 personas, the same pre-freeze slot in the workflow, a different record structure.

	Linear debate (default)	Graph of Debates (extension)
Record	Ordered transcript of rounds	Arguments are nodes; edges are typed supports / refutes
Lines of inquiry	One thread, sequential	Branch off, evolve independently, merge back when they converge
Conclusion	End of the sequence	The most well-supported cluster in the graph, wherever it sits
Cost	One session, cheap	Higher — graph upkeep plus per-node evidence grading

Evidence-strength rubric. "Well-supported" is not a vote count. Grade each supporting node into one of three tiers and let the tier, not the edge count, decide which cluster wins:

1. Ground truth — firmly established and verifiable: the repo's own code, a passing test, a frozen interface contract, a spec.
2. Search-grounded factual evidence — validated against an external source or real-world data (official docs, a release note, a benchmark someone actually ran).
3. Multi-model consensus — several models agree during the debate. Real signal about confidence, but the weakest tier: agreement is not verification.

A cluster resting entirely on tier 3 loses to a smaller cluster anchored in tier 1. This is the guardrail that stops GoD from becoming an expensive majority vote — and it pairs with the self-consistency caution above: converging drafts mean the cheap option would have done.

Use GoD when: the decision is high-stakes and contested, an earlier linear debate ended in a stalemate or an obviously order-dependent answer, or several viable architectures each have real evidence behind them. Stay linear when: the interfaces are stable, the personas agree quickly, or the decision is reversible — the graph's bookkeeping is only worth it when the wrong answer is expensive to undo.

Output into the worker briefs is unchanged: the winning cluster plus its evidence tiers becomes the decision log each worker receives. Carry the refuted branches too — a worker that rediscovers a rejected option needs to know it was considered and why it lost.

Source: Gulli, Agentic Design Patterns (Springer, 2025), Ch. 17 — Reasoning Techniques, presenting GoD as the non-linear successor to Chain of Debates (CoD).

Dispatch Workflow

1. Build a dependency-aware task graph before launching anything.
2. Freeze interfaces, ownership, and verifier commands for each task.
3. Launch only unblocked tasks; use waves unless the work is intentionally read-heavy and low-risk.
4. Cap edit-capable workers at 3 by default. Increase fan-out only for read-only scans, review, tests, or summarization.
5. Require each worker to return a structured report instead of raw intermediate output.
6. Validate the report, verification evidence, and changed files before marking the task complete.
7. Merge one worker result at a time, then unblock the next wave.
8. Stop and re-plan when conflicts or retries show the current graph is wrong.

Minimal worker brief template (paste into subagent system prompt or TOML developer_instructions):

TASK: <one-sentence objective>
OWNED FILES: <exact paths — edit only these>
DO NOT TOUCH: <paths explicitly off-limits>
READ ONLY: <dependency outputs or context files>
DELIVERABLE: <what you return — format and path>
VERIFICATION: <command to run before reporting done>
BUDGET: tokens=<N>, time=<Ns>, tool_calls=<N>
SELF-REJECT IF: <named negative criterion>

ASCII Flow

Multi-agent work
  -> Build task graph
  -> Freeze interfaces, ownership, and verifier commands
  -> Dispatch wave
     +-- unblocked read-only tasks -> broad fan-out allowed
     +-- edit-capable tasks        -> cap at 3 by default
     +-- blocked tasks             -> wait for dependency output
  -> Require structured worker reports
  -> Validate evidence and merge one result at a time
  -> Re-plan when conflicts or retries show the graph is wrong

For CI-safe dispatch, batch fan-out, and blueprint-style deterministic-plus-agentic flows, load references/noninteractive-and-blueprints.md.

Lead Agent Responsibilities

• Maintain task state: pending, in_progress, completed, blocked, failed.
• Own approvals, permissions, and escalation for risky operations.
• Keep the canonical task graph and dependency outputs.
• Reject reports that do not match the expected schema or ownership.
• Run integration verification after merging worker outputs.
• Synthesize the final answer only after the merged state passes validation.

Model Guidance

Role	Model tier	Notes
Lead	Strongest reasoning available	Planning, conflict resolution, synthesis
Edit-capable workers	Balanced coding model	Bounded implementation with reasoning
Read-only workers	Fast / cheap model	Exploration, summarization, triage
Verifiers (routine)	Fast model	Schema, format, ownership checks
Verifiers (security / migration)	Balanced or strong	Auth, risky refactors, policy review

Tiering saves ~40% vs all-Opus teams with minimal capability loss on worker tasks. (cloudzero.com/blog/claude-code-agents, 2026)