Ralph — Autonomous Task Loop Skill for Claude Code / pi

SKILL.md

name	ralph
description	Scaffold and run autonomous task loops (Ralph loops) for building or migrating projects. Use when user wants to set up autonomous coding, a build loop, a migration loop, or says "set up Ralph".
metadata	author version kaiserlich 1.0

Ralph — Autonomous Task Loops

Ralph is a pattern for autonomous, iterative project execution. One task per iteration, tests must pass, learnings compound. Named after the approach, not a person.

When to Use

• Building a new app from scratch
• Migrating an existing app to a new stack
• Any multi-task project where each task has clear acceptance criteria

The Pattern

Ralph = 3 files + 1 script:

project/
├── PLAN.md          # Architecture, decisions, target state
├── TASKS.md         # Ordered task list with acceptance criteria
├── LEARNINGS.md     # Accumulated insights (grows with each iteration)
└── ralph.sh         # The loop script

How It Works

┌─────────────────────────────────┐
│  ralph.sh starts iteration N    │
│  → launches claude session      │
├─────────────────────────────────┤
│  1. Read LEARNINGS.md           │  ← apply past insights
│  2. Find next [ ] task          │  ← from TASKS.md
│  3. Consult reference material  │  ← skills, reference repos
│  4. Execute the task            │  ← code, test, validate
│  5. Post-implementation review  │  ← verify patterns
│  6. Git commit                  │
│  7. Write learnings             │  ← what worked, gotchas
│  8. Mark task [x]               │
│  9. Exit session                │
├─────────────────────────────────┤
│  ralph.sh starts iteration N+1  │
│  → fresh context, new session   │
└─────────────────────────────────┘

Each iteration is a fresh Claude session with full context reload. This prevents context window exhaustion on large projects.

Setup Command

To scaffold Ralph for a project:

# The agent should create these files, NOT a script.
# Read the templates below and adapt to the specific project.

File Templates

PLAN.md

# Project Name

> One-line description of what this is.

## Why
- Why are we building/migrating this?

## Current State (for migrations)
- Stack, dependencies, pain points

## Target State
- Stack, patterns, deploy strategy

## Key Decisions
| Decision | Rationale |
|----------|-----------|

## Architecture
- Models, controllers, views
- Data flow diagram

## Gemfile / Dependencies Target
- What stays, what goes, what's new

TASKS.md

# Project — Tasks

> For architecture, see PLAN.md.

# Phase 1: Name

### [ ] P1-T01: Task Title
Description of what needs to happen.

**Steps:**
- Step 1
- Step 2

**Acceptance:** Concrete criteria. `bin/rails test` passes, feature X works.

---

### [ ] P1-T02: Next Task
...

## Phase 1 Completion Checklist
- [ ] All tests pass
- [ ] Feature X works end-to-end

Task design rules:

• One task = one commit (atomic)
• Acceptance criteria must be testable
• Tasks are ordered — each builds on the previous
• Each task should take 5-30 minutes of agent time
• If a task is too big, split it

LEARNINGS.md

# Project — Learnings

> Implementation insights, gotchas, discoveries.

## Format

### [Task ID] Task Name

**What worked:**
- ...

**What surprised me:**
- ...

**Gotchas:**
- ...

Why learnings matter: Each iteration reads LEARNINGS.md first. Insights from task 3 prevent mistakes in task 12. This is the compound effect — the loop gets smarter as it runs.

ralph.sh

#!/bin/bash
# Ralph autonomous task loop
# Usage: ./ralph.sh [max_iterations]

cd "$(dirname "$0")"

MAX_ITERATIONS=${1:-25}
ITERATION=0

PROMPT='<see prompt template below>'

while [ $ITERATION -lt $MAX_ITERATIONS ]; do
  ITERATION=$((ITERATION + 1))
  echo ""
  echo "=========================================="
  echo "  ITERATION $ITERATION / $MAX_ITERATIONS"
  echo "=========================================="
  echo ""

  if ! grep -q "^### \[ \]" TASKS.md; then
    echo "✅ All tasks complete!"
    exit 0
  fi

  claude --dangerously-skip-permissions -p "$PROMPT"
  sleep 2
done

echo ""
echo "⚠️  Max iterations ($MAX_ITERATIONS) reached"
echo "Run ./ralph.sh to continue"

Prompt Template

The prompt has 4 sections. Adapt each to the project:

1. Context (what are we building?)

You are building/migrating [PROJECT] — [one-line description].

2. Files to Read

## Context Files (read these first)
1. PLAN.md - Architecture and design decisions
2. TASKS.md - Task list with acceptance criteria
3. LEARNINGS.md - Accumulated insights from previous iterations

3. Reference Material (optional but powerful)

## Reference Implementations
- **[Reference project]**: ~/code/path/to/reference/
  - What to look at and why
- **[Relevant skill]**: read /path/to/SKILL.md
  - What patterns to follow

This is what makes Ralph powerful for migrations — point it at a working reference implementation and say "make it like that."

4. The Loop Steps

## Your Job
1. Read LEARNINGS.md first — apply any insights
2. Find the next incomplete task in TASKS.md (first [ ])
3. Before coding: check reference material for patterns
4. Execute ONE task completely
5. Validate against acceptance criteria
6. Run tests (must pass)
7. Post-implementation review: verify patterns match reference
8. Git commit with descriptive message (no AI references)
9. Append learnings to LEARNINGS.md
10. Mark task [x] in TASKS.md

5. Rules (guardrails)

## Rules
- ONE task per iteration
- Tests must pass before commit
- [Project-specific patterns to follow]
- [Things to NOT touch / keep unchanged]
- If stuck, write blocker to LEARNINGS.md and stop

The rules section is critical for migrations — explicitly state what to keep, what to change, and what to never touch.

Design Principles

Why one task per iteration?

• Fresh context window each time (no degradation over long sessions)
• Clean git history (one commit per task)
• Natural checkpoint — if something breaks, you know exactly which task caused it

Why LEARNINGS.md?

• Insights compound across iterations
• Task 1 discovers a gotcha → Task 15 avoids it automatically
• Creates documentation as a side effect

Why reference implementations?

• "Make it like X" is more effective than abstract patterns
• The agent can read actual files from the reference project
• Consistency across projects that share the same patterns

Why --dangerously-skip-permissions?

• The loop runs unattended — can't prompt for file access
• Only use on your own projects in controlled environments

Scaling Estimates

Project Size	Tasks	Iterations	Wall Time
Small (new app)	10-20	15-25	1-2 hours
Medium (migration)	15-30	20-35	2-4 hours
Large (rewrite)	30-50	35-55	4-8 hours

Past Projects

Project	Type	Tasks	Result
Example App	New build	21 tasks	Rails 8 + SQLite, Docker deploy
Example Migration	Migration	16 tasks	PG/Inertia → SQLite/ERB

Common Pitfalls

1. Tasks too big — If a task takes more than ~30 min, split it. The agent loses coherence on long tasks.
2. Missing acceptance criteria — Vague tasks produce vague results. "Make it work" → bad. "Tests pass, endpoint returns 200, data persists" → good.
3. No guardrails — Migrations need explicit "don't touch" rules or the agent will rewrite things that work fine.
4. No reference implementation — Abstract instructions are weaker than "look at this working code and do the same thing."
5. Forgetting LEARNINGS.md — If the agent skips writing learnings, later tasks lose the compound benefit.