skills/agent-swarm/SKILL.md

name, description, whenToUse

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