--- name: ralph-loop-helper description: Guide for using \/ralph-loop command for long-running autonomous tasks. Use when starting iterative development loops, implementing Bedrock plugins, or running test-fix cycles. (project) allowed-tools: Read, Bash, Glob, Grep metadata: author: mineflayer-bedrock version: "1.0" --- # Ralph Loop Helper Guide users on effectively using `\/ralph-loop` for long-running autonomous tasks in the mineflayer-bedrock project. ## Overview The Ralph Wiggum plugin implements an iterative AI development loop. It uses a Stop hook that intercepts Claude's exit attempts, feeding the same prompt back to continue working until completion criteria are met. **Core mechanism**: You run `\/ralph-loop "task"` once. Claude works, tries to exit, the hook blocks it, re-feeds the prompt, and repeats until done. ## When to Use - Implementing a new Bedrock plugin that needs to match Java API - Running test suites and fixing all failures iteratively - Large refactoring tasks with clear completion criteria - Tasks with automatic verification (tests, linters, type checks) - Greenfield implementations with well-defined requirements ## When NOT to Use - Tasks requiring human judgment or design decisions - One-shot operations (single file edits, quick fixes) - Exploratory work with unclear success criteria - Production debugging requiring careful analysis - Tasks where you need to review intermediate results ## Known Limitations ### Multiline Prompts NOT Supported CLI arguments cannot contain newlines due to Bash security restrictions. These GitHub issues track this: - Issue #15640: Bash security blocks newlines - Issue #15712: Command contains newlines error - Issue #15824: Feature request for file-based prompts **Workaround**: Keep prompts single-line or use phased execution (see below). ### Exact String Matching Only `--completion-promise` uses exact string matching. You cannot use regex or multiple conditions like "SUCCESS OR BLOCKED". Use the `TAG<\/promise>` pattern for clarity. ### Token Consumption Each iteration consumes full context window tokens. A 50-iteration loop on a large codebase can cost $50-100+ in API credits. ## Recommended Patterns ### 1. Always Use --max-iterations This is your primary safety mechanism. Never rely solely on completion promises. ```bash \/ralph-loop "Your task..." --max-iterations 30 ``` ### 2. Use Promise Tags Wrap completion signals in tags for clear detection: ```bash \/ralph-loop "Build feature X. Output COMPLETE<\/promise> when done." --completion-promise "COMPLETE" --max-iterations 25 ``` ### 3. Include Stuck Handling Add escape instructions for when Claude gets stuck: ```bash \/ralph-loop "Implement feature. After 10 iterations without progress: document blockers, list attempts, suggest alternatives. Output BLOCKED<\/promise> if truly stuck, DONE<\/promise> if complete." --max-iterations 20 ``` ### 4. Phased Execution for Complex Tasks Break large tasks into phases instead of one massive prompt: ```bash # Phase 1 \/ralph-loop "Phase 1: Create data models. Output P1_DONE<\/promise>" --max-iterations 15 # Phase 2 \/ralph-loop "Phase 2: Implement API endpoints. Output P2_DONE<\/promise>" --max-iterations 20 # Phase 3 \/ralph-loop "Phase 3: Add tests, ensure all pass. Output P3_DONE<\/promise>" --max-iterations 25 ``` ## Project-Specific Examples ### Implement a Bedrock Plugin ```bash \/ralph-loop "Implement inventory.mts Bedrock plugin in lib\/bedrockPlugins\/ matching the Java API in lib\/plugins\/inventory.js. Map Bedrock packets to same bot behavior. Run 'npm run mocha_test' after changes. Output PLUGIN_COMPLETE<\/promise> when tests pass." --max-iterations 30 ``` ### Fix Test Failures ```bash \/ralph-loop "Run 'npm run test:bedrock'. Fix any failing tests. Do not skip tests. Output TESTS_PASS<\/promise> when all tests green." --max-iterations 20 ``` ### API Compatibility Check ```bash \/ralph-loop "Compare lib\/bedrockPlugins\/health.mts with lib\/plugins\/health.js. Ensure Bedrock version exposes same API (functions, events, properties). Fix discrepancies. Run tests. Output API_MATCH<\/promise> when compatible." --max-iterations 15 ``` ### Type Error Resolution ```bash \/ralph-loop "Run 'npx tsc --noEmit'. Fix all TypeScript errors. Do not use 'any' type. Output TYPES_CLEAN<\/promise> when no errors." --max-iterations 25 ``` ## Cost Awareness | Iterations | Estimated Cost | |------------|----------------| | 10-20 | $10-25 | | 30-50 | $30-75 | | 50+ | $50-150+ | **Tips to reduce costs**: - Start with lower `--max-iterations` and increase if needed - Use phased execution to checkpoint progress - Include clear completion criteria to exit early - Monitor iteration count in output ## Commands Reference ### \/ralph-loop Start an iterative development loop. ```bash \/ralph-loop "" --max-iterations --completion-promise "" ``` **Options**: - `--max-iterations `: Stop after N iterations (required for safety) - `--completion-promise `: Exact string that signals completion ### \/cancel-ralph Cancel an active Ralph loop immediately. ```bash \/cancel-ralph ``` ## Common Mistakes | Mistake | Prevention | |---------|------------| | No iteration limit | Always use `--max-iterations` | | Vague completion criteria | Use specific, testable conditions | | Multiline prompts | Keep single-line or use phases | | Relying only on promise | Set iteration limit as backup | | Too many iterations at once | Start small, increase if needed | ## Related Skills - `skill-builder`: For creating new Claude Code skills - `create-analyzer`: For packet analysis tasks