ReddRadar
Agent skill
ralph-supervisor
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.
Install this agent skill to your Project
npx add-skill https://github.com/joelhooks/swarm-tools/tree/main/packages/opencode-swarm-plugin/claude-plugin/skills/ralph-supervisor
SKILL.md
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 |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
joelhooks/swarm-tools
swarm-coordination
Multi-agent coordination patterns for OpenCode swarm workflows. Use when work benefits from parallelization or coordination. Covers: decomposition, worker spawning, file reservations, progress tracking, and review loops.
joelhooks/swarm-tools
swarm-cli
Swarm CLI commands for workers - hivemind memory, hive tasks, swarmmail coordination. Use when working in a swarm context. Covers: swarm memory (find/store/get/stats), swarm cells (query/create/update/close), and coordination commands.
joelhooks/swarm-tools
always-on-guidance
Always-on rule-oriented guidance for claude-plugin agents. Use to align behavior, tool usage, and model-specific defaults while avoiding deprecated bd/cass references. Related skills: swarm-coordination, testing-patterns.
joelhooks/swarm-tools
swarm-coordination
Multi-agent coordination patterns for OpenCode swarm workflows. Use when working on complex tasks that benefit from parallelization, when coordinating multiple agents, or when managing task decomposition. Do NOT use for simple single-agent tasks.
joelhooks/swarm-tools
hive-workflow
Issue tracking and task management using the hive system. Use when creating, updating, or managing work items. Use when you need to track bugs, features, tasks, or epics. Do NOT use for simple one-off questions or explorations.
joelhooks/swarm-tools
skill-creator
Guide for creating effective agent skills. Use when you want to create a new skill, improve an existing skill, or learn best practices for skill development. Helps codify learned patterns into reusable, discoverable skills.
Didn't find tool you were looking for?