Five Files, One Loop

How it works

Ralph Loop, step by step.

1. 01
   Inner Loop

   Picking the next story

   Every iteration starts the same way: the agent reads prd.json, finds the highest-priority story where passes is false and all dependencies have passes: true. No human intervention. No ticket assignment. The PRD is the queue.

   If a story has dependsOn, the agent checks those first. Dependencies naturally sequence work: build the component before integrating it. The agent handles the ordering.

   Priority: highest first / Dependencies: auto-resolved

2. 02
   Inner Loop

   Branching for isolation

   Each story gets its own git branch. The agent checks out from the working branch, creates story/[ID], and works in isolation. If the story fails, the working branch is untouched. If it passes, it merges cleanly.

   This is how you run multiple loops in parallel. Each loop has its own directory, its own PRD, its own progress file. Two agents on the same repo, different branches. The only constraint is git conflicts if they touch the same files.

   Branch: story/[ID] from working branch

3. 03
   Three Modes

   Doing the actual work

   Three modes, one per loop. Code mode: reads and writes code, runs builds, commits. Infrastructure mode: server setup, deployment scripts, cron jobs, SSH into remote servers. Research mode: read-only analysis, codebase audits, documentation.

   The story description is the work instruction. Be specific about what to do, not vague about what to achieve. The agent reads it literally and executes. Vague instructions produce vague results.

   Code / Infrastructure / Research (one per loop)

4. 04
   Quality Gates

   Verifying its own work

   Before any merge, the agent runs build gates. TypeScript must compile. Tests must pass. Git diff must be under 1000 lines. The agent self-reviews the diff for hardcoded values, missing types, accessibility issues.

   If a gate fails, the agent reads the error, fixes it, and retries. Up to 3 attempts. If still failing: document the blocker in progress.txt, skip the story, move to the next one. Don't spin.

   Buildpnpm turbo build must pass

   TypesNo TypeScript errors

   Scopegit diff < 1000 lines

   ReviewNo hardcoded values, no TODOs

   3 retries max / blocker → skip → next

5. 05
   Phase Gates

   Merging and phase boundaries

   Story passes: merge story/[ID] into the working branch, delete the story branch, update prd.json to passes: true. The loop continues with the next story.

   Phase gates are checkpoints between groups of stories. When all stories in a phase pass, the agent runs a full verification before crossing into the next phase. Use these for critical boundaries: all components built before integration starts.

   Phase gate: all stories pass → full verify → next phase

6. 06
   Inner Loop

   Logging everything

   Every story appends to progress.txt: what was done, which files changed, build results, key decisions. The next iteration reads this to understand context. The agent improves by reading its own past output.

   The optional monitor.sh watches progress.txt and triggers voice alerts when stories complete or fail. Or just tail -f progress.txt. The progress file IS the project status.

   progress.txt = project memory / monitor.sh = voice alerts

7. 07

   The agent is the system. The files are the interface.

   Five files. CLAUDE.md (brain), prd.json (work queue), progress.txt (memory), ralph.sh (runner), monitor.sh (eyes). Everything the agent needs to work autonomously is in plain text files. No platform, no dashboard, no vendor lock-in.

   Fork the repo. Write your stories. Run ralph.sh. Come back to merged branches.