Ralph Loop

Ralph Loop Creator

Create autonomous iterative loops that process a backlog of tasks with clear acceptance criteria. Named after the Ralph Wiggum pattern for spec-driven autonomous development.

Overview

A Ralph loop consists of:

• Task System - Native Claude Code task management with dependency tracking
• Prompt (prompt.md) - Instructions for each iteration
• Runner (ralph.sh) - Bash script that loops until completion
• Progress (progress.txt) - Execution log
• Knowledge (knowledge.md) - Accumulated learnings

Quick Start

To create a new Ralph loop, gather requirements then run the init script:

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py <output-dir>

Workflow

Step 1: Gather Requirements

Before creating a loop, clarify these parameters with the user using AskUserQuestion:

Loop Goal:

• What is the global objective of this loop?
• What domain/codebase does it operate on?

Task Structure:

• What kind of tasks/items will be tracked?
• What dependencies exist between tasks?
• What metadata should each task have?

Iteration Process:

• What steps should each iteration perform?
• What tools/commands are needed?
• What files should be read/written?

Acceptance Criteria:

• How to validate a task is completed?
• What checks should pass before marking done?
• Should there be automated validation (tests, builds, typechecks)?

Exit Conditions:

• When should the loop terminate? (all tasks done, specific marker, max iterations)
• What completion marker to use? Default: <promise>COMPLETE</promise>

Step 2: Select or Create Template

Available templates in ~/.claude/skills/ralph-loop/templates/:

Step 3: Generate Loop Files

After gathering requirements, generate the loop structure:

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py \
  --template migration \
  --output ./my-loop \
  --goal "Migrate React components from styled-components to Tailwind"

Or interactively:

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py ./my-loop

Step 4: Create Tasks Using Task System

After generating the loop, create tasks using the native Task tools:

TaskCreate:
  subject: "Migrate Button component"
  description: "Convert Button from styled-components to Tailwind CSS classes"
  activeForm: "Migrating Button component"

Set up dependencies between tasks:

TaskUpdate:
  taskId: "2"
  addBlockedBy: ["1"]  # Task 2 waits for Task 1

Step 5: Run the Loop

cd <output-dir>
./ralph.sh [max-iterations]

Default max iterations: 50

File Structure

<output-dir>/
├── ralph.sh          # Executable bash loop
├── prompt.md         # Iteration instructions (uses Task tools)
├── progress.txt      # Execution log
├── knowledge.md      # Accumulated learnings
└── logs/             # Per-run log files

Task System Integration

The Ralph loop uses Claude Code's native Task management system:

Tools:

• TaskCreate - Create new tasks with subject, description, activeForm
• TaskList - View all tasks with status/owner/blockers
• TaskGet - Fetch full task details by ID
• TaskUpdate - Change status, set dependencies, mark complete

Status values: pending, in_progress, completed

Dependencies:

• blocks - Tasks that cannot start until this one completes
• blockedBy - Tasks that must complete before this one can start

Benefits over JSON backlog:

• Native dependency tracking
• Status validation (can't mark complete if tests fail)
• Parallel agent coordination via owner field
• Progress spinner shows activeForm text

Prompt Template Structure

# Ralph Agent: {Goal}

## Configuration
- List paths, files, tools

## Your Task (One Iteration)

### Step 1: Load Context
Use TaskList to get all tasks, read knowledge.md

### Step 2: Determine State
Check if all tasks are completed → output <promise>COMPLETE</promise>

### Step 3: Select Target
Use TaskList to find first task with:
- status: "pending"
- blockedBy: empty (no unresolved dependencies)
Use TaskUpdate to set status: "in_progress"

### Step 4-N: Execute
Task-specific steps using TaskGet for full details

### Final Step: Update
Use TaskUpdate to set status: "completed"
Update progress.txt and knowledge.md

## Completion
When all tasks completed: <promise>COMPLETE</promise>

Creating Initial Tasks

After generating the loop, create tasks for the backlog. Example for a migration loop:

# Create first task
TaskCreate:
  subject: "Migrate Button component"
  description: "Convert Button.tsx from styled-components to Tailwind. Update imports, replace styled() calls with className props using Tailwind utilities."
  activeForm: "Migrating Button component"

# Create dependent task
TaskCreate:
  subject: "Migrate Modal component"
  description: "Convert Modal.tsx. Depends on Button migration since Modal uses Button internally."
  activeForm: "Migrating Modal component"

# Set dependency
TaskUpdate:
  taskId: "2"
  addBlockedBy: ["1"]

Tip: Use TaskUpdate with addBlockedBy to ensure tasks run in correct order.

Best Practices

1. One task per iteration - Keep iterations focused
2. Clear acceptance criteria - Define what "done" means
3. Use dependencies - Set blockedBy for ordered tasks
4. Incremental commits - Commit after each successful task
5. Knowledge accumulation - Document learnings for future iterations
6. Fail fast - Stop on errors, don't silently continue
7. Idempotent operations - Safe to re-run if interrupted

Troubleshooting

References

• templates/ - Pre-built loop templates
• references/patterns.md - Common iteration patterns