"I'm going to sleep, then when I wake up, I'm going to eat!" - Ralph Wiggum
A file-based, serverless autonomous development system that combines:
- World Model Prompts (DOT cards with AI context)
- Agent Rules (.roomodes definitions)
- Frontend Controls (UI to interact with both)
- 🆕 Parallel Agent Execution (Multiple isolated VS Code instances)
- 🆕 Batch Error Processing (Parse all errors, fix in batches)
- 🆕 Centralized Build Architecture (Single builder, multiple fixers)
- 🆕 Multi-Orchestrator Coordination (Multiple orchestrators, no conflicts!)
Works through Roo Code's agent mode system combined with file-based state management. No server required.
| Feature | Description |
|---|---|
| 🐝 Multi-Orchestrator Coordination | Run ANY number of orchestrators in parallel with automatic task claiming |
| First-Write-Wins Protocol | Orchestrators claim tasks without conflicts using a single coordination file |
| Build Lock System | Only one orchestrator can run cmake at a time |
| Profile Sync Script | Automatically copy .roomodes to all VS Code agent profiles |
| Feature | Description |
|---|---|
| Parallel Agents | Run 4-29 agents simultaneously in isolated VS Code windows |
| Batch Error System | Parse ALL build errors at once, fix in batches |
| Centralized Build | Only orchestrator compiles, all others are fixers |
| 31 Specialist Agents | Technical (9) + Rendering (6) + Player Experience (14) + Core (2) |
| Scratchpad Management | Archive/cleanup tools for inter-agent communication |
See multi_orchestrator/ for the new coordination system. See PARALLEL_AGENTS.md and BATCH_ERROR_SYSTEM.md for v2.0 details.
Ralph's Infinity Rule List is a pattern for running continuous autonomous development cycles using AI coding assistants. It was developed for the Chimera VR project but can be adapted to any codebase.
Instead of trying to build a complex autonomous agent system with servers and APIs, we use:
- Simple file-based state - JSON files that agents read/write
- Prompt templates - Pre-defined prompts for each specialist agent
- Agent mode switching - Using Roo Code's
.roomodessystem - Visual feedback - HTML dashboards that read the state files
The result: A multi-agent system that anyone can run, understand, and modify.
# 1. Copy the agent mode definitions to your project
cp .roomodes your-project/
# 2. Copy the Ralph Orchestrator files
cp -r ralph_orchestrator/ your-project/tools/
# 3. Open the Infinity List UI
open tools/zoom_world_model.html
# 4. Click an agent button to copy its prompt
# 5. Paste the prompt into Roo Code┌─────────────────────────────────────────────────────────────────────────────┐
│ RALPH'S INFINITY RULE LIST │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ World Model │ │ Agent Rules │ │ Control Panel │ │
│ │ (DOT Cards) │ │ (.roomodes) │ │ (HTML UI) │ │
│ │ │ │ │ │ │ │
│ │ • Project │ │ • Build Agent │ │ • Click agent │ │
│ │ Context │ │ • Assets Agent │ │ • Copy prompt │ │
│ │ • AI Prompts │ │ • VR Agent │ │ • Paste in Roo │ │
│ │ • Tasks │ │ • etc... │ │ • View status │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └─────────────────────┴─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Roo Code Agent Modes │ │
│ │ (.roomodes switching) │ │
│ └─────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ State Files │ │
│ │ • .ralph/status.json │ │
│ │ • .ralph/scratchpads/ │ │
│ └─────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Agent | Mode Slug | Specialty |
|---|---|---|
| 🎭 Ralph Orchestrator | orchestrator |
Owns build cycle, dispatches to specialists |
| 📚 Docs Agent | agent7-docs |
Status reports, API docs, project docs |
| Agent | Mode Slug | Specialty |
|---|---|---|
| 🔧 Build Agent | agent1-build |
CMake, compilation (BUILD ONLY - no fixing) |
| 🐛 Debug Agent | debug-agent |
C++ code fixing (FIXER - no building) |
| 🐍 Python Agent | agent9-python |
Python bindings, pybind11 |
| 🎨 Assets Agent | agent2-assets |
glTF models, textures, asset pipeline |
| 🌍 World Agent | agent3-world |
YAML configs, orbital data, NASA JPL |
| 🥽 VR Agent | agent4-vr |
OpenXR, hand tracking, VR interactions |
| ⚛️ Physics Agent | agent5-physics |
Bullet3, orbital mechanics, collisions |
| 🧪 Testing Agent | agent6-testing |
Unit tests, coverage (parallel pytest) |
| 📸 Screenshot Agent | agent8-screenshot |
Visual verification, render validation |
| Agent | Mode Slug | GPU Budget |
|---|---|---|
| 🏔️ Terrain | agent10-terrain |
2ms |
| ☁️ Clouds | agent11-clouds |
2ms |
| 🌊 Ocean | agent12-ocean |
1ms |
| 🌲 Vegetation | agent13-vegetation |
2ms |
| 📊 Quality | agent14-quality |
N/A |
| 🏛️ Guardian | architecture-guardian |
N/A |
| Agent | Mode Slug | Focus |
|---|---|---|
| GDD Agent | gdd-agent |
Game Design Document |
| Psychology | player-psychology |
Flow states, motivation |
| UX/Accessibility | ux-accessibility |
WCAG, VR comfort |
| Children (8-12) | demo-children |
COPPA safety, wonder |
| Teens (13-17) | demo-teens |
Social, competition |
| Young Adult (18-25) | demo-young-adult |
Deep systems, esports |
| Adult (26-45) | demo-adult |
Time-efficient, family |
| Mature (46-65) | demo-mature |
Comfort, nostalgia |
| Senior (65+) | demo-senior |
Max accessibility |
| Casual | demo-casual |
Instant fun, tourist mode |
| Hardcore | demo-hardcore |
Mastery, competition |
| Educational | demo-educational |
NGSS standards |
| Simulation | demo-simulation |
Real physics, procedures |
Each specialist agent is defined as a Roo Code custom mode with:
- slug: agent1-build
name: "Build Agent"
roleDefinition: |-
You are the Build System specialist for Chimera VR.
Your responsibilities:
- CMake configuration and generation
- Compilation error diagnosis and fixing
...
whenToUse: "CMake configuration, compilation errors, build fixes"
groups: ["read", "edit", "command"]- User clicks an agent button in the UI
- JavaScript generates a prompt for that agent
- Prompt is copied to clipboard
- User pastes into Roo Code
- Roo Code switches to the appropriate agent mode
- Agent executes its responsibilities
Agents write their status to .ralph/status.json:
{
"orchestrator": {
"status": "idle",
"current_cycle": 0,
"current_agent": null
},
"agents": {
"build": {
"status": "complete",
"progress": 100,
"message": "Build completed successfully"
}
}
}The UI reads this file (via generated ralph_status.js) to display real-time status.
Each agent has a persistent scratchpad at .ralph/scratchpads/{agent}_scratchpad.md:
# Build Agent Scratchpad
## Context
- Project: Chimera VR
- Build System: CMake + bgfx
## Completed
- Fixed CMake configuration for VR rendering
- Added missing OpenXR dependencies
## In Progress
- Optimizing shader compilation
## Next Actions
- Investigate texture compression issuesThis provides persistent memory across cycles.
| Component | File | Purpose |
|---|---|---|
| Agent Base Class | ralph_orchestrator/agent_base.py |
Base class for all agents with scratchpad and status methods |
| State Manager | ralph_orchestrator/state_manager.py |
Thread-safe file-based state management |
| Infinity List UI | zoom_world_model.html |
World Model visualization + Ralph panel |
| Control Panel | ralph_control_panel.html |
Standalone agent control dashboard |
| Status Compiler | compile_ralph_status.py |
Generates JS from status.json |
| Agent Modes | .roomodes |
Roo Code agent definitions |
- No Server Needed - Everything runs through file I/O
- Transparent - You can read every state file and scratchpad
- Debuggable - Each agent's work is logged and persistent
- Simple - No complex orchestration, just prompts and modes
- Portable - Works with any AI coding assistant that supports mode switching
- Observable - HTML dashboards show exactly what's happening
"Everyone gets a turn, every cycle."
- Deterministic loops (no complex decision trees)
- Every agent runs in sequence (no parallelism headaches)
- Git checkpoints after each agent (easy recovery)
- Accumulate knowledge over time (scratchpads grow)
- ARCHITECTURE.md - Deep dive into system architecture
- SETUP.md - Installation and configuration guide
- USAGE.md - How to use the system day-to-day
- CUSTOM_AGENTS.md - Creating your own specialist agents
MIT License - Feel free to use this pattern in your own projects!
Developed for the Chimera VR project - An open-source VR space simulator.
Inspired by the "Ralph Wiggum" approach to autonomous development: simple, persistent, and always hungry for more progress.