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.

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