# Ralph

> Persistence loop until task completion. Use when work must be verified complete.

- Skill: `changhochien/ralph` (Agent Skill)
- Install (CLI): `npx skillmds@latest add changhochien/ralph`
- Raw SKILL.md: https://api.skillmd.com/api/skills/changhochien/ralph/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: changhochien (https://skillmd.com/u/changhochien)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/changhochien/ralph

---


# Ralph Skill

Keep working until ALL acceptance criteria are verified. PRD-driven persistence loop.

## Usage

```
/skill:ralph "fix all TypeScript errors"
/skill:ralph "implement user authentication"
/skill:ralph "complete the API endpoints"
```

## How It Works

```
RALPH ITERATION 1/10
        ↓
Create/Read PRD (prd.json)
        ↓
Pick next incomplete story
        ↓
Implement + Verify
        ↓
Story passes? → Mark complete → Next story?
        ↓
No → Fix → Re-verify → Loop
        ↓
All stories pass → Architect verification → Done
```

## PRD Format

Create `.omp/prd.json`:

```json
{
  "title": "Implement user authentication",
  "stories": [
    {
      "id": "AUTH-001",
      "description": "User can register",
      "acceptance_criteria": [
        "POST /auth/register accepts email/password",
        "Password is hashed with bcrypt",
        "Returns JWT token",
        "Validates email format",
        "Returns 400 for invalid input"
      ],
      "passes": false
    },
    {
      "id": "AUTH-002",
      "description": "User can login",
      "acceptance_criteria": [
        "POST /auth/login accepts valid credentials",
        "Returns JWT token",
        "Returns 401 for invalid credentials"
      ],
      "passes": false
    }
  ]
}
```

## Steps

### 1. Initialize (Iteration 1)

```json
{
  "active": true,
  "iteration": 1,
  "max_iterations": 10,
  "started_at": "2024-01-15T10:00:00Z",
  "current_phase": "implementing",
  "current_story": "AUTH-001"
}
```

### 2. Pick Next Story

Read `prd.json`, find first story with `"passes": false`.

### 3. Implement

Delegate to executor:

```
Task(subagent_type="oh-my-pi:executor", model="sonnet", prompt="Implement AUTH-001: User registration per acceptance criteria")
```

### 4. Verify Each Criterion

For each acceptance criterion:
- Run relevant tests
- Manual verification if needed
- Collect evidence

### 5. Mark Story Complete

When ALL criteria pass:

```json
{
  "id": "AUTH-001",
  "passes": true,
  "verified_at": "2024-01-15T10:30:00Z",
  "evidence": ["tests pass", "verified manually"]
}
```

### 6. Check Completion

Read `prd.json`:
- All `passes: true`? → Go to Step 7
- Not all complete? → Loop to Step 2

### 7. Architect Verification

```
Task(subagent_type="oh-my-pi:architect", model="opus", prompt="Review implementation against acceptance criteria")
```

If approved → Complete
If rejected → Fix and re-verify

## Anti-Patterns

### ❌ "Looks good, should work"
```typescript
// Wrong - no verification
"Implementation complete, should work correctly"
```

### ✅ Evidence-based
```typescript
// Right - actual verification
"Test results: 12/12 pass"
"Verified: POST /auth/register with valid input returns 200 + JWT"
```

## Progress Tracking

Update `.omp/state/ralph-progress.json`:

```json
{
  "active": true,
  "iteration": 2,
  "current_story": "AUTH-002",
  "completed_stories": ["AUTH-001"],
  "pending_stories": ["AUTH-002", "AUTH-003"],
  "errors_encountered": [],
  "iterations_with_no_progress": 0
}
```

## Completion Criteria

- [ ] All prd.json stories have `passes: true`
- [ ] All acceptance criteria verified with evidence
- [ ] Architect review passed
- [ ] No regressions (all tests pass)
- [ ] Clean state files

## Cancel

```
/skill:cancel
```

Stops ralph and cleans up state.