# Loop

> 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.<name> entry (loop.provider/--provider, acp = headless) or a raw loop.agent template.

- Skill: `theplenkov/loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/loop

---


# /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.<name>` 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 <name>` 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:<name>` bead label wins, unclassed beads take `default`, and
`--class <name>` 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 <provider>`, `--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 `<entry>/<model>` 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 "<task>"` 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 — <kind>: <detail>` — 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.<kind>.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 '<tpl>'`         | One-off agent override — a provider name resolves through the registry                                                                                                                                                                                                  |
| `bro flow loop --provider <name>`       | Provider pick (`--profile`, `--model`, `--auto-approve` tune it)                                                                                                                                                                                                        |
| `bro flow loop --class <name>`          | 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 `<repo>--<bead-id>` on branch `loop/<id>` 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
   `<git-common>/bro/loop/<slug>.log` and a `<slug>.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 <id> --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 — <stage>`
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 — <stage>` 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.

