Ralph Wiggum — Autonomous Development Loop Setup

Features and scope

• Walk through each key feature in detail.
• What's MVP vs. nice-to-have? Be explicit about the boundary.
• UI/UX requirements if applicable — pages, flows, components.

Architecture and constraints

• System structure — monolith, services, serverless, etc.
• External integrations, third-party APIs, auth providers.
• Performance, scale, security requirements.
• Any hard constraints (must use X, can't use Y, needs to run on Z).

Data and state

• What data does the system manage? Models, schemas, relationships.
• Storage — database type, file storage, caching.
• Data flow — how does data move through the system?

Definition of done

• What does "finished" look like concretely?
• How will you verify it works — tests, manual check, deployment?
• Any deployment or packaging requirements?

Edge cases and gotchas

• Non-obvious decisions an autonomous agent might get wrong.
• Known pitfalls, tricky integrations, ordering dependencies.
• Anything you've tried before that didn't work.

Interview rules

• Keep asking until you're confident. If something is ambiguous, ask. If a decision could go multiple ways, ask which way.
• Don't assume — verify. Restate your understanding of complex requirements and confirm.
• Probe for depth. "A user dashboard" is not enough detail. What's on it? What actions can the user take? What data is shown?
• When you feel ready, summarize your complete understanding back to the user as a structured overview and ask them to confirm before generating.

Phase 2: Generate

Once the user confirms your understanding, generate all files in .ralph/.

1. .ralph/prd.md — Product Requirements Document

Write a comprehensive PRD that an engineer with zero prior context could read and know exactly what to build. Include:

• Overview — what this is and why it exists
• Goals — what success looks like
• Target users — who uses this and how
• Tech stack — languages, frameworks, services, with reasoning
• Architecture — how the system is structured, with component descriptions
• Feature requirements — detailed, specific, and actionable. Each feature should describe behavior, not just a name.
• Data model — entities, relationships, key fields
• Non-functional requirements — performance, security, accessibility
• Out of scope — explicitly state what this project does NOT include
• Open questions — anything that still needs resolution (ideally none)

2. .ralph/tasks.md — Task List

An ordered, sequential task list the agent works through. Each task should be:

• Atomic — one clear deliverable
• Ordered by dependency — foundations before features
• Specific — not "set up the backend" but "create Express server with /api/health endpoint"
• Verifiable — includes acceptance criteria

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.

3. .ralph/context.md — The Loop Prompt

This 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.

4. .ralph/run.sh — The Loop Script

Generate 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.

5. Wrap up

Tell the user:

• Summary of what was generated
• To start: .ralph/run.sh
• To monitor: tail -f .ralph/logs/ralph-*.log
• To stop: Ctrl+C
• Loop stops automatically when all tasks are done (agent creates .ralph/DONE)
• To review blockers: check .ralph/blockers.md if the agent got stuck