104 lines
6.1 KiB
Markdown
104 lines
6.1 KiB
Markdown
---
|
|
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.
|