/swarm

name: swarm
description: Use when executing a superlite plan that has a %% taskgraph. Runs a ready-queue scheduler over an idle agent pool, with scripts for the mechanical steps, selective reviews, and a packet-only final review.

Swarm

You are the coordinator. You decide, dispatch and rule; scripts do everything with a definite answer; agents design, write, review and fix. Read each script's one-line output; one narration line per tool call.

Shorthand (every agent brief states `SUPERLITE=<path>`): `SUPERLITE` = the plugin root, two levels above this skill's "Base directory for this skill: ..." path: `SUPERLITE="$(cd "<base dir>/../.." && pwd)"`, passing the base dir through `cygpath -u` first when that exists. `CLI="$SUPERLITE/skills/swarm/scripts/superlite-cli"`; always run it as `bash "$CLI" ...`. `PLAN` = the plan file; pass `--plan $PLAN` everywhere. Exit 3 means no Python: `bash "$CLI" incident add` it and continue.

**You never edit code or run raw `pytest`; fixes go to fixer agents: tiers, escalation and contract in `fixing.md` (Fixing). Never pass `model`.**

**Rulings, not stalls.** Decide conflicts and plan defects yourself (**spec** binds when present: done+why outranks the plan's how; `superlite-cli agent_specs status`). Append `Ruling: <decision> - <why> - <cost if wrong>` to `.superlite/progress.md`.

Setup

• **One feature, one worktree**: a feature (or colliding multi-file build) works only in its own worktree on `superlite/<topic>`: `superlite-cli session create --slug <topic> --worktree` if missing, then enter it (`session: create` / `enter` line; else `cd`). Write the start SHA to `.superlite/progress.md` (`- start <sha>`).
• Wave 0 is never yours: when the machine plan is written, run `bash "$CLI" wave0 --plan $PLAN` and send Wave 0 in the same message as `lint --stable`. Lint skips START FIRST once the brief exists; `STUB UPDATE:` means refresh stubs. `wave0 --plan` reprints the line. Then `checkpoint T0` (tasks never wait for it) and `bash "$CLI" plan_tools adapter --plan $PLAN`.
• Prime now: `bash "$CLI" build_prime --plan $PLAN` prints `hash size` and writes the slim `.superlite/prime.md` (rules, header, constraints, stable interfaces; `--prime full --spec SPEC --sections "1,3"` = whole plan). Start ready tasks now.
• Incidents: `.superlite/incidents.jsonl` (agents call `bash "$CLI" incident add`); you log BLOCKED and NEEDS_CONTEXT with `--agent coordinator`.
• Graphify: `bash "$CLI" graphify_gate` prints JSON; `use` false: skip. Installed: `graphify update .`. `needs_install` and `allowed`: `uv tool install graphifyy`, `graphify extract . --code-only`. You alone run `graphify update .` after each package is checkpointed.

Planning check

`widget:` from lint or finish: show that file verbatim with your inline widget tool (e.g. `show_widget`). Fixed order: write plan -> `bash "$CLI" plan_tools lint --plan $PLAN --spec SPEC --stable` (show the body of its `GRAPH` block to the user as a ```mermaid block; lists STABLE and FIX tasks, writes `.superlite/stable.json`; prints `SEND BEFORE ANY PLAN EDIT:`, ends with `DISPATCH NOW: T2 T4` or `none`) -> `dispatch` and start every task on that line in the same turn -> only then patch the FIX tasks (edits or a rewrite) -> re-lint -> dispatch the newly stable tasks -> repeat until lint passes. Never patch, rewrite or re-lint while a `DISPATCH NOW` task is unsent.

Each dispatch round, in the same message as the Agent calls, run the `THEN LOG` line lint prints (it appends `unblocked: dispatched T2 T4 at HH:MM:SS; waiting on fixes: T1 T3` to progress.md). `finish` checks it against `lint-log.jsonl`.

Dispatched tasks are frozen: a rewrite keeps their blocks byte-identical, else lint says `FROZEN:` (restore it; a real change is a follow-up fix task). `**Status:** draft` is an optional manual hold. `MISSED TARGET: ... critical path T1 -> T5` is a warning: split or stub the named tasks, or `Ruling: accept predicted <N> min - <why sequential> - <cost>`. `NOTE:` is advice.

The scheduling loop

flowchart TB
  N[dispatch] --> A{per batch}
  A -- agent=ID --> M[task message]
  A -- poll IDS --> Q[relevance poll] --> M
  A -- fresh --> P[prime verbatim] -- READY --> M
  M --> D[DONE reports] --> C[checkpoint T.. --dispatch] --> A
  C -. background .-> PR[probe_run --checkpoint]
  C -. both sides in .-> SM[pt_review contract seam]

Keep `.superlite/pool.json`: `{"agents":[{"id","tasks":[...],"files":[...],"context_k":N,"idle_min":N,"busy":false,"current":"Tn","tier":"haiku|sonnet"}]}` (`tier` = the line's; T0's is `haiku`). Sending a line or spawning its agent sets `busy: true` and `current: Tn` (a batch: `Tn,Tm`); `checkpoint` clears each task it records. The ledger and `current` are the state: keep no lists.

1. `bash "$CLI" dispatch --plan $PLAN --cap 10` prints one line per batch (`Tn` or `Tn,Tm`) from packing that minimizes max(B+A, F/T), longest first: `Tn agent=ID tier=T`, `Tn poll ID,ID tier=T` or `Tn fresh tier=T agent=TYPE`. Tiers come from lint (`config/routing.json`); never override or cross them. Start exactly those. Compact every 30 min (`compact_due`). 2. Per line: `agent=ID`: SendMessage the task to that idle agent. `poll ID,ID`: one SendMessage to each listed agent, "Relevance 0-10 for Tn (files, consumes)? Reply `score: N - reason`"; use the replies present at your next turn, highest wins, tie to the smallest `context_k`. `fresh tier=T agent=TYPE`: Agent TYPE with its tier's prime file pasted verbatim (`.superlite/prime.md`; haiku: `build_prime --tier haiku` writes `prime-haiku.md`), and send its task only after its reply `READY`. `evict=ID` (stderr): drop it. `dispatch` never offers a busy agent or one past its tier's limits. 3. Task message (a batch: one message, in line order): heading and `PLAN`, "your task text: `bash "$CLI" task Tn --plan $PLAN`" (current plan, never retyped), Owns and files not to touch, the Review Focus categories for its files, rulings and interface names (a