{
  "markdown": "# 🧠 Ralph Wiggum\n\n> Autonomous AI coding with spec-driven development\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n⚠️ **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.\n\n## Quick Start\n\n### Install as Agent Skill (New!)\n\n```bash\n# Using Vercel's add-skill\nnpx add-skill fstandhartinger/ralph-wiggum\n\n# Using OpenSkills\nopenskills install fstandhartinger/ralph-wiggum\n```\n\n### Full Setup with Interview\n\n**AI Agent? Start Here:**\n> Read and execute [INSTALLATION.md](INSTALLATION.md) for a guided setup with interactive interview.\n\n**Human Developer? Start Here:**\n> Read [INSTALL.md](INSTALL.md) for manual setup instructions.\n\n---\n\n## What is Ralph Wiggum?\n\nRalph Wiggum (in this flavour) combines **Geoffrey Huntley's original iterative bash loop** with **SpecKit-style specifications** for fully autonomous AI-assisted software development.\n\n### Key Features\n\n- 🔄 **Iterative Self-Correction** — Each loop picks ONE task, implements it, verifies, and commits\n- 📋 **Spec-Driven Development** — Professional specifications with clear acceptance criteria\n- 🎯 **Completion Verification** — Agent only outputs `<promise>DONE</promise>` when criteria are 100% met\n- 🧠 **Fresh Context Each Loop** — Every iteration starts with a clean context window\n- 📝 **Shared State on Disk** — `IMPLEMENTATION_PLAN.md` persists between loops\n\n---\n\n## How It Works\n\nBased on [Geoffrey Huntley's methodology](https://github.com/ghuntley/how-to-ralph-wiggum):\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     RALPH LOOP                              │\n├─────────────────────────────────────────────────────────────┤\n│                                                             │\n│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │\n│  │    Orient    │───▶│  Pick Task   │───▶│  Implement   │  │\n│  │  Read specs  │    │  from Plan   │    │   & Test     │  │\n│  └──────────────┘    └──────────────┘    └──────────────┘  │\n│                                                   │         │\n│         ┌────────────────────────────────────────┘         │\n│         ▼                                                   │\n│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │\n│  │   Verify     │───▶│   Commit     │───▶│  Output DONE │  │\n│  │  Criteria    │    │   & Push     │    │  (if passed) │  │\n│  └──────────────┘    └──────────────┘    └──────────────┘  │\n│                                                   │         │\n│         ┌────────────────────────────────────────┘         │\n│         ▼                                                   │\n│  ┌──────────────────────────────────────────────────────┐  │\n│  │ Bash loop checks for <promise>DONE</promise>         │  │\n│  │ If found: next iteration | If not: retry             │  │\n│  └──────────────────────────────────────────────────────┘  │\n│                                                             │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### The Magic Phrase\n\nThe agent outputs `<promise>DONE</promise>` **ONLY** when:\n- All acceptance criteria are verified\n- Tests pass\n- Changes are committed and pushed\n\nThe shell or PowerShell loop checks for this phrase. If not found, it retries.\n\n---\n\n## Two Modes\n\n| Mode | Purpose | Command |\n|------|---------|---------|\n| **build** (default) | Pick spec/task, implement, test, commit | `./scripts/ralph-loop.sh` |\n| **plan** (optional) | Create detailed task breakdown from specs | `./scripts/ralph-loop.sh plan` |\n\nOn Windows PowerShell, use the matching `.ps1` scripts, for example\n`.\\scripts\\ralph-loop.ps1` or `.\\scripts\\ralph-loop-codex.ps1 plan`.\n\n### Planning is OPTIONAL\n\nMost projects work fine **directly from specs**. The agent simply:\n1. Looks at `specs/` folder\n2. Picks the highest priority incomplete spec\n3. Implements it completely\n\nOnly use `plan` mode when you want a detailed breakdown of specs into smaller tasks.\n\n**Tip:** Delete `IMPLEMENTATION_PLAN.md` to return to working directly from specs.\n\n---\n\n## Installation\n\n### For AI Agents (Recommended)\n\nPoint your AI agent to this repo and say:\n\n> \"Set up Ralph Wiggum in my project using https://github.com/fstandhartinger/ralph-wiggum\"\n\nThe agent will read [INSTALLATION.md](INSTALLATION.md) and guide you through a **lightweight, pleasant setup**:\n\n1. **Quick Setup** (~1 min) — Create directories, download scripts\n2. **Project Interview** (~3-5 min) — Focus on your **vision and goals**, not technical minutiae\n3. **Constitution** — Create a guiding document for all future sessions\n4. **Next Steps** — Clear guidance on creating specs and starting Ralph\n\nThe 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.\n\n### Manual Setup\n\nSee [INSTALL.md](INSTALL.md) for step-by-step manual instructions.\n\n---\n\n## Usage\n\n### 1. Create Specifications\n\nTell your AI what you want to build, or use `/speckit.specify` in Cursor:\n\n```\n/speckit.specify Add user authentication with OAuth\n```\n\nThis creates `specs/001-user-auth/spec.md` with:\n- Feature requirements\n- **Clear, testable acceptance criteria** (critical!)\n- Completion signal section\n\n**The key to good specs:** Each spec needs acceptance criteria that are **specific and testable**. Not \"works correctly\" but \"user can log in with Google and session persists across page reloads.\"\n\n### 2. (Optional) Run Planning Mode\n\n```bash\n./scripts/ralph-loop.sh plan\n```\n\nCreates `IMPLEMENTATION_PLAN.md` with detailed task breakdown. **This step is optional** — most projects work fine directly from specs.\n\n### 3. Run Build Mode\n\n```bash\n./scripts/ralph-loop.sh        # Unlimited iterations\n./scripts/ralph-loop.sh 20     # Max 20 iterations\n```\n\nEach iteration:\n1. Picks the highest priority task\n2. Implements it completely\n3. Verifies acceptance criteria\n4. Outputs `<promise>DONE</promise>` only if criteria pass\n5. Bash loop checks for the phrase\n6. Context cleared, next iteration starts\n\n### Logging (All Output Captured)\n\nEvery loop run writes **all output** to log files in `logs/`:\n\n- **Session log:** `logs/ralph_*_session_YYYYMMDD_HHMMSS.log` (entire run, including CLI output)\n- **Iteration logs:** `logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log` (per-iteration CLI output)\n- **Codex last message:** `logs/ralph_codex_output_iter_N_*.txt`\n\nIf something gets stuck, these logs contain the full verbose trace.\n\n### NR_OF_TRIES Tracking\n\nEach spec tracks how many times it has been attempted. After 10 attempts without completion, the spec is flagged as \"stuck\" and should be split into smaller specs.\n\n```bash\n# Check stuck specs\nsource scripts/lib/nr_of_tries.sh\nprint_stuck_specs_summary\n```\n\nThe counter is stored as a comment in the spec file:\n```markdown\n<!-- NR_OF_TRIES: 5 -->\n```\n\n### Telegram Notifications (Optional)\n\nGet progress updates via Telegram! See [TELEGRAM_SETUP.md](TELEGRAM_SETUP.md) for setup.\n\n```bash\n# Enable telegram (requires TG_BOT_TOKEN and TG_CHAT_ID)\n./scripts/ralph-loop.sh\n\n# Enable audio notifications (also requires CHUTES_API_KEY)\n./scripts/ralph-loop.sh --telegram-audio\n\n# Disable telegram\n./scripts/ralph-loop.sh --no-telegram\n```\n\n**What you'll get:**\n- 🚀 Loop start notifications\n- ✅ Spec completion notifications with mermaid diagrams\n- ⚠️ Warnings for consecutive failures or stuck specs\n- 🏁 Summary when loop finishes\n\n### Completion Logs\n\nOn each spec completion, entries are created in `completion_log/`:\n- `YYYY-MM-DD--HH-MM-SS--spec-name.md` — Summary and mermaid code\n- `YYYY-MM-DD--HH-MM-SS--spec-name.png` — Rendered mermaid diagram\n\nThese provide a visual history of what was built.\n\n### Using Codex Instead\n\n```bash\n./scripts/ralph-loop-codex.sh plan\n./scripts/ralph-loop-codex.sh\n```\n\nPowerShell:\n\n```powershell\n.\\scripts\\ralph-loop-codex.ps1 plan\n.\\scripts\\ralph-loop-codex.ps1\n```\n\n---\n\n## File Structure\n\n```\nproject/\n├── .specify/\n│   └── memory/\n│       └── constitution.md       # Single source of truth for all agent behavior\n├── specs/\n│   └── NNN-feature-name.md       # Feature specifications\n├── scripts/\n│   ├── ralph-loop.sh             # Claude Code loop\n│   ├── ralph-loop.ps1            # Claude Code loop for PowerShell\n│   ├── ralph-loop-codex.sh       # OpenAI Codex loop\n│   ├── ralph-loop-codex.ps1      # OpenAI Codex loop for PowerShell\n│   ├── ralph-loop-gemini.sh      # Google Gemini loop\n│   ├── ralph-loop-gemini.ps1     # Google Gemini loop for PowerShell\n│   ├── ralph-loop-copilot.sh     # GitHub Copilot loop\n│   ├── ralph-loop-copilot.ps1    # GitHub Copilot loop for PowerShell\n│   └── lib/                      # Shared shell and PowerShell helpers\n├── AGENTS.md                     # Points to constitution\n└── CLAUDE.md                     # Points to constitution\n```\n\nThe **constitution** is the single source of truth. Optional features (Telegram, GitHub Issues, completion logs) are configured there — not baked into the scripts.\n\n---\n\n## Core Principles\n\n### 1. Fresh Context Each Loop\nEach iteration gets a clean context window. The agent reads files from disk each time.\n\n### 2. Shared State on Disk\n`IMPLEMENTATION_PLAN.md` persists between loops. Agent reads it to pick tasks, updates it with progress.\n\n### 3. Backpressure via Tests\nTests, lints, and builds reject invalid work. Agent must fix issues before the magic phrase.\n\n### 4. Completion Verification\nAgent only outputs `<promise>DONE</promise>` when acceptance criteria are 100% verified. The bash loop enforces this.\n\n### 5. Let Ralph Ralph\nTrust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.\n\n---\n\n## Alternative Spec Sources\n\nDuring installation, you can choose:\n\n1. **SpecKit Specs** (default) — Markdown files in `specs/`\n2. **GitHub Issues** — Fetch from a repository\n3. **Custom Source** — Your own mechanism\n\nThe constitution and prompts adapt accordingly.\n\n---\n\n## Agent Skills Compatibility\n\nRalph Wiggum follows the [Agent Skills specification](https://agentskills.io) and is compatible with:\n\n| Installer | Command |\n|-----------|---------|\n| [Vercel add-skill](https://github.com/vercel-labs/add-skill) | `npx add-skill fstandhartinger/ralph-wiggum` |\n| [OpenSkills](https://github.com/numman-ali/openskills) | `openskills install fstandhartinger/ralph-wiggum` |\n| [Skillset](https://github.com/climax-tools/skillset) | `skillset add fstandhartinger/ralph-wiggum` |\n\nWorks with: **Claude Code**, **Cursor**, **Codex**, **Windsurf**, **Amp**, **OpenCode**, and more.\n\n---\n\n## Credits\n\nThis approach builds upon:\n\n- [Geoffrey Huntley's how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum) — The original methodology\n- [Original Ralph Wiggum technique](https://awesomeclaude.ai/ralph-wiggum) — By the Claude community\n- [Claude Code Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)\n- [SpecKit](https://github.com/github/spec-kit) by GitHub — Spec-driven development\n\nOur contribution: Combining the bash loop approach with SpecKit-style specifications and a smooth AI-driven installation process.\n\n---\n\n## License\n\nMIT License — See [LICENSE](LICENSE) for details.\n\n---\n\n**Website**: [ralph-wiggum-web.onrender.com](https://ralph-wiggum-web.onrender.com)\n",
  "bytes": 11439,
  "sha": "ddce0e64711e8371822970c9219c917a485524c9faf8b72671d9db10c74d8876",
  "repo_slug": "fstandhartinger/ralph-wiggum",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_fstandhartinger_ralph_wiggum_ralph_wiggu_cfb17178/readme"
}