/ralph-supervisor

name: ralph-supervisor
description: |
  Ralph loop pattern - Claude supervises while Codex (gpt-5.3-codex) executes
  implementation work. Use for autonomous coding loops with fresh context per
  iteration, validation gates, and git-backed persistence. Tools: ralph_init,
  ralph_story, ralph_iterate, ralph_loop, ralph_status, ralph_cancel, ralph_review.

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

{
  "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

{
  "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:

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_c