/ralph-loop

name: ralph-loop
description: "Ralph Wiggum-inspired automation loop for specification-driven development. Orchestrates task implementation, review, cleanup, and synchronization using a Python script. Use when: user runs /loop command, user asks to automate task implementation, user wants to iterate through spec tasks step-by-step, or user wants to run development workflow automation with context window management. One step per invocation. State machine: init → choose_task → implementation → review → fix → cleanup → sync → update_done. Supports --from-task and --to-task for task range filtering. State persisted in fix_plan.json."
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite

> **⚠️ 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 `/loop` command 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:** 1. Run `ralph_loop.py --action=loop` 2. Script reads `fix_plan.json` and determines current step 3. Script shows the command to execute (e.g., `/developer-kit-specs:specs.task-implementation`) 4. User executes the command in their CLI 5. User runs `ralph_loop.py --action=loop` again 6. 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