Ralph Guide

Quick reference for operating Choo Choo Ralph across all workflow phases.

The Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   1. Plan   │ ──▶ │  2. Spec    │ ──▶ │  3. Pour    │ ──▶ │  4. Ralph   │ ──▶ │ 5. Harvest  │
│    (you)    │     │  (you + AI) │     │    (AI)     │     │    (AI)     │     │ (you + AI)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

1. •Plan - Write what you want to build (this is on you)
2. •Spec - AI transforms it into structured tasks; you review and refine
3. •Pour - Tasks become beads (workflow or singular)
4. •Ralph - The loop runs autonomously until done
5. •Harvest - Extract learnings into skills, docs, or CLAUDE.md

See ${CLAUDE_PLUGIN_ROOT}/docs/workflow.md for the complete guide.

Prerequisites & Safety

Required:

• •Claude Code - Anthropic's CLI
• •Beads - Git-backed issue tracker (bd command)
• •jq - JSON parsing

Recommended:

• •dev-browser - Browser automation for UI verification

Safety: Ralph runs with --dangerously-skip-permissions. Run in a Docker container or VM, especially for untrusted codebases.

Install

/choo-choo-ralph:install

Creates local copies you can customize:

Spec Phase

Generate a Spec

/choo-choo-ralph:spec [source-file] [spec-name]

• •From plan file: /choo-choo-ralph:spec plans/my-feature.md
• •From conversation: /choo-choo-ralph:spec (uses context)
• •With explicit name: /choo-choo-ralph:spec plans/feature.md auth-system

Specs are stored at .choo-choo-ralph/{spec-name}.spec.md

Spec Format

Tasks use XML-like tags with a review workflow:

<task id="add-login-form" priority="1" category="functional">
  <title>Add Login Form Component</title>
  <description>Create a reusable login form...</description>
  <steps>
    1. Create LoginForm component
    2. Add validation
  </steps>
  <test_steps>
    1. Verify form renders
    2. Test validation
  </test_steps>
  <review></review>  <!-- Empty = ready to pour -->
</task>

Review Process

1. •Add feedback in <review> tags:
   xml

   <review>Split this into two tasks: validation and submission</review>
   

2. •Run /choo-choo-ralph:spec again - AI processes feedback
3. •Repeat until all <review> tags are empty

Common review patterns:

• •Split: <review>Split into: schema creation, indexes, migration</review>
• •Add detail: <review>Add step for handling duplicate emails</review>
• •Remove: <review>Remove - already exists in utils/</review>
• •Combine: <review>Merge with task-xyz, too small separately</review>

See ${CLAUDE_PLUGIN_ROOT}/docs/spec-format.md for complete format reference.

Pour Phase

Convert Spec to Beads

/choo-choo-ralph:pour [target-tasks] [spec-file] [formula]

Examples:

• •Auto-detect everything: /choo-choo-ralph:pour
• •Target 80 tasks: /choo-choo-ralph:pour 80
• •Specific spec and formula: /choo-choo-ralph:pour 80 auth-system choo-choo-ralph

Modes

Workflow Formula (recommended) - Multi-step process per task:

bearings → implement → verify → commit

Singular Tasks - Direct execution without phases (for research, prototyping)

What Happens

1. •Tasks created as beads in .beads/issues/
2. •Spec's poured array updated with bead IDs
3. •Spec archived to .choo-choo-ralph/archive/
4. •Tasks ready for Ralph

See ${CLAUDE_PLUGIN_ROOT}/docs/commands.md for all options.

Ralph Loop

Running Ralph

./ralph.sh              # Default iterations
./ralph.sh 50           # Run up to 50 tasks
./ralph.sh --verbose    # Detailed output
./ralph.sh 20 -v        # 20 iterations, verbose

Test before a long run:

./ralph-once.sh         # Exactly one iteration

How It Works

while [ $iteration -lt $MAX_ITERATIONS ]; do
    available=$(bd list --status=open --assignee=ralph --json | jq -r 'length')
    [ "$available" -eq 0 ] && exit 0

    claude --dangerously-skip-permissions --output-format stream-json -p "
      Run bd list --status=open --assignee=ralph to see available tasks.
      Pick one, claim with bd update <id> --status in_progress, then execute.
    " | ./ralph-format.sh
done

Key insights:

• •Uses --status=open to filter out in_progress tasks
• •Multiple Ralphs can run in parallel - each only sees unclaimed work
• •Beads provide persistent memory per task

Core Concepts

Formula: TOML template defining a workflow (steps, dependencies, prompts) Molecule: Instance of a formula (actual beads with real tasks)

Default choo-choo-ralph formula has 4 steps:

1. •bearings - Health check and codebase understanding
2. •implement - Make changes
3. •verify - Run tests/types
4. •commit - Create git commit

Orchestrator Pattern: When Ralph picks up a molecule root:

1. •Spawns sub-agents for each step
2. •Steps execute in dependency order
3. •Progress tracked via comments
4. •Closes when all steps complete

Viewing Progress

bd show <root-id>              # See molecule structure
bd ready --assignee ralph      # What's ready for work
bd blocked                     # What's waiting
bd comments <id>               # Read progress notes
bd list --status in_progress   # Currently active tasks

Running Multiple Ralphs

Multiple instances run safely in parallel:

# Terminal 1
./ralph.sh

# Terminal 2
./ralph.sh

• •Each claims work by setting in_progress
• •Won't double-pick same task
• •Need multiple ready molecules

Start with 2, scale to 3-4 if stable. Rarely need more than 4-5.

