agent-ralph-wiggum-fstandhartinger

agent-ralph-wiggum-fstandhartinger

Autonomous AI coding with spec-driven development. Ralph Wiggum combines Geoffrey Huntley's original iterative bash loop methodology with SpecKit-style specifications for fully autonomous AI-assisted software development.

When to Use

• Building projects that require hands-free AI implementation
• Working from specification files with clear acceptance criteria
• Running autonomous development loops with completion verification
• Implementing features iteratively with self-correction
• Managing multiple specs in priority order
• Needing fresh context windows for each iteration

Quick Start

Install as Agent Skill

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

# Using OpenSkills
openskills install agent-ralph-wiggum-fstandhartinger

Manual Setup

See Setup and Configuration for detailed installation.

Core Concepts

Ralph Wiggum operates on a simple but powerful principle: each iteration picks ONE task, implements it completely, verifies acceptance criteria, and only outputs <promise>DONE</promise> when 100% complete.

The Ralph Loop

┌─────────────────────────────────────────────────────────────┐
│                     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             │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

See The Ralph Loop Methodology for detailed workflow explanation.

Running Ralph

Build Mode (Default)

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

Planning Mode (Optional)

./scripts/ralph-loop.sh plan      # Create IMPLEMENTATION_PLAN.md from specs

See Running Ralph Loops for all commands and modes.

Creating Specifications

Specifications define what to build with clear acceptance criteria:

# Using Cursor command
/speckit.specify Add user authentication with OAuth

# Or describe to your AI agent
"Create a spec for implementing the billing dashboard"

See Creating Specifications for spec structure and templates.

Reference Files

• references/01-setup-configuration.md - Installation, directory structure, and configuration
• references/02-ralph-loop-methodology.md - Core concepts, workflow, and completion signals
• references/03-running-ralph-loops.md - Commands, modes, logging, and monitoring
• references/04-creating-specifications.md - Spec templates, acceptance criteria, and examples
• references/05-advanced-features.md - Telegram notifications, GitHub issues, circuit breakers
• references/06-troubleshooting.md - Common issues, stuck specs, and debugging

Note: {baseDir} refers to the skill's base directory (.agents/skills/agent-ralph-wiggum-fstandhartinger/). All paths are relative to this directory.

Troubleshooting

Stuck Specs

After 10 attempts without completion, specs are flagged as stuck:

source scripts/lib/nr_of_tries.sh
print_stuck_specs_summary

Consider splitting into smaller specs. See Troubleshooting.

Circuit Breaker

The circuit breaker halts execution after detecting stagnation:

# Check status
show_circuit_status

# Reset manually
reset_circuit_breaker "Fixed blocking issue"

Important Notes

1. Acceptance criteria must be testable - Not "works correctly" but specific verifiable conditions
2. Fresh context each loop - Every iteration starts with clean context window
3. Shared state on disk - IMPLEMENTATION_PLAN.md persists between loops
4. Planning is optional - Most projects work fine directly from specs
5. YOLO mode recommended - Enables autonomous command execution without approval prompts