Ralph Loop Runner

Ralph Loop Runner

Overview

The Ralph Loop is an autonomous execution protocol that drives an implementation plan from start to finish. Each iteration implements one increment, validates it against its test gate, commits the change, and advances to the next increment.

The loop follows the principle: Perceive → Implement → Validate → Commit → Repeat.

A fresh agent instance handles each iteration, ensuring clean context and preventing drift. The loop terminates when all increments reach **Status:** done.

Prerequisites

Before starting the Ralph Loop:

1. PRD exists in docs/product-specs/ with status fields on user stories.
2. Execution plan exists in docs/exec-plans/active/ with **Status:** pending on every increment.
3. Peer review recommended — run spec-peer-reviewer on both documents first.
4. Test infrastructure works — verify the project's test commands run successfully.

Workspace Setup Protocol

Before the first iteration, prepare the workspace:

1. Create workspace directory: docs/exec-plans/active/NNNN_feature-name/
2. Move artifacts into workspace:
   • Copy PRD from docs/product-specs/NNNN_prd_feature-name.md into the workspace
   • Move exec plan from docs/exec-plans/active/NNNN_exec_feature-name.md into the workspace
3. Create progress log: docs/exec-plans/active/NNNN_feature-name/progress.txt
4. Create feature branch: git checkout -b ralph/NNNN-feature-name

Workspace structure after setup:

docs/exec-plans/active/NNNN_feature-name/
  NNNN_prd_feature-name.md      # Copy of PRD
  NNNN_exec_feature-name.md     # Execution plan (source of truth)
  progress.txt                  # Iteration log

Iteration Protocol

Each iteration follows this exact sequence:

1. Read workspace: Load the exec plan and find the next **Status:** pending increment.
2. Set status: Change that increment's status from pending to in-progress. Update **Current Increment:** in the plan header.
3. Implement: Execute the increment's scope items. Follow the primary files list.
4. Run test gate: Execute every command listed in the increment's test gate section.
5. Pottery wheel: If any test gate fails, fix the issue and re-run. Maximum 3 retries per increment.
6. Mark done: Change the increment's status from in-progress to done.
7. Update PRD: Check off any acceptance criteria (- [ ] → - [x]) satisfied by this increment.
8. Commit: Stage and commit with the convention below.
9. Log progress: Append an entry to progress.txt.
10. Exit or continue: If more pending increments remain and running interactively, continue to step 1. If running via ralph.sh, exit with RALPH_COMPLETE signal so the script can spawn a fresh agent.

Marking Convention

Status values for increments:

• **Status:** pending — not yet started
• **Status:** in-progress — currently being implemented
• **Status:** done — implemented and test gate passed

Status values for milestones (in the Milestone Chunks table):

• pending — no increments in this milestone are done
• in-progress — at least one increment is done, others remain
• done — all increments in this milestone are done

Overall plan status:

• **Overall Status:** pending — no work started
• **Overall Status:** in-progress — at least one increment done
• **Overall Status:** done — all increments done

PRD user story status:

• **Status:** pending — not started
• **Status:** in-progress — some acceptance criteria checked
• **Status:** done — all acceptance criteria checked

Progress Log Format

Each entry in progress.txt follows this format:

## Iteration N
- Increment: XX — [Title]
- Status: done | blocked
- Files changed: [list]
- Test gate: passed | failed (retry M)
- Learnings: [any notable observations]
- Commit: [hash]
- Timestamp: [ISO 8601]

Commit Convention

Use conventional commits with the plan ID as scope:

feat|fix|refactor(NNNN): increment XX — [title]

Examples:

• feat(0001): increment 01 — create database schema
• fix(0001): increment 03 — fix validation edge case
• refactor(0001): increment 05 — extract shared utilities

Completion Detection

The loop is complete when:

1. No increments have **Status:** pending or **Status:** in-progress in the exec plan.
2. All milestone statuses in the table are done.
3. **Overall Status:** is set to done.

Archival Protocol

When all increments are done:

1. Move PRD: Copy from workspace back to docs/product-specs/ (overwrite with updated checkboxes). Set PRD status to complete.
2. Move exec plan: Move from workspace to docs/exec-plans/completed/.
3. Delete progress log: Remove progress.txt.
4. Remove workspace: Delete the empty NNNN_feature-name/ directory.
5. Optional: Invoke git-pr-creator to open a pull request for the feature branch.

Error Recovery

Blocked increment

If an increment cannot be completed after 3 pottery-wheel retries:

1. Set its status to **Status:** blocked.
2. Log the blocker in progress.txt with details.
3. Stop the loop — do not skip increments (they may have dependencies).
4. Notify the user with the blocker details.

Crash recovery

If the agent or script crashes mid-iteration:

1. Check git status and git log to determine what was committed.
2. Read progress.txt to find the last completed iteration.
3. Find the first **Status:** pending or **Status:** in-progress increment.
4. If an increment is in-progress but not committed, reset it to pending and restart.

Max retries

• Per-increment pottery wheel: 3 attempts maximum.
• Per-loop max iterations: configurable via ralph.sh --max-iterations (default: 50).