Ralph Wiggum Orchestration

"Me fail migrations? That's unpossible!" - Ralph Wiggum

A pattern for orchestrating complex, multi-phase migrations using AI agents with git worktrees and tmux.

What is Ralph Wiggum?

Ralph Wiggum is an orchestration pattern for running multiple AI agents in parallel during large-scale codebase migrations. It was battle-tested during a Next.js 15→16 + Sanity 3→5 + Tailwind 3→4 migration involving 200+ file changes across 28 phases.

Key Concepts

• Wave-based execution: Tasks grouped into waves with max 4 parallel agents
• Git worktrees: Each agent works in isolation to prevent merge conflicts
• Explicit file ownership: Matrix defining which agent owns which files
• Chrome queue: Serialized access to browser for visual verification
• Verification gates: Per-wave validation before proceeding

Structure

├── scripts/              # Orchestration shell scripts
│   ├── ralph-migration.sh    # Main orchestrator
│   ├── ralph-phase.sh        # Single phase executor
│   ├── ralph-once.sh         # One-shot phase runner
│   └── afk-ralph.sh          # AFK mode runner
├── verification/         # Wave verification scripts
│   ├── verify-wave-0.sh
│   ├── verify-wave-1.sh
│   └── verify-final.sh
├── examples/             # Templates and examples
│   ├── prd-template.md       # Phase PRD template
│   └── wave-structure.md     # Example wave organization
└── .claude/rules/        # Agent instruction files
    ├── 08-ralph-wiggum-orchestration-risk-analysis.md
    └── 09-ralph-wiggum-quick-reference.md

The Pattern

1. Plan

Break your migration into phases with explicit dependencies. Each phase should be:

• Small enough for one agent session
• Have clear inputs and outputs
• Have verifiable completion criteria

2. PRD Each Phase

Document each phase with:

• Context and goals
• Specific tasks with file paths
• Verification commands
• Rollback procedures

3. Assign Ownership

Create a file ownership matrix for each wave. Critical rule: No file can be owned by more than one agent per wave.

4. Execute in Waves

Run agents in parallel using tmux + git worktrees:

• Each agent gets an isolated worktree
• Agents work simultaneously on non-overlapping files
• Wave completes when all agents finish

5. Verify

Run gate scripts before merging:

./verification/verify-wave-1.sh
# Only proceed if exit code is 0

6. Merge

Sequential merge with conflict detection. If conflicts occur, stop and investigate the ownership matrix.

Risk Mitigations

The .claude/rules/ files document:

08-ralph-wiggum-orchestration-risk-analysis.md:

• 10 identified failure modes (merge conflicts, stale worktrees, Chrome contention, etc.)
• Prevention strategies for each
• Recovery procedures
• Monitoring checklists

09-ralph-wiggum-quick-reference.md:

• Pre-wave checklists
• Alert response procedures
• Worktree lifecycle management
• Chrome queue operations

Quick Start

1. Copy the scripts to your project
2. Adapt ralph-migration.sh for your phases
3. Create PRDs for each phase using the template
4. Set up verification scripts for each wave
5. Run with: ./scripts/ralph-migration.sh

When to Use Ralph

Ralph is designed for migrations that are:

• Large: 100+ file changes
• Complex: Multiple interconnected systems
• Parallelizable: Work can be divided by file/directory ownership
• Risky: Need isolation and rollback capabilities

License

MIT