ralph-supervisor

What this skill does

# Ralph Supervisor Pattern

Ralph implements an autonomous coding loop where Claude acts as supervisor and Codex executes implementation work. Named after the pattern from [openclaw-codex-ralph](https://github.com/joelhooks/openclaw-codex-ralph).

## Core Philosophy

Traditional AI sessions accumulate context and drift. Ralph uses:
- **Fresh context per iteration** - Each Codex session starts clean
- **Git-backed persistence** - Completed work lives in commits
- **Validation gates** - Tests must pass before progression
- **Progress carryover** - Learnings flow forward (last 2000 chars)

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    RALPH ARCHITECTURE                     │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │   Claude    │ spawns  │   Codex     │                 │
│  │ (Supervisor)│ ──────► │ (Executor)  │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │ plans/reviews         │ implements              │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │  prd.json   │         │   Code +    │                 │
│  │  (stories)  │         │   Tests     │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │                       │ validates               │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │progress.txt │◄────────│  npm test   │                 │
│  │ (learnings) │ logs    │ typecheck   │                 │
│  └─────────────┘         └─────────────┘                 │
│        │                       │                         │
│        │                       │ on success              │
│        ▼                       ▼                         │
│  ┌─────────────┐         ┌─────────────┐                 │
│  │  Hivemind   │         │ Git Commit  │                 │
│  │ (semantic)  │         │ (persist)   │                 │
│  └─────────────┘         └─────────────┘                 │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

## Iteration Lifecycle

```
1. Read PRD → Find next pending story (by priority)
2. Load progress.txt + AGENTS.md for context
3. Build iteration prompt for Codex
4. Spawn Codex (codex exec --full-auto)
5. Run validation command
6. If success:
   - Mark story.status = "passed"
   - Append to progress.txt
   - Git commit
7. If failure:
   - Log failure details
   - Keep story for retry
8. Repeat until all stories pass or limits hit
```

## Story Structure

```json
{
  "id": "story-1234567890",
  "title": "Add user authentication",
  "description": "Implement login/logout with JWT...",
  "priority": 1,
  "status": "pending",
  "validation_command": "npm test && npm run typecheck",
  "acceptance_criteria": [
    "JWT token generation works",
    "Refresh token flow implemented"
  ],
  "attempts": 0,
  "files_touched": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}
```

## PRD Structure

```json
{
  "version": "1.0",
  "project_name": "My Feature",
  "description": "Adding OAuth support...",
  "stories": [...],
  "metadata": {
    "created_at": "...",
    "last_iteration": "...",
    "total_iterations": 5,
    "total_stories_completed": 3
  }
}
```

## Supervisor Best Practices

### Story Design

- **Granular scope** - Each story should fit in one Codex context
- **Clear acceptance criteria** - Specific, testable requirements
- **Proper validation** - Tests that actually verify the work
- **Priority ordering** - Dependencies first (lower number = higher priority)

### Review Process

```
┌─────────────────────────────────────────────────────────────┐
│                    REVIEW CHECKLIST                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  □ Tests pass (validation_command succeeded)                │
│  □ Acceptance criteria met                                  │
│  □ Code quality acceptable                                  │
│  □ No security issues introduced                            │
│  □ Integration with existing code correct                   │
│                                                             │
│  If YES to all → ralph_review({ approve: true })            │
│  If NO to any  → ralph_review({ approve: false,             │
│                                 feedback: "Specific issue"})│
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Knowledge Persistence

After completing a project, store learnings:

```typescript
hivemind_store({
  information: "OAuth implementation: Used refresh token rotation pattern with 7-day expiry. Key gotcha: must invalidate old refresh token on use.",
  tags: "oauth,auth,tokens,patterns",
  confidence: 0.9
})
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `model` | `gpt-5.3-codex` | Codex model to use |
| `sandbox` | `workspace-write` | Sandbox mode |
| `max_iterations` | `20` | Loop limit |
| `auto_commit` | `true` | Commit on success |
| `progress_context_limit` | `2000` | Chars of progress in prompt |
| `default_validation` | `npm run typecheck; npm test` | Fallback validation |

## Events Emitted

| Event | When |
|-------|------|
| `ralph:init` | Project initialized |
| `ralph:story:added` | Story added to PRD |
| `ralph:iteration:start` | Iteration begins |
| `ralph:iteration:complete` | Iteration ends |
| `ralph:loop:start` | Loop begins |
| `ralph:loop:iteration` | Each loop iteration |
| `ralph:loop:complete` | Loop finishes |
| `ralph:loop:error` | Loop error |
| `ralph:review:approved` | Work approved |
| `ralph:review:rejected` | Work rejected |

## Error Handling

| Error | Recovery |
|-------|----------|
| Codex timeout | Retry with longer timeout |
| Validation fail | Fix in next iteration |
| No stories left | All complete, exit |
| Max iterations | Report remaining work |

## Comparison: Ralph vs Swarm

| Aspect | Ralph | Swarm |
|--------|-------|-------|
| Executor | Codex | Claude workers |
| Parallelism | Sequential | Parallel |
| Context | Fresh per iteration | Shared via hivemind |
| Review | Supervisor reviews each | Coordinator reviews all |
| Best for | Complex sequential tasks | Independent parallel tasks |