Error Handling

Key principle: steps report back to orchestrator, orchestrator makes state changes.

Verification Failures

When verify finds issues:

1. •Small fixes → Verify fixes inline and re-verifies
2. •Significant issues → Verify reports STATUS: FAIL to orchestrator
3. •Orchestrator handles rework → Reopens implement with [REWORK] comment
4. •Attempt tracking → [attempt-N] comments log each failure
5. •After 3 failures → Molecule marked [CRITICAL] and blocked

Health Check Failures

When bearings finds the app already broken:

1. •Bearings reports STATUS: HEALTH_CHECK_FAILED
2. •Orchestrator creates bug bead via bug-fix formula
3. •Current molecule blocked on the bug bead
4. •Once fixed, original molecule becomes ready again

Blocked Beads

After 3 failed attempts:

1. •Orchestrator blocks itself: bd update <id> --status blocked
2. •Loop continues - blocked beads don't appear in bd ready
3. •Other work continues unaffected

Manual resolution:

bd list --status=blocked       # Find blocked beads
bd comments <bead-id>          # Review what went wrong
bd update <bead-id> --status open   # Reopen for retry
# or
bd close <bead-id> --reason "Fixed manually"

See ${CLAUDE_PLUGIN_ROOT}/docs/troubleshooting.md for recovery procedures.

Harvest Phase

Capturing Learnings

Agents capture insights as they work using comment tags:

• •[LEARNING] - Useful discoveries (patterns, gotchas, conventions)
• •[GAP] - Missing work or incomplete implementations

Example comments on a completed bead:

[bearings] This codebase uses barrel exports - import from index.ts
[implement] shadcn Button requires forwardRef when wrapping
[GAP] Missing input validation for user registration API
[summary] Completed: Add settings page. Recommendation: Consider skill for shadcn patterns.

Running Harvest

/choo-choo-ralph:harvest

The harvest workflow:

1. •Finds beads with learnings label (not yet learnings-harvested)
2. •Analyzes comments for patterns and gaps
3. •Creates a harvest plan for review
4. •On approval, creates artifacts and marks beads learnings-harvested

Artifact types:

• •Skills - Patterns that should auto-trigger
• •CLAUDE.md - Critical project guidance
• •Reference docs - Technology-specific documentation
• •Gap tasks - New beads for approved gaps

Labels

Query by label:

bd list --label learnings --no-label learnings-harvested

Customization

All installed files are yours to modify.

Shell Scripts

ralph.sh customization points:

• •MAX_ITERATIONS=100 - Default iteration limit
• •The prompt passed to claude -p - Add project-specific guidance
• •Task sorting: --sort=priority vs --sort=created

ralph-format.sh:

• •Colors and output formatting
• •What gets shown for each tool type

Formulas

Edit .beads/formulas/choo-choo-ralph.formula.toml:

• •Add/remove steps
• •Modify step prompts
• •Change assignee patterns
• •Add conditional steps

Creating custom formulas:

formula = "quick-task"
description = """Instructions for the task..."""
version = 1

[vars]
title = ""
task = ""

[[steps]]
id = "implement"
title = "{{title}}"
assignee = "ralph-subagent-implement"
description = """Step instructions..."""

Assignee Conventions

See ${CLAUDE_PLUGIN_ROOT}/docs/customization.md for complete guide. See ${CLAUDE_PLUGIN_ROOT}/docs/formulas.md for formula reference.

Troubleshooting

Common Issues

Tasks not being picked up:

bd show <bead-id>                    # Check status and assignee
bd update <bead-id> --assignee ralph # Assign to Ralph
bd update <bead-id> --status open    # Set status
bd dep <bead-id>                     # Check for blockers

Health check always failing:

1. •Stop Ralph
2. •Run checks manually: npm test, npm run build, npm run lint
3. •Fix all failures
4. •Resume Ralph

Infinite retry loop:

bd update <bead-id> --status blocked  # Block manually
bd comments <bead-id>                 # Review all attempts
# Fix underlying issue, then:
bd update <bead-id> --status open     # Reopen when ready

Recovery Procedures

Re-pour a spec:

1. •Move spec from archive: mv .choo-choo-ralph/archive/spec.md .choo-choo-ralph/
2. •Delete existing beads (IDs in spec's poured array)
3. •Clear poured: [] in frontmatter
4. •Run /choo-choo-ralph:pour

Session recovery (mid-task crash):

bd list --status=in_progress --assignee=ralph  # Find in-progress task
bd comments <bead-id>                          # Review progress
bd update <bead-id> --status open              # Reopen to retry

Debugging

./ralph-once.sh          # Test single iteration
./ralph.sh -v            # Verbose output
bd comments <bead-id>    # View task history
bd show <root-id>        # Inspect molecule structure

See ${CLAUDE_PLUGIN_ROOT}/docs/troubleshooting.md for complete guide.

Documentation

• •${CLAUDE_PLUGIN_ROOT}/docs/workflow.md - Complete workflow guide
• •${CLAUDE_PLUGIN_ROOT}/docs/spec-format.md - Spec file format reference
• •${CLAUDE_PLUGIN_ROOT}/docs/commands.md - All commands with examples
• •${CLAUDE_PLUGIN_ROOT}/docs/formulas.md - Formula reference and customization
• •${CLAUDE_PLUGIN_ROOT}/docs/customization.md - Customizing Ralph for your project
• •${CLAUDE_PLUGIN_ROOT}/docs/troubleshooting.md - Common issues and solutions

Commands