ralph-loop

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 → up

329stars38forksUpdated 8/13/2026

Data Science & ML Productivity & Workflow #spec-driven-development #workflow #developer-tools #python #automation

Security Assessment

Safe(92/100)

Security Score92/100

About ralph-loop

Ralph Loop is a specification-driven development automation skill that applies Geoffrey Huntley's "Ralph Wiggum as a Software Engineer" technique. It orchestrates the implement-review-fix-cleanup-sync cycle for spec tasks through a Python orchestrator script (`ralph_loop.py`) that runs a state machine, executing exactly one step per invocation and persisting all state to `fix_plan.json`. The problem it solves is context-window explosion: doing implementation, review, and syncing in a single invocation overwhelms the context, so each iteration performs one step, saves state, and stops so the next iteration can resume.

Crucially, the orchestrator does not execute task commands itself — it reads state, determines the current step, and prints the exact command for the user to run in their CLI, then advances state on the next invocation. The skill's own guidance is explicit that Bash should be used ONLY to run `ralph_loop.py` and never for arbitrary commands. It supports task-range filtering (`--from-task`/`--to-task`), multiple CLI environments (Claude Code, Codex, Copilot, Kimi) via an agent code, per-task agent overrides in task frontmatter, and actions for start, loop, status, and resume. Note that the SKILL.md header marks this version as deprecated in favor of a `ralph-loop-v2` command.

The target users are developers practicing spec-driven development who want step-by-step, context-managed automation across multiple task files and CLI agents. Use cases include iterating through a numbered range of spec tasks, coordinating multi-agent workflows, and running a recurring loop that shows the next command to execute at each step.

FAQ

How does the Ralph Loop manage context window limits?

Each invocation runs exactly one step of the state machine (init, choose_task, implementation, review, fix, cleanup, sync, update_done), saves state to fix_plan.json, and stops. The next invocation resumes from saved state, so no single run explodes the context.

Does the orchestrator run my task commands automatically?

No. The Python script generates and displays the correct command for your CLI, but you execute it yourself. The skill instructs that Bash should be used only to run ralph_loop.py, not arbitrary commands.

Which CLI agents are supported?

Claude Code, Codex CLI, Copilot CLI, and Kimi CLI. You set a default agent at start, and can override the agent per task via the task file's frontmatter. Command formatting adapts to each CLI's prefix conventions.

Can I run only a subset of tasks?

Yes. Use --from-task and --to-task to filter to a range (for example TASK-036 to TASK-041). The state file tracks range progress and picks the next pending task with satisfied dependencies.

Is this skill current?

The documentation marks this version as deprecated in favor of a newer ralph-loop-v2 command, and notes the old /specs:ralph-loop command will be removed. Migration is recommended.