⚠️ WARNING: This skill was deprecated in favor of a new command ralph-loop-v2 that uses a Python orchestrator script.
The old /specs:ralph-loop command will be removed soon. Please migrate to the new command.
Ralph Loop — Python Orchestrator
⚠️ IMPORTANT: This skill uses a Python orchestrator script. Do NOT execute arbitrary bash commands. Use Bash ONLY to run ralph_loop.py. All task commands (like /developer-kit-specs:specs.task-implementation) are shown to the user to execute manually.
Overview
The Ralph Loop applies Geoffrey Huntley's "Ralph Wiggum as a Software Engineer" technique to specification-driven development. It uses a Python orchestrator script that manages a state machine: one invocation = one step, state persisted in fix_plan.json.
Key insight: Implementing + reviewing + syncing in one invocation explodes the context window. Solution: each loop iteration does exactly one step, saves state to fix_plan.json, and stops. The next iteration resumes from saved state.
Key improvement: The Python script ralph_loop.py handles all state management, task selection, and command generation. It does NOT execute task commands directly — it shows you the correct command to execute in your CLI.
When to Use
- User runs
/loopcommand for recurring automation - User asks to "automate implementation" or "run tasks in loop"
- User wants to "iterate through tasks step-by-step" or "run workflow automation"
- User needs "context window management" across multiple SDD commands
- User wants to "process task range" from TASK-N to TASK-M
- User needs multi-agent support (different CLIs for different tasks)
Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ralph_loop.py │────▶│ fix_plan.json │────▶│ User executes │
│ (orchestrator)│ │ (state file) │ │ command in CLI │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ ▼
│ ┌─────────────────┐
└──────────────────────────────────────│ Task result │
│ (success/ │
│ failure) │
└─────────────────┘One Step Flow:
- Run
ralph_loop.py --action=loop - Script reads
fix_plan.jsonand determines current step - Script shows the command to execute (e.g.,
/developer-kit-specs:specs.task-implementation) - User executes the command in their CLI
- User runs
ralph_loop.py --action=loopagain - Script updates state based on result and shows next command
State Machine
fix_plan.json state machine:
┌─────────────────────────────────────────────────────────────┐
│ state: "init" │
│ → --action=start: Initialize fix_plan.json │
│ → Load tasks from tasks/TASK-*.md files │
│ → Apply task_range filter │
│ │
│ state: "choose_task" │
│ → Pick next pending task (within range, deps satisfied)│
│ → No tasks in range → state: "complete" │
│ → Task found → state: "implementation" │
│ │
│ state: "implementation" │
│ → Show /developer-kit-specs:specs.task-implementation command │
│ → User executes, then runs loop again │
│ → Next state: "review" │
│ │
│ state: "review" ││ → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│},{find: │
│ → User reviews results, then runs loop again │
│ → Issues found → state: "fix" (retry ≤ 3) │
│ → Clean → state: "cleanup" │
│ │
│ state: "fix" │
│ → Show commands to fix issues │
│ → User applies fixes, then runs loop again │
│ → Next state: "review" │
│ │
│ state: "cleanup" │
│ → Show /developer-kit-specs:specs.task-implementation --action=cleanup command│
│ → Next state: "sync" │
│ │
│ state: "sync" │
│ → Show /developer-kit-specs:specs.sync command │
│ → Next state: "update_done" │
│ │
│ state: "update_done" │
│ → Mark task done, commit git changes │
│ → Re-evaluate dependencies │
│ → state: "choose_task" │
│ │
│ state: "complete" | "failed" │
│ → Print result, stop │
└─────────────────────────────────────────────────────────────┘File Location Requirements
⚠️ CRITICAL: The fix_plan.json file MUST ALWAYS be located in:
docs/specs/[ID-feature]/_ralph_loop/fix_plan.jsonThis is enforced by the script to prevent LLMs from creating files in wrong locations.
Migration: If you have an old fix_plan.json in the root of your spec folder, the script will automatically migrate it to _ralph_loop/ on first run.
Instructions
Phase 1: Initialize
Run the Python script with --action=start to scan task files and create fix_plan.json in the correct location:
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=start \
--spec=docs/specs/001-feature/ \
--from-task=TASK-036 \
--to-task=TASK-041Phase 2: Execute Loop Steps
Run the script with --action=loop to get the current state and the command to execute:
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=loop \
--spec=docs/specs/001-feature/The script will show you the exact command to execute for the current step. Execute it in your CLI, then run the loop command again.
Phase 3: Advance State (Manual)
After executing the shown command, manually advance to the next step:
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=next \
--spec=docs/specs/001-feature/This updates fix_plan.json to the next state (e.g., implementation → review).
Phase 4: Monitor Progress
Check status anytime with --action=status:
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=status \
--spec=docs/specs/001-feature/Quick Start
1. Initialize
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=start \
--spec=docs/specs/001-feature/ \
--from-task=TASK-036 \
--to-task=TASK-041 \
--agent=claude2. Run Loop
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=loop \
--spec=docs/specs/001-feature/The script will show you the command to execute. Run it, then run the loop again.
3. Check Status
python3 plugins/developer-kit-specs/skills/ralph-loop/scripts/ralph_loop.py \
--action=status \
--spec=docs/specs/001-feature/