skills/agent-swarm/SKILL.md

name, description, whenToUse

name	description	whenToUse
agent-swarm	Use for large tasks that split into 8+ independent work units across software, research, content, data, design or operations (codebase-wide changes, audits, migrations, multi-source research, multi-section documents, dataset work, visual redesigns) to run coordinated subagents in waves under one lead, with 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.

The protocol is domain-neutral: software, research, content, data, design and operations all use the same roles and evidence rules. Pick an adapter from references/domains.md; do not force a software pipeline onto non-code work. Tools are optional too: if workflow is unavailable, use subagent or direct sequential work with the same packets.

The skill is a capability, not a mandatory process. Apply the lightest mode that meets the risk:

Mode	When	What it adds
Direct	one unit, fast feedback, low blast radius	none
Paired critic	medium task or risky design decision	independent review, same artifact
Swarm	8+ independent units, breadth dominates	plan, ownership, parallel workers, verifier wave

Do not force task cards, waves or .swarm/ artifacts onto a small request. Conversely, do not skip independent verification on a large or risky one. The user keeps the choice of stack, scope and pace; the skill only adds coordination when breadth or risk justifies it.

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 a re-runnable acceptance check: a command, a named artifact, a source/citation check, a metric, or a rendered result. There is no universal evidence type; match it to the domain adapter.
• 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 available tools and real active-child cap before sizing a wave. Record in state.json: tool availability (workflow, subagent, display/artifact command, build commands), slot cap, active children, planned batch size, and the chosen domain adapter.
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 when the tool exists, using the batched runner in assets/wave.workflow.js; its concurrency must fit the available slots (see Sizing). If workflow/subagent is unavailable, the lead executes the same packets sequentially. 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 (or 1–2 for a small domain task). Use assets/verdict.schema.json and, when available, assets/verify.workflow.js; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. Match evidence to the domain adapter: rerun commands, read rendered artifacts, sample citations, recompute metrics. For GUI products, use 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, .swarm/contracts.md, and the domain adapter in .swarm/profile.md (if any). 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, deployments, external publishes, or any git write command without explicit scope. They do not edit other tasks' files/reports or touch live systems. The lead owns irreversible operations and 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, domain, commands, conventions, hazards
  map.md            repository/source map from recon: paths, entry points, hazards
  contracts.md      frozen interfaces between tasks
  profile.md        domain adapter: artifacts, commands, evidence types (optional)
  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/domains.md — adapters for software, research, content, data, design and operations.
• references/visual-testing.md — isolated Xvfb/container visual tests, deterministic screenshots, verifier procedure (GUI adapter).
• 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.