camone-ralph-loop

External Ralph Loop implementation faithful to Geoffrey Huntley's methodology: a bash while true loop that spawns fresh claude -p sessions, ensuring each iteration starts with a clean context window.

Key Difference from Official Plugin

Operating Modes

Simple Mode (default, backward-compatible)

Single PROMPT.md file drives the loop. Best for focused, well-scoped tasks.

camone-ralph-loop.sh --max-iterations 10 PROMPT.md

Full Ecosystem Mode

Geoffrey Huntley's document ecosystem with separate Plan and Build phases. Best for large, multi-task projects.

# Phase 1: Plan — analyzes specs, generates fix_plan.md
camone-ralph-loop.sh --mode plan --max-iterations 3

# Phase 2: Build — implements one task per iteration
camone-ralph-loop.sh --mode build --max-iterations 20 --completion-promise "ALL TESTS PASSING" --auto-commit

Document Ecosystem — Geoffrey Huntley Method (Full Ecosystem Mode)

For detailed principles, see references/geoffrey-principles.md.

specs/*.md — Specifications (Immutable)

One file per concern (JTBD — Job To Be Done). Claude reads but NEVER modifies these.

fix_plan.md — Progress Tracker (Mutable)

Generated by Plan Loop. Tracks task status, priorities, and dependencies. Updated by Build Loop as tasks complete.

AGENT.md — Self-Learning Document (Mutable)

Operational knowledge Claude discovers during iterations: build quirks, codebase conventions, environment notes. NOT progress notes.

PROMPT_plan.md / PROMPT_build.md — Master Prompts

Phase-specific prompts. --mode plan auto-loads PROMPT_plan.md, --mode build auto-loads PROMPT_build.md. Templates available in assets/templates/.

Workflow

Phase 0: Interview & Setup

PROMPT quality = Ralph Loop output quality. Always interview before running.

Simple Mode

1. Understand intent: Grasp what the user wants to build
2. Deep-dive with AskUserQuestion: Requirements, tech stack, file structure, verification commands, edge cases, completion criteria
3. Explore existing code: Use Glob/Grep/Read to understand patterns
4. Generate PROMPT.md: High-quality prompt following the required structure (see below)
5. User confirmation: Show and get approval

Full Ecosystem Mode (7 steps)

1. Interview: Same as Simple Mode, plus ask about spec decomposition — how many distinct concerns exist?
2. Generate specs/*.md: One file per JTBD. Each spec is immutable once approved.
3. Initialize AGENT.md: Generate from template (assets/templates/AGENT.md.template), pre-fill build/test/lint commands
4. Generate PROMPT_plan.md: Use assets/templates/PROMPT_plan.md.template as reference, fill project-specific values
5. Generate PROMPT_build.md: Use assets/templates/PROMPT_build.md.template as reference, fill project-specific values
6. User review: Present all documents for approval
7. Execution guidance: Recommend "Run Plan Loop first (2-3 iterations), then Build Loop"

Phase 1: Plan Loop (Full Ecosystem Mode only)

"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --mode plan --max-iterations 3

Each iteration reads specs/*.md and generates/refines fix_plan.md. Stops on <promise>PLAN COMPLETE</promise>.

Phase 2: Build Loop

Simple Mode: Uses PROMPT.md directly.

"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --max-iterations 20 --completion-promise "ALL TESTS PASSING" PROMPT.md

Full Ecosystem Mode: Each iteration picks ONE task from fix_plan.md.

"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --mode build --max-iterations 20 --completion-promise "ALL TESTS PASSING" --auto-commit

Options:

• --mode plan|build — Full Ecosystem Mode: auto-select prompt file
• --max-iterations N — Stop after N iterations (default: unlimited)
• --completion-promise TEXT — Stop on <promise>TEXT</promise> detection
• --auto-commit — Git commit after each iteration
• --budget-per-iteration N — USD cap per iteration (passed as --max-cost to claude)
• --timeout-per-iteration SECS — Timeout per iteration in seconds (default: 300)
• --dry-run — Preview config without running
• --log-dir DIR — Log location (default: .ralph-loop/logs/)

Important: Always run --dry-run first to verify config before actual execution.

Phase 3: Monitor

• Logs: .ralph-loop/logs/iteration-NNN.log
• State: .ralph-loop/state.json
• Completion: macOS notification sound + speech

Phase 4: Cancel

Kill the process (Ctrl+C or kill). The script traps both SIGINT and SIGTERM and cleans up child claude processes.

PROMPT.md Required Structure (Simple Mode)

# Task
[Specific task description]

# Requirements
[Functional and non-functional requirements]

# Tech Stack
[Languages, libraries, frameworks]

# File Structure
[File paths to create or modify — use absolute paths]

# Verification
[Test commands and verification steps]
Example: cd /path/to/project && pnpm test

# Completion
[Completion criteria]
When ALL tests pass, output exactly: <promise>ALL TESTS PASSING</promise>

Quality checklist (verify before generating)

• Task is specific and unambiguous
• File paths are absolute
• Verification commands are executable as-is
• Completion criteria use <promise> tag
• Content is self-contained for claude -p (no conversation context dependency)

Usage Examples

Simple Mode

# Dry run
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --dry-run --max-iterations 10 PROMPT.md

# Run with completion promise
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" \
  --max-iterations 20 \
  --completion-promise "ALL TESTS PASSING" \
  --auto-commit \
  PROMPT.md

# Quick inline prompt
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" \
  --max-iterations 5 \
  "Refactor auth module. Output <promise>DONE</promise> when complete."

Full Ecosystem Mode

# Step 1: Plan phase dry run
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --dry-run --mode plan --max-iterations 3

# Step 2: Run plan phase
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --mode plan --max-iterations 3

# Step 3: Build phase dry run
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" --dry-run --mode build --max-iterations 20 --completion-promise "ALL TESTS PASSING"

# Step 4: Run build phase
"${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh" \
  --mode build \
  --max-iterations 20 \
  --completion-promise "ALL TESTS PASSING" \
  --auto-commit

Generated Files

.ralph-loop/
  state.json              # Loop state (active/completed, iteration count, mode)
  logs/
    iteration-001.log     # Each iteration's claude output
    iteration-002.log
    ...

.ralph-loop/ is auto-added to .gitignore on first run.

Troubleshooting

• Script not found: Verify ${CLAUDE_SKILL_ROOT}/scripts/camone-ralph-loop.sh exists and is executable
• "Cannot launch inside another session": The script uses env -u CLAUDECODE to handle this automatically. If it still fails, run from a standalone terminal
• Orphan claude processes: The script tracks child PIDs and kills them on SIGINT/SIGTERM. If manually killed with SIGKILL (kill -9), child processes may survive — use ps aux | grep 'claude.*-p' | grep -v grep to find and kill them
• PROMPT_plan.md not found: When using --mode plan, ensure you've run Phase 0 to generate the prompt file, or specify an explicit prompt path