ralph-loop

⚠️ 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

File Location Requirements

⚠️ CRITICAL: The fix_plan.json file MUST ALWAYS be located in:

This 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:

Phase 2: Execute Loop Steps

Run the script with --action=loop to get the current state and the command to execute:

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:

This updates fix_plan.json to the next state (e.g., implementation → review).

Phase 4: Monitor Progress

Check status anytime with --action=status:

Quick Start

1. Initialize

2. Run Loop

The script will show you the command to execute. Run it, then run the loop again.

3. Check Status

Arguments

Step Details

Step 1: Initialize (--action=start)

The script:

1. Scans tasks/TASK-*.md files in the spec folder
2. Extracts metadata from YAML frontmatter (id, title, status, lang, dependencies, agent)
3. Applies --from-task and --to-task filters
4. Creates fix_plan.json with full state

Step 2: Choose Task (choose_task)

The script:

1. Finds pending tasks within range
2. Checks dependencies are satisfied
3. Selects next task
4. Updates fix_plan.json with current_task
5. Shows command to execute

Step 3: Implementation (implementation)

The script shows:

Step 4: Review (review)

The script shows:

Step 5: Fix (fix) - If Review Failed

If issues found, script shows fix instructions. After fixes, user runs loop again.

Step 6: Cleanup (cleanup)

The script shows:

Step 7: Sync (sync)

The script shows:

Step 8: Update Done (update_done)

The script:

1. Marks task as completed in fix_plan.json
2. Commits git changes (unless --no-commit)
3. Updates iteration count
4. Returns to choose_task

Multi-Agent Support

Default Agent for All Tasks

Per-Task Agent

Specify agent in task file YAML frontmatter:

Supported agents: claude, codex, copilot, kimi, gemini, glm4, minimax

Using with /loop (Claude Code)

For automatic scheduling every 5 minutes:

This will repeatedly run the loop, showing you the next command each time.

Note: The Ralph Loop is now managed directly through the Python script. The deprecated /developer-kit-specs:specs.ralph-loop command has been removed.

Task File Format

Each task should be a separate file: tasks/TASK-XXX.md

Examples

Example 1: Basic Usage

Example 2: With Claude Code /loop

Example 3: Multi-Agent Setup

Best Practices

• One step per invocation: Execute exactly one step, save state, stop
• Trust the state: Read from fix_plan.json, write to fix_plan.json
• No context accumulation: State lives in the file, not in context
• Manual command execution: The script shows commands; you execute them in your CLI
• Retry on review failure: Max 3 retries before failing
• Range filtering: Always filter by task_range
• Dependencies first: Only pick tasks where all dependencies are done
• Git commits: The script auto-commits after each completed task

Constraints and Warnings

• Context explosion: Do NOT implement + review + sync in one invocation — context will overflow
• Max retries: Review failures retry up to 3 times, then fail
• Git state: Ensure clean git state before starting
• Test infrastructure: Loop requires tests to pass — without tests, backpressure is ineffective
• Strict state validation: Valid state.step values are ONLY: init, choose_task, implementation, review, fix, cleanup, sync, update_done, complete, failed
• NO automatic command execution: The script shows commands but does NOT execute them — you must run them in your CLI

Troubleshooting

"fix_plan.json not found"

Run --action=start first:

The script will create fix_plan.json in the correct location:

"fix_plan.json in wrong location"

If you see a warning about the file being in the wrong location, the script will guide you through migration:

The script will automatically migrate old files on first run.

"Invalid spec folder"

Run --action=start first:

Task files not found

Ensure tasks are in tasks/TASK-XXX.md format with YAML frontmatter.

Wrong agent commands

Check --agent parameter or task agent: frontmatter field.

References

• references/state-machine.md - Complete state machine documentation
• references/multi-cli-integration.md - Multi-CLI setup guide
• references/loop-prompt-template.md - Prompt template for shell loops