Ralph Wiggum

1---2name: ralph-wiggum3description: Autonomous AI coding with spec-driven development. Implements Geoffrey Huntley's iterative bash loop methodology where agents work through specs one at a time, outputting a completion signal only when acceptance criteria are 100% met.4license: MIT5metadata:6  author: fstandhartinger7  version: "1.0"8  repository: https://github.com/fstandhartinger/ralph-wiggum9  website: https://ralph-wiggum.ai10---11 12# Ralph Wiggum13 14> Autonomous AI coding with spec-driven development15 16## What is Ralph Wiggum?17 18Ralph Wiggum combines **Geoffrey Huntley's iterative bash loop** with **spec-driven development** for fully autonomous AI-assisted software development.19 20The key insight: **Fresh context each iteration**. Each loop starts a new agent process with a clean context window, preventing context overflow and degradation.21 22## When to Use This Skill23 24Use Ralph Wiggum when:25 26- You have multiple specifications/features to implement27- You want the AI to work autonomously through tasks28- You need consistent, verifiable completion of acceptance criteria29- You want to avoid context window problems in long sessions30 31## How It Works32 33```34┌─────────────────────────────────────────────────────────────┐35│                     RALPH LOOP                              │36├─────────────────────────────────────────────────────────────┤37│  Loop 1: Pick spec A → Implement → Test → Commit → DONE    │38│  Loop 2: Pick spec B → Implement → Test → Commit → DONE    │39│  Loop 3: Pick spec C → Implement → Test → Commit → DONE    │40│  ...                                                        │41│                                                             │42│  Each iteration = Fresh context window                      │43│  Shared state = Files on disk (specs, plan, history)        │44└─────────────────────────────────────────────────────────────┘45```46 47## Installation48 49### Quick Install (via Skill Installers)50 51```bash52# Using Vercel's add-skill53npx add-skill fstandhartinger/ralph-wiggum54 55# Using OpenSkills56openskills install fstandhartinger/ralph-wiggum57```58 59### Full Setup (Recommended)60 61For full Ralph Wiggum setup with constitution and interview:62 63```bash64# Tell your AI agent:65"Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum"66```67 68The agent will guide you through a **lightweight, pleasant setup**:69 701. **Quick Setup** (~1 min) — Create directories, download scripts712. **Project Interview** — Focus on your **vision and goals** (not tech details)723. **Constitution** — Create a guiding document for all sessions734. **Next Steps** — Clear guidance on creating specs and starting Ralph74 75For existing projects, the agent detects your tech stack automatically. The interview prioritizes understanding *what you're building and why*.76 77## Core Concepts78 79### 1. Fresh Context Each Loop80 81Each iteration of the Ralph loop starts a new AI agent process. This means:82- No context window overflow83- No degradation over time84- Clean slate for each task85 86### 2. Shared State on Disk87 88State persists between loops via files:89- `specs/` — Feature specifications with acceptance criteria90- `ralph_history.txt` — Log of breakthroughs, blockers, learnings91- `IMPLEMENTATION_PLAN.md` — Optional detailed task breakdown92 93### 3. Completion Signal94 95The agent outputs `<promise>DONE</promise>` **ONLY** when:96- All acceptance criteria are verified97- Tests pass98- Changes are committed and pushed99 100The bash loop checks for this phrase. If not found, it retries.101 102### 4. Backpressure via Tests103 104Tests, lints, and builds act as guardrails. The agent must fix issues before outputting the completion signal.105 106## Usage107 108### Creating Specifications109 110**The key to success:** Each spec needs **clear, testable acceptance criteria**. This is what tells Ralph when a task is truly "done."111 112```markdown113# Feature: User Authentication114 115## Requirements116- OAuth login with Google117- Session management118- Logout functionality119 120## Acceptance Criteria121- [ ] User can log in with Google122- [ ] Session persists across page reloads123- [ ] User can log out124- [ ] Tests pass125 126**Output when complete:** `<promise>DONE</promise>`127```128 129**Good criteria:** "User can log in with Google and session persists"130**Bad criteria:** "Auth works correctly"131 132The more specific your acceptance criteria, the better Ralph performs.133 134### Running the Loop135 136```bash137# Start building (Claude Code)138./scripts/ralph-loop.sh139 140# With max iterations141./scripts/ralph-loop.sh 20142 143# Using Codex CLI144./scripts/ralph-loop-codex.sh145```146 147### Logging (All Output Captured)148 149Every loop run writes **all output** to log files in `logs/`:150 151- **Session log:** `logs/ralph_*_session_YYYYMMDD_HHMMSS.log` (entire run, including CLI output)152- **Iteration logs:** `logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log` (per-iteration CLI output)153- **Codex last message:** `logs/ralph_codex_output_iter_N_*.txt`154 155## Two Modes156 157| Mode | Purpose | Command |158|------|---------|---------|159| **build** (default) | Pick spec, implement, test, commit | `./scripts/ralph-loop.sh` |160| **plan** (optional) | Create detailed task breakdown | `./scripts/ralph-loop.sh plan` |161 162## Key Principles163 164### Let Ralph Ralph165 166Trust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.167 168### YOLO Mode169 170For Ralph to work effectively, enable full autonomy:171- Claude Code: `--dangerously-skip-permissions`172- Codex: `--dangerously-bypass-approvals-and-sandbox`173 174⚠️ **Use at your own risk.** Only in sandboxed environments.175 176## Links177 178- **GitHub:** https://github.com/fstandhartinger/ralph-wiggum179- **Website:** https://ralph-wiggum.ai180- **Original methodology:** [Geoffrey Huntley's how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum)