# Agent Ralph Wiggum Fstandhartinger 0 3 0

> Autonomous AI coding with spec-driven development combining iterative bash loops and SpecKit-style specifications for fully autonomous AI-assisted software development. Use when building projects that require hands-free AI implementation, working from specification files, or running autonomous development loops with completion verification.

- **Type:** Skill
- **Install:** `agentstack add skill-tangledgroup-tangled-skills-agent-ralph-wiggum-fstandhartinger-0-3-0`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tangledgroup](https://agentstack.voostack.com/s/tangledgroup)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tangledgroup](https://github.com/tangledgroup)
- **Source:** https://github.com/tangledgroup/tangled-skills/tree/main/misc/agent-ralph-wiggum-fstandhartinger-0-3-0

## Install

```sh
agentstack add skill-tangledgroup-tangled-skills-agent-ralph-wiggum-fstandhartinger-0-3-0
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ralph Wiggum — Autonomous AI Coding Loop

## Overview

Ralph Wiggum is a bash-loop-driven autonomous coding system that combines Geoffrey Huntley's iterative loop methodology with SpecKit-style specifications. It turns AI agents into reliable builders: each loop iteration picks one task from a spec, implements it completely, verifies acceptance criteria, commits changes, and exits — then restarts with fresh context for the next task.

The project by fstandhartinger provides:
- Shell scripts for Claude Code, OpenAI Codex, Google Gemini, and GitHub Copilot
- Spec-driven development with testable acceptance criteria
- Interactive AI-guided installation with constitution creation
- NR_OF_TRIES tracking for stuck specs
- Optional Telegram notifications and completion logs

## When to Use

- Setting up autonomous AI coding in a project from scratch
- Converting an existing codebase to spec-driven autonomous development
- Running the Ralph loop (build or plan mode) against specs
- Debugging stuck specs or tuning loop behavior
- Creating project constitutions that guide agent behavior
- Installing Ralph Wiggum via agent skill installers or manually

## Core Concepts

**The Ralph Loop**: A bash `while` loop that repeatedly starts a fresh AI agent process. Each iteration reads the constitution and specs from disk, picks one incomplete task, implements it, verifies acceptance criteria, then outputs `DONE` only when 100% complete. The loop checks for this magic phrase — if found, moves to next iteration; if not, retries with fresh context.

**Fresh Context Each Loop**: Unlike exit-hook approaches that force the same session to continue indefinitely (causing context overflow and lossy compaction), Ralph terminates and restarts cleanly between tasks. Every iteration gets a clean context window.

**Shared State on Disk**: `IMPLEMENTATION_PLAN.md` (optional) or the `specs/` folder persists between loops. The agent reads it each time to pick tasks.

**Backpressure via Tests**: Tests, lints, and builds reject invalid work. The agent must fix issues before outputting the completion signal. Natural convergence through iteration.

**Completion Signal**: `DONE` means all acceptance criteria verified, tests pass, changes committed and pushed. `ALL_DONE` means no work remains.

## Installation / Setup

### Agent Skill Installers

```bash
# Vercel add-skill
npx add-skill fstandhartinger/ralph-wiggum

# OpenSkills
openskills install fstandhartinger/ralph-wiggum

# Skillset
skillset add fstandhartinger/ralph-wiggum
```

### AI-Guided Setup (Recommended)

Point your AI agent to the repo:

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

The agent reads `INSTALLATION.md` and guides through:
1. Creating directory structure (`.specify/memory/`, `specs/`, `scripts/`, `logs/`, etc.)
2. Downloading loop scripts from GitHub
3. Interactive interview about project vision, principles, and tech stack
4. Generating `.specify/memory/constitution.md` — the single source of truth

### Manual Setup

See [Manual Setup](reference/01-manual-setup.md) for step-by-step directory creation, script downloads, and constitution authoring.

## Usage

### Two Modes

- **Build mode** (default) — Pick spec/task, implement, test, commit: `./scripts/ralph-loop.sh`
- **Plan mode** (optional) — Create detailed task breakdown from specs: `./scripts/ralph-loop.sh plan`

### Multiple Agent Backends

| Script | Agent |
|--------|-------|
| `ralph-loop.sh` | Claude Code |
| `ralph-loop-codex.sh` | OpenAI Codex |
| `ralph-loop-gemini.sh` | Google Gemini |
| `ralph-loop-copilot.sh` | GitHub Copilot |

### Limiting Iterations

```bash
./scripts/ralph-loop.sh        # Unlimited iterations
./scripts/ralph-loop.sh 20     # Max 20 iterations
```

### Spec Status Convention

A spec is **COMPLETE** when it contains `Status: COMPLETE` at the start of a line (supports `## Status: COMPLETE`, `**Status**: COMPLETE`, etc.). Any other status or missing status means **INCOMPLETE**.

### NR_OF_TRIES Tracking

Each spec tracks attempt count via `` at the bottom. After 10 attempts without completion, the spec is flagged as stuck and should be split into smaller specs.

```bash
source scripts/lib/nr_of_tries.sh
print_stuck_specs_summary
```

## Advanced Topics

**Manual Setup**: Directory structure, script downloads, constitution authoring → [Manual Setup](reference/01-manual-setup.md)

**Constitution Reference**: The single source of truth for agent behavior, with template and optional sections → [Constitution Reference](reference/02-constitution-reference.md)

**Loop Internals**: How ralph-loop.sh works — prompt generation, iteration cycle, completion detection, logging → [Loop Internals](reference/03-loop-internals.md)

**Optional Features**: Telegram notifications, GitHub Issues integration, completion logs, audio alerts → [Optional Features](reference/04-optional-features.md)

## Credits

Based on Geoffrey Huntley's original Ralph Wiggum methodology. Combined with SpecKit by GitHub for spec-driven development. Influenced by Matt Pocock's variant. Official Claude Code plugin available from Anthropic.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tangledgroup](https://github.com/tangledgroup)
- **Source:** [tangledgroup/tangled-skills](https://github.com/tangledgroup/tangled-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tangledgroup-tangled-skills-agent-ralph-wiggum-fstandhartinger-0-3-0
- Seller: https://agentstack.voostack.com/s/tangledgroup
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.