Spec Loop

Drive the apply phase of an active OpenSpec change with a Ralph-style loop: a shell runner re-invokes a headless agent as a fresh process per iteration, each iteration implements exactly one task from the change's tasks.md, and the runner itself re-checks the checklist and scripts/verify.sh after every iteration. The loop converges only on mechanical evidence — zero unchecked tasks AND green verification — never on the agent's claim of being done.

Use it for the long, mechanical middle of a change whose tasks are already well-decomposed. Do not use it for tasks that need judgment calls or design decisions: those belong in an interactive session. The phases around the loop stay human-gated — it never proposes, syncs, archives, or reviews.

Preconditions

Both must hold before starting; stop and fix if either fails:

1. An active change with a tasks.md exists under openspec/changes/<name>/ (created by openspec-propose). If several changes are active, you must name one.
2. scripts/verify.sh exists and is executable (installed by spec-as-source-setup). The loop is meaningless without its gate.

Step 1 — Install the runner (first use only)

Copy this skill's two templates into the project and make the runner executable:

mkdir -p scripts/ralph
cp <skill-dir>/templates/loop.sh scripts/ralph/loop.sh
cp <skill-dir>/templates/LOOP_PROMPT.md scripts/ralph/LOOP_PROMPT.md
cp <skill-dir>/templates/LOOP_FIX_PROMPT.md scripts/ralph/LOOP_FIX_PROMPT.md
chmod +x scripts/ralph/loop.sh

Verify the executable bit stuck (ls -l scripts/ralph/) — file-write tools do not set it. If scripts/ralph/ already exists, the runner is installed; do not overwrite local adaptations without asking.

Step 2 — Configure the run

Everything is an environment variable; nothing needs editing in the script:

Verification-repair mode: a red scripts/verify.sh is never walked past. From the next iteration the runner swaps in LOOP_FIX_PROMPT.md — fix the code until it satisfies the spec, never touching specs or tasks.md — with the verification output appended, and returns to task mode only when verification is green again. Raise MAX_FIX_ATTEMPTS if you want the loop to be more stubborn before giving the problem back to you.

Permissions trade-off (decide explicitly): the runner never adds permission-bypass flags to AGENT_CMD. A default headless claude -p will stall on permission prompts, so you must choose your risk level yourself — e.g. AGENT_CMD="claude -p --permission-mode acceptEdits" on a trusted branch, or a fully sandboxed/containerized run for anything stronger. Never put a bypass flag you would not defend in a review.

First run advice: start small — MAX_ITERATIONS=3 — inspect the logs and commits, then raise the cap once you trust the prompt discipline on this project.

Step 3 — Run

From the project root, on a dedicated branch (one commit per completed task will accumulate):

git checkout -b loop/<change-name>
MAX_ITERATIONS=3 bash scripts/ralph/loop.sh <change-name>

Per-iteration logs land in scripts/ralph/logs/ (iter-N-agent.log, iter-N-verify.log).

Aborting and recovering

• Manual stop: touch scripts/ralph/STOP — the loop aborts before the next iteration. Remove the file to allow a new run.
• Cap or failure abort (exit 3, 4, or 5 — iteration cap, no-progress, or repair attempts exhausted): read the last iter-N-*.log files; the usual causes are an under-specified task (fix: split or clarify it in tasks.md), a permission stall (fix: revisit AGENT_CMD), or a genuinely red verification (fix interactively, then re-run — completed tasks stay checked, so the loop resumes where it left off).
• Every completed task is one commit: git log is the audit trail, and a bad iteration is one git revert away.

Scope boundaries

The loop automates the derived artifact, never the source. It must not run — and its prompt forbids the in-loop agent from running — openspec-propose, spec-writer, openspec-sync-specs, openspec-archive-change, or work-review. When the loop reports success, the change is implemented, not done: run spec-verify and work-review yourself, then archive.