Ralph Bridge

Ralph Bridge

Fresh-instance loop orchestration for multi-story feature development.

When to Use

Key insight: Fresh instances solve context window exhaustion. Each story gets full context.

How It Works

┌─────────────────────────────────────────┐
│           Ralph Orchestrator            │
│         (moo-ralph.sh script)           │
└────────────────┬────────────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
┌────────┐  ┌────────┐  ┌────────┐
│ Story 1│  │ Story 2│  │ Story 3│
│ Fresh  │  │ Fresh  │  │ Fresh  │
│ Claude │  │ Claude │  │ Claude │
└────────┘  └────────┘  └────────┘
    │            │            │
    ▼            ▼            ▼
┌─────────────────────────────────────────┐
│           prd.json + progress.txt       │
│            (Shared State)               │
└─────────────────────────────────────────┘

Prerequisites

1. prd.json — Structured PRD with stories
2. Git branch — Feature branch for all work
3. Claude Code — Installed and configured

prd.json Format

{
  "feature": "User Settings",
  "branch": "feature/user-settings",
  "stories": [
    {
      "id": "S-001",
      "title": "Settings route",
      "description": "Add /settings route with basic layout",
      "acceptance": [
        "Route renders without error",
        "Navigation link added to header"
      ],
      "blockedBy": [],
      "passes": false
    },
    {
      "id": "S-002",
      "title": "Settings form",
      "description": "Create form with email and name fields",
      "acceptance": [
        "Form validates required fields",
        "Submit calls API endpoint"
      ],
      "blockedBy": ["S-001"],
      "passes": false
    }
  ]
}

Usage

Basic

./moo-ralph.sh

Runs until all stories pass or max iterations reached.

With Options

./moo-ralph.sh [max_iterations] [--colleague-pause]

Execution Flow

Per-Story Protocol

1. Pre-Flight Check

   • Verify prd.json exists
   • Verify git branch matches
   • Check no uncommitted changes

2. Story Selection

   • Find first story with passes: false
   • Verify blockedBy stories all pass
   • Skip blocked stories

3. Silent Audit (per story)

   • Score spec (should be ≥8 for well-written PRD)
   • Calculate fit score
   • Determine workflow shape

4. Must-NOT Extraction

   • Parse story context for constraints
   • Add to circuit breaker triggers

5. Execute

   • Fresh Claude instance
   • Full context window available
   • Work on single story

6. Completion Signal

   • Claude outputs <story-complete> when done
   • Script verifies acceptance criteria
   • Updates prd.json with passes: true

Completion Signals

Story Complete

<story-complete>
Story: S-001
Acceptance verified:
- [x] Route renders without error
- [x] Navigation link added
</story-complete>

Feature Complete

<feature-complete>
All stories complete:
- S-001: Settings route ✓
- S-002: Settings form ✓
- S-003: Settings API ✓
</feature-complete>

Progress Tracking

progress.txt

Human-readable log of all story completions:

[2026-02-01 10:15] S-001: Settings route - COMPLETE
[2026-02-01 10:32] S-002: Settings form - COMPLETE
[2026-02-01 10:45] S-003: Settings API - IN PROGRESS

prd.json Updates

After each story completes:

{
  "id": "S-001",
  "passes": true,
  "completedAt": "2026-02-01T10:15:00Z"
}

Error Handling

Colleague Mode

With --colleague-pause, after each story:

[RALPH] Story S-001 complete
Acceptance criteria verified:
- Route renders: ✓
- Nav link added: ✓

Continue to S-002? [Y/n/skip/quit]

Limitations

• No cross-story context: Each instance is fresh
• Sequential by default: Parallel requires multiple scripts
• JSON output parsing: Stories must signal completion clearly
• Git-based: Requires clean working directory

When NOT to Use

Boundary

Ralph executes user's decomposition, never creates its own.

• Before spawning: "I'll execute stories in this order: [...]. Adjust? [proceed/reorder]"
• Never auto-merge stories or resolve conflicts without asking
• Never make architectural decisions — decomposition is user's responsibility

Ralph orchestrates execution, not design.

Script Location

loop/scripts/moo-ralph.sh

Ensure executable: chmod +x loop/scripts/moo-ralph.sh