ralph-loop

name	ralph-loop
description	Single-agent autonomous iteration loop: PRD-driven, self-verifying, with configurable iteration limits and completion criteria.

Ralph Loop (Single-Agent Autonomous Loop)

A single agent runs in a loop until the task is complete. Each iteration reads a plan, picks the next incomplete item, implements it, runs tests, and commits if passing.

When to Use Ralph Loop vs Team Workflow

Factor	Ralph Loop	Team Workflow
Task scope	Single-domain, well-defined	Multi-domain, cross-cutting
Completion criteria	Verifiable by tests	Requires human judgment
Codebase familiarity	Greenfield or well-understood	Unfamiliar or complex
Design decisions needed	Few or none (plan is locked)	Many, iterative
Parallelism benefit	Low (sequential work)	High (independent domains)
Test suite	Exists and reliable	Missing or incomplete

Use Ralph Loop when:

• The task has clear, testable completion criteria
• A plan is already approved and doesn't need human decisions mid-flight
• Work is sequential (each step depends on the previous)
• You expect 3+ iterations to reach completion

Use Team Workflow when:

• Multiple independent domains can be worked in parallel
• The task requires human design decisions during implementation
• There's no automated test suite to verify progress
• The work spans unrelated parts of the codebase

How It Works

1. PRD file — A structured plan with user stories, each marked pass/fail
2. Progress file — Append-only log of what was done, what was learned
3. Loop — Each iteration: read PRD → pick next failing story → implement → test → commit if passing → update progress → repeat
4. Stop condition — All stories pass, or max iterations reached

Core Pattern

while true; do cat PROMPT.md | claude -p; done

Or use the official ralph-wiggum plugin which implements this via a Stop hook with safety guards.

PRD Format

{
  "stories": [
    { "id": "1", "description": "Set up project structure", "passes": true },
    { "id": "2", "description": "Implement data model", "passes": false },
    { "id": "3", "description": "Add API endpoints", "passes": false }
  ]
}

Each iteration picks the first story where passes: false, implements it, runs tests, and flips to true if tests pass.

PRD Source

When specs/<id>/spec.md exists for the feature being built, use it as the PRD input:

1. Read specs/<id>/spec.md to extract user stories and requirements.
2. Convert each user story (US1, US2, ...) into a PRD story entry with passes: false.
3. Map functional requirements (FR-xxx) to acceptance checks within each story.

If no spec.md exists (e.g., spec_mode: none), use the manually provided PRD format above.

Progress File

Append-only. Each entry records what happened in one iteration:

## Iteration 3 — Story 2: Implement data model
- Created src/models/user.ts with User and Profile entities
- Added Prisma schema migration
- Tests: 12 passed, 0 failed
- Committed: abc1234
- Learned: Prisma requires explicit relation fields on both sides

The "Learned" line is critical — it prevents the agent from repeating mistakes in future iterations.

Safety Guards

• Max iterations — Always set a limit (default: 10). Prevents runaway loops.
• Stuck detection — If the same story fails 3 iterations in a row, stop and ask for help.
• Commit gate — Only commit when tests pass. Never commit broken code.
• Progress check — If progress file hasn't changed in 2 iterations, the agent is stuck.

Hybrid Mode: Ralph Loop Inside Team Workflow

During Phase 2 (Build), the Team Lead can delegate a task to a sub-agent running in Ralph Loop mode. This works well for:

• Implementing a feature with incremental test-driven development
• Fixing a batch of related test failures
• Migrating code one module at a time

The Team Lead sets the PRD and iteration limit, the sub-agent loops until done or stuck, then returns results to the lead for integration.

Model & Effort

Mode	Model	Effort	Delegation
Ralph Loop (standalone)	Fast (Sonnet)	Medium	None — single agent loops
Ralph Loop (inside Build)	Fast (Sonnet)	Medium	Sub-agent runs the loop