ralph-starter

A ready-to-use scaffold for the Ralph Wiggum autonomous AI development loop.

 .-"""-.
/        \
|  O    O  |
|    __    |
|   /  \   |
 \  '=='  /
  '-.  .-'     "I'm helping!"

What is this?

The Ralph Wiggum technique is an autonomous AI coding loop where Claude (or another LLM) iteratively implements features from specs — one task per iteration, fresh context each time. You write the specs, Ralph does the work.

This repo gives you the battle-tested file structure and prompts to get started immediately.

Quick Start

1. Clone and set up

git clone <this-repo> my-project
cd my-project
rm -rf .git && git init

Or open in a devcontainer — see Devcontainer below for an isolated, pre-configured environment.

2. Customize AGENTS.md

Edit AGENTS.md with your project's:

• Build and test commands
• Project layout
• Any conventions Ralph should follow

3. Write your first spec

# Delete the example
rm specs/example-spec.md

# Write your own
cat > specs/my-feature.md << 'EOF'
---
title: My Feature
status: ready
priority: high
tags: [core]
---

# My Feature

## Problem
What problem does this solve?

## Requirements
- What it must do
- How to verify it works
EOF

Update specs/todo.md to track it:

- [ ] My Feature (`specs/my-feature.md`)

4. Run the planning loop

chmod +x loop.sh
./loop.sh plan

This generates IMPLEMENTATION_PLAN.md with a prioritized task breakdown.

5. Run the build loop

./loop.sh        # Unlimited iterations
./loop.sh 5      # Max 5 iterations

Ralph picks the highest-priority task, implements it, runs tests, commits, and exits. The loop restarts with fresh context and picks the next task.

Ctrl+C to stop at any time.

File Structure

my-project/
├── loop.sh                         # The loop script
├── PROMPT_build.md                 # Build mode instructions (implement)
├── PROMPT_plan.md                  # Plan mode instructions (gap analysis)
├── AGENTS.md                       # Operational guide (how to build/test)
├── IMPLEMENTATION_PLAN.md          # Task list (generated by planning loop)
├── IMPLEMENTATION_PLAN_ARCHIVE.md  # Completed tasks (survives plan regen)
├── specs/                          # Requirement specs (immutable)
│   ├── todo.md                     # Feature tracker (only specs/ file agents update)
│   ├── my-feature.md               # Your specs go here
│   └── archive/                    # Completed specs moved here
└── src/                            # Your source code

How It Works

Three Phases

1. Define Requirements — You write specs in specs/. One file per topic. Be specific about what, not how.
2. Plan (./loop.sh plan) — Claude analyzes specs vs code, produces a prioritized task list in IMPLEMENTATION_PLAN.md.
3. Build (./loop.sh) — Claude picks a task, implements it, runs tests, commits. Loop restarts fresh.

Two Prompts

File	When	What it does
PROMPT_plan.md	./loop.sh plan	Gap analysis, task breakdown. No code changes.
PROMPT_build.md	./loop.sh	Implement one task, test, commit.

Key Principles

• One task per iteration — keeps context focused and diffs reviewable
• Fresh context every loop — no accumulated confusion
• Backpressure via tests — Ralph can't commit if tests fail
• AGENTS.md is operational memory — how to build/test, not a changelog
• Specs are immutable — you write them, Ralph reads them
• Plan is disposable — regenerate with ./loop.sh plan when stale

Archive Convention

• Specs: When a spec is fully complete, move from specs/ to specs/archive/, set status: done
• Plan tasks: Move completed tasks from IMPLEMENTATION_PLAN.md to IMPLEMENTATION_PLAN_ARCHIVE.md. Plan sections stay in the plan until all their tasks are done.

This prevents done work from being lost when the plan is regenerated.

Writing Good Specs

A spec should answer:

• What problem does this solve? (Problem section)
• What must it do? (Requirements — observable, testable)
• What could go wrong? (Edge cases)

Keep specs focused: one topic per file. If you need "and" to describe it, split it.

---
title: User Authentication
status: ready
priority: high
tags: [auth, security]
---

# User Authentication

## Problem
Users need to log in securely.

## Requirements
- Support email/password login
- Hash passwords with bcrypt
- Issue JWT tokens with 24h expiry
- Return 401 for invalid credentials

## Edge Cases
- Empty email or password
- Email not found
- Correct email, wrong password
- Expired token refresh

Tips

• Watch the first few iterations — observe where Ralph goes wrong, add guardrails to prompts
• Add utilities to your codebase — Ralph discovers patterns and follows them
• Run in a sandbox — --dangerously-skip-permissions means no safety net
• Regenerate the plan when Ralph goes in circles: ./loop.sh plan
• Keep AGENTS.md under 60 lines — it loads every iteration
• Use spec-view (pip install spec-view) — a TUI + web dashboard that gives you a live view of your specs, tasks, and progress. It parses IMPLEMENTATION_PLAN.md sections, tracks task completion, and auto-detects the archive convention. Run spec-view for the terminal dashboard or spec-view serve for the web UI.

Devcontainer

The repo includes a sandboxed devcontainer — recommended since loop.sh uses --dangerously-skip-permissions. The container has access to only this repo and a scoped GitHub token. No access to your home directory, SSH keys, or other repos.

Prerequisites

• Docker (or Colima on macOS)
• devcontainer CLI: npm install -g @devcontainers/cli

Setup

1. Copy the env template and fill in your values:

   cp .devcontainer/.env.example .devcontainer/.env

2. Edit .devcontainer/.env:

   GH_TOKEN=github_pat_...
   GIT_USER_NAME=Your Name
   GIT_USER_EMAIL=you@example.com
   

   Create a fine-grained GitHub token scoped to only this repo with Contents (read & write) permission.

3. Build and start the container:

   devcontainer up --workspace-folder .

4. First time only — login to Claude Code inside the container:

   devcontainer exec --workspace-folder . claude

   Run /login, then exit. Credentials persist in the mounted ~/.claude directory.

Running the loop

# Using run-container.sh (if present)
./run-container.sh ./loop.sh plan 5
./run-container.sh ./loop.sh

# Or directly
devcontainer exec --workspace-folder . ./loop.sh plan
devcontainer exec --workspace-folder . ./loop.sh

Customizing the container

Add your project's runtime by editing .devcontainer/devcontainer.json:

"features": {
  "ghcr.io/devcontainers/features/node:1": {},
  "ghcr.io/devcontainers/features/python:1": {},   // Python
  "ghcr.io/devcontainers/features/rust:1": {},      // Rust
  "ghcr.io/devcontainers/features/go:1": {}          // Go
}

See available features for more options.

What the container can access

Mount	Purpose
Project directory	Your repo (read-write)
~/.claude	Claude Code auth tokens
Shell history volume	Persists across rebuilds

Not accessible: home directory, SSH keys, other repos, macOS keychain. Git push is scoped to the repo(s) your GH_TOKEN allows.

Troubleshooting

• Claude says "Not logged in": Run claude interactively inside the container and do /login once
• git push fails: Check that .devcontainer/.env has a valid GH_TOKEN with repo access
• "dubious ownership" error: The post-start.sh script handles this — rebuild with devcontainer up --workspace-folder . --remove-existing-container

Safety

The loop runs with --dangerously-skip-permissions. This means Claude can execute any command without asking. The devcontainer mitigates this:

• Filesystem isolated to the project directory only
• Git push scoped via fine-grained GitHub token (single repo)
• No access to host secrets, SSH keys, or other repos
• Shell history and Claude auth are the only persistent state

Credits

Based on the Ralph Wiggum technique by Geoffrey Huntley. Playbook distilled from the ralph-playbook by Clayton Farr.