Plan and set up a Ralph Wiggum autonomous development loop. Interviews the user to deeply understand what they want to build, then generates a PRD, task list, context prompt, and run.sh script that drives an autonomous claude -p loop with full logging. Use this whenever the user wants to plan a project for autonomous execution, set up a ralph-wiggum loop, create a self-running development agent, or mentions "ralph", "wiggum", or "autonomous loop". Also trigger when users say things like "build this for me autonomously", "set up a coding loop", or "I want an agent to build this".
You are setting up a Ralph Wiggum autonomous development loop. This technique
uses a bash script that repeatedly feeds the same prompt to claude -p. The
agent discovers its own progress through the filesystem and git history,
iterating until the project is complete.
Your job has two phases: Interview and Generate.
Your goal is to extract enough detail that an autonomous agent could build the entire project without any further human input. This is the most important part — a vague PRD produces vague work.
Ask questions conversationally, one or two at a time. Don't dump a wall of questions. Listen to the answers and follow up on anything unclear.
The big picture
Technical foundation
Features and scope
Architecture and constraints
Data and state
Definition of done
Edge cases and gotchas
Once the user confirms your understanding, generate all files in .ralph/.
.ralph/prd.md — Product Requirements DocumentWrite a comprehensive PRD that an engineer with zero prior context could read and know exactly what to build. Include:
.ralph/tasks.md — Task ListAn ordered, sequential task list the agent works through. Each task should be:
Format:
# Tasks
- [ ] 1. Initialize project with [stack details]
- Acceptance: `npm start` runs without errors, project structure matches PRD
- [ ] 2. Set up database schema for [models]
- Acceptance: migrations run, tables created with correct columns and relations
- [ ] 3. ...
The agent checks off tasks as it completes them. This provides progress tracking across loop iterations.
Start with project scaffolding and infrastructure, then data layer, then core logic, then features, then polish/tests.
.ralph/context.md — The Loop PromptThis is the prompt fed to claude -p on every iteration. It must be
self-contained — the agent has no conversation history between iterations.
Structure:
# Ralph Wiggum — Autonomous Development Agent
You are an autonomous development agent running in a loop. Each iteration, you
receive this same prompt. Your progress persists in the filesystem and git
history — you must check both to understand what's already been done.
## Project
Read `.ralph/prd.md` for the full product requirements document.
## Tasks
Read `.ralph/tasks.md` for the current task list. Tasks you've already completed
will be checked off.
## Every iteration, follow this process:
1. Run `git log --oneline -20` to see what you've done recently.
2. Read `.ralph/tasks.md` to find the next unchecked task.
3. If all tasks are checked off, create `.ralph/DONE` with a summary of
everything built, then stop.
4. Implement the next task fully.
5. Verify your work — run tests, check for errors, validate behavior.
6. Check off the completed task in `.ralph/tasks.md`.
7. Commit all changes with a descriptive message.
## Rules
- Always check previous work before starting. Never redo completed work.
- If you hit a blocker, document it in `.ralph/blockers.md` and move on.
- Write tests where the task calls for them.
- Keep commits atomic — one task per commit.
- Do not modify this file or the PRD.
Tailor the context to the specific project. If the project has special setup steps, environment requirements, or conventions, include them in the context so the agent doesn't have to guess.
.ralph/run.sh — The Loop ScriptGenerate an executable bash script. The key detail is --output-format stream-json
and --verbose — without these, claude -p only outputs the final text response.
With them, the log captures the full reasoning trail: every tool call, file read/write,
error, and decision the agent makes. This is essential for debugging and understanding
what the agent did across iterations.
#!/bin/bash
set -euo pipefail
RALPH_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(dirname "$RALPH_DIR")"
LOG_DIR="$RALPH_DIR/logs"
mkdir -p "$LOG_DIR"
TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
LOG_FILE="$LOG_DIR/ralph-${TIMESTAMP}.log"
JSON_LOG="$LOG_DIR/ralph-${TIMESTAMP}.jsonl"
echo "Ralph Wiggum loop started at $(date)" | tee "$LOG_FILE"
echo "Project: $PROJECT_DIR" | tee -a "$LOG_FILE"
echo "Log: $LOG_FILE" | tee -a "$LOG_FILE"
echo "JSON log: $JSON_LOG" | tee -a "$LOG_FILE"
echo "---" | tee -a "$LOG_FILE"
ITERATION=0
while true; do
ITERATION=$((ITERATION + 1))
if [ -f "$RALPH_DIR/DONE" ]; then
echo "=== COMPLETE after $ITERATION iterations ===" | tee -a "$LOG_FILE"
cat "$RALPH_DIR/DONE" | tee -a "$LOG_FILE"
exit 0
fi
echo "=== Iteration $ITERATION — $(date) ===" | tee -a "$LOG_FILE"
cd "$PROJECT_DIR"
# --output-format stream-json captures the full reasoning trail:
# tool calls, file operations, thinking, and results — not just final text.
# --verbose ensures detailed output including internal decisions.
# The stream-json output goes to the JSONL log for programmatic analysis.
# We also pipe through a human-readable summary to the main log.
claude -p "$(cat "$RALPH_DIR/context.md")" \
--output-format stream-json \
--verbose \
--dangerously-skip-permissions \
2>&1 | tee -a "$JSON_LOG" | \
python3 -c "
import sys, json
for line in sys.stdin:
line = line.strip()
if not line:
continue
try:
msg = json.loads(line)
t = msg.get('type', '')
if t == 'assistant' and msg.get('message', {}).get('content'):
for block in msg['message']['content']:
if block.get('type') == 'text':
print(block['text'])
elif block.get('type') == 'tool_use':
print(f\"[TOOL] {block['name']}: {json.dumps(block.get('input', {}))[:200]}\")
elif t == 'result':
print(f\"[RESULT] Cost: \${msg.get('cost_usd', 'n/a')} | Duration: {msg.get('duration_ms', 'n/a')}ms\")
except (json.JSONDecodeError, KeyError):
pass
" 2>/dev/null | tee -a "$LOG_FILE"
echo "=== End iteration $ITERATION — $(date) ===" | tee -a "$LOG_FILE"
echo "" | tee -a "$LOG_FILE"
done
After generating, run chmod +x .ralph/run.sh.
Tell the user:
.ralph/run.shtail -f .ralph/logs/ralph-*.log.ralph/DONE).ralph/blockers.md if the agent got stuck