ralph-bridge

# 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

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

### prd.json Format

```json
{
  "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"