--- name: loop description: "Use when the user wants the backlog worked autonomously end-to-end — 'run the backlog', 'bro flow loop', a hands-off /goal over open beads. Unlike /next (one scheduling step), `bro flow loop` IS the loop: bro claims each ready bead, spawns the configured agent in a fresh worktree, drives the act gate, closes the bead, repeats. Requires `bro` and `bd`; the agent is a providers. entry (loop.provider/--provider, acp = headless) or a raw loop.agent template." --- # /loop (bro) **All mechanics live in the `bro` CLI.** This skill is policy only. `bro flow next` schedules one bead; `bro flow loop` runs the queue to exhaustion — claim → worktree → agent → push onto the gate stack → repeat — with no per-item "should I continue?" The backlog's existence is the approval. ## Configure the agent once **Prefer the provider lane** — a `providers.` registry entry resolves the spawn exactly like `bro fleet agents up`: ```json { "providers": { "kilo-cli": { "type": "acp", "command": "kilo --acp", "model": "typesafe/jev-1.13" } }, "loop": { "provider": "kilo-cli" } } ``` An `acp` entry spawns `bro acp-worker` — a stdio ACP server driven by the protocol, headless by construction (no TUI can open on WSL interop). A `cli` entry substitutes its `command` for the template. The picks: `--provider`/`--agent ` flags → `fleet.profiles` preset (`--profile`, `loop.profile`) → `loop.provider` → `agents.native.provider`. `--model` and `--auto-approve` tune the lane. `bro flow loop --agent kilo-cli` works too — a bare `--agent` value that exactly names a configured provider IS a provider pick. **Per-bead routing** — declare `fleet.routing` and each claimed bead's class picks its own provider chain, same as `bro agents up`: the `class:` bead label wins, unclassed beads take `default`, and `--class ` pins the whole run to one class: ```json { "fleet": { "routing": { "default": { "chain": ["opencode"] }, "sweep": { "chain": ["kilo-free"] } } } } ``` The chain head supplies the initial provider (and its inline `model` pin) unless a flag-tier pick already named one — explicit `--provider`, `--agent `, `--profile` still pin the lane for every bead, with the resolved class stamped as provenance (`BRO_AGENT_CLASS`); the config picks (`loop.provider`, `loop.profile`, `agents.native.provider`) are standing defaults the declared table outranks. A resolved class missing from the table is a config error — `default` is preflighted before the first claim, a bad `class:` label parks its bead instead of silently falling through. `fleet.router` (shadow/enforce) classifies unclassed beads by judge verdict, same as `agents up`. For a registry spawn, a fresh step walks from the chain head; a respawn walks from its current provider. `fallthrough` moves forward to the first un-walled provider without wrapping; `park` keeps the step blocked on its current provider. **Model matrix** — `fleet.matrix` (spec `specs/bro-v0pvd.1.md`) is the shadow-only capability router: before each spawn ONE judge `decide()` scores the task's complexity (ordered scale, default low→medium→high) and picks its mode (default planning/coding/review/fix); deterministic code then filters `fleet.matrix.models` rows by declared `modes` + `complexity` ceilings and journals the pick as a `route-matrix` verdict in the judge journal — `no-fit` when nothing can take the task. The lane never changes: shadow journals what it WOULD have spawned, the static resolution above stays authoritative, and `mode: "enforce"` is refused loudly until the follow-up bead lands pick→lane resolution. **Route table** — declare `brouter.routes` and the loop asks the ROUTER's own table instead: the bead's class label is the task's `type`, its priority the task's band, and the table's `chain` names the models (the honest `/` ids). `fleet.routing` stays the compatibility face — a run that declares no table behaves exactly as before. A table that breaks, or names a model `brouter.models` contradicts, is a config error: the run refuses to spawn rather than land the bead elsewhere (`bro router route ""` shows the verdict and the why). `bro loop --explain` prints WHY each bead landed on its route — the route slice (the route, the chain, the rejects), the model slice (the model and who pinned it), the health slice (the walls the router knew) and the cost slice (the ledger's counters). `--explain=route,model` takes a subset; the explanation goes to stderr so the run log on stdout stays clean. **Raw template** — `loop.agent` (or an `--agent` value that names no provider) is the escape hatch: ```json { "loop": { "agent": "opencode --prompt-file {promptFile} -p" } } ``` `{promptFile}` is replaced with the work-order file bro writes into the fresh worktree (no placeholder → the path is appended as the last arg). Examples: `claude -p "$(cat {promptFile})"`, `codex exec "$(cat {promptFile})"`. The spawn env carries `BRO_BEAD_ID`, `BRO_BEAD_TITLE`, `BRO_PROMPT_FILE` (provider lane also pins `BRO_AGENT_PROVIDER`, `BRO_AGENT_MODEL`). Whatever permission flags your agent needs for unattended work are yours to choose — e.g. a permissive flag pair that skips all human confirmation, which is the point of the loop but obviously grants the agent full autonomy; scope it to machines/repos you trust. A template `--agent` flag wins over a configured `loop.provider` — the provider flags can't sit beside it. It also bypasses `fleet.routing` entirely (a warn line says so): every bead runs the literal template. Other `loop` keys: `bootstrap` (runs once per worktree), `stallMin` (advisory output-silence flag at check-in — never a kill), `mergeTimeoutMin`, `fixRounds`, `maxItems`, `maxOpen` — the gate stack's open-PR cap (default 1) — `maxOpenTotal` (default 10, total fleet PRs), `worktreeWarn` (default 40), `worktreeMb` / `diskMinSlots`, the disk floor below — and `batch` / `batchMinPriority`, the clump knobs below. **Spawn guard invariant (spec bro-eqi2d)** — every spawn the loop prepares passes the external-agent exclusion first: while an agent this rig does not own is actively working on the host (an interactive devin or opencode session, a foreign worker, a live copilot task, a session that armed `.work`/`.task` markers here), the pass refuses `cap` — `external agent active — : ` — and holds for the next tick. The session goes idle after `spawn.externalIdleSec` (default 480s) of no proven activity; `spawn.externalBlock: false` opts out. The quota lanes (`agents..maxSessions/maxWorkers/ maxBatchWorkers`) and provider walls refuse on their own — the two guards are independent, both must hold. ## Commands | Command | What it does | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bro flow loop` | Run the queue until idle or gated | | `bro flow loop --max N` | At most N beads this run | | `bro flow loop --max-open N` | Cap the gate stack's open PRs — a full stack only services gates until a merge frees a slot | | `bro flow loop --max-open-total N` | Hard ceiling on total open fleet PRs (`work/`,`loop/`,`stack/`,`fix/bro-`) — claims held while >= ceiling; 0 = off (default 10) | | `bro flow loop --disk-min-slots N` | Disk floor in slot units — pushes hold while free disk < N×`loop.worktreeMb` on any filesystem the run writes to (default 2; 0 disables) | | `bro flow loop --dry-run` | Print the top item's plan (claim, worktree, agent cmd) — changes nothing | | `bro flow loop --agent ''` | One-off agent override — a provider name resolves through the registry | | `bro flow loop --provider ` | Provider pick (`--profile`, `--model`, `--auto-approve` tune it) | | `bro flow loop --class ` | Pin every claimed bead to one `fleet.routing` class (default: the bead's `class:` label, else `default`) | | `bro flow loop --label a,b` | Declared scope — only beads carrying one of these labels are claimable; the rest of the shared queue stays untouched. "Loop the debt beads" never bleeds into unrelated work | | `bro flow loop --batch N` | Batch claims — a claim pulls up to N same-affinity beads into one worktree + worker + PR (default 1 = solo). Affinity binds on the lead's spec/epic/`area:`/path-prefix key; `loop.batchMinPriority` (default 3) keeps urgent work solo; a `solo` label opts a bead out | | `--merge-timeout MIN`, `--interval SEC` | Gate budget and poll overrides | ## What happens per bead 1. **Claim** — top `bd ready` item, `bro flow next`'s rules: HUMAN GATE beads, epics, and molecule steps (convoy-owned) are never auto-claimed. 2. **Worktree** — sibling `--` on branch `loop/` off `origin/main`; `loop.bootstrap` runs once per bead, before the agent. 3. **Agent** — the work-order prompt is written to the worktree and the agent runs to completion — no per-agent wall clock (a hard kill on a working session is an anti-pattern; the run record is how a check-in judges it instead). stdout/stderr append to `/bro/loop/.log` and a `.json` record pins the pid — `bro review watch`/`bro fleet status` report output silence past `loop.stallMin` (45) as an _advisory_; the orchestrator decides, bro never kills. Its env pins `BEADS_DIR` to the runner's store (`bd where`), so `bd` writes inside the worktree reach the shared db regardless of version or a tracked `.beads` copy — and an agent `bd close` is honored as a verdict (`closed`), not reopened as a failure. 4. **Gate stack** — the PR is discovered via `gh pr list --head` and joins the run's gate stack instead of blocking the queue. Each tick services the stack oldest-first, then pushes the next bead while a `loop.maxOpen` slot is free — a pending gate is claimed work, never orchestrator idle. A gate event is the preemption point: green → `bro review act merge` (merge slot + `--match-head-commit` apply); threads → the agent is respawned with the thread list; `CONFLICTING` → a rebase order onto the PR's base; `BEHIND` as the sole blocker → update-branch. Fix and rebase rounds share `loop.fixRounds`; each member waits out its own `mergeTimeoutMin`. 5. **Close** — `bd close --reason "landed via PR #N"`, worktree and branch removed; the freed slot claims the next bead. A member's own loop IS the supervisor — `bro review drive` never needs to spawn fixers against loop-owned worktrees. ## Policy - **The loop ends at `idle`, `gated`, or `--max N`** — `idle` means the backlog is empty; `gated` means only human gates / epics / molecule steps remain. Report which and stop. - **Failures are visible, never silent** — an agent that exits without a PR gets the bead reopened with a `loop:` note; a stalled PR parks the bead: a `loop:` note names the blocker, the claim releases into a deferred snooze for `loop.parkedWakeMin` (default 2h — then it wakes to `open` on the next ready read; `0` ices it until `bd undefer`), and the worktree stays as the resume cache. - **A provider wall is waited on the provider's clock, never churned** — a `rate_limited` worker death carrying a `resetAt` snoozes the claim until the reset (then it wakes and a fresh worker respawns — no attempt burned waiting), and a `rate_limited`/`quota` wall derived at spawn admission either holds pushes until the reset or parks the clump when no reset was reported. The shared exit-cause taxonomy — the same contract convoy supervision runs — decides. Only a `rate_limited` reset at settlement is waited on; quota, reset-less, and stopped exits keep the flat cooldown. - **The open-PR set is bounded** — `loop.maxOpen` (default 1, serial) caps how many gates sit on the stack; `loop.maxOpenTotal` (default 10) is a hard ceiling on all open fleet PRs (`work/`,`loop/`,`stack/`,`fix/bro-`). When at ceiling, claims hold — only gate service and stale-orphan reconcile run. A full stack services gates only until a merge frees a slot. Independent branches drift against shared files fast — keep the cap tight rather than wide, or run `--stack` so members chain onto each other and conflicts surface at rebase-time. - **Pushes also hold on the disk floor** — a slot is priced at `loop.worktreeMb` (default 400 MB: worktree + bootstrap/agent litter); while free disk on the worktree parent or tmpdir drops below `loop.diskMinSlots`× that price (default 2), pushes hold like a full fleet — nothing claimed, nothing parked — until merges free the space. `--disk-min-slots 0` is the emergency escape. - **Already-attempted beads aren't re-picked** within a run — a reopened failure can't spin the loop forever. - **Batch claims are fail-safe, never silent** — with `loop.batch`/`--batch N` a claim is a clump: one worker carries N compatible beads through one worktree and one PR. The contract is per-bead commits naming the bead id (`fix(cli): drift (bro-x1)`) — at merge the gate closes exactly the members the branch's commit log names and re-queues the uncovered tail. A mid-flight batch loses only the in-flight bead, never the landed prefix; a member that merged without a covering commit comes back as open work, not a false close. `--max` bounds beads, not items — a clump fills only up to the remaining claim budget. - **`--dry-run` first on a new repo** — verify the agent template and worktree path before the loop starts claiming. - One `bro flow loop` per repo — two runners would race the same top beads (claim is atomic, so the loser just takes the next one — wasteful, not corrupting). ## Done means verified-clean, not exited A loop iteration is done only when the bead reached a terminal, authoritatively verified state — PR `MERGED` per `gh pr view` and the bead closed per `bd show`, or parked with a `loop:` note naming the blocker and the claim snoozed `deferred`. A process exiting is not a verdict. The loop runs this audit itself at every exit — idle, gated, or error (`try/finally` around the claim cycle). It first reaps provably-done litter — clean `loop/*` worktrees and branches whose bead is closed or whose PR merged (`bro work prune --loop` runs the same sweep by hand) — then names every surviving tail in the run summary: open `loop/*` PRs, kept worktrees and branches, beads still `in_progress`, and cleanup failures collected during the run, then `bro work sync` pushes artifacts and bead state. A clean run prints `clean — no loop tails`. Tails that survive the sweep — dirty trees, open PRs, live claimants — still need a human or a follow-up session to clear. The process itself is held to the same contract: a ref'd heartbeat keeps the event loop open while a run is live (`loop: alive — ` lines name the suspension point, so a stuck await is a visible stall, never a silent drain-exit), and an `exit` listener prints `loop: process exiting mid-run — ` plus a bead note if the process dies with the queue open — signals included. A run can stall or die; it cannot vanish without a trail. Cleanup after a merge wait is `&&`-sequenced or command-owned — never `;`: a failed `act wait` must not touch the PR, branch, worktree, or bead.