---
name: agent-swarm
description: Use when a large task splits into 8+ independent units, or when a risky deliverable needs an independent critic across software, research, content, data, design or operations. Not for small, sequential or tightly coupled work.
whenToUse: The task is broad or risky enough that parallel workers or a fresh verifier change the outcome; one agent would take hours and the units can be described without stepping on each other.
---

# Agent Swarm

A small orchestration core, not a mandatory methodology. Use the lightest mode that meets the
risk; the user keeps the stack, scope and pace.

## Choose the mode

| Mode | Use when | What it adds |
|---|---|---|
| **Direct** | one unit, fast feedback, low blast radius | nothing |
| **Paired critic** | medium task, design decision, risky change | one independent review |
| **Swarm** | 8+ independent units or breadth dominates | ownership, parallel workers, verifier |

If the units share one screen, one design language or one mutable artifact, do not swarm. Use one
implementer and one critic; parallel panel writers produce incoherent UI.

## Invariants

1. **Outcome before process.** Agree on what “done” means and how it will be checked. Do not create
   `.swarm/` files, task cards or reports just to look organized.
2. **One owner per artifact.** In a swarm, every path/artifact belongs to one writer. Shared files
   and contracts belong to the lead/integrator.
3. **Packets, not transcripts.** A worker gets a self-contained brief, its scope, the contract and
   the acceptance checks — never the lead's full conversation.
4. **Independent verification.** The author does not verify their own work. A fresh context checks
   the artifact, not the worker's summary. Verification is required for risky or product work; a
   trivial direct change may only need a command and a read-back.
5. **Evidence before claims.** “Done” means a runnable artifact, a passing command, a citation, a
   metric or a rendered result — not a confident sentence.
6. **A technical pass is not product acceptance.** For product/UI work, measure the release build,
   run a real scenario, compare with the baseline and get the user's verdict. If performance/UX was
   not measured, the product gate is `not_run`, not `pass`.
7. **Do not add features to hide bad quality.** If it is laggy, visually worse or harder to use than
   the baseline, fix the slice before expanding scope.
8. **One milestone at a time.** For product work, do not start M1/M2 while M0 is still rough or
   explicitly “not usable”.
9. **Safety.** Check prerequisites before work; ask before global installs, destructive actions,
   deployments or irreversible changes. Workers never install or touch live systems.
10. **User overrides.** Direct user instructions beat this skill. If the user asks for speed, a
    prototype or “just do it”, drop the ceremony — keep only the safety and evidence that still
    matter.

## Loop

1. **Understand** the outcome, audience, quality bar and constraints. Ask only when the answer
   changes the result.
2. **Check** the environment: toolchain, commands, services, display, credentials. If a required
   item is missing and cannot be resolved safely, ask before starting.
3. **Plan only as much as the risk requires.** For a swarm, write a one-page brief, disjoint scopes,
   frozen contracts and acceptance checks. For direct/paired work, skip the ceremony.
4. **Work.** Direct, paired or batched workers. Keep files small enough that each worker reads only
   what it needs; use available concurrency, not a fixed wave number.
5. **Verify.** Technical checks first, then a fresh critic. For product work, add release performance,
   UX scenario, baseline comparison and the user's explicit verdict.
6. **Accept and integrate.** The lead owns shared files, final checks and the report. No next
   milestone without acceptance (or an explicit waiver).

## If you swarm

Optional, for resumability and coordination — not a requirement for every task:

- `.swarm/brief.md` — goal, quality bar, commands, conventions, hazards;
- `.swarm/contracts.md` — only interfaces that cross a task boundary;
- `.swarm/tasks/Txx.md` — one page per unit;
- `.swarm/reports/Txx.json` — structured evidence, if the lead needs to triage many workers;
- `.swarm/reviews/Vxx.md` — independent verdict and findings.

Use the batched runner in `assets/wave.workflow.js` when `workflow` exists; otherwise use `subagent`
or direct sequential work. Never relaunch an oversubscribed fan-out. Read `references/playbook.md`
for the detailed runbook, `references/packets.md` for cards and `references/orchestration.md` for
tool specifics — only when the task needs them.

## Optional modules

Read only what applies:

- `references/playbook.md` — detailed swarm runbook, gates, recovery.
- `references/packets.md` — brief/task/verifier templates and examples.
- `references/orchestration.md` — `workflow` patterns, retries, batching.
- `references/domains.md` — software, research, content, data, design, operations.
- `references/prerequisites.md` — preflight, install/approval policy.
- `references/token-economy.md` — budgets, context discipline, delta review.
- `references/visual-testing.md` — isolated displays, screenshots, computer-use limits.
- `references/product-quality.md` — performance/UX/baseline/human acceptance.
- `evals/` — how to test this skill itself (baseline vs with-skill, trigger checks).

## Signals

- 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 a check.
- The lead reads more tokens than the workers produce → waves or reports are too large.
- The same defect repeats → fix the brief, not the worker count.
- The product compiles and passes tests but feels worse than the previous version → stop adding
  features and run the product gate.
- You are creating process artifacts that nobody will read → delete them and do the work.
- You are changing this skill without evidence → run `evals/README.md` against a no-skill baseline;
  keep the change only if it improves quality/time without over-orchestration.