---

name: ralph-plan description: Use this skill when the user says 'run ralph', 'start ralph loop', 'execute the plan with ralph', '/ralph-plan', 'ralph this plan', or wants to run an approved plan autonomously using the Ralph Wiggum technique. This skill transforms standard plans into ralph-loop compatible format and executes them. version: 1.0.0

Ralph Plan Executor

This skill transforms approved plan files into ralph-loop compatible format and executes them autonomously using the Ralph Wiggum technique.

When to Use

Activate this skill when the user:

• Says "run ralph" or "start ralph loop"
• Says "/ralph-plan" or "ralph this plan"
• Wants to execute an approved plan autonomously
• Asks to "run the plan with ralph"

Execution Steps

Step 1: Find the Most Recent Plan

Look for the most recent plan file in ~/.claude/plans/. The plan files are named with random words (e.g., lively-crunching-hamster.md). Read the directory and find the most recently modified .md file.

Copyls -t ~/.claude/plans/*.md | head -1

Step 2: Read and Parse the Plan

Read the plan file content. Extract:

• Title: From the first # heading
• Phases: Look for ## Phase or numbered sections
• Success Criteria: Look for checkboxes - [ ] or "Success Criteria" sections
• Files to Create/Modify: Look for file paths or "Files to" sections
• Verification Commands: Look for code blocks with commands (npm, pytest, etc.)

Step 3: Transform into Ralph-Plan Format

Create a new file at .claude/ralph-plans/[timestamp]-ralph-plan.md using this template:

Copy# Ralph Execution Plan: [Original Title]

## CRITICAL INSTRUCTIONS

You are executing this plan autonomously in a Ralph loop. Follow these rules:

1. **Work through each phase in order** - Do not skip phases
2. **Verify each phase before moving on** - Run verification commands
3. **Check off success criteria** - Mark items complete as you finish them
4. **Output completion token when done** - When ALL phases are complete and verified

### Completion Token

When ALL of the following are true, output exactly:
<promise>COMPLETE</promise>

Completion checklist:
- [ ] All phases completed
- [ ] All success criteria met
- [ ] All verification commands pass
- [ ] No failing tests or linter errors

---

## Phase 1: [Phase Name]

### Tasks
[List specific tasks from original plan]

### Files to Modify
[List files with paths]

### Verification
Run these commands to verify completion:
```bash
[verification commands]

Success Criteria

• [Specific, measurable criterion]
• [Specific, measurable criterion]

---

Phase 2: [Phase Name]

[Continue pattern for each phase...]

---

Escape Hatch

If after 40 iterations you cannot complete a phase:

1. Create RALPH_BLOCKERS.md in the project root with:

   • What phase is blocked
   • What was attempted
   • What errors occurred
   • Suggested next steps

2. Output: BLOCKED

This signals the loop to stop so the user can intervene.

---

Progress Tracking

As you work, update this section:

Current Phase: [Phase Number]

Iterations on Current Phase: [Count]

Last Action: [Description]

Blockers: [None / Description]

Copy
### Step 4: Execute Ralph Loop

After saving the ralph-plan, execute the ralph loop with:

/ralph-loop "[full ralph-plan content]" --max-iterations 50 --completion-promise "COMPLETE"

Copy
**Important parameters:**
- `--max-iterations 50`: Default limit to prevent runaway execution
- `--completion-promise "COMPLETE"`: Matches our `<promise>COMPLETE</promise>` token

## Transformation Rules

When converting a standard plan to ralph format:

1. **Make success criteria specific and verifiable**
   - Bad: "Code works correctly"
   - Good: "All tests pass (`npm test` exits with code 0)"

2. **Include verification commands for each phase**
   - If tests exist: `npm test`, `pytest`, `go test`
   - If building: `npm run build`, `cargo build`
   - If linting: `npm run lint`, `ruff check`

3. **Break large phases into smaller sub-phases if needed**
   - Each phase should be completable in ~10 iterations max
   - If a phase is too large, split it

4. **Add explicit file paths**
   - Convert "update the config" to "update `config/settings.yaml`"
   - Be specific about which files to create or modify

5. **Include rollback guidance**
   - If a phase fails repeatedly, what should be reverted?

## Example Transformation

### Original Plan (excerpt):
```markdown
## Phase 1: Add User Authentication

- Add login endpoint
- Add registration endpoint
- Add JWT token generation
- Success: Users can register and login

Ralph Plan (transformed):

Copy## Phase 1: Add User Authentication

### Tasks
1. Create `src/routes/auth.py` with login and registration endpoints
2. Add JWT token generation in `src/utils/jwt.py`
3. Create user model in `src/models/user.py`
4. Add authentication middleware in `src/middleware/auth.py`
5. Write tests in `tests/test_auth.py`

### Files to Modify
- `src/routes/auth.py` (CREATE)
- `src/utils/jwt.py` (CREATE)
- `src/models/user.py` (CREATE)
- `src/middleware/auth.py` (CREATE)
- `tests/test_auth.py` (CREATE)
- `src/main.py` (MODIFY - register routes)

### Verification
```bash
# Run auth tests
pytest tests/test_auth.py -v

# Check endpoints respond
curl -X POST http://localhost:8000/auth/register -d '{"email":"test@test.com","password":"test123"}'

Success Criteria

• POST /auth/register creates user and returns 201
• POST /auth/login returns JWT token for valid credentials
• POST /auth/login returns 401 for invalid credentials
• All tests in tests/test_auth.py pass
• No linter errors (ruff check src/)

Copy
## Default Configuration

- **Max Iterations**: 50
- **Completion Promise**: "COMPLETE"
- **Blocked Promise**: "BLOCKED"
- **Ralph Plan Location**: `.claude/ralph-plans/[timestamp]-ralph-plan.md`

## Tips for Success

1. **Start with a well-structured plan** - The better the input plan, the better the ralph execution
2. **Include tests in your plan** - Automated verification is key to ralph success
3. **Be specific about "done"** - Vague success criteria cause non-convergence
4. **Monitor the first few iterations** - Make sure it's on the right track
5. **Use escape hatches** - Don't let it spin forever on impossible tasks