Loop

/specforge:loop — governed autonomous execution (the Ralph loop, gated)

Drive the active feature's tasks.md to completion by executing tasks one at a time in a loop, checking each off as you go. This is SpecForge's take on the Ralph loop (run the agent repeatedly until the work is done) — but made safe: it can only ever execute a plan a human already approved, and it stops instead of guessing when it hits a blocker.

When to use

• The user explicitly wants to auto-run the remaining implementation of an approved feature.
• Trigger: /specforge:loop (optionally "run one iteration" for a single step).

Preconditions (check first, refuse otherwise)

1. There is an active feature in specforge/state.md with a tasks.md.
2. Its specify and plan are approved (gate OPEN), or fasttrack is on. If not, stop and tell the user to /specforge:approve (or /specforge:quick). The PreToolUse gate would block edits anyway — surface this clearly rather than fail mid-loop.

The loop (each iteration)

1. Read specforge/state.md and the active feature's tasks.md; find the first unchecked task (respect [P] ordering; prefer a tests-first task before its implementation task).
2. If there are none left → mark implement done in state.md, run the feature's quickstart.md / tests to verify, summarize, and exit the loop.
3. Implement only that one task, staying within its scope and the plan/contracts.
4. Verify it (relevant test or a quick check).
5. On success → tick its checkbox [ ]→[x] in tasks.md, append an audit row.
6. On a blocker (ambiguity, a decision that's the human's to make, a failing check you cannot resolve within scope) → do not guess. Write the blocker to specforge/specs/<feature>/loop-blocked.md (what's blocked + the question) and stop the loop.
7. Repeat.

Stop conditions (never spin)

• All tasks checked → done.
• A blocker was recorded → stop for human input.
• No task got checked off in an iteration (no progress) → stop and report.
• A sensible iteration cap (≈ the number of open tasks + a small margin) is reached.

Headless / true Ralph loop (outside the session)

For a fully unattended run, use the bundled runner, which re-invokes the CLI per task and enforces the same gate:

"${CLAUDE_PLUGIN_ROOT}/scripts/ralph-loop.sh" [max_iterations]   # default 25

It refuses to start unless the gate is open, bounds itself, and bails on a blocker or when progress stalls. Requires the claude CLI with this plugin available.

Guardrails

• Governed autonomy: the loop executes an approved, audited plan — it does not create scope. New scope means a new /specforge:specify cycle, not more looping.
• Never edit generated code to paper over a design flaw; if the design is wrong, stop and fix the plan (record it), then resume.
• Every ticked task and every stop is written to state.md / audit.md, so a run is fully reconstructable and /specforge:resume can pick up after any interruption.