prp-ralph-loop

The prp-ralph-loop is an autonomous execution agent skill designed to bridge the gap between planning and production-ready code. Based on the 'Ralph Wiggum' loop technique, this skill facilitates continuous self-correction by running iterative development cycles until all defined criteria are met. It acts as an orchestrator for AI agents tasked with executing Product Requirement Prompts (PRPs), ensuring that code modifications are not just implemented, but rigorously validated through build, linting, and testing gates.

The skill identifies active work sessions by detecting the existence of .claude/prp-ralph.state.md, a state file that tracks iterations, task progress, and historical codebase learnings. By maintaining this state, the agent ensures continuity across iterations—allowing it to debug previous failures, follow patterns discovered in earlier cycles, and systematically check off requirements. It is specifically designed for developers and engineering teams utilizing Claude Code to automate complex feature implementation, bug fixing, and codebase refactoring.

• Executes iterative code implementation cycles until completion signal is detected.

• Enforces strict validation requirements including type-checks, linting, test suites, and build verification.

• Maintains persistent state through the .claude/prp-ralph.state.md file, enabling context-aware recovery and progress logging.

• Integrates with local shell hooks to manage session lifecycle and continuation prompts.

• Supports systematic error handling by forcing re-validation after every fix.

• Requires an initialized project with PRP plan files or specific tasks to execute.

• Best suited for tasks with clear, objective-based validation gates (e.g., test coverage or compiler success).

• Always specify --max-iterations during initial execution to prevent infinite loop scenarios.

• Ensure the stop hook (.claude/hooks/prp-ralph-stop.sh) is properly configured in settings.local.json to enable automatic loop control.

• The loop triggers the final completion signal <promise>COMPLETE</promise> only when all validations (TypeScript, Python, tests, build) exit with code 0 and all plan requirements are fulfilled.