Orchestrate governed parallel agent work. Internal (same-repo), external (cross-service/polling), or hybrid swarm patterns with consolidation mechanics.
Orchestrate multi-agent work with structured consolidation. Unlike /stage (adversarial reasoning for governance input), /swarm coordinates parallel deliverable work with dependency gating and result merging.
/swarm — interactive mode. Describe the work, infer pattern./swarm internal "<task>" — same-repo parallel agents with shared task list./swarm external "<task>" — cross-service agents with polling-based consolidation./swarm hybrid "<task>" — mix of internal agents + external polling./swarm --plan — generate swarm spec without executing (dry run)./swarm --spec <path> — resume from existing swarm spec.All agents operate in the same repo and context. Lead orchestrator holds shared context, delegates work units, and consolidates results.
When to use: parallel code changes, multi-file refactors, research queries that can be parallelized, governance batch operations.
Spawning: Agent() tool with run_in_background: true for parallel execution.
Consolidation: Lead reads agent outputs (file artifacts or return values), validates completeness, merges results.
Dependency gating: Task DAG with blocked_by lists (same pattern as arena phases).
Lead spawns agents A, B, C (parallel, no blockers)
-> A, B, C complete (file artifacts written)
-> Lead reads artifacts, validates
-> Lead spawns D (blocked_by: [A, B, C])
-> D completes
-> Lead consolidates final output
Agents work across services, repos, or external systems. Results arrive asynchronously via polling or inbox.
When to use: CI/CD monitoring, cross-repo coordination, external API orchestration, long-running background processes.
Spawning: Mix of Agent() for initial dispatch + /loop for polling checkpoints.
Consolidation: Artifact-based. Each agent writes results to a known path. Consolidation agent polls for completion artifacts.
Dependency gating: File-existence checks + inbox state machine (arrived/completed).
Lead dispatches work to external surfaces (GH Actions, APIs, repos)
-> /loop polls for completion artifacts at interval
-> On completion detected: Lead reads artifacts
-> Lead consolidates and reports
Internal agents + external polling + inbox-based consolidation. The most flexible pattern.
When to use: work that requires both local computation and external coordination — e.g., generate code locally, deploy externally, validate via polling.
Spawning: Internal agents via Agent(), external monitoring via /loop, inbox for async results.
Consolidation: Internal results merge immediately; external results arrive via inbox transmissions and merge on scan.
Lead spawns internal agents A, B (parallel)
-> A, B complete (immediate consolidation)
-> Lead dispatches external work
-> /loop polls external completion
-> External results arrive in inbox
-> Lead merges internal + external results
-> Final consolidation
Every swarm generates a spec YAML before execution: