prps-agentic-engineering

# PRP (Product Requirement Prompts) - Agentic Engineering > Skill by [ara.so](https://ara.so) — AI Agent Skills collection. PRP (Product Requirement Prompt) is a methodology and toolset for AI-assisted development that combines traditional PRDs with curated codebase intelligence and autonomous validation loops. It enables AI agents to deliver production-ready code on the first pass by providing complete context, patterns, and validation commands. **Key Innovation**: PRP = PRD + codebase intelligence + agent/runbook ## Installation ### Option 1: Copy Commands to Existing Project ```bash # From your project root git clone https://github.com/Wirasm/PRPs-agentic-eng.git /tmp/prp-temp cp -r /tmp/prp-temp/.claude/commands/prp-core .claude/commands/ rm -rf /tmp/prp-temp ``` ### Option 2: Clone Full Repository ```bash git clone https://github.com/Wirasm/PRPs-agentic-eng.git cd PRPs-agentic-eng ``` ### Setup Ralph Loop (Optional but Recommended) Create `.claude/settings.local.json`: ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": ".claude/hooks/prp-ralph-stop.sh" } ] } ] } } ``` Create `.claude/hooks/prp-ralph-stop.sh`: ```bash #!/bin/bash if [ -f .claude/prp-ralph.state.md ]; then echo "Ralph loop still active - stopping" exit 1 fi exit 0 ``` Make executable: ```bash chmod +x .claude/hooks/prp-ralph-stop.sh ``` ## Project Structure ``` your-project/ ├── .claude/ │ ├── commands/prp-core/ # PRP command files │ ├── hooks/ # Stop hooks for Ralph │ ├── PRPs/ # Generated artifacts │ │ ├── prds/ # Product requirement docs │ │ ├── plans/ # Implementation plans │ │ │ └── completed/ # Archived plans │ │ ├── reports/ # Implementation reports │ │ ├── issues/ # Issue investigations │ │ │ └── completed/ # Archived investigations │ │ └── reviews/ # PR reviews │ └── settings.local.json # Ralph hook configuration ├── PRPs/ │ ├── templates/ # PRP templates │ │ ├── prp_base.md │ │ ├── prp_story_task.md │ │ └── prp_planning.md │ └── ai_docs/ # Curated library docs └── CLAUDE.md # Project guidelines ``` ## Core Workflow Commands ### `/prp-prd` - Interactive PRD Generator Creates a comprehensive Product Requirement Document with implementation phases. ```bash /prp-prd "user authentication system with JWT" ``` **Output**: `.claude/PRPs/prds/user-auth-system.prd.md` **PRD Structure**: - Executive Summary - Goals & Success Metrics - User Stories - Technical Requirements - Implementation Phases Table - Dependencies & Constraints **Implementation Phases Table**: ```markdown | # | Phase | Description | Status | Parallel | Depends | PRP Plan | |---|-------|-------------|--------|----------|---------|----------| | 1 | Auth | JWT tokens | pending | - | - | - | | 2 | API | Auth endpoints | pending | - | 1 | - | | 3 | UI | Login forms | pending | with 4 | 2 | - | | 4 | Tests | Test suite | pending | with 3 | 2 | - | ``` ### `/prp-plan` - Create Implementation Plan Generates detailed implementation plan from PRD phase or free-form description. **From PRD**: ```bash /prp-plan .claude/PRPs/prds/user-auth-system.prd.md ``` Auto-selects next pending phase from PRD. **From Description**: ```bash /prp-plan "add pagination to the users API endpoint" ``` **Plan Structure**: ```markdown # Implementation Plan: Feature Name ## Context - Relevant files - Dependencies - Existing patterns ## Tasks 1. [ ] Task description - Subtask details - Files to modify ## Validation Commands npm run type-check npm run lint npm test npm run build ## Success Criteria - [ ] All tests pass - [ ] No type errors - [ ] Follows existing patterns ``` ### `/prp-implement` - Execute Plan Implements plan with validation loops. ```bash /prp-implement .claude/PRPs/plans/add-pagination.plan.md ``` **Process**: 1. Reads plan and context 2. Executes tasks in order 3. Runs validation commands 4. Creates implementation report 5. Updates PRD status (if from PRD) 6. Archives plan to `completed/` **Implementation Report** (`.claude/PRPs/reports/feature-name.report.md`): ```markdown # Implementation Report: Feature Name ## Summary Brief overview of changes ## Changes Made - File modifications - New files created - Dependencies added ## Validation Results ✓ Type check passed ✓ Linting passed ✓ Tests passed (42 passing) ✓ Build successful ## Challenges & Solutions - Challenge faced - Solution applied ## Next Steps - Suggested follow-ups ``` ## Issue & Debug Workflow ### `/prp-issue-investigate` - Analyze GitHub Issue Creates investigation artifact for bug fixes or feature requests. ```bash /prp-issue-investigate 123 ``` **Investigation Artifact** (`.claude/PRPs/issues/issue-123-investigation.md`): ```markdown # Issue Investigation: #123 ## Issue Summary [Auto-fetched from GitHub] ## Root Cause Analysis - What's happening - Why it's happening - Where in codebase ## Proposed Solution 1. Change X in file Y 2. Add validation Z ## Implementation Plan - [ ] Fix core issue - [ ] Add tests - [ ] Update docs ## Validation npm test -- issue-123 npm run lint ``` ### `/prp-issue-fix` - Execute Fix Implements fix from investigation artifact. ```bash /prp-issue-fix 123 ``` Reads investigation, executes plan, creates PR-ready changes. ### `/prp-debug` - Root Cause Analysis Deep debugging with 5 Whys methodology. ```bash /prp-debug "users can't login after password reset" ``` **Output**: ```markdown # Debug Report: Issue Description ## 5 Whys Analysis 1. Why? Users see "invalid token" error 2. Why? Token expired before email delivered 3. Why? Email queue has 5min delay 4. Why? Queue worker throttled 5. Why? Rate limit too conservative ## Root Cause Queue worker rate limit set to 10/min, should be 100/min ## Fix Update `config/queue.js` rate limit configuration ## Validation - Test password reset flow - Check email delivery time ``` ## Git & Review Commands ### `/prp-commit` - Smart Commit Natural language file targeting for commits. ```bash /prp-commit "fix validation bug in user registration" --files "auth, validation" ``` Auto-detects files matching keywords, creates semantic commit. **Commit Message Format**: ``` fix(auth): fix validation bug in user registration - Updated UserValidator.validate() to check email format - Added test coverage for edge cases - Fixes #123 ``` ### `/prp-pr` - Create Pull Request Generates PR with template support. ```bash /prp-pr "Add user authentication" --base main --head feature/auth ``` **PR Template** (if `.github/pull_request_template.md` exists): ```markdown ## Description Added JWT-based authentication system ## Changes - Implemented JWT token generation - Added auth middleware - Created login/logout endpoints ## Testing - [ ] Unit tests pass - [ ] Integration tests pass - [ ] Manual testing completed ## Checklist - [x] Code follows style guide - [x] Self-review completed - [x] Documentation updated ``` ### `/prp-review` - PR Code Review Comprehensive code review with best practices. ```bash /prp-review 456 ``` **Review Report** (`.claude/PRPs/reviews/pr-456-review.md`): ```markdown # PR Review: #456 ## Summary Well-structured implementation with minor suggestions ## Security Issues ⚠️ HIGH: API key exposed in config file - Move to environment variable ## Performance Concerns 💡 MEDIUM: N+1 query in user list - Use eager loading ## Code Quality ✓ GOOD: Clean separation of concerns ✓ GOOD: Comprehensive test coverage (94%) ⚠️ MINOR: Missing JSDoc for exported functions ## Architecture ✓ Follows existing patterns ✓ Proper error handling ## Suggestions 1. Add input validation for email field 2. Consider caching user lookup 3. Extract magic numbers to constants ## Verdict ✅ APPROVE with minor changes requested ``` ## Ralph Loop - Autonomous Execution Based on Geoffrey Huntley's "Ralph Wiggum" technique - self-referential loop that iterates until ALL validations pass. ### `/prp-ralph` - Start Autonomous Loop ```bash /prp-ralph .claude/PRPs/plans/add-user-auth.plan.md --max-iterations 20 ``` **Process**: 1. Implements plan tasks 2. Runs ALL validation commands 3. If any fail → analyzes, fixes, re-validates 4. Repeats until ALL pass 5. Outputs `<promise>COMPLETE</promise>` 6. Exits gracefully **State Tracking** (`.claude/prp-ralph.state.md`): ```markdown # Ralph Loop State Plan: .claude/PRPs/plans/add-user-auth.plan.md Max Iterations: 20 Current Iteration: 7 ## Last Validation Results ✓ npm run type-check ✗ npm run lint (3 errors) ✓ npm test ✗ npm run build (compilation error) ## Current Focus Fixing lint errors in src/auth/jwt.ts Resolving build error in import path ## Learnings - Arrow functions need explicit return types - Barrel imports must use .js extension ``` ### `/prp-ralph-cancel` - Stop Ralph Loop ```bash /prp-ralph-cancel ``` Removes state file, allowing stop hook to exit gracefully. ## Configuration ### CLAUDE.md - Project Guidelines Create `CLAUDE.md` in your project root: ```markdown # Project Context for Claude Code ## Tech Stack - Node.js 20 - TypeScript 5.3 - Express 4.18 - PostgreSQL 15 ## Code Patterns ### File Structure src/ features/ <feature>/ <feature>.controller.ts <feature>.service.ts <feature>.model.ts <feature>.test.ts ### Naming Conventions - Controllers: `XController` - Services: `XService` - Models: `XModel` - Files: kebab-case ### Error Handling ```typescript try { await service.method(); } catch (error) { logger.error('Context', { error }); throw new AppError('User message', 500); } ``` ### Testing - Use Jest - Mock external dependencies - Test edge cases ## Validation Commands npm run type-check npm run lint npm test npm run build ## Environment Variables DATABASE_URL=${DATABASE_URL} JWT_SECRET=${JWT_SECRET} SMTP_HOST=${SMTP_HOST} ``` ### PRP Templates **Base Template** (`PRPs/templates/prp_base.md`): ```markdown # [Feature Name] ## Context ### Current State - Describe existing implementation - List relevant files ### Goal - What we're building - Why it's needed ## Technical Approach ### Architecture - Component structure - Data flow ### Implementation 1. Step 1 2. Step 2 ## Validation ```bash npm run type-check npm test ``` ## Success Criteria - [ ] Criterion 1 - [ ] Criterion 2 ``` ## Real-World Examples ### Example 1: Adding API Pagination **Step 1: Create Plan** ```bash /prp-plan "add cursor-based pagination to /api/users endpoint" ``` **Generated Plan**: ```markdown # Implementation Plan: API Users Pagination ## Context - File: `src/features/users/users.controller.ts` - Current: Returns all users (no pagination) - Pattern: Other endpoints use `PaginationParams` from `src/utils/pagination.ts` ## Tasks 1. [ ] Update UsersController.list() signature - Add `@Query() params: PaginationParams` - Return `PaginatedResponse<User>` 2. [ ] Modify UsersService.findAll() - Accept cursor and limit params - Use cursor-based query - Return hasMore flag 3. [ ] Add tests - Test pagination edge cases - Test cursor validation ## Files to Modify - src/features/users/users.controller.ts - src/features/users/users.service.ts - src/features/users/users.test.ts ## Validation Commands npm run type-check npm run lint npm test -- users npm run build ## Success Criteria - [ ] Endpoint accepts cursor and limit params - [ ] Returns paginated results with hasMore - [ ] All tests pass - [ ] No type errors ``` **Step 2: Implement with Ralph** ```bash