skills/agent-swarm/SKILL.md

---
name: agent-swarm
description: 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.
whenToUse: 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.