Guides customization of Choo Choo Ralph workflows, formulas, learning harvest, troubleshooting loops, and multi-Ralph setups. Use for Ralph-specific questions.
From choo-choo-ralphnpx claudepluginhub mj-meyer/choo-choo-ralphThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Quick reference for operating Choo Choo Ralph across all workflow phases.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 1. Plan │ ──▶ │ 2. Spec │ ──▶ │ 3. Pour │ ──▶ │ 4. Ralph │ ──▶ │ 5. Harvest │
│ (you) │ │ (you + AI) │ │ (AI) │ │ (AI) │ │ (you + AI) │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
See ${CLAUDE_PLUGIN_ROOT}/docs/workflow.md for the complete guide.
Required:
bd command)Recommended:
Safety: Ralph runs with --dangerously-skip-permissions. Run in a Docker container or VM, especially for untrusted codebases.
/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 |
/choo-choo-ralph:spec [source-file] [spec-name]
/choo-choo-ralph:spec plans/my-feature.md/choo-choo-ralph:spec (uses context)/choo-choo-ralph:spec plans/feature.md auth-systemSpecs are stored at .choo-choo-ralph/{spec-name}.spec.md
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> tags:
<review>Split this into two tasks: validation and submission</review>
/choo-choo-ralph:spec again - AI processes feedback<review> tags are emptyCommon review patterns:
<review>Split into: schema creation, indexes, migration</review><review>Add step for handling duplicate emails</review><review>Remove - already exists in utils/</review><review>Merge with task-xyz, too small separately</review>See ${CLAUDE_PLUGIN_ROOT}/docs/spec-format.md for complete format reference.
/choo-choo-ralph:pour [target-tasks] [spec-file] [formula]
Examples:
/choo-choo-ralph:pour/choo-choo-ralph:pour 80/choo-choo-ralph:pour 80 auth-system choo-choo-ralphWorkflow Formula (recommended) - Multi-step process per task:
bearings → implement → verify → commit
Singular Tasks - Direct execution without phases (for research, prototyping)
.beads/issues/poured array updated with bead IDs.choo-choo-ralph/archive/See ${CLAUDE_PLUGIN_ROOT}/docs/commands.md for all options.
./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
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:
--status=open to filter out in_progress tasksFormula: 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:
Orchestrator Pattern: When Ralph picks up a molecule root:
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
Multiple instances run safely in parallel:
# Terminal 1
./ralph.sh
# Terminal 2
./ralph.sh
in_progressStart with 2, scale to 3-4 if stable. Rarely need more than 4-5.
Key principle: steps report back to orchestrator, orchestrator makes state changes.
When verify finds issues:
STATUS: FAIL to orchestrator[REWORK] comment[attempt-N] comments log each failure[CRITICAL] and blockedWhen bearings finds the app already broken:
STATUS: HEALTH_CHECK_FAILEDbug-fix formulaAfter 3 failed attempts:
bd update <id> --status blockedbd readyManual 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.
Agents capture insights as they work using comment tags:
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.
/choo-choo-ralph:harvest
The harvest workflow:
learnings label (not yet learnings-harvested)learnings-harvestedArtifact types:
| 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
All installed files are yours to modify.
ralph.sh customization points:
MAX_ITERATIONS=100 - Default iteration limitclaude -p - Add project-specific guidance--sort=priority vs --sort=createdralph-format.sh:
Edit .beads/formulas/choo-choo-ralph.formula.toml:
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..."""
| 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.
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:
npm test, npm run build, npm run lintInfinite 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
Re-pour a spec:
mv .choo-choo-ralph/archive/spec.md .choo-choo-ralph/poured array)poured: [] in frontmatter/choo-choo-ralph:pourSession 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
./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.
${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| 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 |