/run-the-loop

description: GENERIC, project-independent wrapper for "run the loop". If the current repo ships its OWN .claude/commands/run-the-loop.md, this wrapper LOADS + FOLLOWS that project command verbatim (the project command WINS — this global file never overrides project-specific instructions). Only when NO project command exists does it run a generic convergence loop — orient the canonical home, fan out the 15 named roles + the standing Long-Trail TDD case-owner, converge, adversarially review, verify, ship, reconcile. Fires when the user says "run the loop".
argument-hint: "[role/lane name, category, or 'all' (default)]"

Run The Loop (generic global wrapper)

> **PRECEDENCE CONTRACT (read first — this is the core requirement of this file).** > This is a GENERIC, project-independent wrapper. It does **NOT** replace or override any > repository's own `run-the-loop` command. **The PROJECT command always wins.** When the > current repo ships its own `.claude/commands/run-the-loop.md`, this wrapper's only job is > to **load and follow that project command verbatim**, then STOP. The generic loop below runs > **only** when the repo has no project command of its own.

0 — FIRST INSTRUCTION (mandatory, do this before anything else)

**If `./.claude/commands/run-the-loop.md` exists in the current repo, READ it and EXECUTE its instructions verbatim, passing through `$ARGUMENTS`, then STOP — do not run the generic loop below.** The project command is the canonical owner of that repo's loop; this wrapper defers to it completely.

• Check both common locations, nearest-wins: the repo-root `./.claude/commands/run-the-loop.md`

first, then a monorepo sub-package `./<app-or-package>/.claude/commands/run-the-loop.md` if the current working directory is inside one. If either exists, follow it and STOP.

• This detection is **load-bearing, not decorative.** Claude Code's command resolution can let a

same-named USER (global) command take precedence over the PROJECT one — so this wrapper must actively self-defer rather than assume the harness routes to the project file. Reading + executing the project command here guarantees the project's project-specific instructions run **unchanged**, regardless of which scope the harness picked to invoke.

• Do **not** merge, diff, or "improve" the project command — run it as written. Its roster, phases,

gates, canonical answers, and paths are authoritative for that repo. This wrapper contributes nothing on top of it.

**Only if NO project `run-the-loop.md` exists anywhere in scope → fall through to §1+ below.**

---

Generic convergence loop (fallback — no project command present)

One deliberate, VERIFIED fire of a convergence loop for whatever repo is current. Advance the project's frontier by one coherent, verified slice per active workstream (default `all`; or scope to `$ARGUMENTS`). **One coherent slice per role per fire** — never split a slice across follow-ups; never start a large pass in a context-saturated session. Every fire is a **multi-phase wave** (fan-out → convergence → adversarial-review → verify → ship → reconcile), never queue-draining, and **leaves ≥1 improvement to how future loops run**.

1 — Orient (cheap; NEVER read giant ledgers in the main thread)

• **Canonical home = `.claude/run-the-loop/`** if it exists. Read the small operator docs, in order,

and only the ones present:

• `README.md` — what the loop is + how to run one fire.
• `OPERATING-PRINCIPLES.md` — invariants, gates, the settled canonical answers, the category budget.
• `BACKLOG.md` — the **frontier** (next unmet unit per workstream + acceptance). This is what you advance.
• `ARCHITECTURE.md` — the system shape + load-bearing decisions.
• `DISCOVERIES.md` + `LEDGER.md` — append-only; the main thread does NOT read these wholesale

(delegate any deep read to a fresh `Explore` agent with a ≤150-line output cap; LEDGER is where completed slices + SHAs land).

• **No canonical home?** Orient from what the repo actually has: `README.md`, `CLAUDE.md`/`AGENTS.md`,

a root `TODO.md`/backlog, `docs/`, `e2e/FEATURES.md`, open issues. Reconcile code, docs, tests, and visible behavior before choosing work — treat a doc describing a feature as a requirement to VERIFY, not proof it works.

• `git fetch origin -q && git pull --rebase origin <default-branch>` — a concurrent session may have

progressed work; re-inspect the ACTUAL repo, never assume a prior attempt landed.

• **Context budget:** the main thread holds conclusions only. Never ingest trackers/ledgers/scope docs

or any file it cannot act on directly; delegate inventory reads to fresh Explore agents. Heed any oversized-read/oversized-output guard.

• **HARD STOP = LEAD saturation ONLY.** Checkpoint to `progress.md` + fresh session only when the

ORCHESTRATOR hits "Prompt is too long" / autocompact thrash on the lead / can't spawn. ONE worker agent dying (ECONNRESET, `subagent_tokens: 0` from a network drop, cut-off output) is fan-out ATTRITION → salvage its commit (`git show <branch-tip>` before `git branch -D`), re-queue its slice, and KEEP THE LOOP RUNNING. Read WHICH thing failed before checkpointing.

2 — Fan out the standing roster — EVERY fire, in ONE message

Spawn the roster together in ONE message — fresh, worktree-isolated (mutating) or read-only (research) — on disjoint subtrees. Keep ≥1 coding role active whenever ready work exists. **≤6 concurrent mutating agents** (read-only sweeps are free + uncapped; run >6 units as sequential waves of ≤6). Map each role to the best-fit specialist — NEVER a bare `general-purpose` when a named specialist fits. Emit the assignment table + rejected-agent note BEFORE spawning; run the Agent Diversity Review gate before DONE.

**The 15 canonical roles (a floor, not a ceiling):**

1. **Feature Delivery** — take a READY frontier slice; ONE coherent slice end-to-end (schema + handler + UI + tests + flag + docs). Specialist: domain builder /