🧠 Ralph Wiggum

Autonomous AI coding with spec-driven development

⚠️ Use at your own risk. This tool grants AI agents significant autonomy over your codebase and system. Review all changes and use in isolated environments when possible.

Quick Start

Install as Agent Skill (New!)

# Using Vercel's add-skill
npx add-skill fstandhartinger/ralph-wiggum

# Using OpenSkills
openskills install fstandhartinger/ralph-wiggum

Full Setup with Interview

AI Agent? Start Here:

Read and execute INSTALLATION.md for a guided setup with interactive interview.

Human Developer? Start Here:

Read INSTALL.md for manual setup instructions.

---

What is Ralph Wiggum?

Ralph Wiggum (in this flavour) combines Geoffrey Huntley's original iterative bash loop with SpecKit-style specifications for fully autonomous AI-assisted software development.

Key Features

• 🔄 Iterative Self-Correction — Each loop picks ONE task, implements it, verifies, and commits
• 📋 Spec-Driven Development — Professional specifications with clear acceptance criteria
• 🎯 Completion Verification — Agent only outputs <promise>DONE</promise> when criteria are 100% met
• 🧠 Fresh Context Each Loop — Every iteration starts with a clean context window
• 📝 Shared State on Disk — IMPLEMENTATION_PLAN.md persists between loops

---

How It Works

Based on Geoffrey Huntley's methodology:

┌─────────────────────────────────────────────────────────────┐
│                     RALPH LOOP                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │    Orient    │───▶│  Pick Task   │───▶│  Implement   │  │
│  │  Read specs  │    │  from Plan   │    │   & Test     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                   │         │
│         ┌────────────────────────────────────────┘         │
│         ▼                                                   │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   Verify     │───▶│   Commit     │───▶│  Output DONE │  │
│  │  Criteria    │    │   & Push     │    │  (if passed) │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                   │         │
│         ┌────────────────────────────────────────┘         │
│         ▼                                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Bash loop checks for <promise>DONE</promise>         │  │
│  │ If found: next iteration | If not: retry             │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

The Magic Phrase

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.

---

Two Modes

Planning is OPTIONAL

Most projects work fine directly from specs. The agent simply:

1. Looks at specs/ folder
2. Picks the highest priority incomplete spec
3. Implements it completely

Only use plan mode when you want a detailed breakdown of specs into smaller tasks.

Tip: Delete IMPLEMENTATION_PLAN.md to return to working directly from specs.

---

Installation

For AI Agents (Recommended)

Point your AI agent to this repo and say:

"Set up Ralph Wiggum in my project using https://github.com/fstandhartinger/ralph-wiggum"

The agent will read INSTALLATION.md and guide you through a lightweight, pleasant setup:

1. Quick Setup (~1 min) — Create directories, download scripts
2. Project Interview (~3-5 min) — Focus on your vision and goals, not technical minutiae
3. Constitution — Create a guiding document for all future sessions
4. Next Steps — Clear guidance on creating specs and starting Ralph

The interview prioritizes understanding what you're building and why over interrogating you about tech stack details. For existing projects, the agent can detect your stack automatically.

Manual Setup

See INSTALL.md for step-by-step manual instructions.

---

Usage

1. Create Specifications

Tell your AI what you want to build, or use `/speckit.sp

...