Getting Started with Ralph Wiggum Part 2: The Three-Phase Methodology

specs/
├── authentication.md    # Login, JWT, sessions
├── api-design.md        # Endpoints, request/response formats
├── database.md          # Schema, relationships
└── testing.md           # Coverage requirements, test strategy

You: "I want to build a REST API for managing todos"

Claude: "Let's break this down. What operations do you need?"

You: "CRUD operations - create, read, update, delete todos"

Claude: "Got it. What about authentication? User accounts?"

You: "Yes, users should only see their own todos"

Claude: "Makes sense. How should we handle..."

/ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"

./loop.sh plan

# PLANNING MODE

You are in PLANNING mode. Your job is analysis, not implementation.

## Your Task
1. Read all files in specs/
2. Review the existing codebase in src/
3. Perform gap analysis between requirements and current implementation
4. Create/update IMPLEMENTATION_PLAN.md with prioritized tasks

## Task Structure
Each task in the plan should include:
- Unique ID (e.g., TASK-001, TASK-002)
- Priority level (high/medium/low)
- Clear description (what needs to be built)
- Acceptance criteria (how you'll know it's done)
- Required tests (specific test files or patterns)
- Dependencies (tasks that must complete first)

## File Organization
Organize tasks by priority:
- High Priority: Critical path items
- Medium Priority: Important but not blocking
- Low Priority: Nice-to-haves

## Critical Rules
- DO NOT write any code
- DO NOT make any commits
- DO NOT implement features
- DO NOT run tests or builds
- ONLY analyze and plan

When complete, output "PLAN COMPLETE"

# Implementation Plan

## High Priority

### TASK-001: User Authentication
- **Status**: pending
- **Description**: Implement JWT-based auth with login/logout
- **Acceptance Criteria**:
  - User can register with email/password
  - User can login and receive JWT token
  - Protected routes require valid JWT
- **Tests**: `auth.test.ts`
- **Dependencies**: none

### TASK-002: Todo CRUD Endpoints
- **Status**: pending
- **Description**: Create POST, GET, PUT, DELETE endpoints for todos
- **Acceptance Criteria**:
  - POST /api/todos creates a todo
  - GET /api/todos returns user's todos
  - PUT /api/todos/:id updates a todo
  - DELETE /api/todos/:id deletes a todo
- **Tests**: `todos.test.ts`
- **Dependencies**: TASK-001

## Medium Priority

### TASK-003: Input Validation
- **Status**: pending
- **Description**: Add Zod validation for all endpoints
...

/ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"

./loop.sh              # Default mode is building
./loop.sh build 100    # With custom iteration limit

# BUILDING MODE

You are in BUILDING mode. Your job is implementation with quality gates.

## Your Task Loop
For each iteration:
1. Read IMPLEMENTATION_PLAN.md and progress.txt
2. Pick the SINGLE highest priority task with status: pending
3. Study existing code before implementing
4. Implement the feature completely
5. Write comprehensive tests
6. Run all tests and type checks: npm test && npm run type-check
7. If tests fail, fix them immediately—DO NOT proceed
8. When all tests pass:
   - Commit with descriptive message format: "feat(area): description"
   - Update task status to completed in IMPLEMENTATION_PLAN.md
   - Append learnings to progress.txt with timestamp

## Critical Rules
- Work on ONE task at a time—no exceptions
- NEVER commit failing tests
- NEVER skip test execution
- Tests are your backpressure—respect them
- Each commit must be atomic and working
- Don't add features not in the plan
- Don't refactor unrelated code

## Backpressure Enforcement
Tests MUST pass before committing:
```bash
npm test && npm run type-check && npm run lint
```

If any check fails, fix it in the same iteration.

## Progress Tracking
After completing each task, append to progress.txt:
```
[YYYY-MM-DD HH:MM] Completed TASK-XXX: Task Title
- What was implemented
- Key decisions made
- Challenges encountered
- Learnings for next tasks
```

When all tasks show status: completed, output "ALL TASKS COMPLETE"

#!/bin/bash
# loop.sh - Fresh context per iteration

MODE=${1:-build}  # Default to build mode
MAX_ITERATIONS=${2:-50}

if [[ "$MODE" == "plan" ]]; then
  PROMPT_FILE="PROMPT_plan.md"
  COMPLETION="PLAN COMPLETE"
  MAX_ITERATIONS=${2:-5}  # Planning needs fewer iterations
