Ralph Bridge

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

When to Use

| Situation | Recommendation | |-----------|----------------| | Single story, clear scope | /loop:start | | 2-5 related stories | /loop:prd with dependencies | | N>5 stories, independent | Ralph Bridge | | Long-running feature (days) | Ralph Bridge | | Context exhaustion risk | Ralph Bridge |

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

prd.json — Structured PRD with stories
Git branch — Feature branch for all work
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]

| Option | Description | |--------|-------------| | max_iterations | Default 50. Total Claude invocations allowed. | | --colleague-pause | Pause after each story for human review. |

Execution Flow

Per-Story Protocol

Pre-Flight Check
- Verify prd.json exists
- Verify git branch matches
- Check no uncommitted changes
Story Selection
- Find first story with passes: false
- Verify blockedBy stories all pass
- Skip blocked stories
Silent Audit (per story)
- Score spec (should be ≥8 for well-written PRD)
- Calculate fit score
- Determine workflow shape
Must-NOT Extraction
- Parse story context for constraints
- Add to circuit breaker triggers
Execute
- Fresh Claude instance
- Full context window available
- Work on single story
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

| Situation | Action | |-----------|--------| | Story fails 3x consecutively | Pause, request human intervention | | Dependency not met | Skip to next available story | | Git conflict | Pause, require manual resolution | | Budget exceeded | Pause with progress summary |

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]

| Response | Action | |----------|--------| | Y (default) | Continue to next story | | n | Re-run current story | | skip | Mark as skipped, move to next | | quit | Stop orchestration |

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

| Situation | Why Not | Alternative | |-----------|---------|-------------| | Stories are interdependent | Context loss hurts | /loop:prd | | Rapid iteration needed | Script overhead | /loop:start | | Debug/investigation | Fresh context loses findings | Standard loop | | < 5 stories | Overhead not worth it | /loop:prd |

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