ralph-guide

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:

File	Purpose
./ralph.sh	Main loop script
./ralph-once.sh	Single iteration (for testing)
./ralph-format.sh	Output formatting
.beads/formulas/choo-choo-ralph.formula.toml	Standard workflow formula
.beads/formulas/bug-fix.formula.toml	Bug fix workflow formula
.choo-choo-ralph/	Spec file directory

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:

   <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

Label	Meaning
learnings	Bead has recommendations worth harvesting
learnings-harvested	Learnings have been processed
gaps	Contains identified gaps
gaps-harvested	Gaps have been processed

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

Prefix	Execution
ralph	Picked up by Ralph loop
ralph-subagent-*	Spawned as sub-agent
ralph-inline-*	Executed by orchestrator directly

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

Command	Purpose
/choo-choo-ralph:install	Set up Ralph in project
/choo-choo-ralph:spec	Generate/refine spec from plan
/choo-choo-ralph:pour	Create beads from spec
/choo-choo-ralph:harvest	Extract learnings
./ralph.sh	Run Ralph loop
./ralph-once.sh	Run single task