ralph-init - RALPH Loop Init

The re-regurgitated version. A bare bones RALPH loop for autonomous AI-driven development.

Original Sources

This project is based on the RALPH methodology. Credit where it's due:

• RALPH Playbook by Clayton Farr
• RALPH Diagram
• Geoffrey Huntley's RALPH writeup by Geoffrey Huntley

Quick Start

npx ralph-init

That's it. Run it inside any project directory and it scaffolds the RALPH loop files. Then write specs and start looping.

What Is This?

RALPH is a method where Claude works in a loop, completing one task at a time with a fresh brain each round. Think of it like a very diligent assistant who:

1. Reads the plan
2. Picks the most important task
3. Does it
4. Updates the plan
5. Forgets everything and starts fresh (this keeps it sharp)
6. Repeats

Files

ralph-init/
  loop.sh                  The engine - runs the loop
  PROMPT_plan.md           Instructions for "figure out what to do" mode
  PROMPT_build.md          Instructions for "do the work" mode
  AGENTS.md                Operational notes (starts empty, grows over time)
  IMPLEMENTATION_PLAN.md   The task list (generated by planning mode)
  specs/                   YOUR requirements go here (one file per topic)

Three Phases, Two Prompts, One Loop

Think of it like building with LEGO. You have three jobs: decide what to build, make a plan, then build it one brick at a time. There are two instruction sheets (prompts) and one machine (the loop) that does the building over and over until it's done.

Phase 1: Define Requirements

This is the "what do we want?" phase. You have a conversation with Claude to figure out what you're building. Together you create spec files — one per topic, saved in specs/. NO CODE IS TO BE WRITTEN IS THIS PHASE!

You can talk through your ideas, break them into pieces, and let Claude help write the specs. One topic per file. If you can't describe a spec in one sentence without using "and", split it into two specs.

Phase 2: Plan (the loop in planning mode)

./loop.sh plan

The loop runs using the planning prompt. Claude reads your specs, compares them against any existing code (gap analysis), and produces a prioritized task list in IMPLEMENTATION_PLAN.md. No code is written — planning mode only plans.

Review the plan. If it's wrong, just run planning again — plans are cheap and get refined through multiple passes.

Phase 3: Build (the loop in building mode)

./loop.sh build       # runs until you stop it (Ctrl+C)
./loop.sh build 5     # runs max 5 iterations then stops

The same loop now runs using the building prompt. Each iteration:

1. Orient — study the requirements and existing code
2. Read plan — review IMPLEMENTATION_PLAN.md
3. Select — pick the highest-priority task
4. Investigate — search relevant source files (no guessing)
5. Implement — make the changes
6. Validate — run tests (backpressure — must pass before moving on)
7. Update artifacts — mark the task done, update AGENTS.md
8. Commit — save changes with a descriptive message
9. Clear context — wipe the slate and start fresh

One task per loop. Fresh brain every time. This is what keeps Claude sharp.

Watch the first few loops. If Claude does something weird, add a note to AGENTS.md so it learns for next time. Human guidance happens outside the loop, not within iterations.

Key Ideas

• One loop, two modes — the same loop runs planning or building depending on the prompt
• Specs = what you want (you help create these with Claude)
• Plan = what to do (Claude generates this from specs via gap analysis)
• AGENTS.md = how to work in this project (starts empty, grows as Claude learns)
• One task per loop = keeps Claude sharp and focused
• Plans are disposable = if the plan goes wrong, just re-run planning