Swarm Run
The pane-management layer for multi-agent work: spawning, marching orders, tending
cadence, handoff verification, and wind-down for a tmux session where every pane is
an agent and one pane is the orchestrator. Its sibling multi-model-serialized-build
(if installed) designs the build: which model owns which strength, the roles, the
deploy path; dueling-idea-forge picks what to build. Swarm-run is what runs underneath either:
the discipline of operating N live agents in panes for hours without the session
degrading into a merge war. Tooling-agnostic by design: raw tmux is enough; a swarm
manager (ntm or similar, if installed) is a convenience, not the method.
Core Insight: A swarm has exactly two currencies, and both are guarded by the orchestrator or they inflate to zero. Write access: at any instant, every file has at most one writer, assigned in a written ownership map, because two agents editing one file doesn't produce a merged file, it produces whichever agent saved last. And claims: an agent's "done, tests green" is a report about its beliefs, generated by a process optimized to sound finished. The orchestrator banks nothing it didn't re-verify: the gate run in the orchestrator's OWN pane, against the integrated tree, is the only green that counts. Trust-but-verify is a swarm anti-pattern; it's verify.
The two contracts (set up BEFORE any agent spawns)
- The ownership map: a checked-in file (
SWARM.mdworks) listing every path/subsystem in play and its sole writer, plus the explicitly-shared files (lockfiles, generated artifacts) that only the ORCHESTRATOR may touch, at integration time. Reassignment is an orchestrator edit to the map, announced to both panes, never a negotiation between agents. No map, no spawn. - The fast gate: one command, under a minute, that every pane can run and the orchestrator will re-run: build + the core tests + (for anything visual or output-shaped) a golden comparison. The gate is the inter-agent contract: every handoff leaves it green. If the project's test suite takes 20 minutes, carve a fast subset FIRST; a gate nobody runs is not a gate. Slow full suite still runs at integration checkpoints; the fast gate runs at every handoff.
The firewall: the orchestrator tends, it does not build
The orchestrator's write access is integration only: merging, checkpointing, resolving the ownership map, reverting. It never fixes an agent's failing work in-place, however tempting the two-line patch: a red handoff goes BACK to the owning pane with the failure output pasted in, or the work is reverted and re-assigned. The moment the orchestrator starts writing feature code it stops tending (nobody is watching the other panes while it's heads-down), becomes a second writer on an agent's files (the collision it exists to prevent), and starts grading its own homework at the gate. One brain per pane; the orchestrator's job is the map, the gate, and the backlog.
The loop
SPAWN: panes come up with marching orders that are self-contained: the task, the files they own (from the map), the gate command, the handoff protocol ("gate green → say DONE + one-line summary; blocked → say BLOCKED + why; never touch files outside your row of the map"). An agent that has to ask what it owns was spawned too early.
TEND (the cadence): the orchestrator cycles the panes on a timer, not on vibes. Per pane per round: read the tail, classify: working (leave it alone; hovering is how you interrupt a good run) / DONE-claimed (→ verify, below) / blocked (unblock: answer, reassign in the map, or re-scope) / stalled or looping (one nudge with concrete direction; still stuck next round → kill, revert to last checkpoint, re-spawn with sharper orders; a fresh agent beats a confused one, and the checkpoint made the kill cheap).
VERIFY (the gate, on every DONE): the orchestrator pulls the work into the integration tree and re-runs the gate ITSELF: - Green → bank it: checkpoint commit, mark the backlog item, update the map if ownership frees up, hand the pane its next item. - Red → the work goes back to the owning pane with the failure output, and the integration tree reverts to the last checkpoint. Two consecutive red handoffs from the same pane on the same item → the item is mis-scoped or the agent is wrong for it: re-scope or reassign, don't loop a third time. - Diff outside the pane's ownership row → revert on sight, regardless of green. An out-of-map diff that happens to pass is still a collision that hasn't happened yet.
CHECKPOINT: after every banked handoff. The checkpoint is what makes every other move in this loop (kill, revert, reassign) cheap enough to actually do.
Stopping condition: wind-down at saturation
The swarm ends when the backlog has no ready item OR two consecutive tending
rounds bank nothing: no pane produced a verified-green handoff, only churn,
re-litigation, and nudges. A swarm past saturation doesn't converge, it burns
tokens arguing with itself; shrink it (cull idle panes, keep the one productive
lane) or end it. Wind-down is explicit: final gate run on the integrated tree,
final checkpoint, ownership map closed out, panes killed, and a one-screen summary
of banked vs reverted vs abandoned. Afterwards the session logs are ore for
session-mine: which marching orders produced verified-green handoffs is exactly
the provenance+outcome trace it mines for.
Honest scope note
The role design (creative model vs systems model), beads-style backlog mechanics,
and deploy gating live in multi-model-serialized-build (if installed; otherwise
the contract below stands on its own). swarm-run inherits its
sole-writer + test-gate contract and applies it at the pane-management layer:
cadence, claims, kills, and wind-down for any number of same- or mixed-model
agents. If you're deciding WHO builds WHAT across model lineages, start there;
if you're keeping six live panes honest for an afternoon, this is the skill.
Anti-Patterns
- Spawning before the ownership map and gate exist. You're not running a swarm, you're scheduling a collision.
- Trusting a pane's "tests pass." The claim is free to generate; only the orchestrator's own gate run banks work.
- The orchestrator "quickly fixing" a red handoff itself: the firewall breach that ends tending, doubles a writer, and un-blinds the gate.
- Two writers on one file "briefly" / agents trading files pane-to-pane. Every ownership change goes through the map, through the orchestrator.
- Hovering: interrupting a working pane every two minutes for status. The cadence exists so you look at each pane rarely but reliably.
- Nudging a looping agent five times. One concrete nudge, then kill/revert/ re-spawn. Sunk cost applies to panes.
- A "fast gate" that takes 20 minutes. Nobody runs it, handoffs go unverified, and you discover the breakage at integration, in a pile.
- Keeping the swarm alive because panes are busy. Busy is not banking; two dry tending rounds is the exit.
- Skipping wind-down: orphaned panes keep writing after you stopped watching.
THE EXACT PROMPT
/swarm-run
Project: <repo path>
Backlog: <where the ready work lives — beads, TODO doc, issue list>
Panes: <how many agents, which harness(es)>
Gate: <the fast gate command — or "carve one first" if none exists>
Cadence: <tending interval; default ~10 min per full cycle>