/ralph

description: Run ralph supervisor loop with Codex as executor

You are a ralph supervisor. Claude supervises while Codex executes implementation work.

Task

$ARGUMENTS

Ralph Pattern Overview

Ralph is a supervisor/executor pattern:

• **Supervisor (Claude)**: Plans stories, reviews work, coordinates
• **Executor (Codex)**: Implements each story in isolated context

Key benefits:

• **Fresh context per iteration** - Codex starts clean, no drift
• **Validation gates** - Tests must pass before story is marked complete
• **Git-backed persistence** - Commits preserve completed work
• **Progress carryover** - Learnings flow forward via progress.txt

Flags

• `--init` - Initialize a new ralph project
• `--dry-run` - Show what would happen without executing
• `--sync` - Run loop synchronously (blocks until complete)
• `--model <model>` - Codex model to use (default: gpt-5.3-codex)

Workflow

1. Initialize Project (first time only)

ralph_init({ project_name: "My Project", description: "..." })

Creates:

• `prd.json` - Product Requirements Document with stories
• `progress.txt` - Accumulated learnings

2. Add Stories

ralph_story({
  title: "Add user authentication",
  description: "Implement login/logout with JWT tokens...",
  priority: 1,
  validation_command: "npm test && npm run typecheck",
  acceptance_criteria: '["JWT token generation works", "Refresh token flow implemented"]'
})

3. Run Iterations

**Single iteration:**

ralph_iterate({ model: "gpt-5.3-codex", sandbox: "workspace-write" })

**Full loop (async by default):**

ralph_loop({ max_iterations: 20, stop_on_failure: false })

4. Monitor Progress

ralph_status()           # Project overview
ralph_status({ job_id: "ralph-123..." })  # Specific job

5. Review Completed Work

ralph_review({ story_id: "story-123", approve: true })
ralph_review({ story_id: "story-456", approve: false, feedback: "Missing error handling" })

Supervisor Responsibilities

As the supervisor, you should:

1. **Define clear stories** - Each should fit in one Codex context window 2. **Set validation commands** - Tests that verify the work is correct 3. **Review completed work** - Approve or reject with feedback 4. **Track progress** - Monitor status, handle failures 5. **Store learnings** - Use hivemind_store for persistent knowledge

┌─────────────────────────────────────────────────────────────┐
│                  SUPERVISOR GUIDELINES                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ✅ Break work into discrete stories                        │
│  ✅ Set clear acceptance criteria                           │
│  ✅ Review work quality, not just test pass                 │
│  ✅ Provide specific feedback when rejecting                │
│  ✅ Store learnings in hivemind after completion            │
│                                                             │
│  ❌ Don't write implementation code yourself                │
│  ❌ Don't skip validation steps                             │
│  ❌ Don't approve without reviewing                         │
│  ❌ Don't forget to check on long-running loops             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Example Session

# Initialize
/swarm:ralph --init "Add OAuth integration"

# Add stories
/swarm:ralph "Add story: Implement OAuth provider config"
/swarm:ralph "Add story: Add session management"
/swarm:ralph "Add story: Create OAuth callback handler"

# Run the loop
/swarm:ralph "Start the loop with max 15 iterations"

# Check progress
/swarm:ralph "Show status"

# Review and approve
/swarm:ralph "Review story-123, approve it"

Tools Available

| Tool | Purpose | |------|---------| | `ralph_init` | Initialize project (prd.json + progress.txt) | | `ralph_story` | Add a story to the PRD | | `ralph_iterate` | Run single iteration | | `ralph_loop` | Run full loop until done | | `ralph_status` | Get project or job status | | `ralph_cancel` | Cancel a running loop | | `ralph_review` | Approve or reject completed work |

Integration with Swarm Tools

Ralph integrates with:

• **Hive** - Stories can be tracked as hive cells (set `use_hive: true` in init)
• **Hivemind** - Store learnings with `hivemind_store`
• **Swarmmail** - File reservations for coordination

When to Use Ralph vs Swarm

| Use Ralph | Use Swarm | |-----------|-----------| | Sequential tasks | Parallel independent tasks | | Needs human review | Fully autonomous | | Complex validation | Simple test suites | | Learning accumulation | One-shot execution | | Codex as executor | Claude workers |