Deploying the Ralph Wiggum Technique: A Step‑by‑Step Tutorial

The Ralph Wiggum technique, pioneered by Geoff Huntley, turns a large language model into a fully autonomous software developer. Rather than write code line‑by‑line, you hand the LLM a clear set of prompts, a spec base, and an outer loop that automatically commits and pushes work. Below is a complete walkthrough that you can apply to any GitHub repo—ideally an open‑source project that wants to ship features faster and with fewer human errors.

1. What Is Ralph Wiggum?

• Goal: Reduce software development cost to less than a fast‑food worker’s wage.
• Core idea: A looped prompt that alternates between planning and building stages. Each turn reads the existing codebase, reads the spec, decides on the next bullet‑point task, implements it, runs tests, and commits.
• Why it works: The loop leverages the LLM’s reasoning (Opus or Sonnet) for high‑level tasks and cheap local subagents for file and test operations. Back‑pressure from tests ensures only valid changes are committed.

2. Project Structure

/project-root/
├── loop.sh                # Bash loop that drives Claude
├── PROMPT_build.md        # Build‑mode prompt
├── PROMPT_plan.md         # Planning‑mode prompt
├── AGENTS.md              # Operational guide (build, test, lint)
├── IMPLEMENTATION_PLAN.md# Prioritized task list (generated by Ralph)
├── specs/                 # One file per JTBD topic (requirements)
└── src/                   # Source code that will change

Tip: Keep AGENTS.md short (≈60 lines). It should contain only commands that Ralph needs to validate work.

3. The Three‑Phase Workflow

How the Loop Works

1. Outer loop (loop.sh) feeds the prompt file to Claude.
2. The prompt tells Claude to study PROMPT.md, AGENTS.md, specs/*, and src/*.
3. Depending on the mode (plan/build), the prompt instructs Ralph to:
4. Plan: Produce a gap analysis and write a bullet‑point plan.
5. Build: Pick the next task, implement, test, commit.
6. When the LLM finishes the task, the outer loop restarts with a fresh context.

Because the only shared state is the IMPLEMENTATION_PLAN.md file on disk, the loop requires no elaborate orchestration.

4. The Prompt Templates

4.1 PROMPT_plan.md

0a. Study `specs/*` with up to 250 parallel Sonnet subagents.
0b. Study @IMPLEMENTATION_PLAN.md (if present).
0c. Study `src/lib/*` with up to 250 parallel Sonnet subagents.

1. Do a gap analysis between specs and code.
   Use an Opus subagent to prioritize tasks and create/update @IMPLEMENTATION_PLAN.md.
   **Do NOT implement anything**; only plan.

4.2 PROMPT_build.md

0a. Study `specs/*` (up to 500 Sonnet subagents).
0b. Study @IMPLEMENTATION_PLAN.md.

1. Choose the most important unfinished task from the plan.
2. Search the code base to confirm it is missing.
3. Implement the task, commit, and push.
4. Run all tests defined in AGENTS.md as back‑pressure.
5. Update @IMPLEMENTATION_PLAN.md to mark the task complete.

Note: The 99999 guardrails in PROMPT_build.md enforce best practices like committing with informative messages and updating tags.

5. The Bash Loop (loop.sh)

#!/bin/bash
# Usage examples:
#   ./loop.sh          # Build mode, unlimited iterations
#   ./loop.sh 20       # Build mode, stop after 20 tasks
#   ./loop.sh plan     # Full planning mode, unlimited
#   ./loop.sh plan 5   # Planning, max 5 iterations

MODE=${1:-build}
PROMPT_FILE=()
MAX_ITER=${2:-0}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE=\"PROMPT_plan.md\"
elif [[ "$MODE" =~ ^[0-9]+$ ]]; then
  PROMPT_FILE=\"PROMPT_build.md\"
  MAX_ITER=$MODE
else
  PROMPT_FILE=\"PROMPT_build.md\"
fi

ITERATION=0
while true; do
  [[ $MAX_ITER -gt 0 && $ITERATION -ge $MAX_ITER ]] && exit 0
  cat "$PROMPT_FILE" | claude -p \
    --dangerously-skip-permissions \
    --output-format=stream-json \
    --model opus \
    --verbose
  git push
  ITERATION=$((ITERATION+1))
  echo "--- Loop $ITERATION Complete ---"
done

What it does - Starts a headless Claude session. - Auto‑approves tool calls (--dangerously-skip-permissions). - Streams JSON for easy monitoring. - Pushes every iteration so you can roll back with git reset --hard if something goes wrong.

6. Back‑Pressure and Testing

The AGENTS.md file lists the exact command to run tests, lint, and type‑check. For example:

## Validation
- Run tests: `npm test`
- Lint: `npm run lint`
- Type‑check: `npm run tsc --noEmit`

When Ralph implements a task it will run these automatically. If any fail, the loop restarts and Ralph re‑enters the build phase until tests pass. This ensures every commit is production‑ready.

7. Enhancements & Customization

Plan‑work mode – When you need a focused sprint, the loop script now supports plan-work "<description>" to create a scoped IMPLEMENTATION_PLAN.md on a new branch.

Acceptance‑driven back‑pressure – In future versions you can specify that each plan task must include an associated test based on the spec’s acceptance criteria.

Non‑deterministic back‑pressure – Use the llm-review fixture to let the LLM judge tone, visual hierarchy, or brand consistency.

Feel free to tweak the prompts or add guardrails, but remember: keep the plan separate from the build. Ralph is best when it decides which task to do next, not which subset of tasks.

8. Putting It All Together

1. Fork the repo and clone.
2. Add your project files to src/ and create one specs/*.md per JTBD topic.
3. Run ./loop.sh plan to generate an initial plan.
4. Start building: ./loop.sh.
5. Observe the log; once the plan is empty, the project is built.
6. Open a PR, merge, and repeat for the next feature.

This workflow turns an LLM into a developer‑assistant that handles the grunt work—looping over tasks, testing on the fly, and committing clean code, all while staying transparent and version‑controlled.

9. Key Takeaways

• Loop is the heart: One file (IMPLEMENTATION_PLAN.md) ties everything together.
• Separate Planning vs. Building: Both use the same prompt infrastructure but differ in action and output.
• Back‑pressure is non‑optional: Tests, lint, and type‑check enforce quality.
• You can scale: Use work‑scoped planning for large features, or keep the entire repo in one plan for small projects.
• The LLM is only as good as your prompts: Keep prompts concise, use study not read, and guard with high‑level instructions.

With this guide, you now have a complete blueprint to launch the Ralph Wiggum technique in any project—turning an AI into an autonomous developer working at a fraction of the cost.