Ralph Init

---
description: "Initialize a RALPH loop (.ralph/) with SPEC, PROMPT, TODO, and runner script"
argument-hint: "[task-name]"
allowed-tools:
  - Read
  - Write
  - Bash
  - AskUserQuestion
---

# RALPH Loop Initialization

Create a complete RALPH (Repetitive Autonomous Loop with Persistent History) setup in `.ralph/` directory.

## What is RALPH?

RALPH is an autonomous AI agent pattern where progress persists in files and git history, not the LLM context. Each iteration gets fresh context, picks up from files, implements one task, commits, and repeats until done.

## Core Principle

**Files are memory.** Progress lives in:
- `SPEC.md` - The PRD/requirements (what to build)
- `TODO.md` - Prioritized task checklist (what's left)
- `PROMPT.md` - Instructions for each iteration (how to work)
- `progress.txt` - Learnings log (what was discovered)
- `status.json` - Machine-readable state (for monitoring)
- Git history - What's been done

## Interactive Setup Flow

Ask these questions using AskUserQuestion tool:

### 1. Task Identity
- **Task name**: Short identifier (e.g., "workspace-migration", "auth-feature")
- **Description**: One-line summary of what RALPH will accomplish

### 2. Specification Details
- **Goal**: What is the end state? (Be specific and measurable)
- **Phases**: Break work into 2-5 phases (each phase = group of related tasks)
- **Success criteria**: How do we know it's done? (tests pass, builds succeed, etc.)

### 3. Task Breakdown
For each phase, ask:
- What are the individual tasks? (Each should fit in one context window)
- What order should they execute?
- What verification command confirms each task?

### 4. Context
- **Plan file path**: Optional reference to an existing plan (e.g., `~/.claude/plans/my-plan.md`)
- **Import mappings**: Any before/after mappings for refactoring tasks

## File Generation

After collecting answers, generate these files:

### .ralph/SPEC.md

```markdown
# [Task Name] Specification

## Goal
[One paragraph describing the end state]

## Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] Final verification: `[command]` passes

## Phases

### Phase 1: [Name]
[Description of this phase's purpose]

### Phase 2: [Name]
[Description]

[... more phases]

## Context
[Any import mappings, dependencies, constraints]

## Out of Scope
- [What this RALPH loop will NOT do]

.ralph/TODO.md

# [Task Name] Progress

## Phase 1: [Name]

| Status | Task | Verification |
|--------|------|--------------|
| [ ] | [Task description] | `[verify command]` |
| [ ] | [Task description] | `[verify command]` |

## Phase 2: [Name]

| Status | Task | Verification |
|--------|------|--------------|
| [ ] | [Task description] | `[verify command]` |

[... more phases]

## Completion
- [ ] All tasks checked
- [ ] Final verification passes: `[command]`

.ralph/PROMPT.md

# [Task Name]

You are completing [brief description] following the RALPH pattern.

## Your Context

1. Read the spec: `cat .ralph/SPEC.md`
2. Check progress: `cat .ralph/TODO.md`
3. Verify current state: `[verification command]`

## Your Task

1. **Find next task**: First unchecked `[ ]` item in TODO.md
2. **Implement it**: Make the minimal changes needed
3. **Verify**: Run the task's verification command
4. **Update TODO.md**: Mark the task `[x]` complete
5. **Log learnings**: Append to `.ralph/progress.txt`:
   - What you did
   - Any gotchas discovered
   - Patterns for future iterations
6. **Report**: State what you did and what's next

## Rules

- One task per iteration (keep changes small)
- Always verify before marking complete
- If stuck, document the blocker in TODO.md and progress.txt, then continue
- Follow existing code patterns
- Commit after each task with descriptive message

## Stop Condition

When all TODO.md items are `[x]` AND final verification passes, output:

<promise>RALPH_COMPLETE</promise>

.ralph/progress.txt

# [Task Name] Progress Log
# Each iteration appends learnings here

---
[Initialized: YYYY-MM-DD HH:MM]

.ralph/status.json

{
  "task": "[task-name]",
  "status": "pending",
  "iteration": 0,
  "maxIterations": 50,
  "startedAt": null,
  "lastRunAt": null,
  "completedTasks": 0,
  "totalTasks": 0,
  "currentPhase": null
}

.ralph/ralph-loop.sh

#!/usr/bin/env bash
# ralph-loop.sh - Run RALPH iterations until complete
#
# Usage:
#   .ralph/ralph-loop.sh              # Run the loop
#   .ralph/ralph-loop.sh --dry-run    # Show prompt without running
#   .ralph/ralph-loop.sh --once       # Single iteration
#   .ralph/ralph-loop.sh --status     # Show current status
#
# AFK Monitoring:
#   tmux new -s ralph '.ralph/ralph-loop.sh'  # Run in tmux
#   tmux attach -t ralph                       # Reattach later
#   tail -f .ralph/ralph.log                   # Watch log
#   /ralph-status                              # Check from Claude

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_DIR
PROJECT_ROOT="$(dirname "${SCRIPT_DIR}")"
readonly PROJECT_ROOT
readonly PROMPT_FILE="${SCRIPT_DIR}/PROMPT.md"
readonly TODO_FILE="${SCRIPT_DIR}/TODO.md"
readonly STATUS_FILE="${SCRIPT_DIR}/status.json"
readonly PROGRESS_FILE="${SCRIPT_DIR}/progress.txt"
readonly LOG_FILE="${SCRIPT_DIR}/ralph.log"
readonly MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"

# Colors
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly BLUE='\033[0;34m'
readonly NC='\033[0m'

info() { echo -e "${BLUE}[ralph]${NC} $*"; }
success() { echo -e "${GREEN}[ralph]${NC} $*"; }
warn() { echo -e "${YELLOW}[ralph]${NC} $*"; }
error() { echo -e "${RED}[ralph]${NC} $*" >&2; }

DRY_RUN=false
RUN_ONCE=false
SHOW_STATUS=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --dry-run) DRY_RUN=true; shift ;;
    --once) RUN_ONCE=true; shift ;;
    --status) SHOW_STATUS=true; shift ;;
    --help)
      echo "Usage: $0 [--dry-run] [--once] [--status]