├── .python-version ├── .gitignore ├── pyproject.toml ├── .claude ├── commands │ ├── development │ │ ├── new-dev-branch.md │ │ ├── prime-core.md │ │ ├── smart-commit.md │ │ ├── create-pr.md │ │ ├── debug-RCA.md │ │ └── onboarding.md │ ├── prp-commands │ │ ├── prp-task-execute.md │ │ ├── prp-spec-execute.md │ │ ├── task-list-init.md │ │ ├── prp-story-execute.md │ │ ├── prp-base-execute.md │ │ ├── prp-task-create.md │ │ ├── prp-spec-create.md │ │ ├── api-contract-define.md │ │ ├── prp-planning-create.md │ │ ├── prp-ts-execute.md │ │ ├── prp-base-create.md │ │ ├── prp-story-create.md │ │ └── prp-ts-create.md │ ├── prp-core │ │ ├── prp-core-run-all.md │ │ ├── prp-core-execute.md │ │ ├── prp-core-commit.md │ │ ├── prp-core-pr.md │ │ ├── prp-core-review.md │ │ └── prp-core-new-branch.md │ ├── code-quality │ │ ├── refactor-simple.md │ │ ├── review-staged-unstaged.md │ │ └── review-general.md │ ├── git-operations │ │ ├── conflict-resolver-specific.md │ │ ├── conflict-resolver-general.md │ │ └── smart-resolver.md │ ├── typescript │ │ ├── TS-execute-base-prp.md │ │ ├── TS-create-base-prp.md │ │ ├── TS-review-staged-unstaged.md │ │ └── TS-review-general.md │ └── rapid-development │ │ └── experimental │ │ ├── user-story-rapid.md │ │ ├── prp-validate.md │ │ ├── create-planning-parallel.md │ │ └── create-base-prp-parallel.md ├── skills │ └── prp-core-runner │ │ └── SKILL.md ├── agents │ ├── library-researcher.md │ └── codebase-analyst.md └── PRPs │ └── scripts │ └── invoke_command.py ├── .claude-plugin └── marketplace.json ├── plugins └── prp-core │ ├── .claude-plugin │ └── plugin.json │ └── commands │ ├── prp-core-execute.md │ ├── prp-core-commit.md │ ├── prp-core-pr.md │ ├── prp-core-review.md │ ├── prp-core-new-branch.md │ └── prp-core-run-all.md ├── PRPs ├── templates │ ├── prp_spec.md │ ├── prp_task.md │ ├── prp_story_task.md │ └── prp_planning.md ├── README.md ├── ai_docs │ ├── cc_containers.md │ ├── cc_troubleshoot.md │ └── hooks.md └── STORY_WORKFLOW_GUIDE.md ├── uv.lock └── CLAUDE.md /.python-version: -------------------------------------------------------------------------------- 1 | 3.12 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Python-generated files 2 | __pycache__/ 3 | *.py[oc] 4 | build/ 5 | dist/ 6 | wheels/ 7 | *.egg-info 8 | 9 | # Virtual environments 10 | .venv 11 | 12 | .env 13 | 14 | .ruff_cache -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "PRP-library" 3 | version = "0.1.0" 4 | description = "Library of assets and prompts for Ai Engineering" 5 | readme = "README.md" 6 | requires-python = ">=3.12" 7 | dependencies = [ 8 | "rich>=14.2.0", 9 | ] 10 | -------------------------------------------------------------------------------- /.claude/commands/development/new-dev-branch.md: -------------------------------------------------------------------------------- 1 | Lets start working on a new branch from develop 2 | 3 | ## Instructions 4 | 5 | 1. Move to develop and ensure you pull latest 6 | 2. Create a new branch from develop for $ARGUMENTS 7 | 3. get ready to start working on the new branch 8 | -------------------------------------------------------------------------------- /.claude-plugin/marketplace.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "prp-marketplace", 3 | "owner": { 4 | "name": "Wirasm", 5 | "email": "contact@wirasm.com" 6 | }, 7 | "description": "PRP (Product Requirement Prompt) workflow automation tools and methodology", 8 | "plugins": [ 9 | { 10 | "name": "prp-core", 11 | "source": "./plugins/prp-core", 12 | "description": "Complete PRP workflow automation - create, execute, commit, and PR commands with orchestration scripts" 13 | } 14 | ] 15 | } 16 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-task-execute.md: -------------------------------------------------------------------------------- 1 | # Execute TASK PRP 2 | 3 | Run through a task list from an existing TASK PRP. 4 | 5 | ## PRP File: $ARGUMENTS 6 | 7 | ## Execution Process 8 | 9 | 1. **Load Tasks** 10 | - Read task list 11 | - Understand context 12 | 13 | 2. **Execute Each Task** 14 | - Perform ACTION 15 | - Run VALIDATE 16 | - Fix IF_FAIL issues 17 | 18 | 3. **Complete Checklist** 19 | - Verify all tasks done 20 | - Run final validation 21 | - Check no regressions 22 | 23 | Work through tasks sequentially, validating each. 24 | -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-run-all.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Run all prp core commands in sequence from feature request to pr 3 | --- 4 | 5 | Feature: $ARGUMENTS 6 | 7 | ## Instructions 8 | 9 | Execute in sequence: 10 | 1. `/prp-core-new-branch $ARGUMENTS` 11 | 2. `/prp-core-create $ARGUMENTS` 12 | 3. `/prp-core-execute` (use PRP from step 2) 13 | 4. `/prp-core-commit` 14 | 5. `/prp-core-pr` (generate title from feature) 15 | 16 | Stop if any fails. 17 | 18 | ## Report 19 | 20 | Output summary of completed workflow including: 21 | - Branch name created 22 | - PRP file path 23 | - Commit hash 24 | - PR URL 25 | -------------------------------------------------------------------------------- /plugins/prp-core/.claude-plugin/plugin.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "prp-core", 3 | "version": "1.0.0", 4 | "description": "Complete PRP (Product Requirement Prompt) workflow automation - create, execute, commit, and PR commands with orchestration scripts", 5 | "author": { 6 | "name": "Wirasm", 7 | "email": "hello@rasmuswiding.com" 8 | }, 9 | "repository": "https://github.com/Wirasm/PRPs-agentic-eng.git", 10 | "commands": ["./commands/"], 11 | "keywords": [ 12 | "prp", 13 | "workflow", 14 | "automation", 15 | "product-requirements", 16 | "implementation", 17 | "git", 18 | "ci-cd" 19 | ] 20 | } 21 | -------------------------------------------------------------------------------- /.claude/commands/development/prime-core.md: -------------------------------------------------------------------------------- 1 | > Command for priming Claude Code with core knowledge about your project 2 | 3 | # Prime Context for Claude Code 4 | 5 | Use the command `tree` to get an understanding of the project structure. 6 | 7 | Start with reading the CLAUDE.md file if it exists to get an understanding of the project. 8 | 9 | Read the README.md file to get an understanding of the project. 10 | 11 | Read key files in the src/ directory 12 | 13 | > List any additional files that are important to understand the project. 14 | 15 | Explain back to me: 16 | - Project structure 17 | - Project purpose and goals 18 | - Key files and their purposes 19 | - Any important dependencies 20 | - Any important configuration files -------------------------------------------------------------------------------- /.claude/commands/code-quality/refactor-simple.md: -------------------------------------------------------------------------------- 1 | Quick refactoring check for Python code focusing on: 2 | - Vertical slice boundaries 3 | - Function complexity 4 | - Type safety with Pydantic v2 5 | - Single responsibility 6 | 7 | Scan for: 8 | 1. Functions >20 lines that need decomposition 9 | 2. long files that need decomposition 10 | 3. Missing Pydantic models for I/O 11 | 4. Cross-feature imports violating vertical slices 12 | 5. Classes with multiple responsibilities 13 | 6. Missing type hints 14 | 15 | Desired architecture: 16 | - Vertical slice boundaries 17 | - Single responsibility 18 | - Type safety with Pydantic v2 19 | 20 | For each issue found, provide: 21 | - Location 22 | - Why it's a problem 23 | - Specific fix with code example 24 | - Specific place where the fix should be implemented 25 | - Priority (high/medium/low) 26 | 27 | Focus on actionable items that can be fixed in <1 hour each. 28 | 29 | save a refactor_plan.md in the PRPs/ai_docs folder, ensure you dont overwrite any existing files -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-spec-execute.md: -------------------------------------------------------------------------------- 1 | # Execute SPEC PRP 2 | 3 | Implement a specification using an existing SPEC PRP. 4 | 5 | ## PRP File: $ARGUMENTS 6 | 7 | ## Execution Process 8 | 9 | 1. **Understand Spec** 10 | - Current state analysis 11 | - Desired state goals 12 | - Task dependencies 13 | 14 | 2. **ULTRATHINK** 15 | - Think hard before you execute the plan. Create a comprehensive plan addressing all requirements. 16 | - Break down complex tasks into smaller, manageable steps using your todos tools. 17 | - Use the TodoWrite tool to create and track your implementation plan. 18 | - Identify implementation patterns from existing code to follow. 19 | 20 | 3. **Execute Tasks** 21 | - Follow task order 22 | - Run validation after each 23 | - Fix failures before proceeding 24 | 25 | 4. **Verify Transformation** 26 | - Confirm desired state achieved 27 | - Run all validation gates 28 | - Test integration 29 | 30 | Progress through each objective systematically. -------------------------------------------------------------------------------- /.claude/commands/prp-commands/task-list-init.md: -------------------------------------------------------------------------------- 1 | claude 2 | \*\* Create a comprehensive task list in PRPs/checklist.md for PRP $ARGIMENTS 3 | 4 | Ingest the infomration then dig deep into our existing codebase and PRP, When done -> 5 | 6 | ULTRATHINK about the PRP task and create the plan based adhering to claude.md and extract and refine detailed tasks following this principle: 7 | 8 | ### list of tasks to be completed to fullfill the PRP in the order they should be completed using infomration dense keywords 9 | 10 | - Infomration dense keyword examples: 11 | ADD, CREATE, MODIFY, MIRROR, FIND, EXECUTE, KEEP, PRESERVE etc 12 | 13 | Mark done tasks with: STATUS [DONE], if not done leave empty 14 | 15 | ```yaml 16 | Task 1: 17 | STATUS [ ] 18 | MODIFY src/existing_module.py: 19 | - FIND pattern: "class OldImplementation" 20 | - INJECT after line containing "def __init__" 21 | - PRESERVE existing method signatures 22 | 23 | STATUS [ ] 24 | CREATE src/new_feature.py: 25 | - MIRROR pattern from: src/similar_feature.py 26 | - MODIFY class name and core logic 27 | - KEEP error handling pattern identical 28 | 29 | ...(...) 30 | 31 | Task N: 32 | ... 33 | 34 | ``` 35 | 36 | Each task should have unit test coverage, make tests pass on each task 37 | -------------------------------------------------------------------------------- /.claude/commands/git-operations/conflict-resolver-specific.md: -------------------------------------------------------------------------------- 1 | You are an expert at resolving Git merge conflicts. $ARGUMENTS 2 | 3 | ## Resolution strategy based on arguments: 4 | 5 | - If "safe" is mentioned: Only auto-resolve obvious conflicts, ask for guidance on complex ones 6 | - If "aggressive" is mentioned: Make best judgment calls on all conflicts 7 | - If "test" is mentioned: Run tests after each resolution 8 | - If "ours" is mentioned: Prefer our changes when in doubt 9 | - If "theirs" is mentioned: Prefer their changes when in doubt 10 | - If specific files are mentioned: Only resolve those files 11 | 12 | ## Process: 13 | 14 | 1. Check git status and identify conflicts 15 | 2. use the github cli to check the PRs and understand the context 16 | 3. Think hard about your findings and plan accordingly 17 | 4. Based on the strategy arguments provided, resolve conflicts accordingly 18 | 5. For each resolution, document what decision was made and why 19 | 6. If "test" was specified, run tests after each file resolution 20 | 7. Provide detailed summary of all resolutions 21 | 22 | ## Special handling: 23 | 24 | - package-lock.json / yarn.lock: Usually regenerate these files 25 | - Migration files: Be extra careful, might need to create new migration 26 | - Schema files: Ensure compatibility is maintained 27 | - API files: Check for breaking changes 28 | 29 | Start by running git status to see all conflicts. -------------------------------------------------------------------------------- /.claude/commands/development/smart-commit.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: commit 3 | description: Analyze changes and create a smart git commit 4 | arguments: "Additional instructions for the commit" 5 | --- 6 | 7 | additional instructions = $ARGUMENTS 8 | 9 | type = "feat", "fix", "docs", "style", "refactor", "perf", "test", "chore" 10 | 11 | # Smart Git CommitPRPs/ai_docs 12 | 13 | Please help me create a git commit by: 14 | 15 | 1. First, check the current git status and analyze what changed: 16 | 17 | ```bash 18 | git status 19 | git diff --staged 20 | ``` 21 | 22 | 2. If no files are staged, show me the changes and help me decide what to stage: 23 | 24 | ```bash 25 | git diff 26 | git status -s 27 | ``` 28 | 29 | 3. Based on the changes, suggest: 30 | 31 | - The appropriate commit type (feat/fix/docs/style/refactor/perf/test/chore) 32 | - A concise, descriptive commit message following conventional commits 33 | - If the changes are complex, suggest breaking into multiple commits 34 | 35 | 4. The commit format should be: 36 | 37 | $type: description for simple commits 38 | For complex changes, include a body explaining what and why 39 | 40 | 5. After showing me the suggested commit message, ask if I want to: 41 | 42 | - Use it as-is 43 | - Modify it 44 | - Add more details to the body 45 | - Stage different files 46 | 47 | 6. Once approved, create the commit and show me the result. 48 | 49 | 7. Finally, ask if I want to push or create a PR. 50 | -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-execute.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: "Execute a feature PRP until fully complete" 3 | --- 4 | 5 | # Execute Feature PRP 6 | 7 | ## PRP File: $ARGUMENTS 8 | 9 | ## Instructions 10 | 11 | - Ingest the PRP file completely 12 | - Think hard about the implementation approach 13 | - Execute every task in the STEP-BY-STEP TASKS section sequentially 14 | - Validate after each task using the task's validation command 15 | - If validation fails, fix and re-validate before proceeding 16 | - Run full validation suite from the PRP when all tasks complete 17 | - **Critical**: Don't stop until the entire plan is fulfilled and all validation passes 18 | - Use TodoWrite to track progress through tasks 19 | - Trust the PRP's strategic direction, but verify tactical details (imports, paths, names) 20 | - If the PRP has errors in details, fix them and note in report 21 | 22 | ## Success Criteria 23 | 24 | - ✓ Every task completed 25 | - ✓ All validation commands pass 26 | - ✓ Acceptance criteria met 27 | 28 | ## Completion 29 | 30 | Once all validation passes: 31 | 32 | ```bash 33 | mkdir -p .claude/PRPs/features/completed 34 | mv .claude/PRPs/features/{prp-file}.md .claude/PRPs/features/completed/ 35 | ``` 36 | 37 | ## Report 38 | 39 | After completion: 40 | 41 | **Summary:** 42 | - Feature: {name} 43 | - Tasks completed: {count} 44 | - Files created/modified: {list} 45 | 46 | **Validation:** 47 | ```bash 48 | ✓ Linting: Passed 49 | ✓ Type checking: Passed 50 | ✓ Tests: X/X passed 51 | ``` 52 | 53 | **Adjustments** (if any): 54 | - Note any PRP details that were incorrect and how you fixed them 55 | 56 | **Files Changed:** 57 | ```bash 58 | git diff --stat 59 | ``` 60 | -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-execute.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: "Execute a feature PRP until fully complete" 3 | --- 4 | 5 | # Execute Feature PRP 6 | 7 | ## PRP File: $ARGUMENTS 8 | 9 | ## Instructions 10 | 11 | - Ingest the PRP file completely 12 | - Think hard about the implementation approach 13 | - Execute every task in the STEP-BY-STEP TASKS section sequentially 14 | - Validate after each task using the task's validation command 15 | - If validation fails, fix and re-validate before proceeding 16 | - Run full validation suite from the PRP when all tasks complete 17 | - **Critical**: Don't stop until the entire plan is fulfilled and all validation passes 18 | - Use TodoWrite to track progress through tasks 19 | - Trust the PRP's strategic direction, but verify tactical details (imports, paths, names) 20 | - If the PRP has errors in details, fix them and note in report 21 | 22 | ## Success Criteria 23 | 24 | - ✓ Every task completed 25 | - ✓ All validation commands pass 26 | - ✓ Acceptance criteria met 27 | 28 | ## Completion 29 | 30 | Once all validation passes: 31 | 32 | ```bash 33 | mkdir -p .claude/PRPs/features/completed 34 | mv .claude/PRPs/features/{prp-file}.md .claude/PRPs/features/completed/ 35 | ``` 36 | 37 | ## Report 38 | 39 | After completion: 40 | 41 | **Summary:** 42 | - Feature: {name} 43 | - Tasks completed: {count} 44 | - Files created/modified: {list} 45 | 46 | **Validation:** 47 | ```bash 48 | ✓ Linting: Passed 49 | ✓ Type checking: Passed 50 | ✓ Tests: X/X passed 51 | ``` 52 | 53 | **Adjustments** (if any): 54 | - Note any PRP details that were incorrect and how you fixed them 55 | 56 | **Files Changed:** 57 | ```bash 58 | git diff --stat 59 | ``` 60 | -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-commit.md: -------------------------------------------------------------------------------- 1 | # Create Git Commit 2 | 3 | Create an atomic git commit with a properly formatted commit message following best practices for the uncommited changes or these specific files if specified. 4 | 5 | Specific files (skip if not specified): 6 | 7 | - File 1: $1 8 | - File 2: $2 9 | - File 3: $3 10 | - File 4: $4 11 | - File 5: $5 12 | 13 | ## Instructions 14 | 15 | **Commit Message Format:** 16 | 17 | - Use conventional commits: `: ` 18 | - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` 19 | - Present tense (e.g., "add", "fix", "update", not "added", "fixed", "updated") 20 | - 50 characters or less for the subject line 21 | - Lowercase subject line 22 | - No period at the end 23 | - Be specific and descriptive 24 | 25 | **Examples:** 26 | 27 | - `feat: add web search tool with structured logging` 28 | - `fix: resolve type errors in middleware` 29 | - `test: add unit tests for config module` 30 | - `docs: update CLAUDE.md with testing guidelines` 31 | - `refactor: simplify logging configuration` 32 | - `chore: update dependencies` 33 | 34 | **Atomic Commits:** 35 | 36 | - One logical change per commit 37 | - If you've made multiple unrelated changes, consider splitting into separate commits 38 | - Commit should be self-contained and not break the build 39 | 40 | **IMPORTANT** 41 | 42 | - NEVER mention claude code, anthropic, co authored by or anything similar in the commit messages 43 | 44 | ## Run 45 | 46 | 1. Review changes: `git diff HEAD` 47 | 2. Check status: `git status` 48 | 3. Stage changes: `git add -A` 49 | 4. Create commit: `git commit -m ": "` 50 | 51 | ## Report 52 | 53 | - Output the commit message used 54 | - Confirm commit was successful with commit hash 55 | - List files that were committed 56 | -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-commit.md: -------------------------------------------------------------------------------- 1 | # Create Git Commit 2 | 3 | Create an atomic git commit with a properly formatted commit message following best practices for the uncommited changes or these specific files if specified. 4 | 5 | Specific files (skip if not specified): 6 | 7 | - File 1: $1 8 | - File 2: $2 9 | - File 3: $3 10 | - File 4: $4 11 | - File 5: $5 12 | 13 | ## Instructions 14 | 15 | **Commit Message Format:** 16 | 17 | - Use conventional commits: `: ` 18 | - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` 19 | - Present tense (e.g., "add", "fix", "update", not "added", "fixed", "updated") 20 | - 50 characters or less for the subject line 21 | - Lowercase subject line 22 | - No period at the end 23 | - Be specific and descriptive 24 | 25 | **Examples:** 26 | 27 | - `feat: add web search tool with structured logging` 28 | - `fix: resolve type errors in middleware` 29 | - `test: add unit tests for config module` 30 | - `docs: update CLAUDE.md with testing guidelines` 31 | - `refactor: simplify logging configuration` 32 | - `chore: update dependencies` 33 | 34 | **Atomic Commits:** 35 | 36 | - One logical change per commit 37 | - If you've made multiple unrelated changes, consider splitting into separate commits 38 | - Commit should be self-contained and not break the build 39 | 40 | **IMPORTANT** 41 | 42 | - NEVER mention claude code, anthropic, co authored by or anything similar in the commit messages 43 | 44 | ## Run 45 | 46 | 1. Review changes: `git diff HEAD` 47 | 2. Check status: `git status` 48 | 3. Stage changes: `git add -A` 49 | 4. Create commit: `git commit -m ": "` 50 | 51 | ## Report 52 | 53 | - Output the commit message used 54 | - Confirm commit was successful with commit hash 55 | - List files that were committed 56 | -------------------------------------------------------------------------------- /.claude/commands/git-operations/conflict-resolver-general.md: -------------------------------------------------------------------------------- 1 | You are an expert at resolving Git merge conflicts intelligently. Your task is to resolve all merge conflicts in the current repository. 2 | 3 | ## Step-by-step process: 4 | 5 | 1. First, check the current git status to understand the situation 6 | 2. Identify all files with merge conflicts 7 | 3. For each conflicted file: 8 | - Read and understand both versions (ours and theirs) 9 | - Understand the intent of both changes 10 | - Use the github cli if available 11 | - Think hard and plan how to resolve each conflict 12 | - Resolve conflicts by intelligently combining both changes when possible 13 | - If changes are incompatible, prefer the version that: 14 | - Maintains backward compatibility 15 | - Has better test coverage 16 | - Follows the project's coding standards better 17 | - Is more performant 18 | - Remove all conflict markers (<<<<<<<, =======, >>>>>>>) 19 | 4. After resolving each file, verify the syntax is correct 20 | 5. Run any relevant tests to ensure nothing is broken 21 | 6. Stage the resolved files 22 | 7. Provide a summary of all resolutions made 23 | 24 | ## Important guidelines: 25 | 26 | - NEVER just pick one side blindly - understand both changes 27 | - Preserve the intent of both branches when possible 28 | - Look for semantic conflicts (code that merges cleanly but breaks functionality) 29 | - If unsure, explain the conflict and ask for guidance 30 | - Always test after resolution if tests are available 31 | - Consider the broader context of the codebase 32 | 33 | ## Commands you should use: 34 | 35 | - `git status` - Check current state 36 | - `git diff` - Understand changes 37 | - `git log --oneline -n 20 --graph --all` - Understand recent history 38 | - Read conflicted files to understand the conflicts 39 | - Edit files to resolve conflicts 40 | - `git add ` - Stage resolved files 41 | - Run tests with appropriate commands (npm test, pytest, etc.) 42 | - Use the github cli if available to check the PRs and understand the context and conflicts 43 | 44 | Begin by checking the current git status. -------------------------------------------------------------------------------- /PRPs/templates/prp_spec.md: -------------------------------------------------------------------------------- 1 | # Specification Template (prompt inspired by IndyDevDan) 2 | 3 | > Ingest the information from this file, implement the Low-Level Tasks, and generate the code that will satisfy the High and Mid-Level Objectives. 4 | 5 | ## High-Level Objective 6 | 7 | - [High level goal goes here - what do you want to build?] 8 | 9 | ## Mid-Level Objective 10 | 11 | - [List of mid-level objectives - what are the steps to achieve the high-level objective?] 12 | - [Each objective should be concrete and measurable] 13 | - [But not too detailed - save details for implementation notes] 14 | 15 | ## Implementation Notes 16 | 17 | - [Important technical details - what are the important technical details?] 18 | - [Dependencies and requirements - what are the dependencies and requirements?] 19 | - [Coding standards to follow - what are the coding standards to follow?] 20 | - [Other technical guidance - what are other technical guidance?] 21 | 22 | ## Context 23 | 24 | ### Beginning context 25 | 26 | - [List of files that exist at start - what files exist at start?] 27 | 28 | ### Ending context 29 | 30 | - [List of files that will exist at end - what files will exist at end?] 31 | 32 | ## Low-Level Tasks 33 | 34 | > Ordered from start to finish 35 | 36 | 1. [First task - what is the first task?] 37 | 38 | ``` 39 | What prompt would you run to complete this task? 40 | What file do you want to CREATE or UPDATE? 41 | What function do you want to CREATE or UPDATE? 42 | What are details you want to add to drive the code changes? 43 | ``` 44 | 45 | 2. [Second task - what is the second task?] 46 | 47 | ``` 48 | What prompt would you run to complete this task? 49 | What file do you want to CREATE or UPDATE? 50 | What function do you want to CREATE or UPDATE? 51 | What are details you want to add to drive the code changes? 52 | ``` 53 | 54 | 3. [Third task - what is the third task?] 55 | 56 | ``` 57 | What prompt would you run to complete this task? 58 | What file do you want to CREATE or UPDATE? 59 | What function do you want to CREATE or UPDATE? 60 | What are details you want to add to drive the code changes? 61 | ``` 62 | -------------------------------------------------------------------------------- /.claude/commands/git-operations/smart-resolver.md: -------------------------------------------------------------------------------- 1 | Perform an intelligent merge conflict resolution with deep understanding of our codebase. 2 | 3 | ## Pre-resolution analysis: 4 | 5 | 1. Understand what each branch was trying to achieve: 6 | git log --oneline origin/main..HEAD 7 | git log --oneline HEAD..origin/main 8 | 9 | 2. Check if there are any related issues or PRs: 10 | git log --grep="fix" --grep="feat" --oneline -20 11 | - use the github cli as needed 12 | 13 | 3. Identify the type of conflicts (feature vs feature, fix vs refactor, etc.) 14 | 15 | 4. Think hard about your findings and plan accordingly 16 | 17 | ## Resolution strategy: 18 | 19 | ### For different file types: 20 | 21 | **Source code conflicts (.js, .ts, .py, etc.)**: 22 | - Understand the business logic of both changes 23 | - Merge both features if they're complementary 24 | - If conflicting, check which has better test coverage 25 | - Look for related files that might need updates 26 | 27 | **Test file conflicts**: 28 | - Usually merge both sets of tests 29 | - Ensure no duplicate test names 30 | - Update test descriptions if needed 31 | 32 | **Configuration files**: 33 | - package.json: Merge dependencies, scripts 34 | - .env.example: Include all new variables 35 | - CI/CD configs: Merge all jobs unless duplicate 36 | 37 | **Documentation conflicts**: 38 | - Merge both documentation updates 39 | - Ensure consistency in terminology 40 | - Update table of contents if needed 41 | 42 | **Lock files (package-lock.json, poetry.lock)**: 43 | - Delete and regenerate after resolving package.json/pyproject.toml 44 | 45 | ## Post-resolution verification: 46 | 47 | 1. Run linters to check code style 48 | 2. Run type checkers if applicable 49 | 3. Run test suite 50 | 4. Check for semantic conflicts (code that merges but breaks functionality) 51 | 5. Verify no debugging code was left in 52 | 53 | ## Final steps: 54 | 55 | 1. Create a detailed summary of all resolutions 56 | 2. If any resolutions are uncertain, mark them with TODO comments 57 | 3. Suggest additional testing that might be needed 58 | 4. Stage all resolved files 59 | 60 | Begin by analyzing the current conflict situation with git status and understanding both branches. -------------------------------------------------------------------------------- /.claude/commands/typescript/TS-execute-base-prp.md: -------------------------------------------------------------------------------- 1 | # Execute BASE PRP 2 | 3 | Implement a TypeScript/JavaScript feature using the PRP file. 4 | 5 | ## PRP File: $ARGUMENTS 6 | 7 | ## Execution Process 8 | 9 | 1. **Load PRP** 10 | - Read the specified PRP file 11 | - Understand all context and requirements 12 | - Follow all instructions in the PRP and extend the research if needed 13 | - Ensure you have all needed context to implement the PRP fully 14 | - Do more web searches and codebase exploration as needed 15 | 16 | 2. **ULTRATHINK** 17 | - Ultrathink before you execute the plan. Create a comprehensive plan addressing all requirements. 18 | - Break down the PRP into clear todos using the TodoWrite tool. 19 | - Use agents subagents and batchtool to enhance the process. 20 | - **Important** YOU MUST ENSURE YOU HAVE EXTREMELY CLEAR TASKS FOR SUBAGENTS AND REFERENCE CONTEXT AND MAKE SURE EACH SUBAGENT READS THE PRP AND UNDERSTANDS ITS CONTEXT. 21 | - Identify implementation patterns from existing code to follow. 22 | - Never guess about imports, file names function names etc, ALWAYS be based in reality and real context gathering 23 | 24 | 3. ## **Execute the plan** 25 | 26 | ## Execute the PRP step by step 27 | - Implement all the code 28 | - Follow TypeScript/JavaScript best practices 29 | - Ensure proper type safety and error handling 30 | - Follow existing codebase patterns and conventions 31 | 32 | 4. **Validate** 33 | - Run each validation command from the PRP 34 | - The better validation that is done, the more confident we can be that the implementation is correct. 35 | - Fix any failures (type errors, linting issues, test failures) 36 | - Re-run until all pass 37 | - Always re-read the PRP to validate and review the implementation to ensure it meets the requirements 38 | 39 | 5. **Complete** 40 | - Ensure all checklist items done 41 | - Run final validation suite 42 | - Report completion status 43 | - Read the PRP again to ensure you have implemented everything 44 | 45 | 6. **Reference the PRP** 46 | - You can always reference the PRP again if needed 47 | 48 | Note: If validation fails, use error patterns in PRP to fix and retry. -------------------------------------------------------------------------------- /.claude/commands/development/create-pr.md: -------------------------------------------------------------------------------- 1 | # Create Pull Request 2 | 3 | Create a well-structured pull request with proper description and context. 4 | 5 | ## PR Title (if provided) 6 | $ARGUMENTS 7 | 8 | ## Process 9 | 10 | 1. **Prepare Branch** 11 | ```bash 12 | # Check current branch 13 | git branch --show-current 14 | 15 | # Ensure we're not on main 16 | # If on main, create a feature branch 17 | ``` 18 | 19 | 2. **Review Changes** 20 | ```bash 21 | # See what will be included 22 | git status 23 | git diff main...HEAD 24 | ``` 25 | 26 | 3. **Create Commits** 27 | - Stage relevant files 28 | - Create logical, atomic commits if not already done 29 | - Write clear commit messages following conventional commits, do not include any reference to cluade, written by clade etc: 30 | - `feat:` for new features 31 | - `fix:` for bug fixes 32 | - `docs:` for documentation 33 | - `test:` for tests 34 | - `refactor:` for refactoring 35 | 36 | 4. **Push to Remote** 37 | ```bash 38 | git push -u origin HEAD 39 | ``` 40 | 41 | 5. **Create PR** 42 | ```bash 43 | gh pr create --title "$ARGUMENTS" --body "$(cat <<'EOF' 44 | ## Summary 45 | [Brief description of what this PR does] 46 | 47 | ## Changes 48 | - [List key changes] 49 | - [Be specific] 50 | 51 | ## Type of Change 52 | - [ ] Bug fix 53 | - [ ] New feature 54 | - [ ] Breaking change 55 | - [ ] Documentation update 56 | 57 | ## Testing 58 | - [ ] Tests pass locally 59 | - [ ] Added new tests 60 | - [ ] Manual testing completed 61 | 62 | ## Checklist 63 | - [ ] Code follows project style 64 | - [ ] Self-reviewed 65 | - [ ] Updated documentation 66 | - [ ] No console.logs or debug code 67 | 68 | ## Screenshots (if applicable) 69 | [Add screenshots for UI changes] 70 | 71 | ## Additional Context 72 | [Any extra information reviewers should know] 73 | EOF 74 | )" 75 | ``` 76 | 77 | 6. **Post-Creation** 78 | - Add labels if needed: `gh pr edit --add-label "feature,needs-review"` 79 | - Request reviewers if known 80 | - Link to related issues 81 | 82 | Remember to: 83 | - Keep PRs focused and small 84 | - Provide context for reviewers 85 | - Test thoroughly before creating PR -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-pr.md: -------------------------------------------------------------------------------- 1 | # Create Pull Request 2 | 3 | Create a well-structured pull request with proper description and context. 4 | 5 | ## PR Title (if provided) 6 | $ARGUMENTS 7 | 8 | ## Process 9 | 10 | 1. **Prepare Branch** 11 | ```bash 12 | # Check current branch 13 | git branch --show-current 14 | 15 | # Ensure we're not on main 16 | # If on main, create a feature branch 17 | ``` 18 | 19 | 2. **Review Changes** 20 | ```bash 21 | # See what will be included 22 | git status 23 | git diff main...HEAD 24 | ``` 25 | 26 | 3. **Create Commits** 27 | - Stage relevant files 28 | - Create logical, atomic commits if not already done 29 | - Write clear commit messages following conventional commits, do not include any reference to cluade, written by clade etc: 30 | - `feat:` for new features 31 | - `fix:` for bug fixes 32 | - `docs:` for documentation 33 | - `test:` for tests 34 | - `refactor:` for refactoring 35 | 36 | 4. **Push to Remote** 37 | ```bash 38 | git push -u origin HEAD 39 | ``` 40 | 41 | 5. **Create PR** 42 | ```bash 43 | gh pr create --title "$ARGUMENTS" --body "$(cat <<'EOF' 44 | ## Summary 45 | [Brief description of what this PR does] 46 | 47 | ## Changes 48 | - [List key changes] 49 | - [Be specific] 50 | 51 | ## Type of Change 52 | - [ ] Bug fix 53 | - [ ] New feature 54 | - [ ] Breaking change 55 | - [ ] Documentation update 56 | 57 | ## Testing 58 | - [ ] Tests pass locally 59 | - [ ] Added new tests 60 | - [ ] Manual testing completed 61 | 62 | ## Checklist 63 | - [ ] Code follows project style 64 | - [ ] Self-reviewed 65 | - [ ] Updated documentation 66 | - [ ] No console.logs or debug code 67 | 68 | ## Screenshots (if applicable) 69 | [Add screenshots for UI changes] 70 | 71 | ## Additional Context 72 | [Any extra information reviewers should know] 73 | EOF 74 | )" 75 | ``` 76 | 77 | 6. **Post-Creation** 78 | - Add labels if needed: `gh pr edit --add-label "feature,needs-review"` 79 | - Request reviewers if known 80 | - Link to related issues 81 | 82 | Remember to: 83 | - Keep PRs focused and small 84 | - Provide context for reviewers 85 | - Test thoroughly before creating PR -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-pr.md: -------------------------------------------------------------------------------- 1 | # Create Pull Request 2 | 3 | Create a well-structured pull request with proper description and context. 4 | 5 | ## PR Title (if provided) 6 | $ARGUMENTS 7 | 8 | ## Process 9 | 10 | 1. **Prepare Branch** 11 | ```bash 12 | # Check current branch 13 | git branch --show-current 14 | 15 | # Ensure we're not on main 16 | # If on main, create a feature branch 17 | ``` 18 | 19 | 2. **Review Changes** 20 | ```bash 21 | # See what will be included 22 | git status 23 | git diff main...HEAD 24 | ``` 25 | 26 | 3. **Create Commits** 27 | - Stage relevant files 28 | - Create logical, atomic commits if not already done 29 | - Write clear commit messages following conventional commits, do not include any reference to cluade, written by clade etc: 30 | - `feat:` for new features 31 | - `fix:` for bug fixes 32 | - `docs:` for documentation 33 | - `test:` for tests 34 | - `refactor:` for refactoring 35 | 36 | 4. **Push to Remote** 37 | ```bash 38 | git push -u origin HEAD 39 | ``` 40 | 41 | 5. **Create PR** 42 | ```bash 43 | gh pr create --title "$ARGUMENTS" --body "$(cat <<'EOF' 44 | ## Summary 45 | [Brief description of what this PR does] 46 | 47 | ## Changes 48 | - [List key changes] 49 | - [Be specific] 50 | 51 | ## Type of Change 52 | - [ ] Bug fix 53 | - [ ] New feature 54 | - [ ] Breaking change 55 | - [ ] Documentation update 56 | 57 | ## Testing 58 | - [ ] Tests pass locally 59 | - [ ] Added new tests 60 | - [ ] Manual testing completed 61 | 62 | ## Checklist 63 | - [ ] Code follows project style 64 | - [ ] Self-reviewed 65 | - [ ] Updated documentation 66 | - [ ] No console.logs or debug code 67 | 68 | ## Screenshots (if applicable) 69 | [Add screenshots for UI changes] 70 | 71 | ## Additional Context 72 | [Any extra information reviewers should know] 73 | EOF 74 | )" 75 | ``` 76 | 77 | 6. **Post-Creation** 78 | - Add labels if needed: `gh pr edit --add-label "feature,needs-review"` 79 | - Request reviewers if known 80 | - Link to related issues 81 | 82 | Remember to: 83 | - Keep PRs focused and small 84 | - Provide context for reviewers 85 | - Test thoroughly before creating PR -------------------------------------------------------------------------------- /.claude/commands/code-quality/review-staged-unstaged.md: -------------------------------------------------------------------------------- 1 | List and review any files in the staging area, both staged and unstaged. 2 | Ensure you look at both new files and modified files. 3 | 4 | Check the diff of each file to see what has changed. 5 | 6 | Previous review report: $ARGUMENTS 7 | 8 | May or may not be added, ignore the previous review if not specified. 9 | 10 | ## Review Focus Areas 11 | 12 | 1. **Code Quality** 13 | - Type hints on all functions and classes 14 | - Pydantic v2 models for data validation 15 | - No print() statements (use logging) 16 | - Proper error handling 17 | - Following PEP 8 18 | - Docstrings following google style python docstrings 19 | 20 | 2. **Pydantic v2 Patterns** 21 | - Using ConfigDict not class Config 22 | - field_validator not @validator 23 | - model_dump() not dict() 24 | - Proper use of Annotated types 25 | 26 | 3. **Security** 27 | - Input validation on all endpoints 28 | - No SQL injection vulnerabilities 29 | - Passwords properly hashed 30 | - No hardcoded secrets 31 | 32 | 4. **Structure** 33 | - Unit tests are co-located with the code they test in tests/ folders 34 | - Each feature is self-contained with its own models, service, and tools 35 | - Shared components are only things used by multiple features 36 | - Future improvements (like multiple AI providers) would go in src/shared/ai_providers/ when implemented 37 | - Integration tests remain at the root level in tests/integration/ 38 | 39 | 5. **Linting** 40 | - ruff check --fix 41 | - mypy 42 | 43 | 6. **Testing** 44 | - New code has tests 45 | - Edge cases covered 46 | - Mocking external dependencies 47 | 48 | 7. **Performance** 49 | - No N+1 queries 50 | - Efficient algorithms 51 | - Proper async usage 52 | 53 | 8. **Documentation** 54 | - Clear README with setup instructions 55 | - CLAUDE.md is up to date with any new important utils, dependencies etc for future cluade code instances 56 | 57 | ## Review Output 58 | 59 | Create a concise review report with: 60 | 61 | ```markdown 62 | # Code Review #[number] 63 | 64 | ## Summary 65 | [2-3 sentence overview] 66 | 67 | ## Issues Found 68 | 69 | ### 🔴 Critical (Must Fix) 70 | - [Issue with file:line and suggested fix] 71 | 72 | ### 🟡 Important (Should Fix) 73 | - [Issue with file:line and suggested fix] 74 | 75 | ### 🟢 Minor (Consider) 76 | - [Improvement suggestions] 77 | 78 | ## Good Practices 79 | - [What was done well] 80 | 81 | ## Test Coverage 82 | Current: X% | Required: 80% 83 | Missing tests: [list] 84 | Save report to PRPs/code_reviews/review[#].md (check existing files first) 85 | 86 | -------------------------------------------------------------------------------- /PRPs/README.md: -------------------------------------------------------------------------------- 1 | # Product Requirement Prompt (PRP) Concept 2 | 3 | "Over-specifying what to build while under-specifying the context, and how to build it, is why so many AI-driven coding attempts stall at 80%. A Product Requirement Prompt (PRP) fixes that by fusing the disciplined scope of a classic Product Requirements Document (PRD) with the “context-is-king” mindset of modern prompt engineering." 4 | 5 | ## What is a PRP? 6 | 7 | Product Requirement Prompt (PRP) 8 | A PRP is a structured prompt that supplies an AI coding agent with everything it needs to deliver a vertical slice of working software—no more, no less. 9 | 10 | ### How it differs from a PRD 11 | 12 | A traditional PRD clarifies what the product must do and why customers need it, but deliberately avoids how it will be built. 13 | 14 | A PRP keeps the goal and justification sections of a PRD yet adds three AI-critical layers: 15 | 16 | ### Context 17 | 18 | - Precise file paths and content, library versions and library context, code snippets examples. LLMs generate higher-quality code when given direct, in-prompt references instead of broad descriptions. Usage of a ai_docs/ directory to pipe in library and other docs. 19 | 20 | ### Implementation Details and Strategy 21 | 22 | - In contrast of a traditional PRD, a PRP explicitly states how the product will be built. This includes the use of API endpoints, test runners, or agent patterns (ReAct, Plan-and-Execute) to use. Usage of typehints, dependencies, architectural patterns and other tools to ensure the code is built correctly. 23 | 24 | ### Validation Gates 25 | 26 | - Deterministic checks such as pytest, ruff, or static type passes “Shift-left” quality controls catch defects early and are cheaper than late re-work. 27 | Example: Each new funtion should be individaully tested, Validation gate = all tests pass. 28 | 29 | ### PRP Layer Why It Exists 30 | 31 | - The PRP folder is used to prepare and pipe PRPs to the agentic coder. 32 | 33 | ## Why context is non-negotiable 34 | 35 | Large-language-model outputs are bounded by their context window; irrelevant or missing context literally squeezes out useful tokens 36 | 37 | The industry mantra “Garbage In → Garbage Out” applies doubly to prompt engineering and especially in agentic engineering: sloppy input yields brittle code 38 | 39 | ## In short 40 | 41 | A PRP is PRD + curated codebase intelligence + agent/runbook—the minimum viable packet an AI needs to plausibly ship production-ready code on the first pass. 42 | 43 | The PRP can be small and focusing on a single task or large and covering multiple tasks. 44 | The true power of PRP is in the ability to chain tasks together in a PRP to build, self-validate and ship complex features. 45 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-story-execute.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: "Execute a Story PRP with focused task implementation" 3 | --- 4 | 5 | # Execute Story PRP 6 | 7 | ## PRP File: $ARGUMENTS 8 | 9 | ## Mission 10 | 11 | Execute a story/task PRP through **sequential task completion** with immediate validation. 12 | 13 | **Execution Philosophy**: Complete one task, validate it, then move to the next. No task left behind. 14 | 15 | ## Execution Process 16 | 17 | ### 1. Load Story PRP 18 | 19 | - Read the specified story PRP file 20 | - Understand the original story intent 21 | - Review all context references 22 | - Note validation commands for each task 23 | 24 | ### 2. Pre-Implementation Check 25 | 26 | - Ultrathink about the story intent and task requirements 27 | - Verify all referenced files exist 28 | - Check that patterns mentioned are accessible 29 | - Ensure development environment is ready 30 | - Run any pre-requisite setup commands 31 | 32 | ### 3. Task-by-Task Implementation 33 | 34 | For each task in the PRP: 35 | 36 | **a) Understand Task** 37 | 38 | - Read task requirements completely 39 | - Review referenced patterns 40 | - Check gotchas and constraints 41 | 42 | **b) Implement Task** 43 | 44 | - Follow the specified pattern 45 | - Use the indicated naming conventions 46 | - Apply the documented approach 47 | - Handle edge cases mentioned 48 | 49 | **c) Validate Immediately** 50 | 51 | - Run the task's validation command 52 | - If validation fails, fix and re-validate 53 | - Don't proceed until current task passes 54 | 55 | **d) Mark Complete** 56 | 57 | - Update todo list to track progress 58 | - Document any deviations if necessary 59 | 60 | ### 4. Full Validation 61 | 62 | After all tasks complete: 63 | 64 | - Run the validation gates from PRP 65 | - Execute comprehensive test suite 66 | - Verify all acceptance criteria met 67 | 68 | ### 5. Completion 69 | 70 | - Work through completion checklist 71 | - Ensure story requirements satisfied 72 | - Move completed PRP to PRPs/completed/ create the folder if it does not exist 73 | 74 | ## Execution Rules 75 | 76 | **Validation Gates**: Each task must pass validation, iterate until passed 77 | **Pattern Adherence**: Follow existing patterns, don't create new ones 78 | **No Shortcuts**: Complete all validation steps 79 | 80 | ## Failure Handling 81 | 82 | When a task fails validation: 83 | 84 | 1. Read the error message carefully 85 | 2. Check the pattern reference again 86 | 3. Validate it by investigating the codebase 87 | 4. Fix and re-validate 88 | 5. If stuck, check similar implementations 89 | 90 | ## Success Criteria 91 | 92 | - Every validation command passes 93 | - Full test suite green 94 | - Story acceptance criteria met 95 | - Code follows project conventions 96 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-base-execute.md: -------------------------------------------------------------------------------- 1 | # Execute BASE PRP 2 | 3 | ## PRP File: $ARGUMENTS 4 | 5 | ## Mission: One-Pass Implementation Success 6 | 7 | PRPs enable working code on the first attempt through: 8 | 9 | - **Context Completeness**: Everything needed, nothing guessed 10 | - **Progressive Validation**: 4-level gates catch errors early 11 | - **Pattern Consistency**: Follow existing codebase approaches 12 | - Read PRPs/README.md to understand PRP concepts 13 | 14 | **Your Goal**: Transform the PRP into working code that passes all validation gates. 15 | 16 | ## Execution Process 17 | 18 | 1. **Load PRP** 19 | - Read the specified PRP file completely 20 | - Absorb all context, patterns, requirements and gather codebase intelligence 21 | - Use the provided documentation references and file patterns, consume the right documentation before the appropriate todo/task 22 | - Trust the PRP's context and guidance - it's designed for one-pass success 23 | - If needed do additional codebase exploration and research as needed 24 | 25 | 2. **ULTRATHINK & Plan** 26 | - Create comprehensive implementation plan following the PRP's task order 27 | - Break down into clear todos using TodoWrite tool 28 | - Use subagents for parallel work when beneficial (always create prp inspired prompts for subagents when used) 29 | - Follow the patterns referenced in the PRP 30 | - Use specific file paths, class names, and method signatures from PRP context 31 | - Never guess - always verify the codebase patterns and examples referenced in the PRP yourself 32 | 33 | 3. **Execute Implementation** 34 | - Follow the PRP's Implementation Tasks sequence, add more detail as needed, especially when using subagents 35 | - Use the patterns and examples referenced in the PRP 36 | - Create files in locations specified by the desired codebase tree 37 | - Apply naming conventions from the task specifications and CLAUDE.md 38 | 39 | 4. **Progressive Validation** 40 | 41 | **Execute the level validation system from the PRP:** 42 | - **Level 1**: Run syntax & style validation commands from PRP 43 | - **Level 2**: Execute unit test validation from PRP 44 | - **Level 3**: Run integration testing commands from PRP 45 | - **Level 4**: Execute specified validation from PRP 46 | 47 | **Each level must pass before proceeding to the next.** 48 | 49 | 5. **Completion Verification** 50 | - Work through the Final Validation Checklist in the PRP 51 | - Verify all Success Criteria from the "What" section are met 52 | - Confirm all Anti-Patterns were avoided 53 | - Implementation is ready and working 54 | 55 | **Failure Protocol**: When validation fails, use the patterns and gotchas from the PRP to fix issues, then re-run validation until passing. 56 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-task-create.md: -------------------------------------------------------------------------------- 1 | # Create TASK PRP (Advanced) 2 | 3 | Generate a comprehensive task list for focused changes with validation. 4 | 5 | ## Task: $ARGUMENTS 6 | 7 | ## Analysis Process 8 | 9 | 1. **Scope Definition** 10 | - Identify all affected files 11 | - Map dependencies 12 | - Check for side effects 13 | - Note test coverage 14 | 15 | 2. **Pattern Research** 16 | - Find similar changes in history 17 | - Identify conventions to follow 18 | - Check for helper functions 19 | - Review test patterns 20 | 21 | 3. **User Clarification** 22 | - Confirm change scope 23 | - Verify acceptance criteria 24 | - Check deployment considerations 25 | - Identify blockers 26 | 27 | ## PRP Generation 28 | 29 | **READ** 30 | Using TASK_PRP/PRPs/prp_task.md format: 31 | 32 | ### Context Section 33 | 34 | ```yaml 35 | context: 36 | docs: 37 | - url: [API documentation] 38 | focus: [specific methods] 39 | 40 | patterns: 41 | - file: existing/example.py 42 | copy: [pattern to follow] 43 | 44 | gotchas: 45 | - issue: "Library requires X" 46 | fix: "Always do Y first" 47 | ``` 48 | 49 | ### Task Structure 50 | 51 | ``` 52 | ACTION path/to/file: 53 | - OPERATION: [specific change] 54 | - VALIDATE: [test command] 55 | - IF_FAIL: [debug strategy] 56 | - ROLLBACK: [undo approach] 57 | ``` 58 | 59 | ### Task Sequencing 60 | 61 | 1. **Setup Tasks**: Prerequisites 62 | 2. **Core Changes**: Main modifications 63 | 3. **Integration**: Connect components 64 | 4. **Validation**: Comprehensive tests 65 | 5. **Cleanup**: Remove temp code 66 | 67 | ### Validation Strategy 68 | 69 | - Unit test after each change 70 | - Integration test after groups 71 | - Performance check if relevant 72 | - Security scan for sensitive areas 73 | 74 | ## User Interaction Points 75 | 76 | 1. **Task Review** 77 | - Confirm task breakdown 78 | - Validate sequencing 79 | - Check completeness 80 | 81 | 2. **Risk Assessment** 82 | - Review potential impacts 83 | - Confirm rollback approach 84 | - Set success criteria 85 | 86 | ## Critical Elements 87 | 88 | - Include debug patterns 89 | - Add performance checks 90 | - Note security concerns 91 | - Document assumptions 92 | 93 | ## Output 94 | 95 | Save as: `TASK_PRP/PRPs/{task-name}.md` 96 | 97 | ## Quality Checklist 98 | 99 | - [ ] All changes identified 100 | - [ ] Dependencies mapped 101 | - [ ] Each task has validation 102 | - [ ] Rollback steps included 103 | - [ ] Debug strategies provided 104 | - [ ] Performance impact noted 105 | - [ ] Security checked 106 | - [ ] No missing edge cases 107 | 108 | Remember: Small, focused changes with immediate validation. 109 | -------------------------------------------------------------------------------- /.claude/commands/code-quality/review-general.md: -------------------------------------------------------------------------------- 1 | # Code Review 2 | 3 | Please perform a comprehensive code review of the current changes or specified files. 4 | 5 | ## Review Scope 6 | Scope for review $1 7 | Link to must read PRP file if prp was used for implemnetaiton (skip if this is empty) $2 8 | 9 | ## Review Process 10 | 11 | 1. **Understand Changes** 12 | - If reviewing staged changes: `git diff --staged` 13 | - If reviewing specific files: Read the specified files 14 | - If reviewing a PR: `gh pr view --json files,additions,deletions` 15 | - If reviewing a local directory: `git diff` 16 | - If reviewing the entire codebase: `git diff origin/main` 17 | 18 | ## Review Focus Areas 19 | 20 | 1. **Code Quality** 21 | - Type hints on all functions and classes 22 | - Pydantic v2 models for data validation 23 | - No print() statements (use logging) 24 | - Proper error handling 25 | - Following PEP 8 26 | - Docstrings following google style python docstrings 27 | 28 | 2. **Pydantic v2 Patterns** 29 | - Using ConfigDict not class Config 30 | - field_validator not @validator 31 | - model_dump() not dict() 32 | - Proper use of Annotated types 33 | 34 | 3. **Security** 35 | - Input validation on all endpoints 36 | - No SQL injection vulnerabilities 37 | - Passwords properly hashed 38 | - No hardcoded secrets 39 | 40 | 4. **Structure** 41 | - Unit tests are co-located with the code they test in tests/ folders 42 | - Each feature is self-contained with its own models, service, and tools 43 | - Shared components are only things used by multiple features 44 | - Future improvements (like multiple AI providers) would go in src/shared/ai_providers/ when implemented 45 | - Integration tests remain at the root level in tests/integration/ 46 | 47 | 5. **Linting** 48 | - ruff check --fix 49 | - mypy 50 | 51 | 6. **Testing** 52 | - New code has tests 53 | - Edge cases covered 54 | - Mocking external dependencies 55 | 56 | 7. **Performance** 57 | - No N+1 queries 58 | - Efficient algorithms 59 | - Proper async usage 60 | 61 | 8. **Documentation** 62 | - Clear README with setup instructions 63 | - CLAUDE.md is up to date with any new important utils, dependencies etc for future cluade code instances 64 | 65 | ## Review Output 66 | 67 | Create a concise review report with: 68 | 69 | ```markdown 70 | # Code Review #[number] 71 | 72 | ## Summary 73 | [2-3 sentence overview] 74 | 75 | ## Issues Found 76 | 77 | ### 🔴 Critical (Must Fix) 78 | - [Issue with file:line and suggested fix] 79 | 80 | ### 🟡 Important (Should Fix) 81 | - [Issue with file:line and suggested fix] 82 | 83 | ### 🟢 Minor (Consider) 84 | - [Improvement suggestions] 85 | 86 | ## Good Practices 87 | - [What was done well] 88 | 89 | ## Test Coverage 90 | Current: X% | Required: 80% 91 | Missing tests: [list] 92 | Save report to PRPs/code_reviews/review[#].md (check existing files first) 93 | 94 | -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-review.md: -------------------------------------------------------------------------------- 1 | # Code Review 2 | 3 | Please perform a comprehensive code review of the current changes or specified files. 4 | 5 | ## Review Scope 6 | Scope for review $1 7 | Link to must read PRP file if prp was used for implemnetaiton (skip if this is empty) $2 8 | 9 | ## Review Process 10 | 11 | 1. **Understand Changes** 12 | - If reviewing staged changes: `git diff --staged` 13 | - If reviewing specific files: Read the specified files 14 | - If reviewing a PR: `gh pr view --json files,additions,deletions` 15 | - If reviewing a local directory: `git diff` 16 | - If reviewing the entire codebase: `git diff origin/main` 17 | 18 | ## Review Focus Areas 19 | 20 | 1. **Code Quality** 21 | - Type hints on all functions and classes 22 | - Pydantic v2 models for data validation 23 | - No print() statements (use logging) 24 | - Proper error handling 25 | - Following PEP 8 26 | - Docstrings following google style python docstrings 27 | 28 | 2. **Pydantic v2 Patterns** 29 | - Using ConfigDict not class Config 30 | - field_validator not @validator 31 | - model_dump() not dict() 32 | - Proper use of Annotated types 33 | 34 | 3. **Security** 35 | - Input validation on all endpoints 36 | - No SQL injection vulnerabilities 37 | - Passwords properly hashed 38 | - No hardcoded secrets 39 | 40 | 4. **Structure** 41 | - Unit tests are co-located with the code they test in tests/ folders 42 | - Each feature is self-contained with its own models, service, and tools 43 | - Shared components are only things used by multiple features 44 | - Future improvements (like multiple AI providers) would go in src/shared/ai_providers/ when implemented 45 | - Integration tests remain at the root level in tests/integration/ 46 | 47 | 5. **Linting** 48 | - ruff check --fix 49 | - mypy 50 | 51 | 6. **Testing** 52 | - New code has tests 53 | - Edge cases covered 54 | - Mocking external dependencies 55 | 56 | 7. **Performance** 57 | - No N+1 queries 58 | - Efficient algorithms 59 | - Proper async usage 60 | 61 | 8. **Documentation** 62 | - Clear README with setup instructions 63 | - CLAUDE.md is up to date with any new important utils, dependencies etc for future cluade code instances 64 | 65 | ## Review Output 66 | 67 | Create a concise review report with: 68 | 69 | ```markdown 70 | # Code Review #[number] 71 | 72 | ## Summary 73 | [2-3 sentence overview] 74 | 75 | ## Issues Found 76 | 77 | ### 🔴 Critical (Must Fix) 78 | - [Issue with file:line and suggested fix] 79 | 80 | ### 🟡 Important (Should Fix) 81 | - [Issue with file:line and suggested fix] 82 | 83 | ### 🟢 Minor (Consider) 84 | - [Improvement suggestions] 85 | 86 | ## Good Practices 87 | - [What was done well] 88 | 89 | ## Test Coverage 90 | Current: X% | Required: 80% 91 | Missing tests: [list] 92 | Save report to PRPs/code_reviews/review[#].md (check existing files first) 93 | 94 | -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-review.md: -------------------------------------------------------------------------------- 1 | # Code Review 2 | 3 | Please perform a comprehensive code review of the current changes or specified files. 4 | 5 | ## Review Scope 6 | Scope for review $1 7 | Link to must read PRP file if prp was used for implemnetaiton (skip if this is empty) $2 8 | 9 | ## Review Process 10 | 11 | 1. **Understand Changes** 12 | - If reviewing staged changes: `git diff --staged` 13 | - If reviewing specific files: Read the specified files 14 | - If reviewing a PR: `gh pr view --json files,additions,deletions` 15 | - If reviewing a local directory: `git diff` 16 | - If reviewing the entire codebase: `git diff origin/main` 17 | 18 | ## Review Focus Areas 19 | 20 | 1. **Code Quality** 21 | - Type hints on all functions and classes 22 | - Pydantic v2 models for data validation 23 | - No print() statements (use logging) 24 | - Proper error handling 25 | - Following PEP 8 26 | - Docstrings following google style python docstrings 27 | 28 | 2. **Pydantic v2 Patterns** 29 | - Using ConfigDict not class Config 30 | - field_validator not @validator 31 | - model_dump() not dict() 32 | - Proper use of Annotated types 33 | 34 | 3. **Security** 35 | - Input validation on all endpoints 36 | - No SQL injection vulnerabilities 37 | - Passwords properly hashed 38 | - No hardcoded secrets 39 | 40 | 4. **Structure** 41 | - Unit tests are co-located with the code they test in tests/ folders 42 | - Each feature is self-contained with its own models, service, and tools 43 | - Shared components are only things used by multiple features 44 | - Future improvements (like multiple AI providers) would go in src/shared/ai_providers/ when implemented 45 | - Integration tests remain at the root level in tests/integration/ 46 | 47 | 5. **Linting** 48 | - ruff check --fix 49 | - mypy 50 | 51 | 6. **Testing** 52 | - New code has tests 53 | - Edge cases covered 54 | - Mocking external dependencies 55 | 56 | 7. **Performance** 57 | - No N+1 queries 58 | - Efficient algorithms 59 | - Proper async usage 60 | 61 | 8. **Documentation** 62 | - Clear README with setup instructions 63 | - CLAUDE.md is up to date with any new important utils, dependencies etc for future cluade code instances 64 | 65 | ## Review Output 66 | 67 | Create a concise review report with: 68 | 69 | ```markdown 70 | # Code Review #[number] 71 | 72 | ## Summary 73 | [2-3 sentence overview] 74 | 75 | ## Issues Found 76 | 77 | ### 🔴 Critical (Must Fix) 78 | - [Issue with file:line and suggested fix] 79 | 80 | ### 🟡 Important (Should Fix) 81 | - [Issue with file:line and suggested fix] 82 | 83 | ### 🟢 Minor (Consider) 84 | - [Improvement suggestions] 85 | 86 | ## Good Practices 87 | - [What was done well] 88 | 89 | ## Test Coverage 90 | Current: X% | Required: 80% 91 | Missing tests: [list] 92 | Save report to PRPs/code_reviews/review[#].md (check existing files first) 93 | 94 | -------------------------------------------------------------------------------- /uv.lock: -------------------------------------------------------------------------------- 1 | version = 1 2 | revision = 1 3 | requires-python = ">=3.12" 4 | 5 | [[package]] 6 | name = "markdown-it-py" 7 | version = "4.0.0" 8 | source = { registry = "https://pypi.org/simple" } 9 | dependencies = [ 10 | { name = "mdurl" }, 11 | ] 12 | sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070 } 13 | wheels = [ 14 | { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321 }, 15 | ] 16 | 17 | [[package]] 18 | name = "mdurl" 19 | version = "0.1.2" 20 | source = { registry = "https://pypi.org/simple" } 21 | sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729 } 22 | wheels = [ 23 | { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979 }, 24 | ] 25 | 26 | [[package]] 27 | name = "prp-library" 28 | version = "0.1.0" 29 | source = { virtual = "." } 30 | dependencies = [ 31 | { name = "rich" }, 32 | ] 33 | 34 | [package.metadata] 35 | requires-dist = [{ name = "rich", specifier = ">=14.2.0" }] 36 | 37 | [[package]] 38 | name = "pygments" 39 | version = "2.19.2" 40 | source = { registry = "https://pypi.org/simple" } 41 | sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631 } 42 | wheels = [ 43 | { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217 }, 44 | ] 45 | 46 | [[package]] 47 | name = "rich" 48 | version = "14.2.0" 49 | source = { registry = "https://pypi.org/simple" } 50 | dependencies = [ 51 | { name = "markdown-it-py" }, 52 | { name = "pygments" }, 53 | ] 54 | sdist = { url = "https://files.pythonhosted.org/packages/fb/d2/8920e102050a0de7bfabeb4c4614a49248cf8d5d7a8d01885fbb24dc767a/rich-14.2.0.tar.gz", hash = "sha256:73ff50c7c0c1c77c8243079283f4edb376f0f6442433aecb8ce7e6d0b92d1fe4", size = 219990 } 55 | wheels = [ 56 | { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393 }, 57 | ] 58 | -------------------------------------------------------------------------------- /.claude/commands/development/debug-RCA.md: -------------------------------------------------------------------------------- 1 | # Debug Issue 2 | 3 | Systematically debug and diagnose the reported problem. 4 | 5 | ## Problem Description 6 | 7 | $ARGUMENTS 8 | 9 | ## Debugging Process 10 | 11 | 1. **Reproduce the Issue** 12 | - Get exact steps to reproduce 13 | - Verify you can see the same problem 14 | - Note any error messages or logs 15 | - Document the expected vs actual behavior 16 | 17 | 2. **Gather Information** 18 | 19 | ```bash 20 | # Check recent changes 21 | git log --oneline -10 22 | 23 | # Look for error patterns in logs 24 | # Search for related error messages 25 | ``` 26 | 27 | 3. **Isolate the Problem** 28 | - **Binary Search**: Comment out code sections to narrow down 29 | - **Git Bisect**: Find when the bug was introduced 30 | - **Logging**: Add strategic log statements 31 | - **Debugger**: Set breakpoints if applicable 32 | 33 | 4. **Common Debugging Strategies** 34 | 35 | ### For Runtime Errors 36 | - Read the full stack trace 37 | - Identify the exact line causing the error 38 | - Check variable values at that point 39 | - Verify assumptions about data types 40 | 41 | ### For Logic Errors 42 | - Add print/log statements to trace execution 43 | - Verify each step produces expected results 44 | - Check boundary conditions 45 | - Test with minimal reproducible example 46 | 47 | ### For Performance Issues 48 | - Add timing measurements 49 | - Check for N+1 queries 50 | - Look for inefficient algorithms 51 | - Profile if necessary 52 | 53 | ### For Integration Issues 54 | - Verify external service is accessible 55 | - Check authentication/credentials 56 | - Validate request/response formats 57 | - Test with curl/Postman first 58 | 59 | 5. **Root Cause Analysis** 60 | - Why did this happen? 61 | - Why wasn't it caught earlier? 62 | - Are there similar issues elsewhere? 63 | - How can we prevent this class of bugs? 64 | 65 | 6. **Implement Fix** 66 | - Fix the root cause, not just symptoms 67 | - Add defensive programming if needed 68 | - Consider edge cases 69 | - Keep fix minimal and focused, follow KISS 70 | 71 | 7. **Verify Resolution** 72 | - Confirm original issue is fixed 73 | - Check for regression 74 | - Test related functionality 75 | - Add test to prevent recurrence 76 | 77 | 8. **Document Findings** 78 | 79 | ```markdown 80 | ## Debug Summary 81 | 82 | ### Issue 83 | 84 | [What was broken] 85 | 86 | ### Root Cause 87 | 88 | [Why it was broken] 89 | 90 | ### Fix 91 | 92 | [What was changed] 93 | 94 | ### Prevention 95 | 96 | [How to avoid similar issues] 97 | ``` 98 | 99 | ## Debug Checklist 100 | 101 | - [ ] Issue reproduced locally 102 | - [ ] Root cause identified 103 | - [ ] Fix implemented 104 | - [ ] Tests added/updated 105 | - [ ] No regressions introduced 106 | - [ ] Documentation updated if needed 107 | 108 | Remember: The goal is not just to fix the bug, but to understand why it happened and prevent similar issues in the future. 109 | -------------------------------------------------------------------------------- /.claude/skills/prp-core-runner/SKILL.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: prp-core-runner 3 | description: Orchestrate complete PRP workflow from feature request to pull request. Run create branch, create PRP, execute implementation, commit changes, and create PR in sequence. Use when implementing features using PRP methodology or when user requests full PRP workflow. 4 | --- 5 | 6 | # PRP Core Workflow Runner 7 | 8 | ## Instructions 9 | 10 | When the user requests to implement a feature using the PRP workflow or wants end-to-end automation from idea to PR, use the SlashCommand tool to invoke `/prp-core-run-all` with the user's feature description as the argument. 11 | 12 | **Step-by-step execution:** 13 | 14 | 1. **Invoke the workflow**: Use SlashCommand tool with `/prp-core-run-all {feature-description}` 15 | 2. **Monitor progress**: The workflow will execute 5 steps in sequence: 16 | - Create a conventional git branch 17 | - Generate comprehensive PRP document 18 | - Execute the PRP implementation 19 | - Create atomic git commit 20 | - Create pull request 21 | 3. **Handle failures**: If any step fails: 22 | - Report which step failed and why 23 | - Do NOT proceed to subsequent steps 24 | - Provide actionable guidance for fixing the issue 25 | 4. **Report completion**: When all steps succeed, confirm the workflow completed and provide the PR URL 26 | 27 | **Error Handling:** 28 | 29 | - Stop execution immediately if any validation fails 30 | - Report the specific error clearly 31 | - Guide the user on how to resolve the issue 32 | - Do not attempt to auto-fix complex validation failures 33 | 34 | ## Examples 35 | 36 | **Example 1: Autonomous invocation** 37 | ``` 38 | User: "Can you implement user authentication using JWT with the PRP workflow?" 39 | Assistant: I'll use the prp-core-runner skill to execute the complete PRP workflow for implementing JWT authentication. 40 | [Invokes: /prp-core-run-all Implement user authentication using JWT] 41 | ``` 42 | 43 | **Example 2: Feature request** 44 | ``` 45 | User: "I need to add a search API with Elasticsearch integration using PRP" 46 | Assistant: I'll run the full PRP workflow to implement the search API with Elasticsearch. 47 | [Invokes: /prp-core-run-all Add search API with Elasticsearch integration] 48 | ``` 49 | 50 | **Example 3: Refactoring with PRP** 51 | ``` 52 | User: "Use the PRP methodology to refactor the database layer for better performance" 53 | Assistant: I'll execute the PRP workflow for refactoring the database layer. 54 | [Invokes: /prp-core-run-all Refactor database layer for better performance] 55 | ``` 56 | 57 | ## When to Use 58 | 59 | Use this skill when: 60 | - User explicitly requests to "implement a feature using PRP" 61 | - User asks to "run the full PRP workflow" 62 | - User wants end-to-end automation from feature idea to pull request 63 | - User mentions both "PRP" and a feature to implement 64 | - User requests a complete workflow including branch, implementation, and PR 65 | 66 | Do NOT use this skill when: 67 | - User only wants to run a single PRP command (e.g., just create a PRP) 68 | - User is asking about PRP methodology (provide information instead) 69 | - User wants to implement something without mentioning PRP workflow 70 | -------------------------------------------------------------------------------- /.claude/commands/rapid-development/experimental/user-story-rapid.md: -------------------------------------------------------------------------------- 1 | # Analyze User Story and Create Implementation Plan 2 | 3 | User Story: $ARGUMENTS 4 | 5 | ## Task: Create detailed implementation plan for separate backend and frontend projects based on the tech stack detailed in the user story 6 | 7 | 1. **Parse user story**: 8 | - Extract: As a [user], I want [feature], so that [benefit] 9 | - List explicit and implicit acceptance criteria 10 | - Identify non-functional requirements (performance, security, UX) 11 | - Define success metrics 12 | 13 | 2. **Plan API contract first** (backend/frontend agreement): 14 | ```yaml 15 | Endpoints: 16 | - GET /api/v1/{resources} - List with pagination 17 | - GET /api/v1/{resources}/{id} - Get single resource 18 | - POST /api/v1/{resources} - Create new 19 | - PUT /api/v1/{resources}/{id} - Update existing 20 | - DELETE /api/v1/{resources}/{id} - Delete 21 | 22 | DTOs: 23 | Request: {field validations} 24 | Response: {field types} 25 | Error: {standard error format} 26 | ``` 27 | 28 | 3. **Backend implementation plan** (Java project): 29 | ``` 30 | Package structure: 31 | com.company.feature/ 32 | ├── controller/ 33 | ├── service/ 34 | ├── repository/ 35 | ├── entity/ 36 | ├── dto/ 37 | ├── exception/ 38 | └── mapper/ 39 | ``` 40 | 41 | Implementation order: 42 | 1. Entity with JPA annotations 43 | 2. Repository interface 44 | 3. DTOs with validation 45 | 4. Mapper interface 46 | 5. Service with business logic 47 | 6. Controller with OpenAPI 48 | 7. Exception handling 49 | 8. Integration tests 50 | 51 | 4. **Frontend implementation plan** (React project): 52 | ``` 53 | src/features/{feature}/ 54 | ├── api/ # API client functions 55 | ├── components/ # UI components 56 | ├── hooks/ # Custom hooks 57 | ├── schemas/ # Zod validation 58 | ├── types/ # TypeScript types 59 | ├── __tests__/ # Component tests 60 | └── index.ts # Public exports 61 | ``` 62 | 63 | Implementation order: 64 | 1. Zod schemas matching backend DTOs 65 | 2. TypeScript types 66 | 3. API client functions 67 | 4. Custom hooks with TanStack Query 68 | 5. UI components 69 | 6. Forms with validation 70 | 7. Error handling 71 | 8. Component tests 72 | 73 | 5. **Integration plan**: 74 | - CORS configuration on backend 75 | - Environment variables for API URL 76 | - Error response handling 77 | - Loading states 78 | - Optimistic updates where applicable 79 | 80 | 6. **Validation commands**: 81 | ```bash 82 | # Backend (in Java project) 83 | ./gradlew clean build test 84 | 85 | # Frontend (in React project) 86 | npm run type-check && npm run lint && npm run test:coverage 87 | 88 | # Integration (manual or e2e) 89 | - Start backend: ./gradlew bootRun 90 | - Start frontend: npm run dev 91 | - Test full user flow 92 | ``` 93 | 94 | 7. **Risk mitigation**: 95 | - Start with API contract agreement 96 | - Use API mocking in frontend if backend delayed 97 | - Implement health check endpoint 98 | - Add request/response logging 99 | - Plan for error scenarios 100 | 101 | Save this plan as: `PRPs/implementations/{feature}-plan.md` -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-spec-create.md: -------------------------------------------------------------------------------- 1 | # Create SPEC PRP (Advanced) 2 | 3 | Generate a comprehensive specification-driven PRP with clear transformation goals. 4 | 5 | ## Specification: $ARGUMENTS 6 | 7 | ## Analysis Process 8 | 9 | 1. **Current State Assessment** 10 | - Map existing implementation 11 | - Identify pain points 12 | - Document technical debt 13 | - Note integration points 14 | 15 | 2. **Desired State Research** 16 | - Best practices for target state 17 | - Implementation examples 18 | - Migration strategies 19 | - Risk assessment 20 | - Dependency mapping 21 | 22 | 3. **User Clarification** 23 | - Confirm transformation goals 24 | - Priority of objectives 25 | - Acceptable trade-offs 26 | 27 | ## PRP Generation 28 | 29 | Using /PRPs/templates/prp_spec.md: 30 | 31 | ### State Documentation 32 | 33 | ```yaml 34 | current_state: 35 | files: [list affected files] 36 | behavior: [how it works now] 37 | issues: [specific problems] 38 | 39 | desired_state: 40 | files: [expected structure] 41 | behavior: [target functionality] 42 | benefits: [improvements gained] 43 | ``` 44 | 45 | ### Hierarchical Objectives 46 | 47 | 1. **High-Level**: Overall transformation goal 48 | 2. **Mid-Level**: Major milestones 49 | 3. **Low-Level**: Specific tasks with validation 50 | 51 | ### Task Specification with information dense keywords 52 | 53 | #### Information dense keywords: 54 | 55 | - MIRROR: Mirror the state of existing code to be mirrored to another use case 56 | - COPY: Copy the state of existing code to be copied to another use case 57 | - ADD: Add new code to the codebase 58 | - MODIFY: Modify existing code 59 | - DELETE: Delete existing code 60 | - RENAME: Rename existing code 61 | - MOVE: Move existing code 62 | - REPLACE: Replace existing code 63 | - CREATE: Create new code 64 | 65 | #### Example: 66 | 67 | ```yaml 68 | task_name: 69 | action: MODIFY/CREATE 70 | file: path/to/file 71 | changes: | 72 | - Specific modifications 73 | - Implementation details 74 | - With clear markers 75 | validation: 76 | - command: "test command" 77 | - expect: "success criteria" 78 | ``` 79 | 80 | ### Implementation Strategy 81 | 82 | - Identify dependencies 83 | - Order tasks by priority and implementation order and dependencies logic 84 | - Include rollback plans 85 | - Progressive enhancement 86 | 87 | ## User Interaction Points 88 | 89 | 1. **Objective Validation** 90 | - Review hierarchical breakdown 91 | - Confirm priorities 92 | - Identify missing pieces 93 | 94 | 2. **Risk Review** 95 | - Document identified risks 96 | - Find mitigations 97 | - Set go/no-go criteria 98 | 99 | ## Context Requirements 100 | 101 | - Current implementation details 102 | - Target architecture examples 103 | - Migration best practices 104 | - Testing strategies 105 | 106 | ## Output 107 | 108 | Save as: `SPEC_PRP/PRPs/{spec-name}.md` 109 | 110 | ## Quality Checklist 111 | 112 | - [ ] Current state fully documented 113 | - [ ] Desired state clearly defined 114 | - [ ] All objectives measurable 115 | - [ ] Tasks ordered by dependency 116 | - [ ] Each task has validation that AI can run 117 | - [ ] Risks identified with mitigations 118 | - [ ] Rollback strategy included 119 | - [ ] Integration points noted 120 | 121 | Remember: Focus on the transformation journey, not just the destination. 122 | -------------------------------------------------------------------------------- /.claude/commands/development/onboarding.md: -------------------------------------------------------------------------------- 1 | Please perform a comprehensive onboarding analysis for a new developer joining this project. Execute the following steps: 2 | 3 | ## 1. Project Overview 4 | First, analyze the repository structure and provide: 5 | - Project name, purpose, and main functionality 6 | - Tech stack (languages, frameworks, databases, tools) 7 | - Architecture pattern (MVC, microservices, etc.) 8 | - Key dependencies and their purposes 9 | 10 | ## 2. Repository Structure 11 | Map out the codebase organization: 12 | - List all top-level directories with their purposes 13 | - Identify where different types of code live (models, controllers, utils, tests) 14 | - Highlight any non-standard or unique organizational patterns 15 | - Note any monorepo structures or submodules 16 | 17 | ## 3. Getting Started 18 | Create step-by-step setup instructions: 19 | - Prerequisites (required software, versions) 20 | - Environment setup commands 21 | - How to install dependencies 22 | - Configuration files that need to be created/modified 23 | - How to run the project locally 24 | - How to run tests 25 | - How to build for production 26 | 27 | ## 4. Key Components 28 | Identify and explain the most important files/modules: 29 | - Entry points (main.js, index.py, app.tsx, etc.) 30 | - Core business logic locations 31 | - Database models/schemas 32 | - API endpoints or routes 33 | - Configuration management 34 | - Authentication/authorization implementation 35 | 36 | ## 5. Development Workflow 37 | Document the development process: 38 | - Git branch naming conventions 39 | - How to create a new feature 40 | - Testing requirements 41 | - Code style/linting rules 42 | - PR process and review guidelines 43 | - CI/CD pipeline overview 44 | 45 | ## 6. Architecture Decisions 46 | Identify important patterns and decisions: 47 | - Design patterns used and why 48 | - State management approach 49 | - Error handling strategy 50 | - Logging and monitoring setup 51 | - Security measures 52 | - Performance optimizations 53 | 54 | ## 7. Common Tasks 55 | Provide examples for frequent development tasks: 56 | - How to add a new API endpoint 57 | - How to create a new database model 58 | - How to add a new test 59 | - How to debug common issues 60 | - How to update dependencies 61 | 62 | ## 8. Potential Gotchas 63 | List things that might trip up new developers: 64 | - Non-obvious configurations 65 | - Required environment variables 66 | - External service dependencies 67 | - Known issues or workarounds 68 | - Performance bottlenecks 69 | - Areas of technical debt 70 | 71 | ## 9. Documentation and Resources 72 | - Locate existing documentation (README, wikis, docs/) 73 | - API documentation 74 | - Database schemas 75 | - Deployment guides 76 | - Team conventions or style guides 77 | 78 | ## 10. Next Steps 79 | Create an onboarding checklist for the new developer: 80 | 1. Set up development environment 81 | 2. Run the project successfully 82 | 3. Make a small test change 83 | 4. Run the test suite 84 | 5. Understand the main user flow 85 | 6. Identify area to start contributing 86 | 87 | ## Output Format 88 | Please create: 89 | 1. A comprehensive ONBOARDING.md file at the root of the repository with all above information 90 | 2. A QUICKSTART.md with just the essential setup steps 91 | 3. suggest updates to the README.md if it's missing critical information (dont uopdate the readme directly) 92 | 93 | Focus on clarity and actionability. Assume the developer is experienced but completely new to this codebase. -------------------------------------------------------------------------------- /.claude/agents/library-researcher.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "library-researcher" 3 | description: "Use proactivley to research external libraries and fetch relevant documentation for implementation" 4 | model: "sonnet" 5 | --- 6 | 7 | You are a specialized library research agent focused on gathering implementation-critical documentation. 8 | 9 | ## Your Mission 10 | 11 | Research external libraries and APIs to provide: 12 | 13 | - Specific implementation examples 14 | - API method signatures and patterns 15 | - Common pitfalls and best practices 16 | - Version-specific considerations 17 | 18 | ## Research Strategy 19 | 20 | ### 1. Official Documentation 21 | 22 | - Start with Archon MCP tools and check if we have relevant docs in the database 23 | - Use the RAG tools to search for relevant documentation, use specific keywords and context in your queries 24 | - Use websearch and webfetch to search official docs (check package registry for links) 25 | - Find quickstart guides and API references 26 | - Identify code examples specific to the use case 27 | - Note version-specific features or breaking changes 28 | 29 | ### 2. Implementation Examples 30 | 31 | - Search GitHub for real-world usage 32 | - Find Stack Overflow solutions for common patterns 33 | - Look for blog posts with practical examples 34 | - Check the library's test files for usage patterns 35 | 36 | ### 3. Integration Patterns 37 | 38 | - How do others integrate this library? 39 | - What are common configuration patterns? 40 | - What helper utilities are typically created? 41 | - What are typical error handling patterns? 42 | 43 | ### 4. Known Issues 44 | 45 | - Check library's GitHub issues for gotchas 46 | - Look for migration guides indicating breaking changes 47 | - Find performance considerations 48 | - Note security best practices 49 | 50 | ## Output Format 51 | 52 | Structure findings for immediate use: 53 | 54 | ```yaml 55 | library: [library name] 56 | version: [version in use] 57 | documentation: 58 | quickstart: [URL with section anchor] 59 | api_reference: [specific method docs URL] 60 | examples: [example code URL] 61 | 62 | key_patterns: 63 | initialization: | 64 | [code example] 65 | 66 | common_usage: | 67 | [code example] 68 | 69 | error_handling: | 70 | [code example] 71 | 72 | gotchas: 73 | - issue: [description] 74 | solution: [how to handle] 75 | 76 | best_practices: 77 | - [specific recommendation] 78 | 79 | save_to_ai_docs: [yes/no - if complex enough to warrant local documentation] 80 | ``` 81 | 82 | ## Documentation Curation 83 | 84 | When documentation is complex or critical: 85 | 86 | 1. Create condensed version in PRPs/ai_docs/{library}\_patterns.md 87 | 2. Focus on implementation-relevant sections 88 | 3. Include working code examples 89 | 4. Add project-specific integration notes 90 | 91 | ## Search Queries 92 | 93 | Effective search patterns: 94 | 95 | - "{library} {feature} example" 96 | - "{library} TypeError site:stackoverflow.com" 97 | - "{library} best practices {language}" 98 | - "github {library} {feature} language:{language}" 99 | 100 | ## Key Principles 101 | 102 | - Prefer official docs but verify with real implementations 103 | - Focus on the specific features needed for the story 104 | - Provide executable code examples, not abstract descriptions 105 | - Note version differences if relevant 106 | - Save complex findings to ai_docs for future reference 107 | 108 | Remember: Good library research prevents implementation blockers and reduces debugging time. 109 | -------------------------------------------------------------------------------- /.claude/commands/prp-core/prp-core-new-branch.md: -------------------------------------------------------------------------------- 1 | # Create Git Branch 2 | 3 | Generate a conventional branch name based on user request and create a new git branch. 4 | 5 | ## Variables 6 | 7 | User request: $1 8 | 9 | ## Instructions 10 | 11 | **Step 1: Check Current Branch** 12 | 13 | - Check current branch: `git branch --show-current` 14 | - Check if on main/master: 15 | ```bash 16 | CURRENT_BRANCH=$(git branch --show-current) 17 | if [[ "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" && "$CURRENT_BRANCH" != "development" ]]; then 18 | echo "Warning: Currently on branch '$CURRENT_BRANCH', not main/master/development" 19 | echo "Proceeding with branch creation from current branch" 20 | fi 21 | ``` 22 | - Note: We proceed regardless, but log the warning 23 | 24 | **Step 2: Generate Branch Name** 25 | 26 | Use conventional branch naming: 27 | 28 | **Prefixes:** 29 | - `feat/` - New feature or enhancement 30 | - `fix/` - Bug fix 31 | - `chore/` - Maintenance tasks (dependencies, configs, etc.) 32 | - `docs/` - Documentation only changes 33 | - `refactor/` - Code refactoring (no functionality change) 34 | - `test/` - Adding or updating tests 35 | - `perf/` - Performance improvements 36 | 37 | **Naming Rules:** 38 | - Use kebab-case (lowercase with hyphens) 39 | - Be descriptive but concise (max 50 characters) 40 | - Remove special characters except hyphens 41 | - No spaces, use hyphens instead 42 | 43 | **Examples:** 44 | - "Add user authentication system" → `feat/add-user-auth` 45 | - "Fix login redirect bug" → `fix/login-redirect` 46 | - "Update README documentation" → `docs/update-readme` 47 | - "Refactor database queries" → `refactor/database-queries` 48 | - "Add unit tests for API" → `test/api-unit-tests` 49 | 50 | **Branch Name Generation Logic:** 51 | 1. Analyze user request to determine type (feature/fix/chore/docs/refactor/test/perf) 52 | 2. Extract key action and subject 53 | 3. Convert to kebab-case 54 | 4. Truncate if needed to keep under 50 chars 55 | 5. Validate name is descriptive and follows conventions 56 | 57 | **Step 3: Check Branch Exists** 58 | 59 | - Check if branch name already exists: 60 | ```bash 61 | if git show-ref --verify --quiet refs/heads/; then 62 | echo "Branch already exists" 63 | # Append version suffix 64 | COUNTER=2 65 | while git show-ref --verify --quiet refs/heads/-v$COUNTER; do 66 | COUNTER=$((COUNTER + 1)) 67 | done 68 | BRANCH_NAME="-v$COUNTER" 69 | fi 70 | ``` 71 | - If exists, append `-v2`, `-v3`, etc. until unique 72 | 73 | **Step 4: Create and Checkout Branch** 74 | 75 | - Create and checkout new branch: `git checkout -b ` 76 | - Verify creation: `git branch --show-current` 77 | - Ensure output matches expected branch name 78 | 79 | **Step 5: Verify Branch State** 80 | 81 | - Confirm branch created: `git branch --list ` 82 | - Confirm currently on branch: `[ "$(git branch --show-current)" = "" ]` 83 | - Check remote tracking: `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "No upstream set"` 84 | 85 | **Important Notes:** 86 | 87 | - Branch should be created locally only (no push yet) 88 | - Branch will be pushed later by commit.md command 89 | - If user request is unclear, prefer `feat/` prefix as default 90 | 91 | ## Report 92 | 93 | Output ONLY the branch name (no markdown, no explanations, no quotes): 94 | 95 | 96 | 97 | **Example outputs:** 98 | ``` 99 | feat/add-user-auth 100 | fix/login-redirect-issue 101 | docs/update-api-documentation 102 | refactor/simplify-middleware 103 | ``` 104 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/api-contract-define.md: -------------------------------------------------------------------------------- 1 | # Define API Contract Between Backend and Frontend 2 | 3 | Feature: $ARGUMENTS 4 | 5 | ## Task: Create detailed API contract specification for backend/frontend coordination 6 | 7 | 1. **Define RESTful endpoints**: 8 | 9 | ```yaml 10 | Base URL: /api/v1/{feature} 11 | 12 | Endpoints: 13 | - GET /api/v1/{features} 14 | Query params: page, size, sort, filter 15 | Response: Page<{Feature}Response> 16 | 17 | - GET /api/v1/{features}/{id} 18 | Path param: id (Long) 19 | Response: {Feature}Response 20 | 21 | - POST /api/v1/{features} 22 | Body: {Feature}Request 23 | Response: {Feature}Response (201 Created) 24 | 25 | - PUT /api/v1/{features}/{id} 26 | Path param: id (Long) 27 | Body: {Feature}Request 28 | Response: {Feature}Response 29 | 30 | - DELETE /api/v1/{features}/{id} 31 | Path param: id (Long) 32 | Response: 204 No Content 33 | ``` 34 | 35 | 2. **Define request/response DTOs**: 36 | 37 | ```typescript 38 | // Request DTO (for POST/PUT) 39 | interface {Feature}Request { 40 | name: string; // min: 2, max: 100 41 | description?: string; // max: 1000 42 | // Add domain-specific fields 43 | } 44 | 45 | // Response DTO (for GET) 46 | interface {Feature}Response { 47 | id: number; 48 | name: string; 49 | description?: string; 50 | createdAt: string; // ISO 8601 51 | updatedAt: string; // ISO 8601 52 | // Add computed fields 53 | } 54 | 55 | // Page response wrapper 56 | interface Page { 57 | content: T[]; 58 | totalElements: number; 59 | totalPages: number; 60 | size: number; 61 | number: number; 62 | } 63 | ``` 64 | 65 | 3. **Define error responses**: 66 | 67 | ```json 68 | { 69 | "timestamp": "2024-01-20T10:30:00Z", 70 | "status": 400, 71 | "error": "Bad Request", 72 | "message": "Validation failed", 73 | "path": "/api/v1/{features}", 74 | "errors": [ 75 | { 76 | "field": "name", 77 | "message": "Name is required" 78 | } 79 | ] 80 | } 81 | ``` 82 | 83 | 4. **Define validation rules**: 84 | - Backend: Bean Validation annotations 85 | - Frontend: Matching Zod schemas 86 | 87 | ``` 88 | name: required, 2-100 chars 89 | description: optional, max 1000 chars 90 | email: valid email format 91 | date: ISO 8601 format 92 | ``` 93 | 94 | 5. **Define status codes**: 95 | - 200: OK (GET, PUT) 96 | - 201: Created (POST) 97 | - 204: No Content (DELETE) 98 | - 400: Bad Request (validation) 99 | - 404: Not Found 100 | - 409: Conflict (duplicate) 101 | - 500: Internal Server Error 102 | 103 | 6. **Integration requirements**: 104 | - CORS: Allow frontend origin 105 | - Content-Type: application/json 106 | - Authentication: Bearer token (if needed) 107 | - Pagination: Spring Pageable format 108 | - Sorting: field,direction (e.g., "name,asc") 109 | 110 | 7. **Backend implementation notes**: 111 | 112 | ```java 113 | // Entity fields match response DTO 114 | // Use MapStruct for DTO mapping 115 | // Repository method naming conventions 116 | // Service layer validation 117 | ``` 118 | 119 | 8. **Frontend implementation notes**: 120 | ```typescript 121 | // Zod schemas match validation rules 122 | // API client with base configuration 123 | // TanStack Query hooks 124 | // Error handling utilities 125 | ``` 126 | 127 | Save this contract as: `PRPs/contracts/{feature}-api-contract.md` 128 | 129 | Share this file between backend and frontend teams for alignment. 130 | -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-new-branch.md: -------------------------------------------------------------------------------- 1 | # Create Git Branch 2 | 3 | Generate a conventional branch name based on user request and create a new git branch. 4 | 5 | ## Variables 6 | 7 | User request: $1 8 | 9 | ## Instructions 10 | 11 | **Step 1: Check Current Branch** 12 | 13 | - Check current branch: `git branch --show-current` 14 | - Check if on main/master: 15 | ```bash 16 | CURRENT_BRANCH=$(git branch --show-current) 17 | if [[ "$CURRENT_BRANCH" != "main" && "$CURRENT_BRANCH" != "master" ]]; then 18 | echo "Warning: Currently on branch '$CURRENT_BRANCH', not main/master" 19 | echo "Proceeding with branch creation from current branch" 20 | fi 21 | ``` 22 | - Note: We proceed regardless, but log the warning 23 | 24 | **Step 2: Generate Branch Name** 25 | 26 | Use conventional branch naming: 27 | 28 | **Prefixes:** 29 | - `feat/` - New feature or enhancement 30 | - `fix/` - Bug fix 31 | - `chore/` - Maintenance tasks (dependencies, configs, etc.) 32 | - `docs/` - Documentation only changes 33 | - `refactor/` - Code refactoring (no functionality change) 34 | - `test/` - Adding or updating tests 35 | - `perf/` - Performance improvements 36 | 37 | **Naming Rules:** 38 | - Use kebab-case (lowercase with hyphens) 39 | - Be descriptive but concise (max 50 characters) 40 | - Remove special characters except hyphens 41 | - No spaces, use hyphens instead 42 | 43 | **Examples:** 44 | - "Add user authentication system" → `feat/add-user-auth` 45 | - "Fix login redirect bug" → `fix/login-redirect` 46 | - "Update README documentation" → `docs/update-readme` 47 | - "Refactor database queries" → `refactor/database-queries` 48 | - "Add unit tests for API" → `test/api-unit-tests` 49 | 50 | **Branch Name Generation Logic:** 51 | 1. Analyze user request to determine type (feature/fix/chore/docs/refactor/test/perf) 52 | 2. Extract key action and subject 53 | 3. Convert to kebab-case 54 | 4. Truncate if needed to keep under 50 chars 55 | 5. Validate name is descriptive and follows conventions 56 | 57 | **Step 3: Check Branch Exists** 58 | 59 | - Check if branch name already exists: 60 | ```bash 61 | if git show-ref --verify --quiet refs/heads/; then 62 | echo "Branch already exists" 63 | # Append version suffix 64 | COUNTER=2 65 | while git show-ref --verify --quiet refs/heads/-v$COUNTER; do 66 | COUNTER=$((COUNTER + 1)) 67 | done 68 | BRANCH_NAME="-v$COUNTER" 69 | fi 70 | ``` 71 | - If exists, append `-v2`, `-v3`, etc. until unique 72 | 73 | **Step 4: Create and Checkout Branch** 74 | 75 | - Create and checkout new branch: `git checkout -b ` 76 | - Verify creation: `git branch --show-current` 77 | - Ensure output matches expected branch name 78 | 79 | **Step 5: Verify Branch State** 80 | 81 | - Confirm branch created: `git branch --list ` 82 | - Confirm currently on branch: `[ "$(git branch --show-current)" = "" ]` 83 | - Check remote tracking: `git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "No upstream set"` 84 | 85 | **Important Notes:** 86 | 87 | - NEVER mention Claude Code, Anthropic, AI, or co-authoring in any output 88 | - Branch should be created locally only (no push yet) 89 | - Branch will be pushed later by commit.md command 90 | - If user request is unclear, prefer `feat/` prefix as default 91 | 92 | ## Report 93 | 94 | Output ONLY the branch name (no markdown, no explanations, no quotes): 95 | 96 | 97 | 98 | **Example outputs:** 99 | ``` 100 | feat/add-user-auth 101 | fix/login-redirect-issue 102 | docs/update-api-documentation 103 | refactor/simplify-middleware 104 | ``` 105 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-planning-create.md: -------------------------------------------------------------------------------- 1 | # Create PLANNING PRP (Advanced) 2 | 3 | Transform rough ideas into comprehensive PRDs with rich visual documentation. 4 | 5 | ## Idea: $ARGUMENTS 6 | 7 | ## Discovery Process 8 | 9 | 1. **Concept Expansion** 10 | - Break down the core idea 11 | - Define success criteria 12 | - Map to business goals if provided 13 | 14 | 2. **Market & Technical Research** 15 | - Do deep web search for the following: 16 | - Market analysis 17 | - Competitor analysis 18 | - Technical feasibility study 19 | - Best practice examples 20 | - Integration possibilities 21 | 22 | 3. **User Research & Clarification** 23 | - Ask user for the following if not provided: 24 | - Target user personas? 25 | - Key pain points? 26 | - Success metrics? 27 | - Constraints/requirements? 28 | 29 | ## PRD Generation 30 | 31 | Using /PRPs/templates/prp_planning_base.md: 32 | 33 | ### Visual Documentation Plan 34 | ```yaml 35 | diagrams_needed: 36 | user_flows: 37 | - Happy path journey 38 | - Error scenarios 39 | - Edge cases 40 | 41 | architecture: 42 | - System components 43 | - Data flow 44 | - Integration points 45 | 46 | sequences: 47 | - API interactions 48 | - Event flows 49 | - State changes 50 | 51 | data_models: 52 | - Entity relationships 53 | - Schema design 54 | - State machines 55 | ``` 56 | 57 | ### Research Integration 58 | - **Market Analysis**: Include findings in PRD 59 | - **Technical Options**: Compare approaches 60 | - **Risk Assessment**: With mitigation strategies 61 | - **Success Metrics**: Specific, measurable 62 | 63 | ### User Story Development 64 | ```markdown 65 | ## Epic: [High-level feature] 66 | 67 | ### Story 1: [User need] 68 | **As a** [user type] 69 | **I want** [capability] 70 | **So that** [benefit] 71 | 72 | **Acceptance Criteria:** 73 | - [ ] Specific behavior 74 | - [ ] Edge case handling 75 | - [ ] Performance requirement 76 | 77 | **Technical Notes:** 78 | - Implementation approach 79 | - API implications 80 | - Data requirements 81 | ``` 82 | 83 | ### Implementation Strategy 84 | - Phases with dependencies (no dates) 85 | - Priority ordering 86 | - MVP vs enhanced features 87 | - Technical prerequisites 88 | 89 | ## User Interaction Points 90 | 91 | 1. **Idea Validation** 92 | - Confirm understanding 93 | - Clarify ambiguities 94 | - Set boundaries 95 | 96 | 2. **Research Review** 97 | - Share findings 98 | - Validate assumptions 99 | - Adjust direction 100 | 101 | 3. **PRD Draft Review** 102 | - Architecture approval 103 | - Risk acknowledgment 104 | - Success metric agreement 105 | 106 | ## Diagram Guidelines 107 | - Use Mermaid for all diagrams 108 | - Include legends where needed 109 | - Show error paths 110 | - Annotate complex flows 111 | 112 | ## Output Structure 113 | ```markdown 114 | 1. Executive Summary 115 | 2. Problem & Solution 116 | 3. User Stories (with diagrams) 117 | 4. Technical Architecture (with diagrams) 118 | 5. API Specifications 119 | 6. Data Models 120 | 7. Implementation Phases 121 | 8. Risks & Mitigations 122 | 9. Success Metrics 123 | 10. Appendices 124 | ``` 125 | 126 | Save as: `PRPs/{feature-name}-prd.md` 127 | 128 | ## Quality Checklist 129 | - [ ] Problem clearly articulated 130 | - [ ] Solution addresses problem 131 | - [ ] All user flows diagrammed 132 | - [ ] Wireframes included if needed 133 | - [ ] Architecture visualized 134 | - [ ] APIs fully specified with examples 135 | - [ ] Data models included 136 | - [ ] Dependencies identified 137 | - [ ] Risks identified and mitigated 138 | - [ ] Success metrics measurable 139 | - [ ] Implementation phases logical 140 | - [ ] Ready for implementation PRP 141 | 142 | Remember: Great PRDs prevent implementation confusion. -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-ts-execute.md: -------------------------------------------------------------------------------- 1 | # Execute TypeScript PRP 2 | 3 | ## PRP File: $ARGUMENTS 4 | 5 | ## Mission: One-Pass TypeScript Implementation Success 6 | 7 | PRPs enable working TypeScript/React code on the first attempt through: 8 | 9 | - **Context Completeness**: Everything needed, nothing guessed 10 | - **Progressive Validation**: 4-level gates catch errors early 11 | - **Pattern Consistency**: Follow existing TypeScript/React codebase approaches 12 | - **Type Safety**: Leverage TypeScript's compile-time error detection 13 | - Read PRPs/README.md to understand PRP concepts 14 | 15 | **Your Goal**: Transform the PRP into working TypeScript code that passes all validation gates and maintains type safety. 16 | 17 | ## Execution Process 18 | 19 | 1. **Load PRP** 20 | - Read the specified TypeScript PRP file completely 21 | - Absorb all context, patterns, requirements and gather codebase intelligence 22 | - Use the provided documentation references and file patterns, consume the right documentation before the appropriate todo/task 23 | - Trust the PRP's context and guidance - it's designed for one-pass success 24 | - If needed do additional codebase exploration and research as needed 25 | - Pay special attention to TypeScript interfaces, component patterns, and Next.js App Router structure 26 | 27 | 2. **ULTRATHINK & Plan** 28 | - Create comprehensive implementation plan following the PRP's task order 29 | - Break down into clear todos using TodoWrite tool 30 | - Use subagents for parallel work when beneficial (always create prp inspired prompts for subagents when used) 31 | - Follow the TypeScript/React patterns referenced in the PRP 32 | - Use specific file paths, interface names, component names, and type definitions from PRP context 33 | - Never guess - always verify the codebase patterns and examples referenced in the PRP yourself 34 | - Consider TypeScript compilation dependencies (types before components, components before pages) 35 | 36 | 3. **Execute Implementation** 37 | - Follow the PRP's Implementation Tasks sequence, add more detail as needed, especially when using subagents 38 | - Use the TypeScript/React patterns and examples referenced in the PRP 39 | - Create files in locations specified by the desired codebase tree 40 | - Apply TypeScript naming conventions from the task specifications and CLAUDE.md 41 | - Ensure proper TypeScript typing throughout (interfaces, props, return types) 42 | - Follow Next.js App Router patterns for file-based routing 43 | 44 | 4. **Progressive Validation** 45 | 46 | **Execute the 4-level validation system from the TypeScript PRP:** 47 | - **Level 1**: Run TypeScript syntax & style validation commands from PRP (ESLint, tsc, Prettier) 48 | - **Level 2**: Execute component and hook unit test validation from PRP 49 | - **Level 3**: Run Next.js integration testing commands from PRP (dev server, API routes, production build) 50 | - **Level 4**: Execute TypeScript/React-specific validation from PRP (E2E, performance, accessibility) 51 | 52 | **Each level must pass before proceeding to the next.** 53 | 54 | 5. **Completion Verification** 55 | - Work through the Final Validation Checklist in the PRP 56 | - Verify all Success Criteria from the "What" section are met 57 | - Confirm all Anti-Patterns were avoided (especially TypeScript/React-specific ones) 58 | - Verify TypeScript compilation is successful with no errors 59 | - Ensure proper Server/Client component separation if using Next.js 60 | - Implementation is ready and working with full type safety 61 | 62 | **Failure Protocol**: When validation fails, use the TypeScript/React patterns and gotchas from the PRP to fix issues, then re-run validation until passing. Pay special attention to: 63 | - TypeScript compilation errors and type mismatches 64 | - React hydration issues between server and client 65 | - Next.js App Router specific requirements 66 | - Component prop interface violations -------------------------------------------------------------------------------- /.claude/agents/codebase-analyst.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "codebase-analyst" 3 | description: "Use proactively to find codebase patterns, coding style and team standards. Specialized agent for deep codebase pattern analysis and convention discovery" 4 | model: "sonnet" 5 | --- 6 | 7 | You are a specialized codebase analysis agent focused on discovering patterns, conventions, and implementation approaches. 8 | 9 | ## Your Mission 10 | 11 | Perform deep, systematic analysis of codebases to extract: 12 | 13 | - Architectural patterns and project structure 14 | - Coding conventions and naming standards 15 | - Integration patterns between components 16 | - Testing approaches and validation commands 17 | - External library usage and configuration 18 | 19 | ## Analysis Methodology 20 | 21 | ### 1. Project Structure Discovery 22 | 23 | - Start looking for Architecture docs rules files such as claude.md, agents.md, cursorrules, windsurfrules, agent wiki, or similar documentation 24 | - Continue with root-level config files (package.json, pyproject.toml, go.mod, etc.) 25 | - Map directory structure to understand organization 26 | - Identify primary language and framework 27 | - Note build/run commands 28 | 29 | ### 2. Pattern Extraction 30 | 31 | - Find similar implementations to the requested feature 32 | - Extract common patterns (error handling, API structure, data flow) 33 | - Identify naming conventions (files, functions, variables) 34 | - Document import patterns and module organization 35 | 36 | ### 3. Integration Analysis 37 | 38 | - How are new features typically added? 39 | - Where do routes/endpoints get registered? 40 | - How are services/components wired together? 41 | - What's the typical file creation pattern? 42 | 43 | ### 4. Testing Patterns 44 | 45 | - What test framework is used? 46 | - How are tests structured? 47 | - What are common test patterns? 48 | - Extract validation command examples 49 | 50 | ### 5. Documentation Discovery 51 | 52 | - Check for README files 53 | - Find API documentation 54 | - Look for inline code comments with patterns 55 | - Check PRPs/ai_docs/ for curated documentation 56 | 57 | ## Output Format 58 | 59 | Provide findings in structured format: 60 | 61 | ```yaml 62 | project: 63 | language: [detected language] 64 | framework: [main framework] 65 | structure: [brief description] 66 | 67 | patterns: 68 | naming: 69 | files: [pattern description] 70 | functions: [pattern description] 71 | classes: [pattern description] 72 | 73 | architecture: 74 | services: [how services are structured] 75 | models: [data model patterns] 76 | api: [API patterns] 77 | 78 | testing: 79 | framework: [test framework] 80 | structure: [test file organization] 81 | commands: [common test commands] 82 | 83 | similar_implementations: 84 | - file: [path] 85 | relevance: [why relevant] 86 | pattern: [what to learn from it] 87 | 88 | libraries: 89 | - name: [library] 90 | usage: [how it's used] 91 | patterns: [integration patterns] 92 | 93 | validation_commands: 94 | syntax: [linting/formatting commands] 95 | test: [test commands] 96 | run: [run/serve commands] 97 | ``` 98 | 99 | ## Key Principles 100 | 101 | - Be specific - point to exact files and line numbers 102 | - Extract executable commands, not abstract descriptions 103 | - Focus on patterns that repeat across the codebase 104 | - Note both good patterns to follow and anti-patterns to avoid 105 | - Prioritize relevance to the requested feature/story 106 | 107 | ## Search Strategy 108 | 109 | 1. Start broad (project structure) then narrow (specific patterns) 110 | 2. Use parallel searches when investigating multiple aspects 111 | 3. Follow references - if a file imports something, investigate it 112 | 4. Look for "similar" not "same" - patterns often repeat with variations 113 | 114 | Remember: Your analysis directly determines implementation success. Be thorough, specific, and actionable. 115 | -------------------------------------------------------------------------------- /.claude/commands/typescript/TS-create-base-prp.md: -------------------------------------------------------------------------------- 1 | # Create BASE PRP 2 | 3 | ## Feature: $ARGUMENTS 4 | 5 | Generate a complete PRP for TypeScript/JavaScript feature implementation with deep and thorough research. Ensure rich context is passed to the AI through the PRP to enable one pass implementation success through self-validation and iterative refinement. 6 | 7 | The AI agent only gets the context you are appending to the PRP and its own training data. Assume the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples. 8 | 9 | ## Research Process 10 | 11 | > During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. we optimize for chance of success and not for speed. 12 | 13 | 1. **Codebase Analysis in depth** 14 | - Create clear todos and spawn subagents to search the codebase for similar features/patterns Think hard and plan your approach 15 | - Identify all the necessary files to reference in the PRP 16 | - Note all existing conventions to follow (TypeScript patterns, React patterns, etc.) 17 | - Check existing test patterns for validation approach (Jest, Vitest, Cypress, etc.) 18 | - Use the batch tools to spawn subagents to search the codebase for similar features/patterns 19 | 20 | 2. **External Research at scale** 21 | - Create clear todos and spawn with instructions subagents to do deep research for similar features/patterns online and include urls to documentation and examples 22 | - Library documentation (include specific URLs for TypeScript/JavaScript libraries) 23 | - For critical pieces of documentation add a .md file to PRPs/ai_docs and reference it in the PRP with clear reasoning and instructions 24 | - Implementation examples (GitHub/StackOverflow/blogs with TypeScript focus) 25 | - Best practices and common pitfalls found during research 26 | - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples 27 | 28 | 3. **User Clarification** 29 | - Ask for clarification if you need it 30 | 31 | ## PRP Generation 32 | 33 | Using PRPs/templates/prp_base_typescript.md as template: 34 | 35 | ### Critical Context at minimum to Include and pass to the AI agent as part of the PRP 36 | 37 | - **Documentation**: URLs with specific sections 38 | - **Code Examples**: Real snippets from codebase 39 | - **Gotchas**: Library quirks, version issues, TypeScript gotchas 40 | - **Patterns**: Existing approaches to follow 41 | - **Best Practices**: Common pitfalls found during research 42 | 43 | ### Implementation Blueprint 44 | 45 | - Start with pseudocode showing approach 46 | - Reference real files for patterns 47 | - Include error handling strategy 48 | - List tasks to be completed to fulfill the PRP in the order they should be completed, use the pattern in the PRP with information dense keywords 49 | 50 | ### Validation Gates (Must be Executable by the AI agent) 51 | 52 | ```bash 53 | # Type checking 54 | npm run typecheck 55 | 56 | # Linting and formatting 57 | npm run lint 58 | 59 | # Unit Tests 60 | npm test 61 | 62 | # Build validation 63 | npm run build 64 | 65 | # Integration tests (if applicable) 66 | npm run test:integration 67 | ``` 68 | 69 | The more validation gates the better, but make sure they are executable by the AI agent. 70 | Include tests, build validation, linting, and any other relevant validation gates. Get creative with the validation gates. 71 | 72 | **_ CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP _** 73 | 74 | **_ ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH IN DETAILED TODOS THEN START WRITING THE PRP _** 75 | 76 | ## Output 77 | 78 | Save as: `PRPs/{feature-name}.md` 79 | 80 | ## Quality Checklist 81 | 82 | - [ ] All necessary context included 83 | - [ ] Validation gates are executable by AI 84 | - [ ] References existing patterns 85 | - [ ] Clear implementation path 86 | - [ ] Error handling documented 87 | 88 | Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes) 89 | 90 | Remember: The goal is one-pass implementation success through comprehensive context. 91 | -------------------------------------------------------------------------------- /PRPs/ai_docs/cc_containers.md: -------------------------------------------------------------------------------- 1 | # Development containers 2 | 3 | > Learn about the Claude Code development container for teams that need consistent, secure environments. 4 | 5 | The preconfigured [devcontainer setup](https://code.visualstudio.com/docs/devcontainers/containers) works seamlessly with VS Code's Remote - Containers extension and similar tools. 6 | 7 | The container's enhanced security measures (isolation and firewall rules) allow you to run `claude --dangerously-skip-permissions` to bypass permission prompts for unattended operation. 8 | We've included a [reference implementation](https://github.com/anthropics/claude-code/tree/main/.devcontainer) that you can customize for your needs. 9 | 10 | 11 | While the devcontainer provides substantial protections, no system is completely immune to all attacks. 12 | When executed with `--dangerously-skip-permissions`, devcontainers do not prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials. 13 | We recommend only using devcontainers when developing with trusted repositories. 14 | Always maintain good security practices and monitor Claude's activities. 15 | 16 | 17 | ## Key features 18 | 19 | - **Production-ready Node.js**: Built on Node.js 20 with essential development dependencies 20 | - **Security by design**: Custom firewall restricting network access to only necessary services 21 | - **Developer-friendly tools**: Includes git, ZSH with productivity enhancements, fzf, and more 22 | - **Seamless VS Code integration**: Pre-configured extensions and optimized settings 23 | - **Session persistence**: Preserves command history and configurations between container restarts 24 | - **Works everywhere**: Compatible with macOS, Windows, and Linux development environments 25 | 26 | ## Getting started in 4 steps 27 | 28 | 1. Install VS Code and the Remote - Containers extension 29 | 2. Clone the [Claude Code reference implementation](https://github.com/anthropics/claude-code/tree/main/.devcontainer) repository 30 | 3. Open the repository in VS Code 31 | 4. When prompted, click "Reopen in Container" (or use Command Palette: Cmd+Shift+P → "Remote-Containers: Reopen in Container") 32 | 33 | ## Configuration breakdown 34 | 35 | The devcontainer setup consists of three primary components: 36 | 37 | - [**devcontainer.json**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json): Controls container settings, extensions, and volume mounts 38 | - [**Dockerfile**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile): Defines the container image and installed tools 39 | - [**init-firewall.sh**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh): Establishes network security rules 40 | 41 | ## Security features 42 | 43 | The container implements a multi-layered security approach with its firewall configuration: 44 | 45 | - **Precise access control**: Restricts outbound connections to whitelisted domains only (npm registry, GitHub, Anthropic API, etc.) 46 | - **Allowed outbound connections**: The firewall permits outbound DNS and SSH connections 47 | - **Default-deny policy**: Blocks all other external network access 48 | - **Startup verification**: Validates firewall rules when the container initializes 49 | - **Isolation**: Creates a secure development environment separated from your main system 50 | 51 | ## Customization options 52 | 53 | The devcontainer configuration is designed to be adaptable to your needs: 54 | 55 | - Add or remove VS Code extensions based on your workflow 56 | - Modify resource allocations for different hardware environments 57 | - Adjust network access permissions 58 | - Customize shell configurations and developer tooling 59 | 60 | ## Example use cases 61 | 62 | ### Secure client work 63 | 64 | Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments. 65 | 66 | ### Team onboarding 67 | 68 | New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed. 69 | 70 | ### Consistent CI/CD environments 71 | 72 | Mirror your devcontainer configuration in CI/CD pipelines to ensure development and production environments match. 73 | 74 | ## Related resources 75 | 76 | - [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers) 77 | - [Claude Code security best practices](/en/docs/claude-code/security) 78 | - [Corporate proxy configuration](/en/docs/claude-code/corporate-proxy) 79 | -------------------------------------------------------------------------------- /.claude/commands/typescript/TS-review-staged-unstaged.md: -------------------------------------------------------------------------------- 1 | List and review any files in the staging area, both staged and unstaged. 2 | Ensure you look at both new files and modified files. 3 | 4 | Check the diff of each file to see what has changed. 5 | 6 | Previous review report: $ARGUMENTS 7 | 8 | May or may not be added, ignore the previous review if not specified. 9 | 10 | ## Review Focus Areas 11 | 12 | 1. **TypeScript Code Quality** 13 | - Strict TypeScript usage with explicit types 14 | - No `any` types - use `unknown` if type is truly unknown 15 | - Proper type imports with `import type { }` syntax 16 | - Component props interfaces defined 17 | - Astro's built-in types used (HTMLAttributes, ComponentProps) 18 | - Following TypeScript strict mode compliance 19 | 20 | 2. **Astro-Specific Patterns** 21 | - Proper hydration directives usage (client:load, client:visible, client:idle) 22 | - Static-first approach with selective hydration 23 | - Astro components for static content, framework components only for interactivity 24 | - Proper use of Astro.props and component interfaces 25 | - Content collections with Zod schemas 26 | - Server islands implementation where appropriate 27 | 28 | 3. **Performance & Bundle Optimization** 29 | - No unnecessary client-side JavaScript 30 | - Appropriate hydration strategy choices 31 | - Image optimization with Astro's Image component 32 | - Bundle size considerations 33 | - No over-hydration of static content 34 | 35 | 4. **Security & Validation** 36 | - Input validation with Zod schemas 37 | - Environment variables properly typed with astro:env 38 | - Content Security Policy implementation 39 | - No hardcoded secrets in client-side code 40 | - API route validation with proper error handling 41 | 42 | 5. **Content Management** 43 | - Content collections properly configured 44 | - Zod schemas for all content types 45 | - Type-safe content queries 46 | - Proper content rendering and data handling 47 | 48 | 6. **Package Management** 49 | - Using pnpm (not npm or yarn) 50 | - Proper dependency management 51 | - No unused dependencies 52 | - Correct dev vs runtime dependencies 53 | 54 | 7. **Code Structure & Architecture** 55 | - Components under 200 lines (500 line hard limit) 56 | - Functions under 50 lines with single responsibility 57 | - Proper separation of concerns 58 | - Feature-based organization 59 | - Islands architecture principles followed 60 | 61 | 8. **Testing & Quality Assurance** 62 | - Vitest configuration and tests 63 | - 80%+ test coverage maintained 64 | - Component tests using Astro Container API 65 | - API route integration tests 66 | - Proper mocking of external dependencies 67 | 68 | 9. **Build & Development** 69 | - `astro check` passes with zero errors 70 | - ESLint compliance with zero warnings 71 | - Prettier formatting applied 72 | - Production build succeeds 73 | - No hydration mismatches 74 | 75 | 10. **Documentation & Maintenance** 76 | - Clear component interfaces 77 | - Proper prop descriptions 78 | - CLAUDE.md updates for new patterns/dependencies 79 | - README updates if needed 80 | 81 | ## Review Output 82 | 83 | Create a concise review report with: 84 | 85 | ```markdown 86 | # TypeScript/Astro Code Review #[number] 87 | 88 | ## Summary 89 | [2-3 sentence overview focusing on Astro-specific patterns and TypeScript quality] 90 | 91 | ## Issues Found 92 | 93 | ### 🔴 Critical (Must Fix) 94 | - [Issue with file:line and suggested fix - focus on type safety, hydration, security] 95 | 96 | ### 🟡 Important (Should Fix) 97 | - [Issue with file:line and suggested fix - focus on performance, patterns] 98 | 99 | ### 🟢 Minor (Consider) 100 | - [Improvement suggestions for optimization, maintainability] 101 | 102 | ## Good Practices 103 | - [What was done well - highlight proper Astro patterns, TypeScript usage] 104 | 105 | ## Astro-Specific Findings 106 | - [Hydration strategy assessment] 107 | - [Bundle size impact] 108 | - [Content collection usage] 109 | - [Performance optimizations] 110 | 111 | ## TypeScript Quality 112 | - [Type safety assessment] 113 | - [Strict mode compliance] 114 | - [Interface definitions] 115 | 116 | ## Test Coverage 117 | Current: X% | Required: 80% 118 | Missing tests: [list with focus on component and API tests] 119 | 120 | ## Build Validation 121 | - [ ] `astro check` passes 122 | - [ ] `pnpm run lint` passes 123 | - [ ] `pnpm run build` succeeds 124 | - [ ] `pnpm test` passes with 80%+ coverage 125 | ``` 126 | 127 | Save report to PRPs/code_reviews/review[#].md (check existing files first) -------------------------------------------------------------------------------- /PRPs/templates/prp_task.md: -------------------------------------------------------------------------------- 1 | --- 2 | Intended for Jira/GitHub tasks or other task management systems to break down and plan the implementation. 3 | --- 4 | 5 | # Task Template v2 - Information Dense with Validation Loops 6 | 7 | > Concise, executable tasks with embedded context and validation commands 8 | 9 | ## Format 10 | 11 | ``` 12 | [ACTION] path/to/file: 13 | - [OPERATION]: [DETAILS] 14 | - VALIDATE: [COMMAND] 15 | - IF_FAIL: [DEBUG_HINT] 16 | ``` 17 | 18 | ## Actions keywords to use when creating tasks for concise and meaningful descriptions 19 | 20 | - **READ**: Understand existing patterns 21 | - **CREATE**: New file with specific content 22 | - **UPDATE**: Modify existing file 23 | - **DELETE**: Remove file/code 24 | - **FIND**: Search for patterns 25 | - **TEST**: Verify behavior 26 | - **FIX**: Debug and repair 27 | 28 | ## Critical Context Section 29 | 30 | ```yaml 31 | # Include these BEFORE tasks when context is crucial 32 | context: 33 | docs: 34 | - url: [API documentation] 35 | focus: [specific method/section] 36 | 37 | patterns: 38 | - file: existing/example.py 39 | copy: [pattern name] 40 | 41 | gotchas: 42 | - issue: "Library X requires Y" 43 | fix: "Always do Z first" 44 | ``` 45 | 46 | ## Task Examples with Validation 47 | 48 | ### Setup Tasks 49 | 50 | ``` 51 | READ src/config/settings.py: 52 | - UNDERSTAND: Current configuration structure 53 | - FIND: Model configuration pattern 54 | - NOTE: Config uses pydantic BaseSettings 55 | 56 | READ tests/test_models.py: 57 | - UNDERSTAND: Test pattern for models 58 | - FIND: Fixture setup approach 59 | - NOTE: Uses pytest-asyncio for async tests 60 | ``` 61 | 62 | ### Implementation Tasks 63 | 64 | ```` 65 | UPDATE path/to/file: 66 | - FIND: MODEL_REGISTRY = { 67 | - ADD: "new-model": NewModelClass, 68 | - VALIDATE: python -c "from path/to/file import MODEL_REGISTRY; assert 'new-model' in MODEL_REGISTRY" 69 | - IF_FAIL: Check import statement for NewModelClass 70 | 71 | CREATE path/to/file: 72 | - COPY_PATTERN: path/to/other/file 73 | - IMPLEMENT: 74 | - [Detailed description of what needs to be implemented based on codebase intelligence] 75 | - VALIDATE: uv run pytest path/to/file -v 76 | 77 | UPDATE path/to/file: 78 | - FIND: app.include_router( 79 | - ADD_AFTER: 80 | ```python 81 | from .endpoints import new_model_router 82 | app.include_router(new_model_router, prefix="/api/v1") 83 | ``` 84 | - VALIDATE: uv run pytest path/to/file -v 85 | ```` 86 | 87 | ## Validation Checkpoints 88 | 89 | ``` 90 | CHECKPOINT syntax: 91 | - RUN: ruff check && mypy . 92 | - FIX: Any reported issues 93 | - CONTINUE: Only when clean 94 | 95 | CHECKPOINT tests: 96 | - RUN: uv run pytest path/to/file -v 97 | - REQUIRE: All passing 98 | - DEBUG: uv run pytest -vvs path/to/file/failing_test.py 99 | - CONTINUE: Only when all green 100 | 101 | CHECKPOINT integration: 102 | - START: docker-compose up -d 103 | - RUN: ./scripts/integration_test.sh 104 | - EXPECT: "All tests passed" 105 | - CLEANUP: docker-compose down 106 | ``` 107 | 108 | ## Debug Patterns 109 | 110 | ``` 111 | DEBUG import_error: 112 | - CHECK: File exists at path 113 | - CHECK: __init__.py in all parent dirs 114 | - TRY: python -c "import path/to/file" 115 | - FIX: Add to PYTHONPATH or fix import 116 | 117 | DEBUG test_failure: 118 | - RUN: uv run pytest -vvs path/to/test.py::test_name 119 | - ADD: print(f"Debug: {variable}") 120 | - IDENTIFY: Assertion vs implementation issue 121 | - FIX: Update test or fix code 122 | 123 | DEBUG api_error: 124 | - CHECK: Server running (ps aux | grep uvicorn) 125 | - TEST: curl http://localhost:8000/health 126 | - READ: Server logs for stack trace 127 | - FIX: Based on specific error 128 | ``` 129 | 130 | ## Common Task examples 131 | 132 | ### Add New Feature 133 | 134 | ``` 135 | 1. READ existing similar feature 136 | 2. CREATE new feature file (COPY pattern) 137 | 3. UPDATE registry/router to include 138 | 4. CREATE tests for feature 139 | 5. TEST all tests pass 140 | 6. FIX any linting/type issues 141 | 7. TEST integration works 142 | ``` 143 | 144 | ### Fix Bug 145 | 146 | ``` 147 | 1. CREATE failing test that reproduces bug 148 | 2. TEST confirm test fails 149 | 3. READ relevant code to understand 150 | 4. UPDATE code with fix 151 | 5. TEST confirm test now passes 152 | 6. TEST no other tests broken 153 | 7. UPDATE changelog 154 | ``` 155 | 156 | ### Refactor Code 157 | 158 | ``` 159 | 1. TEST current tests pass (baseline) 160 | 2. CREATE new structure (don't delete old yet) 161 | 3. UPDATE one usage to new structure 162 | 4. TEST still passes 163 | 5. UPDATE remaining usages incrementally 164 | 6. DELETE old structure 165 | 7. TEST full suite passes 166 | ``` 167 | 168 | ## Tips for Effective Tasks 169 | 170 | - Use VALIDATE after every change 171 | - Include IF_FAIL hints for common issues 172 | - Reference specific line numbers or patterns 173 | - Keep validation commands simple and fast 174 | - Chain related tasks with clear dependencies 175 | - Always include rollback/undo steps for risky changes 176 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-base-create.md: -------------------------------------------------------------------------------- 1 | # Create BASE PRP 2 | 3 | ## Feature: $ARGUMENTS 4 | 5 | ## PRP Creation Mission 6 | 7 | Create a comprehensive PRP that enables **one-pass implementation success** through systematic research and context curation. 8 | 9 | **Critical Understanding**: The executing AI agent only receives: 10 | 11 | - Start by reading and understanding the prp concepts PRPs/README.md 12 | - The PRP content you create 13 | - Its training data knowledge 14 | - Access to codebase files (but needs guidance on which ones) 15 | 16 | **Therefore**: Your research and context curation directly determines implementation success. Incomplete context = implementation failure. 17 | 18 | ## Research Process 19 | 20 | > During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. we optminize for chance of success and not for speed. 21 | 22 | 1. **Codebase Analysis in depth** 23 | - Create clear todos and spawn subagents to search the codebase for similar features/patterns Think hard and plan your approach 24 | - Identify all the necessary files to reference in the PRP 25 | - Note all existing conventions to follow 26 | - Check existing test patterns for validation approach 27 | - Use the batch tools to spawn subagents to search the codebase for similar features/patterns 28 | 29 | 2. **External Research at scale** 30 | - Create clear todos and spawn with instructions subagents to do deep research for similar features/patterns online and include urls to documentation and examples 31 | - Library documentation (include specific URLs) 32 | - For critical pieces of documentation add a .md file to PRPs/ai_docs and reference it in the PRP with clear reasoning and instructions 33 | - Implementation examples (GitHub/StackOverflow/blogs) 34 | - Best practices and common pitfalls found during research 35 | - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples 36 | 37 | 3. **User Clarification** 38 | - Ask for clarification if you need it 39 | 40 | ## PRP Generation Process 41 | 42 | ### Step 1: Choose Template 43 | 44 | Use `PRPs/templates/prp_base.md` as your template structure - it contains all necessary sections and formatting. 45 | 46 | ### Step 2: Context Completeness Validation 47 | 48 | Before writing, apply the **"No Prior Knowledge" test** from the template: 49 | _"If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_ 50 | 51 | ### Step 3: Research Integration 52 | 53 | Transform your research findings into the template sections: 54 | 55 | **Goal Section**: Use research to define specific, measurable Feature Goal and concrete Deliverable 56 | **Context Section**: Populate YAML structure with your research findings - specific URLs, file patterns, gotchas 57 | **Implementation Tasks**: Create dependency-ordered tasks using information-dense keywords from codebase analysis 58 | **Validation Gates**: Use project-specific validation commands that you've verified work in this codebase 59 | 60 | ### Step 4: Information Density Standards 61 | 62 | Ensure every reference is **specific and actionable**: 63 | 64 | - URLs include section anchors, not just domain names 65 | - File references include specific patterns to follow, not generic mentions 66 | - Task specifications include exact naming conventions and placement 67 | - Validation commands are project-specific and executable 68 | 69 | ### Step 5: ULTRATHINK Before Writing 70 | 71 | After research completion, create comprehensive PRP writing plan using TodoWrite tool: 72 | 73 | - Plan how to structure each template section with your research findings 74 | - Identify gaps that need additional research 75 | - Create systematic approach to filling template with actionable context 76 | 77 | ## Output 78 | 79 | Save as: `PRPs/{feature-name}.md` 80 | 81 | ## PRP Quality Gates 82 | 83 | ### Context Completeness Check 84 | 85 | - [ ] Passes "No Prior Knowledge" test from template 86 | - [ ] All YAML references are specific and accessible 87 | - [ ] Implementation tasks include exact naming and placement guidance 88 | - [ ] Validation commands are project-specific and verified working 89 | 90 | ### Template Structure Compliance 91 | 92 | - [ ] All required template sections completed 93 | - [ ] Goal section has specific Feature Goal, Deliverable, Success Definition 94 | - [ ] Implementation Tasks follow dependency ordering 95 | - [ ] Final Validation Checklist is comprehensive 96 | 97 | ### Information Density Standards 98 | 99 | - [ ] No generic references - all are specific and actionable 100 | - [ ] File patterns point at specific examples to follow 101 | - [ ] URLs include section anchors for exact guidance 102 | - [ ] Task specifications use information-dense keywords from codebase 103 | 104 | ## Success Metrics 105 | 106 | **Confidence Score**: Rate 1-10 for one-pass implementation success likelihood 107 | 108 | **Validation**: The completed PRP should enable an AI agent unfamiliar with the codebase to implement the feature successfully using only the PRP content and codebase access. 109 | -------------------------------------------------------------------------------- /.claude/commands/rapid-development/experimental/prp-validate.md: -------------------------------------------------------------------------------- 1 | # Validate PRP 2 | 3 | ## PRP File: $ARGUMENTS 4 | 5 | Pre-flight validation of a PRP to ensure all context and dependencies are available before execution. 6 | 7 | ## Validation Process 8 | 9 | 1. **Parse PRP** 10 | - Read the specified PRP file 11 | - Extract all file references, URLs, and dependencies 12 | - Parse validation checklist items 13 | 14 | 2. **Context Validation** 15 | - Check all referenced files exist 16 | - Validate all URLs are accessible 17 | - Verify environment dependencies are available 18 | - Check for required API keys/credentials 19 | 20 | 3. **Codebase Analysis** 21 | - Scan for similar patterns mentioned in PRP 22 | - Validate existing examples are current 23 | - Check for architectural consistency 24 | 25 | 4. **Dependency Check** 26 | - Verify all required libraries are installed 27 | - Check version compatibility 28 | - Validate external service connectivity 29 | 30 | 5. **Risk Assessment** 31 | - Analyze failure patterns mentioned in PRP 32 | - Assess complexity and confidence score 33 | - Identify potential bottlenecks 34 | 35 | ## Validation Gates 36 | 37 | ### File References 38 | 39 | ```bash 40 | # Check all referenced files exist 41 | echo "Validating file references..." 42 | for file in $(grep -o 'file: [^[:space:]]*' "$PRP_FILE" | cut -d' ' -f2); do 43 | if [ ! -f "$file" ]; then 44 | echo "❌ Missing file: $file" 45 | exit 1 46 | else 47 | echo "✅ Found: $file" 48 | fi 49 | done 50 | ``` 51 | 52 | ### URL Accessibility 53 | 54 | ```bash 55 | # Check all referenced URLs are accessible 56 | echo "Validating URL references..." 57 | for url in $(grep -o 'url: [^[:space:]]*' "$PRP_FILE" | cut -d' ' -f2); do 58 | if curl -s --head "$url" > /dev/null; then 59 | echo "✅ Accessible: $url" 60 | else 61 | echo "⚠️ Cannot access: $url" 62 | fi 63 | done 64 | ``` 65 | 66 | ### Environment Dependencies 67 | 68 | ```bash 69 | # Check environment setup 70 | echo "Validating environment dependencies..." 71 | 72 | # Check Python dependencies 73 | if command -v python3 &> /dev/null; then 74 | echo "✅ Python3 available" 75 | 76 | # Check specific imports mentioned in PRP 77 | python3 -c " 78 | import re 79 | import sys 80 | # Read PRP file and extract import statements 81 | with open('$PRP_FILE', 'r') as f: 82 | content = f.read() 83 | # Find import statements in code blocks 84 | imports = re.findall(r'^(?:import|from)\s+([a-zA-Z_][a-zA-Z0-9_]*)', content, re.MULTILINE) 85 | unique_imports = set(imports) 86 | failed_imports = [] 87 | for module in unique_imports: 88 | try: 89 | __import__(module) 90 | print(f'✅ Module available: {module}') 91 | except ImportError: 92 | failed_imports.append(module) 93 | print(f'⚠️ Module missing: {module}') 94 | if failed_imports: 95 | print(f'❌ Missing modules: {failed_imports}') 96 | sys.exit(1) 97 | " 98 | else 99 | echo "❌ Python3 not available" 100 | exit 1 101 | fi 102 | ``` 103 | 104 | ### API Connectivity 105 | 106 | ```bash 107 | # Check external API connectivity 108 | echo "Validating API connectivity..." 109 | 110 | # Check common APIs mentioned in PRP 111 | if grep -q "api.openai.com" "$PRP_FILE"; then 112 | if [ -n "$OPENAI_API_KEY" ]; then 113 | echo "✅ OpenAI API key configured" 114 | else 115 | echo "⚠️ OpenAI API key not set" 116 | fi 117 | fi 118 | 119 | if grep -q "api.anthropic.com" "$PRP_FILE"; then 120 | if [ -n "$ANTHROPIC_API_KEY" ]; then 121 | echo "✅ Anthropic API key configured" 122 | else 123 | echo "⚠️ Anthropic API key not set" 124 | fi 125 | fi 126 | 127 | # Add more API checks as needed 128 | ``` 129 | 130 | ## Validation Report 131 | 132 | Generate a comprehensive validation report with: 133 | 134 | 1. **Context Completeness Score** (0-100) 135 | 2. **Dependency Readiness** (Ready/Issues/Blocked) 136 | 3. **Risk Assessment** (Low/Medium/High) 137 | 4. **Recommended Actions** (before execution) 138 | 139 | ## Output Format 140 | 141 | ``` 142 | 🔍 PRP Validation Report 143 | ======================== 144 | 📁 Context Validation: [PASS/FAIL] 145 | - Files referenced: X/X found 146 | - URLs accessible: X/X responding 147 | - Examples current: [YES/NO] 148 | 🔧 Dependencies: [READY/ISSUES/BLOCKED] 149 | - Python modules: X/X available 150 | - External services: X/X accessible 151 | - API keys: X/X configured 152 | ⚠️ Risk Assessment: [LOW/MEDIUM/HIGH] 153 | - Complexity score: X/10 154 | - Failure patterns: X identified 155 | - Mitigation strategies: X documented 156 | 📊 Readiness Score: XX/100 157 | 🎯 Recommended Actions: 158 | [ ] Install missing dependencies 159 | [ ] Configure missing API keys 160 | [ ] Update stale examples 161 | [ ] Review risk mitigation strategies 162 | Status: [READY_TO_EXECUTE/NEEDS_ATTENTION/BLOCKED] 163 | ``` 164 | 165 | ## Auto-Fix Suggestions 166 | 167 | When validation fails, provide actionable suggestions: 168 | 169 | ```bash 170 | # Auto-generate fixes where possible 171 | if [ "$STATUS" != "READY_TO_EXECUTE" ]; then 172 | echo "🔧 Auto-fix suggestions:" 173 | echo "pip install missing-module-1 missing-module-2" 174 | echo "export MISSING_API_KEY=your_key_here" 175 | echo "git checkout HEAD -- outdated-example.py" 176 | fi 177 | ``` 178 | 179 | ## Integration with Execute Command 180 | 181 | The validate command should be automatically called by execute-prp before starting implementation: 182 | 183 | ```bash 184 | # In execute-prp.md, add this as step 0: 185 | echo "Running pre-execution validation..." 186 | validate-prp "$PRP_FILE" 187 | if [ $? -ne 0 ]; then 188 | echo "❌ Validation failed. Please fix issues before execution." 189 | exit 1 190 | fi 191 | ``` 192 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-story-create.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: "Convert user story/task into executable PRP with deep codebase analysis" 3 | --- 4 | 5 | # Create Story PRP from User Story/Task 6 | 7 | ## Story/Task: $ARGUMENTS 8 | 9 | ## Mission 10 | 11 | Transform a user story or task into a **tactical implementation PRP** through systematic codebase analysis and task decomposition. 12 | 13 | We do not write any code in this step, the goal is to create a detailed context engineered implementation plan for the implementation agent. 14 | 15 | **Key Principle**: We must first gather the context about the story/task before proceeding with the analysis. 16 | 17 | When we understand the story/task, we can proceed with the codebase analysis. We systematically dig deep into the codebase to gather intelligence and identify patterns and implementation points. We then use this information to create a PRP that can be executed by a coding agent. 18 | 19 | The contents of the created PRP should encapsulate all the information the agent needs to complete the story/task in one pass. 20 | 21 | Remember that subagents will only receive their details from you, the user has no way of interacting with the subagents. so you need to share all the relevant context to the subagent in the subagent prompt and in the TODO that is shared with the particular agent. 22 | 23 | Create detailed todos and spawn parallel subagents to analyze (Use specialized subagents when apropriate): 24 | 25 | ## Analysis Process 26 | 27 | ### Phase 1: Story Decomposition 28 | 29 | Analyze the story to determine: 30 | 31 | - **Story/Task Type**: Feature/Bug/Enhancement/Refactor 32 | - **Complexity**: Low, Medium, High 33 | - **Affected Systems**: Which components/services need changes 34 | 35 | Get a deep understanding about the story/task before proceeding so that you can effectively guide the rest of the process. 36 | 37 | ### Phase 2: Codebase Intelligence Gathering 38 | 39 | **1. Project Structure Analysis** 40 | 41 | - Detect primary language(s) and frameworks 42 | - Map directory structure and conventions to identify integration points for the story/task 43 | - Identify service/component boundaries 44 | - Find configuration files and environment setup 45 | 46 | **2. Pattern Recognition** 47 | 48 | - Search for similar implementations in codebase 49 | - Identify coding conventions (naming, structure, error handling) start in CLAUDE.md AGENTS.md or relevant rules files such as .cursorrules 50 | - Extract common patterns for the story's domain that should be added to the PRP as context for the implementation agent. 51 | - Note anti-patterns to avoid 52 | 53 | **3. Dependency Analysis** 54 | 55 | - Catalog external libraries used if relevant to the story/task (check package.json, pyproject.toml, go.mod, etc.) 56 | - Understand how libraries are integrated 57 | - Find relevant documentation in PRPs/ai_docs/ if shared, ai_docs directory is used by the user to paste in relevant additional context that may be relevant to our story/task 58 | 59 | **4. Testing Patterns** 60 | 61 | - Identify test framework and structure 62 | - Find similar test examples and test setup 63 | - Suggest test cases and scenarios 64 | 65 | **5. Integration Points** 66 | 67 | - Identify files that will need updates 68 | - Identify if new files needs to be created and where to create them 69 | - Find router/API registration patterns 70 | - Understand database/model patterns if relevant 71 | 72 | ### Phase 3: Think harder about the story and its components. 73 | 74 | Really think hard about everything you just learned during the research phases. 75 | 76 | ### Phase 4: PRP Task Generation 77 | 78 | Transform analysis into concrete tasks: 79 | 80 | Read and understand the template @PRPs/templates/prp_story_task.md 81 | 82 | **Task Rules**: 83 | 84 | 1. Each task is atomic and independently testable 85 | 2. Tasks are ordered by dependency 86 | 3. Use action verbs that are information dense: CREATE, UPDATE, ADD, REMOVE, REFACTOR, MIRROR 87 | 4. Include specific implementation details from codebase analysis 88 | 5. Every task has an executable validation command 89 | 90 | **Task Action Types**: 91 | 92 | We use the concept of information dense keywords to describe the action to be taken, below is a guidance. 93 | But you can use your own words to describe the action to be taken as long as you follow this same principle. 94 | 95 | Examples: 96 | 97 | - **CREATE**: New files/components 98 | - **UPDATE**: Modify existing files 99 | - **ADD**: Insert new functionality into existing code 100 | - **REMOVE**: Delete deprecated code 101 | - **REFACTOR**: Restructure without changing behavior 102 | - **MIRROR**: Mirror existing pattern or functionality that exists elsewhere in the codebase 103 | 104 | ### Phase 5: Validation Design 105 | 106 | For each task, design validation that: 107 | 108 | - Can run immediately after task completion 109 | - Provides clear pass/fail feedback 110 | - Uses project-specific commands discovered in analysis 111 | 112 | ## Quality Criteria 113 | 114 | ### Task Clarity 115 | 116 | - [ ] The PRP is clear and concise and follows KISS principle 117 | - [ ] Each task has clear action and target 118 | - [ ] Implementation details reference specific patterns 119 | - [ ] Validation commands are executable 120 | 121 | ### Context Completeness 122 | 123 | - [ ] All necessary patterns identified 124 | - [ ] External library usage documented 125 | - [ ] Integration points mapped 126 | - [ ] External context references populated 127 | 128 | ### Story Coverage 129 | 130 | - [ ] All acceptance criteria addressed 131 | - [ ] Edge cases considered 132 | - [ ] Error handling included where needed 133 | 134 | ## Output 135 | 136 | Save as: `PRPs/story_{kebab-case-summary}.md` 137 | 138 | ## Success Metrics 139 | 140 | **Implementation Ready**: Another developer could execute these tasks without additional context 141 | **Validation Complete**: Every task has atleast one working validation command 142 | **Pattern Consistent**: Tasks follow existing codebase conventions 143 | -------------------------------------------------------------------------------- /PRPs/ai_docs/cc_troubleshoot.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting 2 | 3 | > Discover solutions to common issues with Claude Code installation and usage. 4 | 5 | ## Common installation issues 6 | 7 | ### Windows installation issues: errors in WSL 8 | 9 | You might encounter the following issues in WSL: 10 | 11 | **OS/platform detection issues**: If you receive an error during installation, WSL may be using Windows `npm`. Try: 12 | 13 | - Run `npm config set os linux` before installation 14 | - Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check` (Do NOT use `sudo`) 15 | 16 | **Node not found errors**: If you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution's package manager or via [`nvm`](https://github.com/nvm-sh/nvm). 17 | 18 | ### Linux and Mac installation issues: permission or command not found errors 19 | 20 | When installing Claude Code with npm, `PATH` problems may prevent access to `claude`. 21 | You may also encounter permission errors if your npm global prefix is not user writable (eg. `/usr`, or `/usr/local`). 22 | 23 | #### Recommended solution: Native Claude Code installation 24 | 25 | Claude Code has a native installation that doesn't depend on npm or Node.js. 26 | 27 | 28 | The native Claude Code installer is currently in beta. 29 | 30 | 31 | Use the following command to run the native installer. 32 | 33 | **macOS, Linux, WSL:** 34 | 35 | ```bash 36 | # Install stable version (default) 37 | curl -fsSL https://claude.ai/install.sh | bash 38 | 39 | # Install latest version 40 | curl -fsSL https://claude.ai/install.sh | bash -s latest 41 | 42 | # Install specific version number 43 | curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58 44 | ``` 45 | 46 | **Windows PowerShell:** 47 | 48 | ```powershell 49 | # Install stable version (default) 50 | irm https://claude.ai/install.ps1 | iex 51 | 52 | # Install latest version 53 | & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest 54 | 55 | # Install specific version number 56 | & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58 57 | 58 | ``` 59 | 60 | This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude`. 61 | 62 | 63 | Make sure that you have the installation directory in your system PATH. 64 | 65 | 66 | #### Alternative solution: Migrate to local installation 67 | 68 | Alternatively, if Claude Code will run, you can migrate to a local installation: 69 | 70 | ```bash 71 | claude migrate-installer 72 | ``` 73 | 74 | This moves Claude Code to `~/.claude/local/` and sets up an alias in your shell configuration. No `sudo` is required for future updates. 75 | 76 | After migration, restart your shell, and then verify your installation: 77 | 78 | On macOS/Linux/WSL: 79 | 80 | ```bash 81 | which claude # Should show an alias to ~/.claude/local/claude 82 | ``` 83 | 84 | On Windows: 85 | 86 | ```powershell 87 | where claude # Should show path to claude executable 88 | ``` 89 | 90 | Verify installation: 91 | 92 | ```bash 93 | claude doctor # Check installation health 94 | ``` 95 | 96 | ## Permissions and authentication 97 | 98 | ### Repeated permission prompts 99 | 100 | If you find yourself repeatedly approving the same commands, you can allow specific tools 101 | to run without approval using the `/permissions` command. See [Permissions docs](/en/docs/claude-code/iam#configuring-permissions). 102 | 103 | ### Authentication issues 104 | 105 | If you're experiencing authentication problems: 106 | 107 | 1. Run `/logout` to sign out completely 108 | 2. Close Claude Code 109 | 3. Restart with `claude` and complete the authentication process again 110 | 111 | If problems persist, try: 112 | 113 | ```bash 114 | rm -rf ~/.config/claude-code/auth.json 115 | claude 116 | ``` 117 | 118 | This removes your stored authentication information and forces a clean login. 119 | 120 | ## Performance and stability 121 | 122 | ### High CPU or memory usage 123 | 124 | Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues: 125 | 126 | 1. Use `/compact` regularly to reduce context size 127 | 2. Close and restart Claude Code between major tasks 128 | 3. Consider adding large build directories to your `.gitignore` file 129 | 130 | ### Command hangs or freezes 131 | 132 | If Claude Code seems unresponsive: 133 | 134 | 1. Press Ctrl+C to attempt to cancel the current operation 135 | 2. If unresponsive, you may need to close the terminal and restart 136 | 137 | ### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals 138 | 139 | If you're using Claude Code in JetBrains terminals and the ESC key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts. 140 | 141 | To fix this issue: 142 | 143 | 1. Go to Settings → Tools → Terminal 144 | 2. Click the "Configure terminal keybindings" hyperlink next to "Override IDE Shortcuts" 145 | 3. Within the terminal keybindings, scroll down to "Switch focus to Editor" and delete that shortcut 146 | 147 | This will allow the ESC key to properly function for canceling Claude Code operations instead of being captured by PyCharm's "Switch focus to Editor" action. 148 | 149 | ## Getting more help 150 | 151 | If you're experiencing issues not covered here: 152 | 153 | 1. Use the `/bug` command within Claude Code to report problems directly to Anthropic 154 | 2. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues 155 | 3. Run `/doctor` to check the health of your Claude Code installation 156 | 4. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation 157 | -------------------------------------------------------------------------------- /PRPs/STORY_WORKFLOW_GUIDE.md: -------------------------------------------------------------------------------- 1 | # Story PRP Workflow Guide 2 | 3 | ## Overview 4 | 5 | The Story PRP workflow is a streamlined approach for converting user stories/tasks from Jira, Linear, or other project management tools into executable implementation plans. Unlike the comprehensive Base PRP flow, Story PRPs focus on tactical, task-oriented implementation. 6 | 7 | ## Key Differences from Base PRPs 8 | 9 | | Aspect | Base PRP | Story PRP | 10 | |--------|----------|-----------| 11 | | **Scope** | Full feature/product | Single story/task | 12 | | **Context** | Extensive documentation | Focused references | 13 | | **Format** | Detailed blueprint | Task checklist | 14 | | **Validation** | 4-level comprehensive | Inline per-task | 15 | | **Use Case** | New features, major changes | Sprint tasks, bug fixes | 16 | 17 | ## Workflow Components 18 | 19 | ### 1. Template: `PRPs/templates/prp_story.md` 20 | - Simplified structure focused on implementation tasks 21 | - Each task has inline validation 22 | - No extensive blueprint sections 23 | - Direct, actionable format 24 | 25 | ### 2. Commands 26 | 27 | #### `/prp-story-create {story description}` 28 | Creates a Story PRP by: 29 | - Analyzing codebase for patterns and conventions 30 | - Breaking down story into concrete tasks 31 | - Generating validation commands 32 | - Leveraging specialized subagents for parallel analysis 33 | 34 | #### `/prp-story-execute {prp_file}` 35 | Executes a Story PRP by: 36 | - Implementing tasks sequentially 37 | - Validating each task immediately 38 | - Following discovered patterns exactly 39 | - Ensuring all acceptance criteria are met 40 | 41 | ### 3. Specialized Subagents 42 | 43 | #### `@codebase-analyst` 44 | - Deep pattern analysis 45 | - Convention discovery 46 | - Architecture understanding 47 | - Testing pattern extraction 48 | 49 | #### `@library-researcher` 50 | - External documentation fetching 51 | - Implementation example finding 52 | - Best practices research 53 | - Known issues identification 54 | 55 | ## Usage Examples 56 | 57 | ### Creating a Story PRP 58 | 59 | ```bash 60 | # From a user story 61 | /prp-story-create As a user, I want to add pagination to the product list API so that large result sets load faster 62 | 63 | # From a bug report 64 | /prp-story-create BUG: Email notifications are not being sent when users reset their password 65 | 66 | # From a technical task 67 | /prp-story-create Refactor database connection pool to use async context managers 68 | ``` 69 | 70 | ### Executing a Story PRP 71 | 72 | ```bash 73 | # Execute the generated PRP 74 | /prp-story-execute PRPs/story_add_pagination.md 75 | 76 | # Or use the runner script 77 | uv run PRPs/scripts/prp_runner.py --prp story_add_pagination --interactive 78 | ``` 79 | 80 | ## Task Format Examples 81 | 82 | ### CREATE Task 83 | ```markdown 84 | ### CREATE services/pagination_service.py: 85 | - IMPLEMENT: PaginationService with calculate_offset() method 86 | - PATTERN: Follow services/filter_service.py structure 87 | - IMPORTS: from typing import Tuple; from math import ceil 88 | - GOTCHA: Handle negative page numbers gracefully 89 | - **VALIDATE**: `python -c "from services.pagination_service import PaginationService; print('✓')"` 90 | ``` 91 | 92 | ### UPDATE Task 93 | ```markdown 94 | ### UPDATE api/products.py: 95 | - ADD: pagination parameters to list_products endpoint 96 | - FIND: `async def list_products(request: Request):` 97 | - INSERT: `page: int = Query(1, ge=1), per_page: int = Query(20, le=100)` 98 | - **VALIDATE**: `grep -q "page.*Query" api/products.py && echo "✓ Params added"` 99 | ``` 100 | 101 | ## Best Practices 102 | 103 | ### When Creating Story PRPs 104 | 105 | 1. **Provide Clear Context**: Include acceptance criteria and any constraints 106 | 2. **Let Agents Analyze**: Don't pre-specify implementation details 107 | 3. **Trust the Process**: The system will discover patterns and conventions 108 | 109 | ### When Executing Story PRPs 110 | 111 | 1. **Sequential Execution**: Complete tasks in order 112 | 2. **Validate Immediately**: Run validation after each task 113 | 3. **Follow Patterns**: Don't create new patterns, use existing ones 114 | 4. **Fix Forward**: If validation fails, fix and continue 115 | 116 | ## Typical Story Types 117 | 118 | - **Feature Addition**: New endpoints, services, or components 119 | - **Bug Fixes**: Targeted fixes with test coverage 120 | - **Refactoring**: Code improvements maintaining behavior 121 | - **Integration**: Adding third-party services or libraries 122 | - **Performance**: Optimization tasks with benchmarks 123 | - **Security**: Adding auth, validation, or hardening 124 | 125 | ## Advanced Usage 126 | 127 | ### Parallel Analysis 128 | The create command spawns multiple subagents to analyze: 129 | - Project structure 130 | - Similar implementations 131 | - External documentation 132 | - Testing patterns 133 | 134 | ### Custom Validation 135 | Each task can have custom validation beyond standard commands: 136 | - API endpoint testing with curl 137 | - Database verification queries 138 | - Performance benchmarks 139 | - Integration tests 140 | 141 | ### Context References 142 | The system automatically discovers and includes: 143 | - Relevant codebase patterns 144 | - External documentation 145 | - Configuration examples 146 | - Test patterns 147 | 148 | ## When to Use Story PRPs vs Base PRPs 149 | 150 | **Use Story PRPs for:** 151 | - Sprint tasks and user stories 152 | - Bug fixes and small features 153 | - Refactoring and optimization 154 | - Tasks with clear scope 155 | 156 | **Use Base PRPs for:** 157 | - New products or major features 158 | - Complex architectural changes 159 | - Multi-system integrations 160 | - Features requiring extensive context 161 | 162 | ## Troubleshooting 163 | 164 | **Issue**: Tasks seem too high-level 165 | **Solution**: Provide more specific acceptance criteria in the story 166 | 167 | **Issue**: Wrong patterns detected 168 | **Solution**: Include hints about which part of codebase to reference 169 | 170 | **Issue**: Validation commands fail 171 | **Solution**: Check project setup, ensure dependencies installed 172 | 173 | ## Example Output 174 | 175 | See `PRPs/story_add_rate_limiting_example.md` for a complete example of a generated Story PRP from a user story about adding rate limiting to an API. -------------------------------------------------------------------------------- /PRPs/templates/prp_story_task.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: "Story PRP Template - Task Implementation Focus" 3 | description: "Template for converting user stories into executable implementation tasks" 4 | --- 5 | 6 | ## Original Story 7 | 8 | Paste in the original story shared by the user below: 9 | 10 | ``` 11 | [User story/task description from Jira/Linear/etc] 12 | ``` 13 | 14 | ## Story Metadata 15 | 16 | **Story Type**: [Feature/Bug/Enhancement/Refactor] 17 | **Estimated Complexity**: [Low/Medium/High] 18 | **Primary Systems Affected**: [List of main components/services] 19 | 20 | --- 21 | 22 | ## CONTEXT REFERENCES 23 | 24 | [Auto-discovered documentation and patterns] 25 | 26 | - {file_path} - {Why this pattern/file is relevant} 27 | - {doc_path} - {Specific sections needed for implementation} 28 | - {external_url} - {Library documentation or examples} 29 | 30 | --- 31 | 32 | ## IMPLEMENTATION TASKS 33 | 34 | [Task blocks in dependency order - each block is atomic and testable] 35 | 36 | ### Concept For tasks 37 | 38 | - We are using Information dense keywords to be specific and concise about implementation steps and details. 39 | - The tasks have to be detailed and specific to ensure clarity and accuracy. 40 | - The developer that will execute the tasks should be able to complete the task using only the context of this file, with references to relevant codebase paths and integration points. 41 | 42 | ### {ACTION} {target_file}: 43 | 44 | - {VERB/KEYWORD}: {Specific implementation detail} 45 | - {PATTERN}: {Existing pattern to follow from codebase} 46 | - {IMPORTS}: {Required imports or dependencies} 47 | - {GOTCHA}: {Known issues or constraints to avoid} 48 | - **VALIDATE**: `{executable validation command}` 49 | 50 | ### Example Format: 51 | 52 | ### CREATE services/user_service.py: 53 | 54 | - IMPLEMENT: UserService class with async CRUD operations 55 | - PATTERN: Follow services/product_service.py structure 56 | - IMPORTS: from models.user import User; from db import get_session 57 | - GOTCHA: Always use async session context manager 58 | - **VALIDATE**: ` uv run python -c "from services.user_service import UserService; print('✓ Import successful')"` 59 | 60 | ### UPDATE api/routes.py: 61 | 62 | - ADD: user_router to main router 63 | - FIND: `app.include_router(product_router)` 64 | - INSERT: `app.include_router(user_router, prefix="/users", tags=["users"])` 65 | - **VALIDATE**: `grep -q "user_router" api/routes.py && echo "✓ Router added"` 66 | 67 | ### ADD tests/ 68 | 69 | - CREATE: tests/user_service_test.py 70 | - IMPLEMENT: Test cases for UserService class 71 | - PATTERN: Follow tests/product_service_test.py structure 72 | - IMPORTS: from services.user_service import UserService; from models.user import User; from db import get_session 73 | - GOTCHA: Use async session context manager in tests 74 | - **VALIDATE**: `uv run python -m pytest tests/user_service_test.py && echo "✓ Tests passed"` 75 | 76 | --- 77 | 78 | ## Validation Loop 79 | 80 | ### Level 1: Syntax & Style (Immediate Feedback) 81 | 82 | ```bash 83 | # Run after each file creation - fix before proceeding 84 | ruff check src/{new_files} --fix # Auto-format and fix linting issues 85 | mypy src/{new_files} # Type checking with specific files 86 | ruff format src/{new_files} # Ensure consistent formatting 87 | 88 | # Project-wide validation 89 | ruff check src/ --fix 90 | mypy src/ 91 | ruff format src/ 92 | 93 | # Expected: Zero errors. If errors exist, READ output and fix before proceeding. 94 | ``` 95 | 96 | ### Level 2: Unit Tests (Component Validation) 97 | 98 | ```bash 99 | # Test each component as it's created 100 | uv run pytest src/services/tests/test_{domain}_service.py -v 101 | uv run pytest src/tools/tests/test_{action}_{resource}.py -v 102 | 103 | # Full test suite for affected areas 104 | uv run pytest src/services/tests/ -v 105 | uv run pytest src/tools/tests/ -v 106 | 107 | # Coverage validation (if coverage tools available) 108 | uv run pytest src/ --cov=src --cov-report=term-missing 109 | 110 | # Expected: All tests pass. If failing, debug root cause and fix implementation. 111 | ``` 112 | 113 | ### Level 3: Integration Testing (System Validation) 114 | 115 | ```bash 116 | # Service startup validation 117 | uv run python main.py & 118 | sleep 3 # Allow startup time 119 | 120 | # Health check validation 121 | curl -f http://localhost:8000/health || echo "Service health check failed" 122 | 123 | # Feature-specific endpoint testing 124 | curl -X POST http://localhost:8000/{your_endpoint} \ 125 | -H "Content-Type: application/json" \ 126 | -d '{"test": "data"}' \ 127 | | jq . # Pretty print JSON response 128 | 129 | # MCP server validation (if MCP-based) 130 | # Test MCP tool functionality 131 | echo '{"method": "tools/call", "params": {"name": "{tool_name}", "arguments": {}}}' | \ 132 | uv run python -m src.main 133 | 134 | # Database validation (if database integration) 135 | # Verify database schema, connections, migrations 136 | psql $DATABASE_URL -c "SELECT 1;" || echo "Database connection failed" 137 | 138 | # Expected: All integrations working, proper responses, no connection errors 139 | ``` 140 | 141 | ### Level 4: Creative & Domain-Specific Validation 142 | 143 | You can use CLI that are installed on the system or MCP servers to extend the validation and self closing loop. 144 | 145 | Identify if you are connected to any MCP servers that can be used for validation and if you have any cli tools installed on the system that can help with validation. 146 | 147 | For example: 148 | 149 | ```bash 150 | # MCP Server Validation Examples: 151 | 152 | # Playwright MCP (for web interfaces) 153 | playwright-mcp --url http://localhost:8000 --test-user-journey 154 | 155 | # Docker MCP (for containerized services) 156 | docker-mcp --build --test --cleanup 157 | 158 | # Database MCP (for data operations) 159 | database-mcp --validate-schema --test-queries --check-performance 160 | ``` 161 | 162 | --- 163 | 164 | ## COMPLETION CHECKLIST 165 | 166 | - [ ] All tasks completed 167 | - [ ] Each task validation passed 168 | - [ ] Full test suite passes 169 | - [ ] No linting errors 170 | - [ ] All available validation gates passed 171 | - [ ] Story acceptance criteria met 172 | 173 | --- 174 | 175 | ## Notes 176 | 177 | [Any additional context, decisions made, or follow-up items] 178 | 179 | ``` 180 | 181 | ``` 182 | -------------------------------------------------------------------------------- /.claude/PRPs/scripts/invoke_command.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env -S uv run --script 2 | """Invoke a Claude Code slash command from Python. 3 | 4 | Usage: 5 | uv run .claude/PRPs/scripts/invoke_command.py prp-core-create "Add JWT authentication" 6 | uv run .claude/PRPs/scripts/invoke_command.py prp-core-execute my-feature --interactive 7 | uv run .claude/PRPs/scripts/invoke_command.py .claude/commands/prp-core/prp-core-pr.md "Add auth feature" 8 | """ 9 | 10 | from __future__ import annotations 11 | 12 | import argparse 13 | import subprocess 14 | import sys 15 | from pathlib import Path 16 | 17 | ROOT = Path(__file__).resolve().parent.parent.parent.parent # project root 18 | 19 | 20 | def resolve_command_path(command: str) -> Path: 21 | """Resolve command name or path to full .md file path. 22 | 23 | Args: 24 | command: Either a command name (e.g., "prp-core-create") or full path 25 | 26 | Returns: 27 | Path to the command .md file 28 | """ 29 | # If it's already a path, use it 30 | if command.endswith(".md"): 31 | path = Path(command) 32 | if path.is_absolute(): 33 | return path 34 | return ROOT / path 35 | 36 | # Otherwise, search in .claude/commands/ 37 | commands_dir = ROOT / ".claude" / "commands" 38 | 39 | # Try common locations 40 | search_paths = [ 41 | commands_dir / f"{command}.md", 42 | commands_dir / "prp-core" / f"{command}.md", 43 | commands_dir / "prp-commands" / f"{command}.md", 44 | commands_dir / "development" / f"{command}.md", 45 | commands_dir / "code-quality" / f"{command}.md", 46 | ] 47 | 48 | for path in search_paths: 49 | if path.exists(): 50 | return path 51 | 52 | # Fallback: search recursively 53 | for md_file in commands_dir.rglob("*.md"): 54 | if md_file.stem == command: 55 | return md_file 56 | 57 | sys.exit(f"Command not found: {command}") 58 | 59 | 60 | def strip_frontmatter(content: str) -> str: 61 | """Remove YAML frontmatter from markdown content. 62 | 63 | Frontmatter is delimited by --- at the start and end. 64 | """ 65 | if content.startswith("---\n"): 66 | # Find the closing --- 67 | end_marker = content.find("\n---\n", 4) 68 | if end_marker != -1: 69 | # Return content after frontmatter 70 | return content[end_marker + 5:].lstrip() 71 | return content 72 | 73 | 74 | def expand_template(template: str, arguments: str) -> str: 75 | """Expand template with arguments. 76 | 77 | Supports: 78 | - $ARGUMENTS: all arguments as single string 79 | - $1, $2, $3, etc.: individual positional arguments 80 | """ 81 | # Strip frontmatter first 82 | template = strip_frontmatter(template) 83 | 84 | # Replace $ARGUMENTS with full argument string 85 | expanded = template.replace("$ARGUMENTS", arguments) 86 | 87 | # Replace positional arguments 88 | args_list = arguments.split() 89 | for i, arg in enumerate(args_list, 1): 90 | expanded = expanded.replace(f"${i}", arg) 91 | 92 | return expanded 93 | 94 | 95 | def invoke_command( 96 | command_path: Path, 97 | arguments: str = "", 98 | interactive: bool = False, 99 | output_format: str = "text", 100 | allowed_tools: str = "Edit,Bash,Write,Read,Glob,Grep,TodoWrite,WebFetch,WebSearch,Task", 101 | ) -> None: 102 | """Invoke a Claude Code slash command. 103 | 104 | Args: 105 | command_path: Path to command .md file 106 | arguments: Arguments to pass to command 107 | interactive: Run in interactive mode 108 | output_format: Output format for headless mode (text, json, stream-json) 109 | allowed_tools: Comma-separated list of allowed tools 110 | """ 111 | # Read and expand template 112 | template = command_path.read_text() 113 | prompt = expand_template(template, arguments) 114 | 115 | # Build command 116 | if interactive: 117 | # Interactive mode: pipe via stdin 118 | cmd = [ 119 | "claude", 120 | "--allowedTools", 121 | allowed_tools, 122 | ] 123 | subprocess.run(cmd, input=prompt.encode(), check=True) 124 | else: 125 | # Headless mode: use -p flag 126 | cmd = [ 127 | "claude", 128 | "-p", 129 | prompt, 130 | "--allowedTools", 131 | allowed_tools, 132 | "--output-format", 133 | output_format, 134 | ] 135 | subprocess.run(cmd, check=True) 136 | 137 | 138 | def main() -> None: 139 | parser = argparse.ArgumentParser( 140 | description="Invoke a Claude Code slash command", 141 | epilog=""" 142 | Examples: 143 | %(prog)s prp-core-create "Add JWT authentication" 144 | %(prog)s prp-core-execute my-feature --interactive 145 | %(prog)s .claude/commands/prp-core/prp-core-pr.md "Add auth" --output-format json 146 | """, 147 | formatter_class=argparse.RawDescriptionHelpFormatter, 148 | ) 149 | parser.add_argument( 150 | "command", 151 | help="Command name (e.g., 'prp-core-create') or path to .md file", 152 | ) 153 | parser.add_argument( 154 | "arguments", 155 | nargs="?", 156 | default="", 157 | help="Arguments to pass to the command", 158 | ) 159 | parser.add_argument( 160 | "--interactive", 161 | "-i", 162 | action="store_true", 163 | help="Run in interactive mode", 164 | ) 165 | parser.add_argument( 166 | "--output-format", 167 | choices=["text", "json", "stream-json"], 168 | default="text", 169 | help="Output format for headless mode (default: text)", 170 | ) 171 | parser.add_argument( 172 | "--allowed-tools", 173 | default="Edit,Bash,Write,Read,Glob,Grep,TodoWrite,WebFetch,WebSearch,Task", 174 | help="Comma-separated list of allowed tools", 175 | ) 176 | 177 | args = parser.parse_args() 178 | 179 | # Resolve command path 180 | command_path = resolve_command_path(args.command) 181 | print(f"Invoking: {command_path.relative_to(ROOT)}", file=sys.stderr) 182 | if args.arguments: 183 | print(f"Arguments: {args.arguments}", file=sys.stderr) 184 | print(file=sys.stderr) 185 | 186 | # Invoke command 187 | invoke_command( 188 | command_path=command_path, 189 | arguments=args.arguments, 190 | interactive=args.interactive, 191 | output_format=args.output_format, 192 | allowed_tools=args.allowed_tools, 193 | ) 194 | 195 | 196 | if __name__ == "__main__": 197 | main() 198 | -------------------------------------------------------------------------------- /PRPs/ai_docs/hooks.md: -------------------------------------------------------------------------------- 1 | # Get started with Claude Code hooks 2 | 3 | > Learn how to customize and extend Claude Code's behavior by registering shell commands 4 | 5 | Claude Code hooks are user-defined shell commands that execute at various points 6 | in Claude Code's lifecycle. Hooks provide deterministic control over Claude 7 | Code's behavior, ensuring certain actions always happen rather than relying on 8 | the LLM to choose to run them. 9 | 10 | 11 | For reference documentation on hooks, see [Hooks reference](/en/docs/claude-code/hooks). 12 | 13 | 14 | Example use cases for hooks include: 15 | 16 | - **Notifications**: Customize how you get notified when Claude Code is awaiting 17 | your input or permission to run something. 18 | - **Automatic formatting**: Run `prettier` on .ts files, `gofmt` on .go files, 19 | etc. after every file edit. 20 | - **Logging**: Track and count all executed commands for compliance or 21 | debugging. 22 | - **Feedback**: Provide automated feedback when Claude Code produces code that 23 | does not follow your codebase conventions. 24 | - **Custom permissions**: Block modifications to production files or sensitive 25 | directories. 26 | 27 | By encoding these rules as hooks rather than prompting instructions, you turn 28 | suggestions into app-level code that executes every time it is expected to run. 29 | 30 | 31 | You must consider the security implication of hooks as you add them, because hooks run automatically during the agent loop with your current environment's credentials. 32 | For example, malicious hooks code can exfiltrate your data. Always review your hooks implementation before registering them. 33 | 34 | For full security best practices, see [Security Considerations](/en/docs/claude-code/hooks#security-considerations) in the hooks reference documentation. 35 | 36 | 37 | ## Hook Events Overview 38 | 39 | Claude Code provides several hook events that run at different points in the 40 | workflow: 41 | 42 | - **PreToolUse**: Runs before tool calls (can block them) 43 | - **PostToolUse**: Runs after tool calls complete 44 | - **Notification**: Runs when Claude Code sends notifications 45 | - **Stop**: Runs when Claude Code finishes responding 46 | - **Subagent Stop**: Runs when subagent tasks complete 47 | 48 | Each event receives different data and can control Claude's behavior in 49 | different ways. 50 | 51 | ## Quickstart 52 | 53 | In this quickstart, you'll add a hook that logs the shell commands that Claude 54 | Code runs. 55 | 56 | ### Prerequisites 57 | 58 | Install `jq` for JSON processing in the command line. 59 | 60 | ### Step 1: Open hooks configuration 61 | 62 | Run the `/hooks` [slash command](/en/docs/claude-code/slash-commands) and select 63 | the `PreToolUse` hook event. 64 | 65 | `PreToolUse` hooks run before tool calls and can block them while providing 66 | Claude feedback on what to do differently. 67 | 68 | ### Step 2: Add a matcher 69 | 70 | Select `+ Add new matcher…` to run your hook only on Bash tool calls. 71 | 72 | Type `Bash` for the matcher. 73 | 74 | You can use `*` to match all tools. 75 | 76 | ### Step 3: Add the hook 77 | 78 | Select `+ Add new hook…` and enter this command: 79 | 80 | ```bash 81 | jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt 82 | ``` 83 | 84 | ### Step 4: Save your configuration 85 | 86 | For storage location, select `User settings` since you're logging to your home 87 | directory. This hook will then apply to all projects, not just your current 88 | project. 89 | 90 | Then press Esc until you return to the REPL. Your hook is now registered! 91 | 92 | ### Step 5: Verify your hook 93 | 94 | Run `/hooks` again or check `~/.claude/settings.json` to see your configuration: 95 | 96 | ```json 97 | { 98 | "hooks": { 99 | "PreToolUse": [ 100 | { 101 | "matcher": "Bash", 102 | "hooks": [ 103 | { 104 | "type": "command", 105 | "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt" 106 | } 107 | ] 108 | } 109 | ] 110 | } 111 | } 112 | ``` 113 | 114 | ### Step 6: Test your hook 115 | 116 | Ask Claude to run a simple command like `ls` and check your log file: 117 | 118 | ```bash 119 | cat ~/.claude/bash-command-log.txt 120 | ``` 121 | 122 | You should see entries like: 123 | 124 | ``` 125 | ls - Lists files and directories 126 | ``` 127 | 128 | ## More Examples 129 | 130 | 131 | For a complete example implementation, see the [bash command validator example](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py) in our public codebase. 132 | 133 | 134 | ### Code Formatting Hook 135 | 136 | Automatically format TypeScript files after editing: 137 | 138 | ```json 139 | { 140 | "hooks": { 141 | "PostToolUse": [ 142 | { 143 | "matcher": "Edit|MultiEdit|Write", 144 | "hooks": [ 145 | { 146 | "type": "command", 147 | "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }" 148 | } 149 | ] 150 | } 151 | ] 152 | } 153 | } 154 | ``` 155 | 156 | ### Custom Notification Hook 157 | 158 | Get desktop notifications when Claude needs input: 159 | 160 | ```json 161 | { 162 | "hooks": { 163 | "Notification": [ 164 | { 165 | "matcher": "", 166 | "hooks": [ 167 | { 168 | "type": "command", 169 | "command": "notify-send 'Claude Code' 'Awaiting your input'" 170 | } 171 | ] 172 | } 173 | ] 174 | } 175 | } 176 | ``` 177 | 178 | ### File Protection Hook 179 | 180 | Block edits to sensitive files: 181 | 182 | ```json 183 | { 184 | "hooks": { 185 | "PreToolUse": [ 186 | { 187 | "matcher": "Edit|MultiEdit|Write", 188 | "hooks": [ 189 | { 190 | "type": "command", 191 | "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\"" 192 | } 193 | ] 194 | } 195 | ] 196 | } 197 | } 198 | ``` 199 | 200 | ## Learn more 201 | 202 | - For reference documentation on hooks, see [Hooks reference](/en/docs/claude-code/hooks). 203 | - For comprehensive security best practices and safety guidelines, see [Security Considerations](/en/docs/claude-code/hooks#security-considerations) in the hooks reference documentation. 204 | - For troubleshooting steps and debugging techniques, see [Debugging](/en/docs/claude-code/hooks#debugging) in the hooks reference 205 | documentation. 206 | -------------------------------------------------------------------------------- /.claude/commands/prp-commands/prp-ts-create.md: -------------------------------------------------------------------------------- 1 | # Create TypeScript PRP 2 | 3 | ## Feature: $ARGUMENTS 4 | 5 | ## PRP Creation Mission 6 | 7 | Create a comprehensive TypeScript PRP that enables **one-pass implementation success** through systematic research and context curation. 8 | 9 | **Critical Understanding**: The executing AI agent only receives: 10 | 11 | - Start by reading and understanding the prp concepts PRPs/README.md 12 | - The PRP content you create 13 | - Its training data knowledge 14 | - Access to codebase files (but needs guidance on which ones) 15 | 16 | **Therefore**: Your research and context curation directly determines implementation success. Incomplete context = implementation failure. 17 | 18 | ## Research Process 19 | 20 | > During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. we optminize for chance of success and not for speed. 21 | 22 | 1. **TypeScript/React Codebase Analysis in depth** 23 | - Create clear todos and spawn subagents to search the codebase for similar features/patterns Think hard and plan your approach 24 | - Identify all the necessary TypeScript files to reference in the PRP 25 | - Note all existing TypeScript/React conventions to follow 26 | - Check existing component patterns, hook patterns, and API route patterns 27 | - Analyze TypeScript interface definitions and type usage patterns 28 | - Check existing test patterns for React components and TypeScript code validation approach 29 | - Use the batch tools to spawn subagents to search the codebase for similar features/patterns 30 | 31 | 2. **TypeScript/React External Research at scale** 32 | - Create clear todos and spawn with instructions subagents to do deep research for similar features/patterns online and include urls to documentation and examples 33 | - TypeScript documentation (include specific URLs with version compatibility) 34 | - React/Next.js documentation (include specific URLs for App Router, Server Components, etc.) 35 | - For critical pieces of documentation add a .md file to PRPs/ai_docs and reference it in the PRP with clear reasoning and instructions 36 | - Implementation examples (GitHub/StackOverflow/blogs) specific to TypeScript/React/Next.js 37 | - Best practices and common pitfalls found during research (TypeScript compilation issues, React hydration, Next.js gotchas) 38 | - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples 39 | 40 | 3. **User Clarification** 41 | - Ask for clarification if you need it 42 | 43 | ## PRP Generation Process 44 | 45 | ### Step 1: Choose Template 46 | 47 | Use `PRPs/templates/prp_base_typescript.md` as your template structure - it contains all necessary sections and formatting specific to TypeScript/React development. 48 | 49 | ### Step 2: Context Completeness Validation 50 | 51 | Before writing, apply the **"No Prior Knowledge" test** from the template: 52 | _"If someone knew nothing about this TypeScript/React codebase, would they have everything needed to implement this successfully?"_ 53 | 54 | ### Step 3: Research Integration 55 | 56 | Transform your research findings into the template sections: 57 | 58 | **Goal Section**: Use research to define specific, measurable Feature Goal and concrete Deliverable (component, API route, integration, etc.) 59 | **Context Section**: Populate YAML structure with your research findings - specific TypeScript/React URLs, file patterns, gotchas 60 | **Implementation Tasks**: Create dependency-ordered tasks using information-dense keywords from TypeScript/React codebase analysis 61 | **Validation Gates**: Use TypeScript/React-specific validation commands that you've verified work in this codebase 62 | 63 | ### Step 4: TypeScript/React Information Density Standards 64 | 65 | Ensure every reference is **specific and actionable** for TypeScript development: 66 | 67 | - URLs include section anchors, not just domain names (React docs, TypeScript handbook, Next.js docs) 68 | - File references include specific TypeScript patterns to follow (interfaces, component props, hook patterns) 69 | - Task specifications include exact TypeScript naming conventions and placement (PascalCase components, camelCase props, etc.) 70 | - Validation commands are TypeScript/React-specific and executable (tsc, eslint with TypeScript rules, React Testing Library) 71 | 72 | ### Step 5: ULTRATHINK Before Writing 73 | 74 | After research completion, create comprehensive PRP writing plan using TodoWrite tool: 75 | 76 | - Plan how to structure each template section with your TypeScript/React research findings 77 | - Identify gaps that need additional TypeScript/React research 78 | - Create systematic approach to filling template with actionable TypeScript context 79 | - Consider TypeScript compilation dependencies and React component hierarchies 80 | 81 | ## Output 82 | 83 | Save as: `PRPs/{feature-name}.md` 84 | 85 | ## TypeScript PRP Quality Gates 86 | 87 | ### Context Completeness Check 88 | 89 | - [ ] Passes "No Prior Knowledge" test from TypeScript template 90 | - [ ] All YAML references are specific and accessible (TypeScript/React docs, component examples) 91 | - [ ] Implementation tasks include exact TypeScript naming and placement guidance 92 | - [ ] Validation commands are TypeScript/React-specific and verified working 93 | - [ ] TypeScript interface definitions and component prop types are specified 94 | 95 | ### Template Structure Compliance 96 | 97 | - [ ] All required TypeScript template sections completed 98 | - [ ] Goal section has specific Feature Goal, Deliverable, Success Definition 99 | - [ ] Implementation Tasks follow TypeScript dependency ordering (types → components → pages → tests) 100 | - [ ] Final Validation Checklist includes TypeScript/React-specific validation 101 | 102 | ### TypeScript/React Information Density Standards 103 | 104 | - [ ] No generic references - all are specific to TypeScript/React patterns 105 | - [ ] File patterns include specific TypeScript examples to follow (interfaces, components, hooks) 106 | - [ ] URLs include section anchors for exact TypeScript/React guidance 107 | - [ ] Task specifications use information-dense keywords from TypeScript/React codebase 108 | - [ ] Component patterns specify Server vs Client component usage 109 | - [ ] Type definitions are comprehensive and follow existing patterns 110 | 111 | ## Success Metrics 112 | 113 | **Confidence Score**: Rate 1-10 for one-pass TypeScript implementation success likelihood 114 | 115 | **Quality Standard**: Minimum 8/10 required before PRP approval 116 | 117 | **Validation**: The completed PRP should enable an AI agent unfamiliar with the TypeScript/React codebase to implement the feature successfully using only the PRP content and codebase access, with full type safety and React best practices. 118 | -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md 2 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. 4 | 5 | ## Project Nature 6 | 7 | This is a **PRP (Product Requirement Prompt) Framework** repository, not a traditional software project. The core concept: **"PRP = PRD + curated codebase intelligence + agent/runbook"** - designed to enable AI agents to ship production-ready code on the first pass. 8 | 9 | ## Core Architecture 10 | 11 | ### Command-Driven System 12 | 13 | - **pre-configured Claude Code commands** in `.claude/commands/` 14 | - Commands organized by function: 15 | - `prp-core/` - Core PRP workflow (creation and execution) 16 | - `prp-commands/` - Legacy PRP workflows (story, base, planning variants) 17 | - `development/` - Core development utilities (prime-core, onboarding, debug) 18 | - `code-quality/` - Review and refactoring commands 19 | - `rapid-development/experimental/` - Parallel PRP creation and hackathon tools 20 | - `git-operations/` - Conflict resolution and smart git operations 21 | 22 | ### Template-Based Methodology 23 | 24 | - **PRP Templates** in `PRPs/templates/` follow structured format with validation loops 25 | - **Context-Rich Approach**: Every PRP must include comprehensive documentation, examples, and gotchas 26 | - **Validation-First Design**: Each PRP contains executable validation gates (syntax, tests, integration) 27 | 28 | ### AI Documentation Curation 29 | 30 | - `PRPs/ai_docs/` contains curated Claude Code documentation for context injection 31 | - `claude_md_files/` provides framework-specific CLAUDE.md examples 32 | 33 | ## Development Commands 34 | 35 | ### PRP Execution 36 | 37 | ```bash 38 | # Interactive mode (recommended for development) 39 | uv run PRPs/scripts/prp_runner.py --prp [prp-name] --interactive 40 | 41 | # Headless mode (for CI/CD) 42 | uv run PRPs/scripts/prp_runner.py --prp [prp-name] --output-format json 43 | 44 | # Streaming JSON (for real-time monitoring) 45 | uv run PRPs/scripts/prp_runner.py --prp [prp-name] --output-format stream-json 46 | ``` 47 | 48 | ### Key Claude Commands 49 | 50 | **Core PRP Workflow (Recommended)**: 51 | - `/prp-core-run-all` - Run complete PRP workflow from feature to PR (orchestrates all steps below) 52 | - `/prp-core-new-branch` - Create conventional git branch for feature 53 | - `/prp-core-create` - Create comprehensive feature PRP with deep codebase analysis 54 | - `/prp-core-execute` - Execute feature PRP with sequential validation 55 | - `/prp-core-commit` - Create atomic git commit with validation 56 | - `/prp-core-pr` - Push changes and create PR with comprehensive description 57 | 58 | **Agent Skills**: 59 | - `prp-core-runner` - Autonomous skill that orchestrates the complete PRP workflow when you request to implement features using PRP methodology 60 | 61 | **Legacy PRP Workflows**: 62 | - `/prp-story-create` - Convert user story/task into tactical PRP 63 | - `/prp-story-execute` - Execute story PRP 64 | - `/prp-base-create` - Generate comprehensive PRPs with research 65 | - `/prp-base-execute` - Execute PRPs against codebase 66 | - `/prp-planning-create` - Create planning documents with diagrams 67 | 68 | **Development Utilities**: 69 | - `/prime-core` - Prime Claude with project context 70 | - `/review-staged-unstaged` - Review git changes using PRP methodology 71 | - `/smart-commit` - Analyze changes and create smart git commit 72 | 73 | ## Critical Success Patterns 74 | 75 | ### The PRP Methodology 76 | 77 | 1. **Context is King**: Include ALL necessary documentation, examples, and caveats 78 | 2. **Validation Loops**: Provide executable tests/lints the AI can run and fix 79 | 3. **Information Dense**: Use keywords and patterns from the codebase 80 | 4. **Progressive Success**: Start simple, validate, then enhance 81 | 82 | ### PRP Structure Requirements 83 | 84 | - **Goal**: Specific end state and desires 85 | - **Why**: Business value and user impact 86 | - **What**: User-visible behavior and technical requirements 87 | - **All Needed Context**: Documentation URLs, code examples, gotchas, patterns 88 | - **Implementation Blueprint**: Pseudocode with critical details and task lists 89 | - **Validation Loop**: Executable commands for syntax, tests, integration 90 | 91 | ### Validation Gates (Must be Executable) 92 | 93 | ```bash 94 | # Level 1: Syntax & Style 95 | ruff check --fix && mypy . 96 | 97 | # Level 2: Unit Tests 98 | uv run pytest tests/ -v 99 | 100 | # Level 3: Integration 101 | uv run uvicorn main:app --reload 102 | curl -X POST http://localhost:8000/endpoint -H "Content-Type: application/json" -d '{...}' 103 | 104 | # Level 4: Deployment 105 | # mcp servers, or other creative ways to self validate 106 | ``` 107 | 108 | ## Anti-Patterns to Avoid 109 | 110 | - L Don't create minimal context prompts - context is everything - the PRP must be comprehensive and self-contained, reference relevant documentation and examples. 111 | - L Don't skip validation steps - they're critical for one-pass success - The better The AI is at running the validation loop, the more likely it is to succeed. 112 | - L Don't ignore the structured PRP format - it's battle-tested 113 | - L Don't create new patterns when existing templates work 114 | - L Don't hardcode values that should be config 115 | - L Don't catch all exceptions - be specific 116 | 117 | ## Working with This Framework 118 | 119 | ### When Creating new PRPs 120 | 121 | 1. **Context Process**: New PRPs must consist of context sections, Context is King! 122 | 2. 123 | 124 | ### When Executing PRPs 125 | 126 | 1. **Load PRP**: Read and understand all context and requirements 127 | 2. **ULTRATHINK**: Create comprehensive plan, break down into todos, use subagents, batch tool etc check prps/ai_docs/ 128 | 3. **Execute**: Implement following the blueprint 129 | 4. **Validate**: Run each validation command, fix failures 130 | 5. **Complete**: Ensure all checklist items done 131 | 132 | ### Command Usage 133 | 134 | - Read the .claude/commands directory 135 | - Access via `/` prefix in Claude Code 136 | - Commands are self-documenting with argument placeholders 137 | - Use parallel creation commands for rapid development 138 | - Leverage existing review and refactoring commands 139 | 140 | ## Project Structure Understanding 141 | 142 | ``` 143 | PRPs-agentic-eng/ 144 | .claude/ 145 | commands/ # 28+ Claude Code commands 146 | settings.local.json # Tool permissions 147 | PRPs/ 148 | templates/ # PRP templates with validation 149 | scripts/ # PRP runner and utilities 150 | ai_docs/ # Curated Claude Code documentation 151 | *.md # Active and example PRPs 152 | claude_md_files/ # Framework-specific CLAUDE.md examples 153 | pyproject.toml # Python package configuration 154 | ``` 155 | 156 | Remember: This framework is about **one-pass implementation success through comprehensive context and validation**. Every PRP should contain the exact context for an AI agent to successfully implement working code in a single pass. 157 | -------------------------------------------------------------------------------- /.claude/commands/rapid-development/experimental/create-planning-parallel.md: -------------------------------------------------------------------------------- 1 | # Create PLANNING PRP (Parallel Research) 2 | 3 | Transform rough ideas into comprehensive PRDs using parallel research agents for maximum efficiency and depth. 4 | 5 | ## Idea: $ARGUMENTS 6 | 7 | ## Phase 1: Parallel Research Discovery 8 | 9 | **IMPORTANT**: Execute the following 4 research agents simultaneously using multiple Agent tool calls in a single response to maximize research efficiency. 10 | 11 | ### Research Agent Coordination 12 | 13 | Launch these agents concurrently - do not wait for one to complete before starting the next: 14 | 15 | #### Agent 1: Market Intelligence 16 | ``` 17 | Task: Market Research Analysis 18 | Prompt: Research the market landscape for "$ARGUMENTS". Conduct deep analysis of: 19 | - Competitor landscape and positioning 20 | - Market size, growth trends, and opportunities 21 | - Pricing models and revenue strategies 22 | - Existing solutions and their limitations 23 | - Market gaps and unmet needs 24 | - Target audience and user segments 25 | 26 | Focus purely on research - do not write any code. Use web search extensively. Return a comprehensive market analysis report with specific data points and insights. 27 | ``` 28 | 29 | #### Agent 2: Technical Feasibility 30 | ``` 31 | Task: Technical Architecture Research 32 | Prompt: Analyze technical feasibility for "$ARGUMENTS". Research and evaluate: 33 | - Recommended technology stacks and frameworks 34 | - System architecture patterns and best practices 35 | - Integration possibilities with existing systems 36 | - Scalability and performance considerations 37 | - Technical challenges and solutions 38 | - Development effort estimation 39 | 40 | Focus on research only - no code implementation. Use web search for current best practices. Return technical recommendations with pros/cons analysis. 41 | ``` 42 | 43 | #### Agent 3: User Experience Research 44 | ``` 45 | Task: UX Pattern Analysis 46 | Prompt: Research user experience patterns for "$ARGUMENTS". Investigate: 47 | - User journey mapping and flow examples 48 | - Pain points in existing solutions 49 | - UX best practices and design patterns 50 | - Accessibility standards and requirements 51 | - User interface trends and innovations 52 | - Usability testing insights from similar products 53 | 54 | Research only - no design creation. Use web search for UX case studies. Return UX analysis with actionable recommendations. 55 | ``` 56 | 57 | #### Agent 4: Best Practices & Compliance 58 | ``` 59 | Task: Industry Standards Research 60 | Prompt: Research industry best practices for "$ARGUMENTS". Cover: 61 | - Security standards and compliance requirements 62 | - Data privacy and protection regulations 63 | - Performance benchmarks and KPIs 64 | - Quality assurance methodologies 65 | - Risk management practices 66 | - Legal and regulatory considerations 67 | 68 | Research focus only. Use web search for compliance guides. Return comprehensive best practices guide with specific standards. 69 | ``` 70 | 71 | ## Phase 2: Research Synthesis & Analysis 72 | 73 | Once all agents complete their research, synthesize the findings into: 74 | 75 | ### Market Opportunity Assessment 76 | - Market size and growth potential 77 | - Competitive landscape overview 78 | - Target user segments and personas 79 | - Value proposition differentiation 80 | 81 | ### Technical Architecture Framework 82 | - Recommended technology stack 83 | - System design approach 84 | - Integration strategy 85 | - Scalability plan 86 | 87 | ### User Experience Blueprint 88 | - User journey mapping 89 | - Key interaction patterns 90 | - Accessibility requirements 91 | - Design system recommendations 92 | 93 | ### Implementation Readiness 94 | - Security and compliance checklist 95 | - Risk assessment and mitigation 96 | - Success metrics and KPIs 97 | - Quality gates and validation 98 | 99 | ## Phase 3: User Validation & Requirements Gathering 100 | 101 | ### Critical Questions for User 102 | Before generating the final PRD, ask the user to clarify: 103 | 104 | 1. **Scope & Constraints** 105 | - What's the target timeline? 106 | - Budget or resource constraints? 107 | - Must-have vs nice-to-have features? 108 | 109 | 2. **Success Definition** 110 | - Primary success metrics? 111 | - User adoption goals? 112 | - Business objectives? 113 | 114 | 3. **Technical Context** 115 | - Existing systems to integrate with? 116 | - Technology preferences or restrictions? 117 | - Team expertise and capabilities? 118 | 119 | 4. **User Context** 120 | - Primary user personas? 121 | - Use case priorities? 122 | - Current user pain points? 123 | 124 | ## Phase 4: PRD Generation 125 | 126 | Using the synthesized research and user input, create a comprehensive PRD following this structure: 127 | 128 | ### PRD Output Template 129 | ```markdown 130 | # Product Requirements Document: [Feature Name] 131 | 132 | ## 1. Executive Summary 133 | - Problem statement 134 | - Proposed solution 135 | - Success criteria 136 | - Resource requirements 137 | 138 | ## 2. Market Analysis 139 | [Insert Market Intelligence Agent findings] 140 | - Market opportunity 141 | - Competitive landscape 142 | - User segments 143 | 144 | ## 3. User Experience Design 145 | [Insert UX Research Agent findings] 146 | - User personas and journeys 147 | - Key user flows (with Mermaid diagrams) 148 | - Wireframes and mockups needed 149 | 150 | ## 4. Technical Architecture 151 | [Insert Technical Feasibility Agent findings] 152 | - System architecture (with Mermaid diagrams) 153 | - Technology stack 154 | - Integration points 155 | - Scalability considerations 156 | 157 | ## 5. Security & Compliance 158 | [Insert Best Practices Agent findings] 159 | - Security requirements 160 | - Compliance standards 161 | - Risk assessment 162 | 163 | ## 6. Implementation Plan 164 | - Development phases 165 | - Dependencies and prerequisites 166 | - Timeline estimates 167 | - Resource allocation 168 | 169 | ## 7. Success Metrics 170 | - Key Performance Indicators 171 | - Acceptance criteria 172 | - Testing strategy 173 | 174 | ## 8. Risk Assessment 175 | - Technical risks and mitigation 176 | - Market risks and contingencies 177 | - Resource risks and alternatives 178 | ``` 179 | 180 | ### Required Diagrams (using Mermaid) 181 | Generate these diagrams in the PRD: 182 | 183 | 1. **User Flow Diagram** 184 | ```mermaid 185 | flowchart TD 186 | A[User Entry] --> B{Decision Point} 187 | B -->|Yes| C[Success Path] 188 | B -->|No| D[Alternative Path] 189 | ``` 190 | 191 | 2. **System Architecture Diagram** 192 | ```mermaid 193 | graph TB 194 | Frontend --> API 195 | API --> Database 196 | API --> ExternalService 197 | ``` 198 | 199 | 3. **Implementation Timeline** 200 | ```mermaid 201 | gantt 202 | title Implementation Phases 203 | section Phase 1 204 | Research & Design: 2024-01-01, 2w 205 | section Phase 2 206 | Core Development: 2w 207 | ``` 208 | 209 | ## Phase 5: Save and Handoff 210 | 211 | Save the completed PRD as: `PRPs/{sanitized-feature-name}-prd.md` 212 | 213 | ### Quality Checklist 214 | Before marking complete, verify: 215 | - [ ] All 4 research areas covered comprehensively 216 | - [ ] User validation questions answered 217 | - [ ] Technical architecture clearly defined 218 | - [ ] User flows diagrammed with Mermaid 219 | - [ ] Implementation phases outlined 220 | - [ ] Success metrics defined 221 | - [ ] Security requirements documented 222 | - [ ] Ready for implementation PRP creation 223 | 224 | ### Next Steps 225 | 1. Review PRD with stakeholders 226 | 2. Create implementation PRP using `/prp` command 227 | 3. Begin development planning and sprint creation 228 | 229 | --- 230 | 231 | **Remember**: This command leverages parallel research agents to create comprehensive PRDs 4x faster than sequential research. The quality depends on thorough agent coordination and synthesis of findings. -------------------------------------------------------------------------------- /.claude/commands/typescript/TS-review-general.md: -------------------------------------------------------------------------------- 1 | # General TypeScript/Astro Codebase Review 2 | 3 | Perform a comprehensive review of the entire TypeScript/Astro codebase focusing on architecture, patterns, and best practices. 4 | 5 | Review scope: $ARGUMENTS 6 | 7 | If no specific scope provided, review the entire codebase. 8 | 9 | ## Review Process 10 | 11 | 1. **Codebase Analysis** 12 | - Analyze overall project structure and architecture 13 | - Review component organization and modularity 14 | - Check for consistency across the codebase 15 | - Identify technical debt and improvement opportunities 16 | 17 | 2. **Pattern Consistency** 18 | - Ensure consistent use of Astro patterns 19 | - Validate TypeScript usage across files 20 | - Check for consistent naming conventions 21 | - Review import/export patterns 22 | 23 | 3. **Performance Assessment** 24 | - Evaluate bundle size and optimization 25 | - Review hydration strategy implementation 26 | - Check for unnecessary client-side JavaScript 27 | - Assess image optimization usage 28 | 29 | ## Review Focus Areas 30 | 31 | ### 1. **Architecture & Structure** 32 | - Islands Architecture implementation 33 | - Component organization (static vs interactive) 34 | - Content collections structure 35 | - API routes organization 36 | - Proper separation of concerns 37 | 38 | ### 2. **TypeScript Quality** 39 | - Strict mode compliance across all files 40 | - Type safety and explicit typing 41 | - Interface definitions and exports 42 | - Proper use of Astro's built-in types 43 | - Generic usage and constraints 44 | 45 | ### 3. **Astro-Specific Patterns** 46 | - Hydration directives usage patterns 47 | - Static-first approach implementation 48 | - Server islands configuration 49 | - Content management patterns 50 | - Framework integration consistency 51 | 52 | ### 4. **Performance & Optimization** 53 | - Bundle analysis and optimization 54 | - Image optimization implementation 55 | - Code splitting and lazy loading 56 | - Unnecessary JavaScript elimination 57 | - Hydration strategy effectiveness 58 | 59 | ### 5. **Security & Validation** 60 | - Environment variable management 61 | - Content Security Policy implementation 62 | - Input validation patterns 63 | - API security measures 64 | - Zod schema consistency 65 | 66 | ### 6. **Code Quality Standards** 67 | - Component size limits (200 lines Astro, 500 lines max) 68 | - Function complexity and length 69 | - Code duplication assessment 70 | - Error handling patterns 71 | - Logging and debugging practices 72 | 73 | ### 7. **Testing Coverage** 74 | - Vitest configuration and usage 75 | - Component test coverage 76 | - API route testing 77 | - Integration test quality 78 | - Mock usage patterns 79 | 80 | ### 8. **Dependencies & Tooling** 81 | - pnpm usage compliance 82 | - Dependency management 83 | - Build configuration 84 | - Development tooling setup 85 | - Integration configurations 86 | 87 | ### 9. **Documentation & Maintenance** 88 | - Code documentation quality 89 | - README completeness 90 | - Component prop documentation 91 | - API documentation 92 | - CLAUDE.md updates 93 | 94 | ### 10. **Standards Compliance** 95 | - ESLint configuration and compliance 96 | - Prettier formatting consistency 97 | - TypeScript strict mode adherence 98 | - Build process compliance 99 | - Pre-commit hook effectiveness 100 | 101 | ## Analysis Commands 102 | 103 | Execute these commands to gather comprehensive data: 104 | 105 | ```bash 106 | # Project structure analysis 107 | tree -I 'node_modules|dist|.git' -L 3 108 | 109 | # TypeScript analysis 110 | npx tsc --noEmit --listFiles 111 | 112 | # Bundle analysis 113 | pnpm run build && du -sh dist/ 114 | 115 | # Code quality metrics 116 | rg --stats "client:" --type astro 117 | rg --stats "export interface" --type ts 118 | rg --stats "import type" --type ts 119 | 120 | # Test coverage 121 | pnpm run test:coverage 122 | 123 | # Dependency analysis 124 | pnpm list --depth=0 125 | pnpm audit 126 | ``` 127 | 128 | ## Review Output 129 | 130 | Create a comprehensive review report: 131 | 132 | ```markdown 133 | # TypeScript/Astro Codebase Review #[number] 134 | 135 | ## Executive Summary 136 | [High-level overview of codebase health, architecture quality, and key findings] 137 | 138 | ## Architecture Assessment 139 | 140 | ### 🏗️ Structure Quality: [Grade A-F] 141 | - [Overall architecture assessment] 142 | - [Component organization evaluation] 143 | - [Islands Architecture implementation] 144 | 145 | ### 📊 Metrics 146 | - Total Components: X (.astro: Y, Framework: Z) 147 | - Bundle Size: X MB (JS: Y MB, CSS: Z MB) 148 | - Test Coverage: X% (Target: 80%) 149 | - TypeScript Compliance: X% strict mode 150 | 151 | ## Critical Findings 152 | 153 | ### 🔴 Architecture Issues (Must Fix) 154 | - [Structural problems requiring immediate attention] 155 | - [Performance bottlenecks] 156 | - [Security vulnerabilities] 157 | 158 | ### 🟡 Pattern Inconsistencies (Should Fix) 159 | - [Inconsistent implementations] 160 | - [Suboptimal patterns] 161 | - [Technical debt items] 162 | 163 | ### 🟢 Optimization Opportunities (Consider) 164 | - [Performance improvements] 165 | - [Code quality enhancements] 166 | - [Maintainability improvements] 167 | 168 | ## Quality Assessment 169 | 170 | ### TypeScript Quality: [Grade A-F] 171 | - Type safety compliance 172 | - Interface definitions 173 | - Strict mode adherence 174 | - Generic usage patterns 175 | 176 | ### Astro Patterns: [Grade A-F] 177 | - Hydration strategy implementation 178 | - Static-first approach 179 | - Content management 180 | - Framework integration 181 | 182 | ### Performance Score: [Grade A-F] 183 | - Bundle optimization 184 | - Image optimization 185 | - Hydration efficiency 186 | - Loading performance 187 | 188 | ## Detailed Analysis 189 | 190 | ### Component Analysis 191 | - [Component size distribution] 192 | - [Hydration patterns used] 193 | - [Framework usage breakdown] 194 | - [Reusability assessment] 195 | 196 | ### Security Review 197 | - [Environment variable usage] 198 | - [Input validation patterns] 199 | - [API security measures] 200 | - [Content Security Policy] 201 | 202 | ### Testing Quality 203 | - [Coverage distribution] 204 | - [Test quality assessment] 205 | - [Missing test areas] 206 | - [Mock usage patterns] 207 | 208 | ## Recommendations 209 | 210 | ### Immediate Actions (Next Sprint) 211 | 1. [Priority fixes with specific file references] 212 | 2. [Critical performance improvements] 213 | 3. [Security enhancements] 214 | 215 | ### Medium-term Improvements (Next Month) 216 | 1. [Architecture improvements] 217 | 2. [Code quality enhancements] 218 | 3. [Testing improvements] 219 | 220 | ### Long-term Strategy (Next Quarter) 221 | 1. [Architectural evolution] 222 | 2. [Performance optimization strategy] 223 | 3. [Maintenance improvements] 224 | 225 | ## Best Practices Observed 226 | - [Highlight excellent implementations] 227 | - [Patterns worth replicating] 228 | - [Quality code examples] 229 | 230 | ## Compliance Checklist 231 | - [ ] `astro check` passes project-wide 232 | - [ ] `pnpm run lint` zero warnings 233 | - [ ] `pnpm run build` succeeds 234 | - [ ] `pnpm test` 80%+ coverage 235 | - [ ] All components under size limits 236 | - [ ] No `any` types in codebase 237 | - [ ] Proper hydration directives 238 | - [ ] Environment variables typed 239 | - [ ] Content collections with schemas 240 | - [ ] Security headers implemented 241 | 242 | ## Metrics Dashboard 243 | ``` 244 | Code Quality Score: X/100 245 | ├── TypeScript Quality: X/25 246 | ├── Astro Patterns: X/25 247 | ├── Performance: X/25 248 | └── Testing: X/25 249 | 250 | Technical Debt: X hours estimated 251 | Bundle Size: X MB (Target: <2MB) 252 | Build Time: X seconds 253 | Test Coverage: X% (Target: 80%) 254 | ``` 255 | 256 | ## Next Review 257 | Recommended review frequency: [Monthly/Quarterly] 258 | Focus areas for next review: [Specific areas to monitor] 259 | ``` 260 | 261 | Save report to PRPs/code_reviews/general_review_[YYYY-MM-DD].md -------------------------------------------------------------------------------- /plugins/prp-core/commands/prp-core-run-all.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Run all prp core commands in sequence from feature request to pr 3 | --- 4 | 5 | # PRP Core Complete Workflow 6 | 7 | Feature: $ARGUMENTS 8 | 9 | ## Instructions 10 | 11 | Execute the complete PRP workflow from feature idea to GitHub PR. This workflow uses a mix of subagent delegation (via Task tool) and main agent execution to optimize context usage and performance. 12 | 13 | **CRITICAL**: Follow the delegation strategy exactly as specified. Some steps MUST run in subagents, others MUST run in the main conversation. 14 | 15 | --- 16 | 17 | ### Step 1: Create Branch (SUBAGENT) 🌿 18 | 19 | **Delegation Strategy**: Use Task tool to delegate to subagent. 20 | 21 | **Why subagent**: Branch creation is a simple, isolated task that doesn't require conversation context. 22 | 23 | **Task Tool Invocation**: 24 | ``` 25 | description: "Create conventional git branch" 26 | prompt: "You must execute the slash command /prp-core:prp-core-new-branch with the argument: '$ARGUMENTS' 27 | 28 | Follow ALL instructions in that command exactly: 29 | 1. Check current branch 30 | 2. Generate conventional branch name (feat/, fix/, chore/, etc.) 31 | 3. Handle conflicts with version suffixes if needed 32 | 4. Create and checkout the new branch 33 | 5. Verify creation 34 | 35 | After completion, report ONLY the branch name that was created (no additional text). 36 | 37 | Example output: feat/add-user-auth" 38 | subagent_type: "general-purpose" 39 | ``` 40 | 41 | **Wait for completion**. Capture the branch name from subagent output. 42 | 43 | **Validation**: Verify branch name follows conventional format (prefix/description). 44 | 45 | --- 46 | 47 | ### Step 2: Create PRP (SUBAGENT) 📝 48 | 49 | **Delegation Strategy**: Use Task tool to delegate to subagent. 50 | 51 | **Why subagent**: PRP creation is research-heavy and benefits from isolated context window for codebase analysis. 52 | 53 | **Task Tool Invocation**: 54 | ``` 55 | description: "Generate comprehensive feature PRP" 56 | prompt: "You must execute the slash command /prp-core:prp-core-create with the argument: '$ARGUMENTS' 57 | 58 | This command will guide you through creating a comprehensive Product Requirement Prompt. Follow ALL phases: 59 | 60 | Phase 1: Feature Understanding 61 | - Analyze the feature request thoroughly 62 | - Create user story format 63 | - Assess complexity 64 | 65 | Phase 2: Codebase Intelligence Gathering 66 | - Use specialized agents for pattern recognition 67 | - Analyze project structure 68 | - Identify dependencies and integration points 69 | 70 | Phase 3: External Research & Documentation 71 | - Research relevant libraries and best practices 72 | - Gather documentation with specific anchors 73 | - Identify gotchas and known issues 74 | 75 | Phase 4: Deep Strategic Thinking 76 | - Consider edge cases and design decisions 77 | - Plan for extensibility and maintainability 78 | 79 | Phase 5: PRP Generation 80 | - Output comprehensive PRP file to .claude/PRPs/features/ 81 | 82 | After completion, report the EXACT file path of the created PRP. 83 | 84 | Example output: .claude/PRPs/features/add-user-authentication.md" 85 | subagent_type: "general-purpose" 86 | ``` 87 | 88 | **Wait for completion**. Capture the PRP file path from subagent output. 89 | 90 | **Validation**: 91 | 1. Verify PRP file exists at reported path 92 | 2. Verify file is not empty 93 | 3. Verify it contains required sections (STEP-BY-STEP TASKS, VALIDATION COMMANDS) 94 | 95 | --- 96 | 97 | ### Step 3: Execute PRP (MAIN AGENT) ⚙️ 98 | 99 | **Delegation Strategy**: DO NOT delegate. Execute directly in main conversation using SlashCommand tool. 100 | 101 | **Why main agent**: 102 | - PRP execution is complex and long-running (10-50+ tasks) 103 | - Requires full conversation context and memory 104 | - Needs user interaction capability for clarifications 105 | - Must manage state across many sequential operations 106 | - Benefits from conversation history and continuity 107 | 108 | **Direct Execution**: 109 | 110 | Use the SlashCommand tool to invoke: 111 | ``` 112 | /prp-core:prp-core-execute [PRP-file-path-from-step-2] 113 | ``` 114 | 115 | This will: 116 | 1. Ingest the complete PRP file 117 | 2. Execute every task in STEP-BY-STEP TASKS sequentially 118 | 3. Validate after each task 119 | 4. Fix failures and re-validate before proceeding 120 | 5. Run full validation suite on completion 121 | 6. Move completed PRP to .claude/PRPs/features/completed/ 122 | 123 | **IMPORTANT**: 124 | - Execute this step YOURSELF in the main conversation 125 | - DO NOT use Task tool for this step 126 | - Track progress with TodoWrite 127 | - Don't stop until entire PRP is complete and validated 128 | 129 | **Wait for execution to fully complete** before proceeding to Step 4. 130 | 131 | **Validation**: 132 | 1. All tasks completed 133 | 2. PRP moved to completed/ directory 134 | 3. All validation commands passed 135 | 136 | --- 137 | 138 | ### Step 4: Commit Changes (SUBAGENT) 💾 139 | 140 | **Delegation Strategy**: Use Task tool to delegate to subagent. 141 | 142 | **Why subagent**: Commit creation is isolated and only needs current git state. 143 | 144 | **Task Tool Invocation**: 145 | ``` 146 | description: "Create conventional commit" 147 | prompt: "You must execute the slash command /prp-core:prp-core-commit 148 | 149 | Follow ALL instructions in that command: 150 | 1. Review uncommitted changes with git diff 151 | 2. Check git status 152 | 3. Stage all changes with git add -A 153 | 4. Create commit with conventional format: : 154 | - Types: feat, fix, docs, style, refactor, test, chore 155 | - Present tense, lowercase, ≤50 chars, no period 156 | - NEVER mention Claude Code, Anthropic, or AI 157 | 158 | After completion, report the commit hash and commit message. 159 | 160 | Example output: 161 | Commit: a1b2c3d 162 | Message: feat: add user authentication system" 163 | subagent_type: "general-purpose" 164 | ``` 165 | 166 | **Wait for completion**. Capture commit hash and message. 167 | 168 | **Validation**: Verify commit exists with `git log -1 --oneline`. 169 | 170 | --- 171 | 172 | ### Step 5: Create PR (SUBAGENT) 🚀 173 | 174 | **Delegation Strategy**: Use Task tool to delegate to subagent. 175 | 176 | **Why subagent**: PR creation is isolated and only needs git history. 177 | 178 | **Task Tool Invocation**: 179 | ``` 180 | description: "Push and create GitHub PR" 181 | prompt: "You must execute the slash command /prp-core:prp-core-pr with the title generated from the feature: '$ARGUMENTS' 182 | 183 | Follow ALL instructions in that command: 184 | 1. Check current branch 185 | 2. Review changes with git status and git diff 186 | 3. Push to remote with git push -u origin HEAD 187 | 4. Create GitHub PR using gh pr create with: 188 | - Title: Generated from feature request 189 | - Body: Comprehensive description with summary, changes, type, testing, checklist 190 | 191 | After completion, report the PR URL. 192 | 193 | Example output: https://github.com/Wirasm/PRPs-agentic-eng/pull/15" 194 | subagent_type: "general-purpose" 195 | ``` 196 | 197 | **Wait for completion**. Capture PR URL. 198 | 199 | **Validation**: Verify PR URL is accessible. 200 | 201 | --- 202 | 203 | ## Completion Report 204 | 205 | After all 5 steps complete successfully, provide a comprehensive summary: 206 | 207 | ``` 208 | ✅ PRP Core Workflow Complete 209 | 210 | Branch: [branch-name-from-step-1] 211 | PRP: [prp-file-path-from-step-2] → completed/ 212 | Commit: [commit-hash-from-step-4] - [commit-message] 213 | PR: [pr-url-from-step-5] 214 | 215 | Summary: 216 | - Created conventional git branch 217 | - Generated comprehensive PRP with deep codebase analysis 218 | - Executed all [X] tasks with validation 219 | - Committed changes with conventional format 220 | - Pushed and created GitHub pull request 221 | 222 | The feature is now ready for review! 223 | ``` 224 | 225 | --- 226 | 227 | ## Error Handling 228 | 229 | If any step fails: 230 | 1. **STOP immediately** - do not proceed to next step 231 | 2. Report which step failed and the error message 232 | 3. Provide actionable guidance for fixing the issue 233 | 4. Do NOT attempt automatic retry without user confirmation 234 | 235 | --- 236 | 237 | ## Design Rationale 238 | 239 | **Subagent Delegation (Steps 1, 2, 4, 5)**: 240 | - Simple, isolated tasks 241 | - Don't need conversation context 242 | - Benefit from fresh context windows 243 | - Can run independently 244 | 245 | **Main Agent Execution (Step 3)**: 246 | - Complex, multi-task execution 247 | - Requires conversation continuity 248 | - Needs full context and state management 249 | - May require user interaction 250 | - Long-running operation (10-50+ sequential tasks) 251 | 252 | This hybrid approach optimizes: 253 | - **Context window usage**: Subagents for simple tasks don't pollute main context 254 | - **Performance**: Isolated tasks complete faster in dedicated contexts 255 | - **Reliability**: Complex execution stays in main agent with full capabilities 256 | - **User experience**: Main agent maintains conversation for complex work 257 | -------------------------------------------------------------------------------- /.claude/commands/rapid-development/experimental/create-base-prp-parallel.md: -------------------------------------------------------------------------------- 1 | # Create BASE PRP with Parallel Research 2 | 3 | ## Feature: $ARGUMENTS 4 | 5 | Generate a comprehensive PRP using parallel research agents for maximum context gathering efficiency and depth. This command leverages multiple AI agents working simultaneously to research different aspects of the feature, ensuring comprehensive context is passed to enable self-validation and iterative refinement. 6 | 7 | ## Parallel Research Phase 8 | 9 | **IMPORTANT**: Execute the following 4 research agents simultaneously using multiple Agent tool calls in a single response to maximize research efficiency. 10 | 11 | ### Research Agent Coordination 12 | 13 | Launch these agents concurrently - do not wait for one to complete before starting the next: 14 | 15 | #### Agent 1: Codebase Pattern Analysis 16 | ``` 17 | Task: Codebase Context Research 18 | Prompt: Analyze the codebase for patterns relevant to "$ARGUMENTS". Research and identify: 19 | - Similar features/patterns already implemented in the codebase 20 | - Files that contain relevant examples or patterns to reference 21 | - Existing conventions, architectural patterns, and code styles to follow 22 | - Test patterns and validation approaches used in similar features 23 | - Integration points and dependencies to consider 24 | - File structure and organization patterns to mirror 25 | 26 | Focus on codebase exploration only - do not write code. Use Glob, Grep, and Read tools extensively. Return a comprehensive analysis of existing patterns with specific file paths and code examples to reference in the PRP. 27 | ``` 28 | 29 | #### Agent 2: External Technical Research 30 | ``` 31 | Task: External Technical Research 32 | Prompt: Research external technical resources for "$ARGUMENTS". Investigate: 33 | - Library documentation and API references (include specific URLs) 34 | - Implementation examples from GitHub, StackOverflow, and technical blogs 35 | - Best practices and architectural patterns for similar features 36 | - Common pitfalls, gotchas, and solutions 37 | - Performance considerations and optimization techniques 38 | - Security considerations and vulnerability patterns 39 | 40 | Focus purely on research - do not write code. Use web search extensively. Return comprehensive technical research with specific URLs, code examples, and implementation guidance. 41 | ``` 42 | 43 | #### Agent 3: Testing & Validation Strategy 44 | ``` 45 | Task: Testing Strategy Research 46 | Prompt: Research testing and validation approaches for "$ARGUMENTS". Analyze: 47 | - Test patterns used in the current codebase 48 | - Unit testing strategies and frameworks 49 | - Integration testing approaches 50 | - Validation gates and quality checks 51 | - Error handling and edge case patterns 52 | - Performance testing considerations 53 | 54 | Research only - no test implementation. Use codebase analysis and web search. Return detailed testing strategy with specific patterns to follow and validation commands to include in the PRP. 55 | ``` 56 | 57 | #### Agent 4: Documentation & Context Research 58 | ``` 59 | Task: Documentation Context Research 60 | Prompt: Research documentation and context resources for "$ARGUMENTS". Gather: 61 | - Check PRPs/ai_docs/ for relevant documentation files 62 | - Configuration examples and setup patterns 63 | - Environment and dependency requirements 64 | - Known issues and workarounds documented 65 | - Related feature documentation and examples 66 | - User guides and implementation notes 67 | 68 | Research focus only. Use Read tool to examine ai_docs directory. Return documentation context with specific file references and configuration examples to include in the PRP. 69 | ``` 70 | 71 | ## Research Synthesis & PRP Generation 72 | 73 | Once all agents complete their research, synthesize the findings and generate a comprehensive PRP using the base template structure: 74 | 75 | ### PRP Template Integration 76 | 77 | Using PRPs/templates/prp_base.md as the foundation, integrate the research findings: 78 | 79 | #### Critical Context Integration 80 | From the research agents, include: 81 | - **Codebase Patterns**: Specific file paths and code examples from Agent 1 82 | - **Technical Documentation**: URLs and specific sections from Agent 2 83 | - **Testing Strategies**: Validation approaches and patterns from Agent 3 84 | - **Project Documentation**: Relevant ai_docs and configuration from Agent 4 85 | 86 | #### Implementation Blueprint Enhancement 87 | - Start with pseudocode informed by existing patterns 88 | - Reference real files and patterns discovered in research 89 | - Include error handling strategies from similar implementations 90 | - List tasks in order of completion based on codebase analysis 91 | 92 | #### Context-Rich Validation Gates 93 | ```bash 94 | # Syntax/Style (from codebase analysis) 95 | uv run ruff check . --fix 96 | uv run mypy . 97 | 98 | # Unit Tests (following existing patterns) 99 | uv run pytest tests/ -v 100 | 101 | # Integration Tests (if applicable) 102 | [specific commands found in codebase] 103 | ``` 104 | 105 | ### PRP Generation Process 106 | 107 | 1. **Context Assembly**: Combine all research findings into comprehensive context 108 | 2. **Goal Definition**: Clear, specific end state based on research insights 109 | 3. **Implementation Strategy**: Step-by-step approach using discovered patterns 110 | 4. **Validation Framework**: Executable tests and quality gates 111 | 5. **Integration Planning**: Connection points with existing systems 112 | 113 | ### Required PRP Sections 114 | 115 | Generate a complete PRP including: 116 | 117 | ```yaml 118 | ## Goal 119 | [Specific, measurable outcome based on research] 120 | 121 | ## Why 122 | - Business value and user impact 123 | - Integration with existing features (from codebase analysis) 124 | - Problems this solves and for whom 125 | 126 | ## What 127 | [User-visible behavior and technical requirements] 128 | 129 | ## All Needed Context 130 | ### Documentation & References 131 | - url: [Specific URLs from external research] 132 | - file: [Specific file paths from codebase analysis] 133 | - docfile: [Relevant PRPs/ai_docs/ files] 134 | 135 | ### Current Codebase Context 136 | [Tree structure and relevant files] 137 | 138 | ### Implementation Patterns 139 | [Specific patterns to follow from codebase analysis] 140 | 141 | ### Known Gotchas 142 | [Library quirks and caveats from research] 143 | 144 | ## Implementation Blueprint 145 | ### Data Models and Structure 146 | [Type-safe models following existing patterns] 147 | 148 | ### Task List 149 | [Ordered tasks based on dependency analysis] 150 | 151 | ### Pseudocode 152 | [Implementation approach with critical details] 153 | 154 | ### Integration Points 155 | [Database, config, routes based on existing patterns] 156 | 157 | ## Validation Loop 158 | ### Level 1: Syntax & Style 159 | [Commands specific to this codebase] 160 | 161 | ### Level 2: Unit Tests 162 | [Test patterns from codebase analysis] 163 | 164 | ### Level 3: Integration Tests 165 | [End-to-end validation approach] 166 | 167 | ## Final Validation Checklist 168 | [Comprehensive quality gates] 169 | ``` 170 | 171 | ## Quality Assurance 172 | 173 | Before finalizing the PRP, ensure: 174 | 175 | ### Research Quality 176 | - [ ] All 4 research agents completed successfully 177 | - [ ] Codebase patterns thoroughly analyzed 178 | - [ ] External documentation properly referenced 179 | - [ ] Testing strategies aligned with existing patterns 180 | - [ ] Documentation context comprehensive 181 | 182 | ### PRP Quality 183 | - [ ] All necessary context included from research 184 | - [ ] Validation gates are executable and specific 185 | - [ ] References existing patterns and conventions 186 | - [ ] Clear implementation path with dependencies 187 | - [ ] Error handling documented with examples 188 | - [ ] Integration points clearly defined 189 | 190 | ### Context Completeness 191 | - [ ] Specific file paths and examples included 192 | - [ ] URLs with relevant sections specified 193 | - [ ] Library versions and dependencies noted 194 | - [ ] Configuration examples provided 195 | - [ ] Known issues and workarounds documented 196 | 197 | ## Output 198 | 199 | Save the comprehensive PRP as: `PRPs/{feature-name}-parallel.md` 200 | 201 | ## Success Metrics 202 | 203 | Score the PRP on a scale of 1-10 for: 204 | - **Context Richness**: How much relevant context is included 205 | - **Implementation Clarity**: How clear the implementation path is 206 | - **Validation Completeness**: How comprehensive the testing strategy is 207 | - **One-Pass Success Probability**: Confidence level for successful implementation 208 | 209 | Target: 8+ on all metrics through parallel research depth 210 | 211 | ## Time Efficiency 212 | 213 | This parallel approach reduces PRP creation time by: 214 | - **4x faster research**: Parallel agents vs sequential 215 | - **Better context**: Multiple perspectives simultaneously 216 | - **Reduced iterations**: Comprehensive upfront research 217 | - **Higher success rate**: More thorough preparation 218 | 219 | Remember: The goal is one-pass implementation success through comprehensive parallel research and context gathering. -------------------------------------------------------------------------------- /PRPs/templates/prp_planning.md: -------------------------------------------------------------------------------- 1 | name: "Planning PRP Template - PRD Generation with Diagrams" 2 | description: | 3 | 4 | ## Purpose 5 | Generate comprehensive Product Requirements Documents (PRDs) with visual diagrams, turning rough ideas into detailed specifications ready for implementation PRPs. 6 | 7 | ## Philosophy 8 | 1. **Research First**: Gather context before planning 9 | 2. **Visual Thinking**: Use diagrams to clarify concepts 10 | 3. **Validation Built-in**: Include challenges and edge cases 11 | 4. **Implementation Ready**: Output feeds directly into other PRPs 12 | 13 | --- 14 | 15 | ## Initial Concept 16 | $ARGUMENTS 17 | 18 | ## Planning Process 19 | 20 | ### Phase 1: Idea Expansion & Research 21 | 22 | #### Context Gathering 23 | ```yaml 24 | research_areas: 25 | market_analysis: 26 | - competitors: [Research similar solutions] 27 | - user_needs: [Identify pain points] 28 | - trends: [Current industry directions] 29 | 30 | technical_research: 31 | - existing_solutions: [How others solve this] 32 | - libraries: [Available tools/frameworks] 33 | - patterns: [Common implementation approaches] 34 | 35 | internal_context: 36 | - current_system: [How it works today] 37 | - constraints: [Technical/business limitations] 38 | - integration_points: [What it must work with] 39 | ``` 40 | 41 | #### Initial Exploration 42 | ``` 43 | RESEARCH similar solutions: 44 | - WEB_SEARCH: "{concept} implementation examples" 45 | - WEB_SEARCH: "{concept} best practices" 46 | - WEB_SEARCH: "{concept} architecture patterns" 47 | 48 | ANALYZE existing codebase: 49 | - FIND: Similar features already implemented 50 | - IDENTIFY: Patterns to follow 51 | - NOTE: Technical constraints 52 | ``` 53 | 54 | ### Phase 2: PRD Structure Generation 55 | 56 | #### 1. Executive Summary 57 | ```markdown 58 | ## Problem Statement 59 | [Clear articulation of the problem being solved] 60 | 61 | ## Solution Overview 62 | [High-level description of proposed solution] 63 | 64 | ## Success Metrics 65 | - Metric 1: [Measurable outcome] 66 | - Metric 2: [Measurable outcome] 67 | - KPI: [Key performance indicator] 68 | ``` 69 | 70 | #### 2. User Stories & Scenarios 71 | ```markdown 72 | ## Primary User Flow 73 | \```mermaid 74 | graph LR 75 | A[User Action] --> B{Decision Point} 76 | B -->|Path 1| C[Outcome 1] 77 | B -->|Path 2| D[Outcome 2] 78 | D --> E[Final State] 79 | C --> E 80 | \``` 81 | 82 | ## User Stories 83 | 1. **As a [user type]**, I want to [action] so that [benefit] 84 | - Acceptance Criteria: 85 | - [ ] Criterion 1 86 | - [ ] Criterion 2 87 | - Edge Cases: 88 | - [Edge case 1] 89 | - [Edge case 2] 90 | ``` 91 | 92 | #### 3. System Architecture 93 | ```markdown 94 | ## High-Level Architecture 95 | \```mermaid 96 | graph TB 97 | subgraph "Frontend" 98 | UI[User Interface] 99 | State[State Management] 100 | end 101 | 102 | subgraph "Backend" 103 | API[API Layer] 104 | BL[Business Logic] 105 | DB[(Database)] 106 | end 107 | 108 | subgraph "External" 109 | EXT[External Services] 110 | end 111 | 112 | UI --> API 113 | API --> BL 114 | BL --> DB 115 | BL --> EXT 116 | State --> UI 117 | \``` 118 | 119 | ## Component Breakdown 120 | - **Frontend Components**: 121 | - [Component 1]: [Purpose] 122 | - [Component 2]: [Purpose] 123 | 124 | - **Backend Services**: 125 | - [Service 1]: [Purpose] 126 | - [Service 2]: [Purpose] 127 | 128 | - **Data Models**: 129 | - [Model 1]: [Fields and relationships] 130 | - [Model 2]: [Fields and relationships] 131 | ``` 132 | 133 | #### 4. Technical Specifications 134 | ```markdown 135 | ## API Design 136 | \```mermaid 137 | sequenceDiagram 138 | participant U as User 139 | participant F as Frontend 140 | participant A as API 141 | participant D as Database 142 | participant E as External Service 143 | 144 | U->>F: Initiates Action 145 | F->>A: POST /api/endpoint 146 | A->>D: Query Data 147 | D-->>A: Return Data 148 | A->>E: Call External API 149 | E-->>A: Response 150 | A-->>F: Processed Result 151 | F-->>U: Display Result 152 | \``` 153 | 154 | ## Endpoints 155 | - **POST /api/[resource]** 156 | - Request: `{field1: type, field2: type}` 157 | - Response: `{status: string, data: {...}}` 158 | - Errors: `400 Bad Request`, `401 Unauthorized` 159 | 160 | ## Data Flow 161 | \```mermaid 162 | flowchart TD 163 | A[Input Data] --> B{Validation} 164 | B -->|Valid| C[Processing] 165 | B -->|Invalid| D[Error Response] 166 | C --> E[Transform] 167 | E --> F[Store] 168 | F --> G[Return Success] 169 | \``` 170 | ``` 171 | 172 | #### 5. Implementation Strategy 173 | ```markdown 174 | ## Development Phases 175 | \```mermaid 176 | graph LR 177 | A[Foundation] --> B[Core Features] 178 | B --> C[Integration] 179 | C --> D[Testing] 180 | D --> E[Deployment] 181 | 182 | A -.- F[Database Schema
API Framework
Authentication] 183 | B -.- G[Business Logic
API Endpoints
Basic UI] 184 | C -.- H[External Services
Full UI Integration
Error Handling] 185 | D -.- I[Unit Tests
Integration Tests
Performance Tests] 186 | E -.- J[Documentation
Monitoring
Launch] 187 | \``` 188 | 189 | ## Implementation Priority 190 | 1. **Foundation**: Core infrastructure and setup 191 | 2. **MVP Features**: Minimum viable functionality 192 | 3. **Enhanced Features**: Additional capabilities 193 | 4. **Polish**: Performance, UX improvements 194 | 5. **Production Ready**: Full testing and deployment 195 | ``` 196 | 197 | ### Phase 3: Challenge & Validation 198 | 199 | #### Devil's Advocate Analysis 200 | ```yaml 201 | challenges: 202 | technical_risks: 203 | - risk: "Performance at scale" 204 | mitigation: "Implement caching layer" 205 | 206 | - risk: "Third-party API reliability" 207 | mitigation: "Build fallback mechanisms" 208 | 209 | business_risks: 210 | - risk: "User adoption" 211 | mitigation: "Phased rollout with feedback loops" 212 | 213 | - risk: "Scope creep" 214 | mitigation: "Strict MVP definition" 215 | 216 | edge_cases: 217 | - scenario: "No network connectivity" 218 | handling: "Offline mode with sync" 219 | 220 | - scenario: "Concurrent updates" 221 | handling: "Optimistic locking" 222 | ``` 223 | 224 | #### Success Criteria 225 | ```markdown 226 | ## Definition of Done 227 | - [ ] All user stories implemented 228 | - [ ] Test coverage > 80% 229 | - [ ] Performance benchmarks met 230 | - [ ] Security review passed 231 | - [ ] Documentation complete 232 | 233 | ## Measurable Outcomes 234 | - Metric 1: [Target value] 235 | - Metric 2: [Target value] 236 | - User satisfaction: [Target score] 237 | ``` 238 | 239 | ### Phase 4: Validation & Output 240 | 241 | #### Pre-Implementation Checklist 242 | ``` 243 | VALIDATE assumptions: 244 | - Technical feasibility confirmed 245 | - Resource availability verified 246 | - Dependencies identified 247 | - Risks documented with mitigations 248 | 249 | REVIEW with stakeholders: 250 | - Business alignment confirmed 251 | - Technical approach approved 252 | - Timeline acceptable 253 | - Success metrics agreed 254 | ``` 255 | 256 | #### Output Format 257 | The final PRD should be structured as: 258 | 259 | 1. **Executive Summary** (1 page) 260 | 2. **Detailed Requirements** (with diagrams) 261 | 3. **Technical Architecture** (with diagrams) 262 | 4. **Implementation Plan** (with timeline) 263 | 5. **Appendices** (research, alternatives considered) 264 | 265 | ### Validation Commands 266 | 267 | ```bash 268 | # Verify PRD completeness 269 | grep -E "(TODO|TBD|FIXME)" generated_prd.md 270 | 271 | # Check diagram syntax 272 | mermaid-cli -i generated_prd.md -o prd_diagrams.pdf 273 | 274 | # Validate structure 275 | python validate_prd_structure.py generated_prd.md 276 | ``` 277 | 278 | ## Anti-Patterns to Avoid 279 | - ❌ Vague requirements without acceptance criteria 280 | - ❌ Missing edge cases and error scenarios 281 | - ❌ Diagrams that don't match the text 282 | - ❌ Technical jargon without explanation 283 | - ❌ Unrealistic timelines 284 | - ❌ No success metrics 285 | 286 | ## Success Indicators 287 | - ✅ Another developer could implement from this PRD alone 288 | - ✅ All stakeholders understand the plan 289 | - ✅ Risks are identified with mitigations 290 | - ✅ Clear path from current state to desired state 291 | - ✅ Diagrams clarify rather than confuse 292 | 293 | ## Template Usage Example 294 | 295 | Input: "Build a notification system for our app" 296 | 297 | Output would include: 298 | - User flow diagrams for different notification types 299 | - System architecture showing pub/sub patterns 300 | - Sequence diagrams for real-time delivery 301 | - Database schema for notification preferences 302 | - API specifications for notification endpoints 303 | - Implementation phases and priorities 304 | - Edge cases like offline users, rate limiting 305 | - Success metrics like delivery rate, user engagement 306 | 307 | The resulting PRD becomes the `$ARGUMENTS` input for implementation PRPs like BASE_PRP or SPEC_PRP. --------------------------------------------------------------------------------