loop-runner

name

loop-runner

description

Execute exactly one disciplined iteration of a designed loop from .loop/<name>/ (LOOP.md charter + state.json + journal.md). Use when asked to "run the loop", "run one iteration of <loop>", "continue the <name> loop", or when invoked on a cadence (cron, /loop, while-loop) against a loop directory. Works identically under Claude Code, Codex, Gemini CLI, or any coding agent — state lives in files, not in this conversation.

Loop Runner

You are one iteration of a durable loop. You start cold, you finish clean, and everything you learn goes into files — the next iteration (possibly a different agent, possibly you tomorrow) knows only what the loop directory says. Run exactly one unit; resist finishing "just one more".

The iteration protocol

Execute in order. Do not skip, reorder, or batch steps.

0 · Load

Read, in this order: .loop/<name>/LOOP.md (the whole charter), .loop/<name>/signs.md (every line is a binding rule earned from a past failure — treat them like Guardrails), .loop/<name>/state.json, the last 3 entries of .loop/<name>/journal.md, and .loop/<name>/backlog.md if the archetype uses one. Do not read the full journal — old entries are archive, not context.

1 · Gate

Refuse to run (exit with one journal line explaining why) if ANY of:

• .loop/STOP or .loop/<name>/STOP exists — the operator's kill switch. Never delete a STOP file.
• status is paused, stalled, blocked, done, or retired — only an operator or the orchestrator changes those.
• iteration >= budget.max_iterations.
• Done-when already passes → set status: done, journal it, report, stop.
• The working tree is dirty with changes this loop didn't journal → set status: blocked, escalate per charter (H4 debris — a prior iteration died; a human or the orchestrator must adjudicate, not you).

Then check .loop/<name>/STEER.md. If present, it is live operator steering: incorporate it into this iteration's choices, quote it in the journal entry, then delete the file. Steering outranks the journal's Next: hint but never overrides Guardrails or promotion mode.

2 · Pick

Select the single unit per the charter's Iteration contract (top eligible backlog item; next failing test; the current blocker for a babysitter; …). If the last journal entry's Next: names a unit, prefer it unless it's now ineligible. If the same unit appears in the last 2 entries with ❌, you MUST take a different approach or escalate — never re-run a failed approach verbatim.

3 · Do

Complete the unit within the charter's Guardrails and wall-clock budget. Touch only what the unit requires. If mid-unit you discover it's oversized, stop at a coherent boundary, split the remainder into new backlog items, and treat the completed part as your unit.

4 · Verify

Run every command in the charter's Verification section and read the ratchet via its "Read via" command. This step is not optional and not skippable under time pressure — an unverified unit is a failed unit. Evidence, not assertions: the journal gets the actual command output (exit code, counts, failing test names), never "tests pass". You may not record a result you did not observe this iteration. An iteration that produced no changes counts as no ratchet movement (stall_count+1), even if nothing failed.

• All pass + ratchet moved right (or held, for non-ratchet units) → proceed.
• Ratchet regressed → revert your changes now (git restore / revert), journal the regression with the ❌ flag. Do not debug forward. Do not leave the regression for the next iteration.
• Verification fails → fix within budget or revert. Never record a ❌ unit as done.
• Any failure with an identifiable cause → append one line to .loop/<name>/signs.md: a rule that would have prevented it ("do not edit generated files under X — regenerate", "run the schema migration before the type check"). Signs come only from observed failures — never add speculative ones.
• You overran the wall-clock budget noticeably? Treat it as a drift alarm even if verification passed — journal what made the unit slow; it usually means a wrong mental model or an oversized unit (propose the split in Next:).

5 · Record

In this order (order matters — a crash between steps must never leave done-looking state with no evidence):

1. Append the journal entry to .loop/<name>/journal.md (format in the loop's state-schema reference — Unit / Did / Verify with actual command output / Ratchet old→new / Next / Flags).
2. Update .loop/<name>/state.json: iteration+1, ratchet.value (and ratchet.best), ratchet.stall_count (0 if moved, +1 if not), promotion.clean_cycles (+1 if clean; reset to 0 on any ❌, regression, or guardrail near-miss), last_run, last_agent.
3. Strike through / advance the unit in .loop/<name>/backlog.md.
4. Commit if the loop's promotion mode allows it; otherwise leave the change as a proposal per the charter (branch, PR, or staged diff — whatever the charter says). Working tree must end clean-or-committed either way.

6 · Report & handoff

• ratchet.stall_count >= ratchet.stall_threshold → before escalating to a human, take one in-loop escalation if the charter allows it: hand the blocker (files + failed approaches from the journal) to a stronger reasoner or a fresh different-vendor model for a hypothesis. If that iteration also fails → set status: stalled and escalate per the charter's Escalation channel — a real message to a human, not a journal line. Recommend a backlog regeneration if the journal shows circling.
• Done-when now passes → status: done, escalate the good news the same way.
• Nothing needed attention (watch loops, no-change cycles) → reply exactly the charter's OK-token (default LOOP_OK) and suppress any channel report — the silence contract is what keeps the human reading the reports that matter.
• Otherwise: one-line report (iteration N: <unit> ✅, ratchet X→Y, next: <unit>) and stop. Never start iteration N+1 yourself — cadence belongs to the scheduler (cron, /loop, while-loop, orchestrator), not to you.

Hard rules

1. One unit per iteration. The loop's convergence proof depends on it.
2. Files are the only memory. Anything worth knowing goes in .loop/<name>/ (journal/state/backlog/signs) before you exit.
3. Propose-only means propose-only. If promotion.mode is propose-only, you do not commit to protected branches, publish, send, deploy, or spend — no matter what the unit seems to need. The gate is the point.
4. Escalations must leave the loop directory. Slack, PR comment, inbox file — per charter. Journal-only escalation is a silent failure.
5. Never edit LOOP.md. Charter changes are the designer's/operator's job. If the charter is wrong, escalate with the specific defect.

Running under different harnesses

The protocol is identical everywhere; only the scheduler differs.

Harness	One iteration	Cadence
Claude Code	claude -p "run one iteration of .loop/<name> per loop-runner" --output-format json	native /loop 30m <same>, Stop-hook driver, or cron
Codex CLI	codex exec --sandbox workspace-write --output-last-message /tmp/out.md "run one iteration of .loop/<name> per the loop-runner skill"	while :; do codex exec "…"; sleep 1800; done or cron
Gemini / Grok / other	equivalent one-shot exec with the same instruction	cron / while-loop
Cloud (CCR routines, Actions)	schedule the one-iteration instruction	platform cron

Driver-loop notes: agent progress streams to stderr, final message to stdout — keep stdout clean for the driver to parse. In CI, scope API keys to the single exec invocation (never job-level env — repo-controlled code inside the loop can read job env). Fresh context per iteration is a feature — do not "optimize" it away by running many iterations in one long session; that reintroduces the context rot the loop exists to prevent.