else
  PROMPT_FILE="PROMPT_build.md"
  COMPLETION="ALL TASKS COMPLETE"
fi

echo "Running in $MODE mode with max $MAX_ITERATIONS iterations"
echo "Using prompt: $PROMPT_FILE"
echo "Completion signal: $COMPLETION"
echo "=========================================="

for ((i=1; i<=$MAX_ITERATIONS; i++)); do
  echo "Iteration $i / $MAX_ITERATIONS"
  echo "--------------------------------"

  # The -p flag runs Claude in one-shot mode (see Mastery Part 1: https://jocv.dev/blog/claude-code-mastery-01-getting-started#one-shot-mode-quick-questions)
  result=$(claude -p "$(cat $PROMPT_FILE)" --output-format text 2>&1) || true
  echo "$result"

  if [[ "$result" == *"$COMPLETION"* ]]; then
    echo "=========================================="
    echo "$MODE complete after $i iterations."
    exit 0
  fi

  echo "--- End of iteration $i ---"
done

echo "Reached max iterations ($MAX_ITERATIONS)"
exit 1

chmod +x loop.sh

./loop.sh plan      # Run planning mode (default 5 iterations)
./loop.sh build     # Run building mode (default 50 iterations)
./loop.sh           # Same as ./loop.sh build
./loop.sh build 30  # Building mode with 30 iterations max

# Phase 1: Define Requirements (conversational, not looped)
# Talk with Claude to create specs/*.md files
# Example: specs/authentication.md, specs/api-design.md, specs/database.md

# Phase 2: Generate Plan (run once, or when plan needs refresh)
./loop.sh plan
# Or with the plugin: /ralph-loop "$(cat PROMPT_plan.md)" --max-iterations 5 --completion-promise "PLAN COMPLETE"
# Creates IMPLEMENTATION_PLAN.md with prioritized tasks

# Phase 3: Build Autonomously (continuous loop)
./loop.sh
# Or with the plugin: /ralph-loop "$(cat PROMPT_build.md)" --max-iterations 50 --completion-promise "ALL TASKS COMPLETE"
# Implements tasks one by one, commits, loops

# When plan becomes stale (features changed, new requirements):
rm IMPLEMENTATION_PLAN.md
./loop.sh plan          # Regenerate plan
./loop.sh               # Resume building

your-project/
├── specs/
│   ├── authentication.md
│   ├── api-design.md
│   ├── database.md
│   └── testing.md
├── PROMPT_plan.md          # Planning mode prompt
├── PROMPT_build.md         # Building mode prompt
├── IMPLEMENTATION_PLAN.md  # Generated by planning, updated by building
├── progress.txt            # Append-only log of learnings
├── loop.sh                 # Bash orchestrator script
└── src/                    # Your actual code
    ├── api/
    ├── auth/
    └── tests/

In your prompt, instruct the agent to:
"After each task, APPEND (don't overwrite) your learnings to progress.txt"

[2026-01-16 14:30] Completed TASK-001: User Authentication
- Implemented JWT signing/verification using jsonwebtoken
- Added httpOnly cookie storage for tokens
- All auth tests passing (12/12)
- Learning: Cookie sameSite setting needed for cross-origin requests
- Challenge: Had to debug token expiry edge case
- Next: Tackle TASK-002 (Todo CRUD endpoints)

# Implementation Plan

## High Priority

- [ ] TASK-001: User Authentication (status: pending)
  - Tests: auth.test.ts
  - Dependencies: none

## Medium Priority

- [ ] TASK-002: Todo CRUD (status: pending)
  - Tests: todos.test.ts
  - Dependencies: TASK-001

## Completed

- [x] TASK-000: Project Setup (status: completed)
  - Completed: 2026-01-15 22:00

Read progress.txt to see what's been accomplished.
After completing each task, APPEND (never overwrite) your progress.

Each commit MUST pass all tests and type checks.
Run: npm test && npm run type-check && npm run lint
If anything fails, fix it before moving on.
NEVER commit broken code.

Pick the SINGLE highest priority task from IMPLEMENTATION_PLAN.md.
Work ONLY on that task—don't add features or refactor unrelated code.

Study the codebase first.
Don't assume something isn't implemented—verify by reading files.
Use ultrathink before making changes.