skills/agent-swarm/SKILL.md

name, description, whenToUse

name	description	whenToUse
agent-swarm	Use for large tasks that split into 8+ independent work units (codebase-wide changes, audits, migrations, multi-source research, multi-section documents) to run dozens of coordinated subagents in waves under one lead, with file ownership, packed context, and independent verification. Not for single-file, sequential, or highly coupled work.	The task is broad, parallelizable, and has executable acceptance checks; one agent would take hours and separate agents can finish units without touching the same files.

Agent Swarm

Run a large task as waves of coordinated subagents. The lead plans and integrates; workers execute one work packet each; verifiers check independently. A swarm is only as fast as its briefs are clear and its write scopes are disjoint.

Fit check — before spawning anything

Swarm only when all are true:

• The task splits into 8+ independent units with disjoint write scopes.
• Each unit has an executable acceptance check (command, test, or verifiable criterion).
• Wall-clock is dominated by breadth, not by one deep sequential chain.
• You can state the interfaces between units before dispatch.

Otherwise: one agent for small work; 2–5 subagent calls for a few long-lived roles you need to steer. Never swarm one bug, one design decision, or work where every unit edits the same files.

Roles

• Lead — you. Owns the plan, packets, contracts, gates, integration, and the final report. Does not implement during waves.
• Recon (2–4) — maps files, commands, conventions, and hazards. Does not design the solution.
• Worker — one task card, one write scope, one structured report.
• Verifier — fresh context; checks the artifact against acceptance criteria, never the worker's summary.
• Integrator (1–2) — owns shared files and cross-cutting fixes after the parallel waves. During a wave, the lead/integrator may make a small contract/shared-file change to unblock a task, then resume that same worker with send_message; do not spawn a replacement.

Protocol

0. Fit check & preflight — go/no-go, budget (max_agents, max_waves), and discover the real active-child cap before sizing a wave (see Sizing). Record the cap, current active children, and planned batch size in state.json.
1. Recon — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into .swarm/brief.md and .swarm/map.md, then stop them; recon must not hold slots during the build wave.
2. Plan gate — write .swarm/plan.json, plan.md, ownership.md, contracts.md, and one tasks/Txx.md per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a LEAD/INTEGRATOR task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. Do not dispatch until this gate passes.
3. Build wave — one workflow call per build wave, using the batched runner in assets/wave.workflow.js; its concurrency must fit the available slots (see Sizing). Retry null/failed once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out.
4. Audit — run scripts/audit-scope.mjs from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate.
5. Verify wave — freeze source changes, then run 4–6 fresh verifiers by risk cluster. Use assets/verdict.schema.json and assets/verify.workflow.js; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. For GUI products, verify in per-agent isolated displays, never a shared desktop (see references/visual-testing.md). If you fix findings, re-run the affected verifier and mark the old review stale.
6. Integrate — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build.
7. Close — freeze the build and run a final independent review against the original request (not the plan), then write final-report.md.

Hard rules

1. One writer per path. A path appears in at most one task's write list. Shared files (package.json, lockfiles, barrels, schemas, migrations, CI) belong to the integrator only.
2. Packet, not transcript. Each worker reads .swarm/brief.md, its tasks/Txx.md, and .swarm/contracts.md. Never fork the lead's conversation for dozens of workers.
3. Structured reports. Workers return {task_id, status, summary, files_changed, evidence, acceptance, issues, assumptions} and write the same object to .swarm/reports/Txx.json. Verifiers write the full review to .swarm/reviews/Vxx.md and return the minimal {task_id, verdict, summary, review_file}. Prose is not a report.
4. No self-verification. The worker's own checks are a smoke test; a different agent verifies the artifact.
5. No global side effects. Workers do not run installs, repo-wide format/lint/codegen, migrations, dev servers, or any git write command. They do not edit other tasks' files or reports. The lead owns git and commits only after the final review.
6. Respect the runtime slot cap. Active children include recon, verifiers, integrators and any other subagents. A spawn-limit error is a scheduling bug, not a worker failure: shrink the batch, keep completed results, and dispatch the remainder.
7. Freeze during verification. Once the verify wave starts, do not edit source/tests/docs except to fix a verified finding. After a fix, re-run the affected verifier; an old review is stale.
8. Stop rules. Two waves with no net progress → stop and re-plan. Verification failure rate > 30% → fix briefs/contracts, not agent count. Budget exhausted → report partial and list unverified areas.
9. No shared visual desktop. Visual agents get their own display/config/project copy; see references/visual-testing.md. A screenshot from a shared desktop is not evidence.

