🔄 speckit-ralph

Iterative execution engine for SPEC-KIT.

Automate the Ralph Wiggum Loop for Spec-Driven Development workflows.

---

Table of Contents

• 🤔 What is speckit-ralph?
• ⚡ Quick Start
• 📽️ How It Works
• 🤖 Supported AI Agents
• 🔧 CLI Reference
• 🛡️ Guardrails (Signs)
• 📊 Activity Logging
• ⚙️ Environment Variables
• 🔍 Troubleshooting
• 📖 Learn More
• 📄 License

🤔 What is speckit-ralph?

SPEC-KIT is GitHub's official toolkit for Spec-Driven Development — a structured approach where specifications become executable, directly generating working implementations.

While SPEC-KIT's /speckit.implement runs tasks once, speckit-ralph automates the iterative loop:

1. Reads tasks from specs/<branch>/tasks.md
2. Feeds them to your AI agent (Claude Code or Codex)
3. Runs multiple iterations until completion
4. Tracks progress, learns from failures, applies guardrails

Think of it as: SPEC-KIT defines the "what" and "how", Ralph executes the "do" repeatedly until done.

⚡ Quick Start

Prerequisites

1. SPEC-KIT installed and initialized in your project
2. Spec workflow complete: spec.md, plan.md, tasks.md exist in specs/<branch>/
3. Feature branch matching your spec directory (e.g., feature/auth → specs/feature/auth/)

Installation

uv tool install speckit-ralph --from git+https://github.com/merllinsbeard/speckit-ralph.git

Usage

# 1. Checkout your feature branch
git checkout feature/my-feature

# 2. Initialize Ralph (creates .speckit-ralph/ directory)
speckit-ralph init

# 3. Run the loop
speckit-ralph once --agent claude      # Single iteration (review each step)
speckit-ralph loop 10 --agent claude   # Multiple iterations (AFK mode)

Optional: Inspect the prompt

# See what Ralph will send to the AI agent
speckit-ralph build-prompt

# Save to file for review
speckit-ralph build-prompt --output prompt.md

New to SPEC-KIT?

If you haven't set up SPEC-KIT yet:

# Install SPEC-KIT
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Initialize in your project
specify init . --here --ai claude

# Create spec workflow (in Claude Code)
/speckit.specify    # Create specifications
/speckit.plan       # Create implementation plan
/speckit.tasks      # Generate task breakdown

# Then install and run Ralph
uv tool install speckit-ralph --from git+https://github.com/merllinsbeard/speckit-ralph.git
speckit-ralph init
speckit-ralph loop 10 --agent claude

📽️ How It Works

┌─────────────────────────────────────────────────────────────┐
│                    SPEC-KIT Phase                           │
│                   (Human-Guided)                            │
├─────────────────────────────────────────────────────────────┤
│  /speckit.specify  →  specs/<branch>/spec.md               │
│  /speckit.plan     →  specs/<branch>/plan.md               │
│  /speckit.tasks    →  specs/<branch>/tasks.md              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    Ralph Phase                              │
│                  (Automated Loop)                           │
├─────────────────────────────────────────────────────────────┤
│  speckit-ralph loop 10 --agent claude                       │
│    ├─ AI reads tasks.md, spec.md, plan.md                  │
│    ├─ AI implements one task per iteration                 │
│    ├─ AI sees previous work via git history (self-ref)     │
│    └─ Loop continues until:                                │
│        ├─ All tasks complete                               │
│        ├─ <promise>COMPLETE</promise> detected             │
│        └─ Max iterations reached                           │
└─────────────────────────────────────────────────────────────┘

🤖 Supported AI Agents

Agent	CLI	Status
Claude Code	claude	✅
Codex CLI	codex	✅
Droid	droid	✅
OpenCode	opencode	✅

🔧 CLI Reference

Commands

Command	Description
speckit-ralph once	Run a single iteration
speckit-ralph loop <N>	Run N iterations
speckit-ralph init	Initialize .speckit-ralph directory
speckit-ralph show-guardrails	Display guardrails
speckit-ralph show-activity	Display activity log
speckit-ralph show-errors	Display errors log
speckit-ralph build-prompt	Generate prompt for inspection
speckit-ralph scripts-path	Print bundled scripts path

Options

Option	Commands	Description
--agent, -a	once, loop	Required. Agent: claude, codex, droid, or opencode
--keep-artifacts, -k	once, loop	Keep temp files for debugging
--promise, -p	once, loop	Completion promise string
--detach, -d	loop	Run in background
--sleep, -s	loop	Seconds between iterations
--spec, -S	once, loop, build-prompt	Spec directory path (overrides branch detection)
--root, -r	init, show-activity, show-errors, show-guardrails	Project root directory
--lines, -n	show-activity, show-errors	Number of lines to show (default: 50)
--output, -o	build-prompt	Output file path

