Ralph Wiggum
Run autonomous spec-by-spec implementation loops with fresh agent context each iteration until acceptance criteria pass.
Overview
Ralph Wiggum is an agent skill most often used in Build (also Ship, Operate) that implements Geoffrey Huntley's iterative bash loop so agents complete one spec per fresh context until acceptance criteria are fully met.
Install
npx skills add https://github.com/fstandhartinger/ralph-wiggum --skill ralph-wiggumWhat is this skill?
- Geoffrey Huntley–style iterative bash loop with fresh context per iteration
- Spec-driven picks: one spec at a time, implement, test, commit, emit DONE only at 100% criteria
- Designed to avoid long-session context overflow and degradation
- Verifiable completion signal per loop before advancing to the next specification
- Fresh context each iteration in the outer Ralph loop
Adoption & trust: 927 installs on skills.sh; 247 GitHub stars; 0/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a stack of specs but one marathon agent session degrades, loses track of criteria, and never cleanly finishes each item.
Who is it for?
Indie devs with multiple written specs who want overnight or hands-off autonomous implementation with hard acceptance gates.
Skip if: Exploratory spikes with no specs, one-liner tweaks, or teams that forbid autonomous commit loops without human review on every file.
When should I use this skill?
When you have multiple specifications to implement autonomously and need verifiable completion per spec without context window degradation.
What do I get? / Deliverables
Each loop ends with tested, committed work and an explicit completion signal per spec, so the backlog shrinks predictably without context rot.
- Implemented spec per loop
- Commits with passing tests
- Per-spec completion signal
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ralph Wiggum is agent orchestration for turning specs into shipped code—primary shelf is Build agent-tooling because the loop lives in your dev environment. Agent-tooling subphase is where solo builders wire iterative bash loops, completion signals, and spec pickers into Claude Code or similar runners.
Where it fits
Wire the Ralph loop script so each morning's agent pass picks the next open spec from a markdown backlog.
Require tests green inside the loop before the DONE signal unlocks the next spec.
Queue small bugfix specs and let the loop commit fixes with criteria-checked regression checks.
How it compares
Use as a spec-loop orchestration methodology, not as a single-shot code generator or an MCP server.
Common Questions / FAQ
Who is ralph-wiggum for?
Solo builders and small teams running Claude Code or similar agents who already write specs and want an outer loop that resets context each task.
When should I use ralph-wiggum?
Use it in Build when batching feature specs through an agent runner, in Ship when each loop must test and commit before moving on, and in Operate when iterating small production fixes from ticket specs.
Is ralph-wiggum safe to install?
The skill describes autonomous implement-test-commit loops—treat repo access and git permissions carefully and review the Security Audits panel on this Prism page before enabling in production repos.
SKILL.md
READMESKILL.md - Ralph Wiggum
# Ralph Wiggum > Autonomous AI coding with spec-driven development ## What is Ralph Wiggum? Ralph Wiggum combines **Geoffrey Huntley's iterative bash loop** with **spec-driven development** for fully autonomous AI-assisted software development. The key insight: **Fresh context each iteration**. Each loop starts a new agent process with a clean context window, preventing context overflow and degradation. ## When to Use This Skill Use Ralph Wiggum when: - You have multiple specifications/features to implement - You want the AI to work autonomously through tasks - You need consistent, verifiable completion of acceptance criteria - You want to avoid context window problems in long sessions ## How It Works ``` ┌─────────────────────────────────────────────────────────────┐ │ RALPH LOOP │ ├─────────────────────────────────────────────────────────────┤ │ Loop 1: Pick spec A → Implement → Test → Commit → DONE │ │ Loop 2: Pick spec B → Implement → Test → Commit → DONE │ │ Loop 3: Pick spec C → Implement → Test → Commit → DONE │ │ ... │ │ │ │ Each iteration = Fresh context window │ │ Shared state = Files on disk (specs, plan, history) │ └─────────────────────────────────────────────────────────────┘ ``` ## Installation ### Quick Install (via Skill Installers) ```bash # Using Vercel's add-skill npx add-skill fstandhartinger/ralph-wiggum # Using OpenSkills openskills install fstandhartinger/ralph-wiggum ``` ### Full Setup (Recommended) For full Ralph Wiggum setup with constitution and interview: ```bash # Tell your AI agent: "Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum" ``` The agent will guide you through a **lightweight, pleasant setup**: 1. **Quick Setup** (~1 min) — Create directories, download scripts 2. **Project Interview** — Focus on your **vision and goals** (not tech details) 3. **Constitution** — Create a guiding document for all sessions 4. **Next Steps** — Clear guidance on creating specs and starting Ralph For existing projects, the agent detects your tech stack automatically. The interview prioritizes understanding *what you're building and why*. ## Core Concepts ### 1. Fresh Context Each Loop Each iteration of the Ralph loop starts a new AI agent process. This means: - No context window overflow - No degradation over time - Clean slate for each task ### 2. Shared State on Disk State persists between loops via files: - `specs/` — Feature specifications with acceptance criteria - `ralph_history.txt` — Log of breakthroughs, blockers, learnings - `IMPLEMENTATION_PLAN.md` — Optional detailed task breakdown ### 3. Completion Signal The agent outputs `<promise>DONE</promise>` **ONLY** when: - All acceptance criteria are verified - Tests pass - Changes are committed and pushed The bash loop checks for this phrase. If not found, it retries. ### 4. Backpressure via Tests Tests, lints, and builds act as guardrails. The agent must fix issues before outputting the completion signal. ## Usage ### Creating Specifications **The key to success:** Each spec needs **clear, testable acceptance criteria**. This is what tells Ralph when a task is truly "done." ```markdown # Feature: User Authentication ## Requirements - OAuth login with Google - Session management - Logout functionality ## Acceptance Criteria - [ ] User can log in with Google - [