Sizing

Independent units	Batch size	Batches	Agents	Notes
< 8	—	—	—	Do not swarm
8–11	6–8	1 + verify	~12–14	Small swarm; one batch
12–24	6–8	2	~20	Default; 2 batches per build wave
25–48	6–8	3–4	~40	Large; watch the lead's context
49+	6–8	5+	60+	Only if truly independent; the lead becomes the bottleneck

The wave size is not fixed by this table. The runtime active-child cap is host/policy-specific and may be as low as 8; do not assume 14 or any default. Discover it before dispatch (runtime diagnostics or a tiny trial), subtract active recon/other children, and leave at least one slot free for retries. If the cap is unknown, start with 6 workers. The batched runner in assets/wave.workflow.js starts tasks in chunks, so a failure to spawn one chunk does not discard completed work.

Workspace

.swarm/
  brief.md          shared context: goal, stack, commands, conventions, hazards
  map.md            repository map from recon: paths, entry points, hazards
  contracts.md      frozen interfaces between tasks
  plan.json         tasks, deps, write scopes, waves, status
  plan.md           human-readable plan + coverage matrix
  ownership.md      path -> task map
  tasks/T01.md      one work packet per task
  reports/T01.json  worker report (worker writes)
  reviews/V01.md    verifier report (verifier writes)
  baseline.json     pre-swarm file manifest (`--init`)
  report.schema.json  report contract for workers
  verdict.schema.json minimal contract for verifiers
  state.json        wave, budget spent, open issues
  final-report.md
  tmp/T01/          worker scratch, never shared

Coordination loop

Between waves the lead does only four things: continue, answer blocked tasks and retry, re-scope, or stop. Read structured reports and review files, not raw logs. Keep state.json current, including the real slot cap, retries and re-verifications. The lead is the only agent that talks to the user.

For a blocked task: apply the smallest contract/shared-file change, update contracts.md, record it in state.json, then send_message to the same worker with the answer and let it continue. Do not spawn a replacement for a worker that only needed a decision.

References

• references/playbook.md — phase-by-phase runbook, gates, checklists, failure recovery.
• references/packets.md — how to write briefs, task cards, and verifier cards; examples and common mistakes.
• references/orchestration.md — workflow cookbook: script patterns, schema subset, retries, background runs, archetypes (code / research / content).
• references/visual-testing.md — isolated Xvfb/container visual tests, deterministic screenshots, verifier procedure.
• assets/ — copyable brief, task, and verifier templates; report.schema.json, verdict.schema.json; wave.workflow.js (batched workers), verify.workflow.js (frozen verification).
• scripts/audit-scope.mjs — compares changed files to the ownership map.

Signals that the swarm is failing

• Workers ask the same question or edit the same file → the plan or contracts are underspecified.
• Reports are long on prose and short on evidence → the task card lacks executable checks.
• The lead spends more tokens reading reports than the workers spend working → waves are too large or reports too verbose.
• Verification finds the same class of defect repeatedly → fix the brief, not the worker.
• A workflow ends with no usable verdict although reviews exist on disk → the verifier schema is too strict; read the review files and switch to assets/verdict.schema.json.
• A wave dies with active child limit reached → the batch was sized from the wrong cap; halve it, subtract recon, and dispatch only unstarted tasks.