ralph

Iterates on tasks until all prd.json user stories pass reviewer verification.

Updated Dec 18, 2025
One-click install
npx skills add https://github.com/l0lxl0lw/dotfiles --skill ralph-l0lxl0lw
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ralph
Source: https://github.com/l0lxl0lw/dotfiles/tree/main/ai/shared/skills/omc/ralph
Command: npx skills add https://github.com/l0lxl0lw/dotfiles --skill ralph-l0lxl0lw

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Complex tasks often get declared done prematurely: partial implementations ship, tests get skipped, and edge cases are forgotten. Ralph enforces guaranteed completion by looping on a task until every user story in a structured PRD passes and a reviewer signs off. ## Core Features & Use Cases - PRD-Driven Execution: Auto-generates and refines a prd.json file that breaks work into user stories with concrete, testable acceptance criteria. - Persistent Iteration Loop: Picks the highest-priority incomplete story, implements it with tiered agent delegation (Haiku/Sonnet/Opus), verifies each acceptance criterion with fresh evidence, and tracks progress in progress.txt. - Reviewer Verification: Requires an architect, critic, or codex reviewer (selectable via --critic flag) to validate work against specific acceptance criteria before completion. - Use Case: You ask the agent to "ralph: migrate the auth module to OAuth2 and don't stop until done." Ralph scaffolds a PRD with stories like token refresh and session handling, implements each one, runs tests, and loops until an architect reviewer approves every story. ## Quick Start Ask the agent to ralph your task, for example: "ralph: add rate limiting to all API endpoints and keep going until done."

Frequently Asked Questions about ralph

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make an AI agent keep working until a task is fully complete?

Invoke ralph with your task, for example "ralph: implement feature X and don't stop until done." It creates a prd.json of user stories, implements each one, verifies acceptance criteria with fresh test runs, and loops until a reviewer approves everything.

How does ralph verify that work is actually done?

Ralph verifies each user story against its specific acceptance criteria in prd.json using fresh evidence from test, build, lint, and typecheck runs. After all stories pass, a reviewer agent (architect by default) re-verifies against those criteria before completion is declared.

Can I choose which reviewer approves ralph's completion?

Yes. Pass --critic=architect, --critic=critic, or --critic=codex in the ralph prompt to select the completion reviewer for that run. The architect reviewer is the default, and the minimum verification tier is STANDARD (Sonnet).

When should I not use a persistence loop like ralph?

Skip ralph when you want to explore or plan before committing (use a plan skill instead), when you need a quick one-shot fix (delegate directly to an executor agent), or when you want manual control over completion. The --no-prd flag also exists for trivial fixes.

What happens if ralph gets stuck on a recurring issue?

Ralph stops and reports when a fundamental blocker requires user input, such as missing credentials or unclear requirements. If the same issue recurs across three or more iterations, it reports it as a potential fundamental problem rather than looping forever.