Examples

# Single iteration with Claude
speckit-ralph once --agent claude

# Single iteration with Codex
speckit-ralph once --agent codex

# 10 iterations with Claude, keep artifacts
speckit-ralph loop 10 --agent claude --keep-artifacts

# Run Codex in background
speckit-ralph loop 20 --agent codex --detach

# Custom sleep between iterations
speckit-ralph loop 10 --agent claude --sleep 5

# Multi-spec: explicitly specify which spec to use
speckit-ralph loop 5 --agent claude --spec specs/feature/auth
speckit-ralph once --agent codex --spec specs/feature/payments

Multi-Spec Projects

By default, Ralph detects which spec to use based on your current git branch name (e.g., feature/auth maps to specs/feature/auth/).

For projects with multiple specs, you can explicitly specify which spec to use:

# Override branch detection with --spec
speckit-ralph loop 10 --agent claude --spec specs/feature/auth

# Use relative path from repo root
speckit-ralph once --agent codex --spec specs/feature/payments

# Or absolute path
speckit-ralph loop 5 --agent claude --spec /path/to/my-project/specs/feature/checkout

When to use --spec:

• Working on a different spec than your current branch
• Running multiple loops in parallel for different specs
• Testing a spec from a non-feature branch (e.g., main)

🛡️ Guardrails (Signs)

Guardrails are signs — lessons learned from failures that prevent recurring mistakes. They are stored in .speckit-ralph/guardrails.md and injected into each iteration's prompt.

Edit .speckit-ralph/guardrails.md directly to add new signs.

Sign Format

### Sign: [Name]

- **Trigger**: When this applies
- **Instruction**: What to do instead
- **Added after**: Why it was added

Types of Signs

Type	Purpose
Preventive	Stop problems before they happen
Corrective	Fix recurring mistakes
Process	Enforce good practices
Architecture	Guide design decisions

📊 Activity Logging

Ralph automatically logs all activity to .speckit-ralph/activity.log:

• Loop start/end events
• Iteration start/end with duration
• Errors and failures
• Git HEAD changes per iteration

Run summaries are stored in .speckit-ralph/runs/ with:

• CLI used (claude or codex)
• Duration
• Status (success or error)
• Git commits made

⚙️ Environment Variables

Variable	Default	Description
RALPH_AGENT	claude	Agent: claude or codex
RALPH_PROMISE	COMPLETE	Completion promise string
RALPH_SLEEP_SECONDS	2 (claude), 1 (codex)	Seconds between iterations
RALPH_ARTIFACT_DIR	(temp)	Directory for artifacts
RALPH_SKIP_BRANCH_CHECK	0	Skip feature branch validation
RALPH_SPEC_DIR	(auto)	Override spec directory (multi-spec)
CODEX_SANDBOX	workspace-write	Codex sandbox mode
CODEX_APPROVAL_POLICY	never	Codex approval policy

🔍 Troubleshooting

SPEC-KIT not initialized

ERROR: SPEC-KIT not initialized in this project.

Solution: Ralph requires SPEC-KIT to be set up first. Run these commands:

# 1. Install SPEC-KIT
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 2. Initialize SPEC-KIT in your project
specify init . --here --ai claude

# 3. Create your spec in Claude Code
/speckit.specify
/speckit.plan
/speckit.tasks

# 4. Now Ralph can run
speckit-ralph init
speckit-ralph loop 10

plan.md not found

ERROR: plan.md not found at specs/<branch>/plan.md

Solution: Complete the SPEC-KIT workflow:

/speckit.specify    # Create spec.md
/speckit.plan       # Create plan.md
/speckit.tasks      # Create tasks.md
speckit-ralph loop 10   # Now Ralph can run

Tasks not recognized

Solution: Ensure tasks.md follows SPEC-KIT format:

## User Story 1: [Title]

- [ ] Task 1 description
- [ ] Task 2 description

## User Story 2: [Title]

- [ ] Task 3 description

📖 Learn More

• SPEC-KIT — GitHub's official Spec-Driven Development toolkit
• Spec-Driven Methodology — Complete methodology guide
• Ralph Wiggum Technique — Original methodology
• 11 Tips for Better Ralph Wiggums — Best practices

📄 License

This project is licensed under the terms of the MIT open source license. See LICENSE for details.