ralph-loop

Executes autonomous build loops that implement user stories from a PRD JSON with quality gates and atomic commits.

1|Updated Sep 3, 2026
One-click install
npx skills add https://github.com/amanpal3/SKILLs --skill ralph-loop-amanpal3
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ralph-loop
Source: https://github.com/amanpal3/SKILLs/tree/main/.agent/plugins/ralph/skills/ralph-loop
Command: npx skills add https://github.com/amanpal3/SKILLs --skill ralph-loop-amanpal3

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Manually working through a product requirements document story-by-story is slow and error-prone, with no guarantee that each change passes tests or gets committed cleanly. This Skill automates the entire loop: selecting the next open story, implementing it, verifying quality gates, and committing atomically. ## Core Features & Use Cases - Dependency-Aware Story Selection: Scans prd.json for the first open story whose dependencies have all passed, ensuring work happens in the correct order. - Non-Negotiable Quality Gates: Runs top-level checks like npm test, lint, and typecheck plus story-specific acceptance criteria before marking anything complete. - Browser Verification for UI Stories: Loads the dev-browser skill to verify frontend rendering and confirm zero console errors. - Progress Logging & Atomic Commits: Appends results to .ralph/progress.md, updates story status, and commits with a conventional message per story. - Use Case: You have a prd.json with 20 user stories for a new feature. Invoke the Ralph loop and it implements each story sequentially, running tests after each one and committing only verified work. ## Quick Start Ask the agent to run the Ralph build loop on the prd.json in this repository and execute the next open user story.

Frequently Asked Questions about ralph-loop

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

FAQPage Schema
How do I run an autonomous build loop from a PRD JSON file?▼

Place your prd.json at .agents/tasks/prd.json or .ralph/prd.json, then invoke the Ralph loop. It selects the first open story whose dependencies have passed, implements it, runs quality gates, and commits the change atomically.

How does the Ralph loop decide which user story to implement next?▼

It scans prd.json for the first story with status "open" where every ID in its dependsOn array has status "passed" or "completed". If no eligible story remains, it announces that all stories are complete.

What quality gates run before a story is marked complete?▼

The loop runs top-level qualityGates commands such as npm test, npm run lint, and npm run typecheck, plus story-specific acceptanceCriteria verification commands. UI stories also require browser verification with zero console errors.

Does the Ralph loop handle frontend or UI stories differently?▼

Yes. For UI and frontend stories it starts or verifies the dev server, loads the dev-browser skill, and confirms the interface renders correctly with zero console errors before marking the story passed.

What happens if a story implementation fails its verification checks?▼

The story is not marked as passed and no completion commit is made. Errors are recorded in .ralph/errors.log so future iterations avoid repeating the same failures.