ralph-wiggum

Install as Agent Skill (New!)

```bash

# 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](INSTALLATION.md) for a guided setup with interactive interview.

Human Developer? Start Here:

> Read [INSTALL.md](INSTALL.md) for manual setup instructions.

---

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 DONE 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

---

Based on [Geoffrey Huntley's methodology](https://github.com/ghuntley/how-to-ralph-wiggum):

```

┌─────────────────────────────────────────────────────────────┐

│ RALPH LOOP │

├─────────────────────────────────────────────────────────────┤

│ │

│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │

│ │ Orient │───▶│ Pick Task │───▶│ Implement │ │

│ │ Read specs │ │ from Plan │ │ & Test │ │

│ └──────────────┘ └──────────────┘ └──────────────┘ │

│ │ │

│ ┌────────────────────────────────────────┘ │

│ ▼ │

│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │

│ │ Verify │───▶│ Commit │───▶│ Output DONE │ │

│ │ Criteria │ │ & Push │ │ (if passed) │ │

│ └──────────────┘ └──────────────┘ └──────────────┘ │

│ │ │

│ ┌────────────────────────────────────────┘ │

│ ▼ │

│ ┌──────────────────────────────────────────────────────┐ │

│ │ Bash loop checks for DONE │ │

│ │ If found: next iteration | If not: retry │ │

│ └──────────────────────────────────────────────────────┘ │

│ │

└─────────────────────────────────────────────────────────────┘

```

The Magic Phrase

The agent outputs DONE 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.

---

| Mode | Purpose | Command |

|------|---------|---------|

| build (default) | Pick spec/task, implement, test, commit | ./scripts/ralph-loop.sh |

| plan (optional) | Create detailed task breakdown from specs | ./scripts/ralph-loop.sh plan |

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