Prp Ralph

---
description: Start autonomous Ralph loop to execute PRP plan until all validations pass
argument-hint: <plan.md|prd.md> [--max-iterations N]
---

# PRP Ralph Loop

**Input**: $ARGUMENTS

---

## Your Mission

Start an autonomous Ralph loop that executes a PRP plan iteratively until all validations pass.

**Core Philosophy**: Self-referential feedback loop. Each iteration, you see your previous work in files and git history. You implement, validate, fix, repeat - until complete.

**Skill Reference**: The `prp-ralph-loop` skill provides detailed execution guidance. It will be automatically available during loop iterations.

---

## Phase 1: PARSE - Validate Input

### 1.1 Parse Arguments

Extract from input:
- **File path**: Must end in `.plan.md` or `.prd.md`
- **Max iterations**: `--max-iterations N` (default: 20)

### 1.2 Validate Input Type

| Input | Action |
|-------|--------|
| Ends with `.plan.md` | Valid - use as plan file |
| Ends with `.prd.md` | Valid - will select next phase |
| Free-form text | STOP with message below |
| No input | STOP with message below |

**If invalid input:**

Ralph requires a PRP plan or PRD file.

Create one first: /prp-plan "your feature description" # Creates plan from description /prp-prd "your product idea" # Creates PRD with phases

Then run: /prp-ralph .claude/PRPs/plans/your-feature.plan.md --max-iterations 20

### 1.3 Verify File Exists

```bash
test -f "{file_path}" && echo "EXISTS" || echo "NOT_FOUND"

If NOT_FOUND: Stop with error message.

1.4 If PRD File - Select Next Phase

If input is a .prd.md file:

1. Read the PRD
2. Parse Implementation Phases table
3. Find first phase with Status: pending where dependencies are complete
4. Report which phase will be executed
5. Note: The loop will create and execute a plan for this phase

PHASE_1_CHECKPOINT:

• Input parsed (file path + max iterations)
• File exists and is valid type
• If PRD: next phase identified

---

Phase 2: SETUP - Initialize Ralph Loop

2.1 Create State File

Create .claude/prp-ralph.state.md:

mkdir -p .claude
mkdir -p .claude/PRPs/ralph-archives

Write state file with this structure:

---
iteration: 1
max_iterations: {N}
plan_path: "{file_path}"
input_type: "{plan|prd}"
started_at: "{ISO timestamp}"
---

# PRP Ralph Loop State

## Codebase Patterns
(Consolidate reusable patterns here - future iterations read this first)

## Current Task
Execute PRP plan and iterate until all validations pass.

## Plan Reference
{file_path}

## Instructions
1. Read the plan file
2. Implement all incomplete tasks
3. Run ALL validation commands from the plan
4. If any validation fails: fix and re-validate
5. Update plan file: mark completed tasks, add notes
6. When ALL validations pass: output <promise>COMPLETE</promise>

## Progress Log
(Append learnings after each iteration)

---

2.2 Display Startup Message

## PRP Ralph Loop Activated

**Plan**: {file_path}
**Iteration**: 1
**Max iterations**: {N}

The stop hook is now active. When you try to exit:
- If validations incomplete → same prompt fed back
- If all validations pass → loop exits

To monitor: `cat .claude/prp-ralph.state.md`
To cancel: `/prp-ralph-cancel`

---

CRITICAL REQUIREMENTS:
- Work through ALL tasks in the plan
- Run ALL validation commands
- Fix failures before proceeding
- Only output <promise>COMPLETE</promise> when ALL validations pass
- Do NOT lie to exit - the loop continues until genuinely complete

---

Starting iteration 1...

PHASE_2_CHECKPOINT:

• State file created
• Archive directory exists
• Startup message displayed

---

Phase 3: EXECUTE - Work on Plan

3.1 Read Context First

Before implementing anything:

1. Read the state file - check "Codebase Patterns" section
2. Read the plan file - understand all tasks
3. Check git status - what's already changed?
4. Review progress log - what did previous iterations do?

3.2 Identify Work

From the plan, identify:

• Tasks not yet completed
• Validation commands to run
• Acceptance criteria to meet

3.3 Implement

For each incomplete task:

1. Read the task requirements
2. Read any MIRROR/pattern references
3. Implement the change
4. Run task-specific validation if specified

3.4 Validate

Run ALL validation commands from the plan:

# Typical validation levels (adapt to plan)
bun run type-check || npm run type-check
bun run lint || npm run lint
bun test || npm test
bun run build || npm run build

3.5 Track Results

Check	Result	Notes
Type check	PASS/FAIL	{details}
Lint	PASS/FAIL	{details}
Tests	PASS/FAIL	{details}
Build	PASS/FAIL	{details}

3.6 If Any Validation Fails

1. Analyze the failure
2. Fix the issue
3. Re-run validation
4. Repeat until passing

3.7 Update Plan File

After each significant change:

• Mark completed tasks with checkboxes
• Add notes about what was done
• Document any deviations

3.8 Update State File Progress Log

Append to Progress Log section using this format:

## Iteration {N} - {ISO timestamp}

### Completed
- {Task 1 summary}
- {Task 2 summary}

### Validation Status
- Type-check: PASS/FAIL ({error count if failing})
- Lint: PASS/FAIL
- Tests: PASS/FAIL ({X/Y passing})
- Build: PASS/FAIL

### Learnings
- {Pattern discovered: "this codebase uses X for Y"}
- {Gotcha found: "don't forget to Z when doing W"}
- {Context: "the component X is in directory Y"}

### Next Steps
- {What still needs to be done}
- {Specific blockers to address}

---

3.9 Consolidate Codebase Patterns

If you discover a reusable pattern, add it to the "Codebase Patterns" section at the TOP of the state file:

## Codebase Patterns
- Use `sql<number>` template for type-safe SQL aggregations
- Always use `IF NOT EXISTS` in migrations
- Export types from actions.ts for UI components
- Form validati