Ralph Plan Executor

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

# 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]

### Step 4: Execute Ralph Loop

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

**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

## 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"}'

## 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