/nw-swarm

name: nw-swarm
description: How a root LLM runs several nwdes lanes in parallel with one lane orchestrator per lane, on any host. Load when more than one feature or lane is open or about to be.
user-invocable: false

nw-swarm

A swarm is several nwdes lanes advancing at once, each driven end to end by one lane orchestrator, while the root stays the only writer on trunk. The verbs are nwdes (Python) and the lane is a git worktree, so every host can run it; the host only needs to start a sub-agent and, ideally, send it messages. Verbs and lane open, compose, integrate: `nw-nwdes`. Capacity, Lane flow, worktree lifecycle: `nw-throughput`. Role invocation forms: `nw-role-invocation`. None is restated here.

Roles

| Role | Does | Never does | |---|---|---| | Root | opens lanes, briefs and revives orchestrators, answers questions, rules on options, composes and integrates one lane at a time, keeps the board | role work, repairing a role's values, a second trunk writer | | Lane orchestrator (`nw-lane-orchestrator`) | runs ONE lane: design, oracle, review, craft, host verification, compose, whole-candidate review and examine on the composed candidate; launches roles with `nwdes prompt` output verbatim | role work, push, CI dispatch, `nwdes lane integrate` | | Role agents | record through their nwdes kind verbs and close | commit another role's half, edit another role's file |

Trunk has one writer: the root. A lane writes only inside its own worktree.

Size and WIP

Size the work by the work, never by the free slot. WIP limits per size (how many L, M, S lanes may be open) are project configuration; read them from the project instructions. Without them, open one lane and add another only while the box keeps its headroom and end-to-end wall time does not rise (`nw-throughput`, Strategy). Rework of an open lane precedes opening new work (`nw-throughput`, Lane flow).

Open a lane

1. Check `git worktree list` and the lane tree: no lane for this feature exists yet. 2. `nwdes lane open --feature <feature>` from the root checkout; the lane is `ROOT/lanes/<feature>`. 3. Record the lane's ABSOLUTE path. Every later message names absolute paths, never relative ones. 4. Put host-only output (diffs, receipts) outside the worktree, under a bounded scratch root.

Brief a lane orchestrator

Start the installed `nw-lane-orchestrator` with the host's native sub-agent tool and pass the brief by FILE path, not inline. The brief is common rules plus the feature brief plus root context:

Lane: <feature>            Lane path: <ABSOLUTE ROOT>/lanes/<feature>
Request: <verbatim>        Size: <S|M|L> and why
Decide alone: routine findings settled from an authority fact, related caller/doc edits within scope
Return to root: scope or trade-off questions, a finding still open at the review-round limit the role bundle prints (nwdes prompt), a refusal you cannot fix
Checks a reviewer may run: <list>; interpreter: the lane environment, never a bare python
Box: heavy test run only when MemAvailable covers it and no other run is live; wait ends your turn
One owner per file and per record: <names>
Stop after: nwdes lane compose, then candidate review and examine recorded on that candidate; report, do not integrate

What returns to the root (the final message, facts with evidence): the lane path; EXPECTED and CANDIDATE from compose; commit SHAs; each verdict (oracle approval, whole-candidate review, examine) with its recorded id; exact refusals; open findings with owner and round count; decisions only the human can make, with the consequence of each option. The orchestrator stops there.

Per-wake checklist (root, every wake)

1. List the agents. An orchestrator that ended its turn with a status report is STALLED, not finished: revive it by message with the next instruction. 2. An orchestrator waiting for the box ended its turn and will not wake itself: wake it by message when the box is free. 3. `git status` of the root checkout: any stray write is a defect to report and revert at its source. 4. Read each returned report against the board; the board changes at the same step as the work. 5. Check pending questions: answer, rule, or escalate to the human; a pending owner answer blocks only the work that depends on it (`nw-auto`, owner questions). 6. Check capacity before admitting the next heavy run (`nw-throughput`).

Rulings

Rulings go to the SAME orchestrator by message, with the reason. The root never edits a role's values; the owner role fixes its own artifact. Cap rounds per finding class at the review-round limit the role bundle prints (nwdes prompt), then the finding returns to its owner or to the human (`nw-throughput`, Lane flow).

Compose and integrate

One lane at a time. Order: the lane's implementation is stable, then `nwdes lane compose --feature <feature>` prints EXPECTED and CANDIDATE, then the whole-candidate review and the source-blind EXAMINE run on that composed candidate, then the root runs `nwdes lane integrate --feature <feature> --expected <EXPECTED> --candidate <CANDIDATE>` with the unchanged identities. Confirm with `git log` that trunk holds the candidate before the board says integrated. After each integration refresh any locally installed copy of the tooling the next lane runs. If trunk moved or the lane changed after compose, compose again and reassess the evidence for the new candidate; a verdict never carries to another candidate (`nw-throughput`, Feature record).

Traps

• **Stray writes to the root checkout** WHAT: sub-agents resolve relative paths against the host

cwd. WHY: hosts give sub-agents no cwd parameter. HOW: absolute lane paths in every message; check root status after every role turn; a project hook may refuse root writes while lanes are live.

• **Two writers in one lane** WHAT: corrupt review draft or acceptance record. HOW: name ONE owner

per file and record; nothing else writes while a reviewer observes.

• **Review staleness