joelhooks/ralph-supervisor

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.

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