angry-ralph
A Claude Code plugin that transforms a feature spec into a fully implemented, reviewed, and tested codebase, using adversarial multi-LLM review and TDD-gated execution.
Built on the shoulders of giants. angry-ralph unifies and extends three foundational projects by piercelamb:
- deep-project - Feature decomposition and stakeholder interviews
- deep-plan - Detailed implementation planning with section-level specs
- deep-implement - TDD execution with strict red-green cycles
angry-ralph combines all three into a single self-contained plugin, adds adversarial review via Gemini and Codex CLIs, and enforces execution with a built-in Ralph Wiggum Loop, a Stop hook that blocks exit until tests pass.
What It Does
Give angry-ralph a spec file and it runs a 6-phase pipeline:
| Phase | What Happens |
|---|
| 1. DECOMPOSE | Reads your spec, interviews you to clarify scope, identifies planning units |
| 2. PLAN | Writes a detailed implementation plan with numbered sections |
| 3. ADVERSARIAL REVIEW | Dispatches Gemini and Codex CLIs to review the plan, triages findings, iterates up to N times |
| 4. SPLIT | Finalizes the plan into individual section spec files |
| 5. EXECUTE | TDD Ralph Loop per section: tests first, implement, all tests pass, inline review gate, atomic commit |
| 6. FINAL REVIEW | Self-healing review loop: external LLMs review, fix, re-review until clean or capped |
Every phase produces persistent artifacts on disk. If the session is interrupted, re-running the command detects prior state and offers to resume.
Prerequisites
Required:
Optional (upgrades review tier):
angry-ralph works out-of-the-box with only the required tools. External CLIs upgrade the review from Self-Reflection (Claude reviewing its own work in a fresh session) to Adversarial (cross-model scrutiny).
Verify your environment:
bash /path/to/angry-ralph/scripts/checks/validate-env.sh
Quick Start
Option A: Install via Marketplace
/plugin marketplace add Custos/angry-ralph
/plugin install angry-ralph@custos-plugins
Option B: Load from Local Path
git clone https://github.com/Custos/angry-ralph.git
claude --plugin-dir /path/to/angry-ralph
Or for fully autonomous execution (no permission prompts):
claude --plugin-dir /path/to/angry-ralph --dangerously-skip-permissions
Warning: --dangerously-skip-permissions gives Claude unrestricted access to your filesystem, shell, and network. The Ralph Loop is designed to run autonomously and will hit permission prompts repeatedly without this flag, but you should understand the risk. Use in isolated environments or repositories you trust. The TDD gate and fail-closed Stop hook provide safety at the execution level, but they do not replace filesystem-level caution.
Run against your spec
/angry-ralph @path/to/your-spec.md
With a custom review iteration cap:
/angry-ralph @path/to/your-spec.md --max-review-iterations 5
With a custom section review iteration cap:
/angry-ralph @path/to/your-spec.md --max-section-review-iterations 3
The current working directory should be a git repo (or angry-ralph will offer to git init one for you). This is where the code gets built.
Commands
| Command | Description |
|---|
/angry-ralph @spec.md [--auto] | Start the full 6-phase pipeline against a spec file |
/angry-architect @spec.md [--auto] | Run Phases 1-2 only (decompose + plan) |
/angry-review [plan|code|section <name>] | Adversarial review — pipeline Phase 3 or on-demand |
/angry-execute [--auto] [--rebuild <section>] | Run Phases 4-6 (split, TDD execute, final review) |
/angry-fix [context] [prompt] | Surgical TDD strike on a specific file or bug |
/angry-diagnose [@ctx] "problem" | Adversarial bug diagnosis with differential diagnosis and TDD fix |
/cancel-ralph | Cancel an active Ralph Loop and remove state |
/angry-status | Show current pipeline state (read-only) |
All commands are thin wrappers that delegate to scripts/lib/pipeline.sh and scripts/lib/mechanical-gates.sh.
Architecture
