ralph-loop

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 }
  ]
}