Add PRP story task template and reorganize PRP commands (#508)

* Reorganize PRP commands and add story task template

- Move PRP commands to dedicated subdirectories
- Add new agent definitions for codebase analysis and library research
- Create story task PRP template for user story implementation
- Rename prp-base.md to prp_base.md for consistency

* Update .claude/agents/library-researcher.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update .claude/commands/prp-claude-code/prp-story-task-create.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update .claude/commands/prp-claude-code/prp-story-task-create.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update PRPs/templates/prp_story_task.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update PRPs/templates/prp_story_task.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

.claude/agents/codebase-analyst.md

@@ -0,0 +1,114 @@
+---
+name: "codebase-analyst"
+description: "Use proactively to find codebase patterns, coding style and team standards. Specialized agent for deep codebase pattern analysis and convention discovery"
+model: "sonnet"
+---
+
+You are a specialized codebase analysis agent focused on discovering patterns, conventions, and implementation approaches.
+
+## Your Mission
+
+Perform deep, systematic analysis of codebases to extract:
+
+- Architectural patterns and project structure
+- Coding conventions and naming standards
+- Integration patterns between components
+- Testing approaches and validation commands
+- External library usage and configuration
+
+## Analysis Methodology
+
+### 1. Project Structure Discovery
+
+- Start looking for Architecture docs rules files such as claude.md, agents.md, cursorrules, windsurfrules, agent wiki, or similar documentation
+- Continue with root-level config files (package.json, pyproject.toml, go.mod, etc.)
+- Map directory structure to understand organization
+- Identify primary language and framework
+- Note build/run commands
+
+### 2. Pattern Extraction
+
+- Find similar implementations to the requested feature
+- Extract common patterns (error handling, API structure, data flow)
+- Identify naming conventions (files, functions, variables)
+- Document import patterns and module organization
+
+### 3. Integration Analysis
+
+- How are new features typically added?
+- Where do routes/endpoints get registered?
+- How are services/components wired together?
+- What's the typical file creation pattern?
+
+### 4. Testing Patterns
+
+- What test framework is used?
+- How are tests structured?
+- What are common test patterns?
+- Extract validation command examples
+
+### 5. Documentation Discovery
+
+- Check for README files
+- Find API documentation
+- Look for inline code comments with patterns
+- Check PRPs/ai_docs/ for curated documentation
+
+## Output Format
+
+Provide findings in structured format:
+
+```yaml
+project:
+  language: [detected language]
+  framework: [main framework]
+  structure: [brief description]
+
+patterns:
+  naming:
+    files: [pattern description]
+    functions: [pattern description]
+    classes: [pattern description]
+
+  architecture:
+    services: [how services are structured]
+    models: [data model patterns]
+    api: [API patterns]
+
+  testing:
+    framework: [test framework]
+    structure: [test file organization]
+    commands: [common test commands]
+
+similar_implementations:
+  - file: [path]
+    relevance: [why relevant]
+    pattern: [what to learn from it]
+
+libraries:
+  - name: [library]
+    usage: [how it's used]
+    patterns: [integration patterns]
+
+validation_commands:
+  syntax: [linting/formatting commands]
+  test: [test commands]
+  run: [run/serve commands]
+```
+
+## Key Principles
+
+- Be specific - point to exact files and line numbers
+- Extract executable commands, not abstract descriptions
+- Focus on patterns that repeat across the codebase
+- Note both good patterns to follow and anti-patterns to avoid
+- Prioritize relevance to the requested feature/story
+
+## Search Strategy
+
+1. Start broad (project structure) then narrow (specific patterns)
+2. Use parallel searches when investigating multiple aspects
+3. Follow references - if a file imports something, investigate it
+4. Look for "similar" not "same" - patterns often repeat with variations
+
+Remember: Your analysis directly determines implementation success. Be thorough, specific, and actionable.

.claude/agents/library-researcher.md

@@ -0,0 +1,108 @@
+---
+name: "library-researcher"
+description: "Use proactively to research external libraries and fetch implementation-critical documentation"
+model: "sonnet"
+---
+
+You are a specialized library research agent focused on gathering implementation-critical documentation.
+
+## Your Mission
+
+Research external libraries and APIs to provide:
+
+- Specific implementation examples
+- API method signatures and patterns
+- Common pitfalls and best practices
+- Version-specific considerations
+
+## Research Strategy
+
+### 1. Official Documentation
+
+- Start with Archon MCP tools and check if we have relevant docs in the database
+- Use the RAG tools to search for relevant documentation, use specific keywords and context in your queries
+- Use websearch and webfetch to search official docs (check package registry for links)
+- Find quickstart guides and API references
+- Identify code examples specific to the use case
+- Note version-specific features or breaking changes
+
+### 2. Implementation Examples
+
+- Search GitHub for real-world usage
+- Find Stack Overflow solutions for common patterns
+- Look for blog posts with practical examples
+- Check the library's test files for usage patterns
+
+### 3. Integration Patterns
+
+- How do others integrate this library?
+- What are common configuration patterns?
+- What helper utilities are typically created?
+- What are typical error handling patterns?
+
+### 4. Known Issues
+
+- Check library's GitHub issues for gotchas
+- Look for migration guides indicating breaking changes
+- Find performance considerations
+- Note security best practices
+
+## Output Format
+
+Structure findings for immediate use:
+
+```yaml
+library: [library name]
+version: [version in use]
+documentation:
+  quickstart: [URL with section anchor]
+  api_reference: [specific method docs URL]
+  examples: [example code URL]
+
+key_patterns:
+  initialization: |
+    [code example]
+
+  common_usage: |
+    [code example]
+
+  error_handling: |
+    [code example]
+
+gotchas:
+  - issue: [description]
+    solution: [how to handle]
+
+best_practices:
+  - [specific recommendation]
+
+save_to_ai_docs: [yes/no - if complex enough to warrant local documentation]
+```
+
+## Documentation Curation
+
+When documentation is complex or critical:
+
+1. Create condensed version in PRPs/ai_docs/{library}\_patterns.md
+2. Focus on implementation-relevant sections
+3. Include working code examples
+4. Add project-specific integration notes
+
+## Search Queries
+
+Effective search patterns:
+
+- "{library} {feature} example"
+- "{library} TypeError site:stackoverflow.com"
+- "{library} best practices {language}"
+- "github {library} {feature} language:{language}"
+
+## Key Principles
+
+- Prefer official docs but verify with real implementations
+- Focus on the specific features needed for the story
+- Provide executable code examples, not abstract descriptions
+- Note version differences if relevant
+- Save complex findings to ai_docs for future reference
+
+Remember: Good library research prevents implementation blockers and reduces debugging time.

.claude/commands/prp-claude-code/prp-claude-code-create.md

@@ -8,7 +8,6 @@ Create a comprehensive PRP that enables **one-pass implementation success** thro
 
 **Critical Understanding**: The executing AI agent only receives:
 
-- Start by reading and understanding the prp concepts PRPs/README.md
 - The PRP content you create
 - Its training data knowledge
 - Access to codebase files (but needs guidance on which ones)

.claude/commands/prp-claude-code/prp-claude-code-execute.md

@@ -9,7 +9,6 @@ PRPs enable working code on the first attempt through:
 - **Context Completeness**: Everything needed, nothing guessed
 - **Progressive Validation**: 4-level gates catch errors early
 - **Pattern Consistency**: Follow existing codebase approaches
-- Read PRPs/README.md to understand PRP concepts
 
 **Your Goal**: Transform the PRP into working code that passes all validation gates.
 

.claude/commands/prp-claude-code/prp-story-task-create.md

@@ -0,0 +1,142 @@
+---
+description: "Convert user story/task into executable PRP with deep codebase analysis"
+---
+
+# Create Story PRP from User Story/Task
+
+## Story/Task: $ARGUMENTS
+
+## Mission
+
+Transform a user story or task into a **tactical implementation PRP** through systematic codebase analysis and task decomposition.
+
+We do not write any code in this step, the goal is to create a detailed context engineered implementation plan for the implementation agent.
+
+**Key Principle**: We must first gather the context about the story/task before proceeding with the analysis.
+
+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.
+
+The contents of the created PRP should encapsulate all the information the agent needs to complete the story/task in one pass.
+
+Remember that subagents will only receive details from you; the user cannot interact with them directly. Therefore, include all relevant context in the subagent prompt and TODO.
+
+Create detailed TODOs and spawn parallel subagents to analyze (use specialized subagents when appropriate).
+
+## Analysis Process
+
+### Phase 1: Story Decomposition
+
+Analyze the story to determine:
+
+- **Story/Task Type**: Feature/Bug/Enhancement/Refactor
+- **Complexity**: Low, Medium, High
+- **Affected Systems**: Which components/services need changes
+
+Get a deep understanding about the story/task before proceeding so that you can effectively guide the rest of the process.
+
+### Phase 2: Codebase Intelligence Gathering
+
+**1. Project Structure Analysis**
+
+- Detect primary language(s) and frameworks
+- Map directory structure and conventions to identify integration points for the story/task
+- Identify service/component boundaries
+- Find configuration files and environment setup
+
+**2. Pattern Recognition**
+
+- Search for similar implementations in codebase
+- Identify coding conventions (naming, structure, error handling) start in CLAUDE.md AGENTS.md or relevant rules files such as .cursorrules
+- Extract common patterns for the story's domain that should be added to the PRP as context for the implementation agent.
+- Note anti-patterns to avoid
+
+**3. Dependency Analysis**
+
+- Catalog external libraries used if relevant to the story/task (check package.json, pyproject.toml, go.mod, etc.)
+- Understand how libraries are integrated
+- 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
+
+**4. Testing Patterns**
+
+- Identify test framework and structure
+- Find similar test examples and test setup
+- Suggest test cases and scenarios
+
+**5. Integration Points**
+
+- Identify files that will need updates
+- Identify if new files needs to be created and where to create them
+- Find router/API registration patterns
+- Understand database/model patterns if relevant
+
+### Phase 3: Think harder about the story and its components.
+
+Really think hard about everything you just learned during the research phases.
+
+### Phase 4: PRP Task Generation
+
+Transform analysis into concrete tasks:
+
+Read and understand the template @PRPs/templates/prp_story_task.md
+
+**Task Rules**:
+
+1. Each task is atomic and independently testable
+2. Tasks are ordered by dependency
+3. Use action verbs that are information dense: CREATE, UPDATE, ADD, REMOVE, REFACTOR, MIRROR
+4. Include specific implementation details from codebase analysis
+5. Every task has an executable validation command
+
+**Task Action Types**:
+
+We use the concept of information dense keywords to describe the action to be taken, below is a guidance.
+But you can use your own words to describe the action to be taken as long as you follow this same principle.
+
+Examples:
+
+- **CREATE**: New files/components
+- **UPDATE**: Modify existing files
+- **ADD**: Insert new functionality into existing code
+- **REMOVE**: Delete deprecated code
+- **REFACTOR**: Restructure without changing behavior
+- **MIRROR**: Mirror existing pattern or functionality that exists elsewhere in the codebase
+
+### Phase 5: Validation Design
+
+For each task, design validation that:
+
+- Can run immediately after task completion
+- Provides clear pass/fail feedback
+- Uses project-specific commands discovered in analysis
+
+## Quality Criteria
+
+### Task Clarity
+
+- [ ] The PRP is clear and concise and follows KISS principle
+- [ ] Each task has clear action and target
+- [ ] Implementation details reference specific patterns
+- [ ] Validation commands are executable
+
+### Context Completeness
+
+- [ ] All necessary patterns identified
+- [ ] External library usage documented
+- [ ] Integration points mapped
+- [ ] External context references populated
+
+### Story Coverage
+
+- [ ] All acceptance criteria addressed
+- [ ] Edge cases considered
+- [ ] Error handling included where needed
+
+## Output
+
+Save as: `PRPs/story_{kebab-case-summary}.md`
+
+## Success Metrics
+
+**Implementation Ready**: Another developer could execute these tasks without additional context
+**Validation Complete**: Every task has at least one working validation command
+**Pattern Consistent**: Tasks follow existing codebase conventions

.claude/commands/prp-claude-code/prp-story-task-execute.md

@@ -0,0 +1,95 @@
+---
+description: "Execute a Story PRP with focused task implementation"
+---
+
+# Execute Story PRP
+
+## PRP File: $ARGUMENTS
+
+## Mission
+
+Execute a story/task PRP through **sequential task completion** with immediate validation.
+
+**Execution Philosophy**: Complete one task, validate it, then move to the next. No task left behind.
+
+## Execution Process
+
+### 1. Load Story PRP
+
+- Read the specified story PRP file
+- Understand the original story intent
+- Review all context references
+- Note validation commands for each task
+
+### 2. Pre-Implementation Check
+
+- Ultrathink about the story intent and task requirements
+- Verify all referenced files exist
+- Check that patterns mentioned are accessible
+- Ensure development environment is ready
+- Run any pre-requisite setup commands
+
+### 3. Task-by-Task Implementation
+
+For each task in the PRP:
+
+**a) Understand Task**
+
+- Read task requirements completely
+- Review referenced patterns
+- Check gotchas and constraints
+
+**b) Implement Task**
+
+- Follow the specified pattern
+- Use the indicated naming conventions
+- Apply the documented approach
+- Handle edge cases mentioned
+
+**c) Validate Immediately**
+
+- Run the task's validation command
+- If validation fails, fix and re-validate
+- Don't proceed until current task passes
+
+**d) Mark Complete**
+
+- Update todo list to track progress
+- Document any deviations if necessary
+
+### 4. Full Validation
+
+After all tasks complete:
+
+- Run the validation gates from PRP
+- Execute comprehensive test suite
+- Verify all acceptance criteria met
+
+### 5. Completion
+
+- Work through completion checklist
+- Ensure story requirements satisfied
+- Move completed PRP to PRPs/completed/ create the folder if it does not exist
+
+## Execution Rules
+
+**Validation Gates**: Each task must pass validation, iterate until passed
+**Pattern Adherence**: Follow existing patterns, don't create new ones
+**No Shortcuts**: Complete all validation steps
+
+## Failure Handling
+
+When a task fails validation:
+
+1. Read the error message carefully
+2. Check the pattern reference again
+3. Validate it by investigating the codebase
+4. Fix and re-validate
+5. If stuck, check similar implementations
+
+## Success Criteria
+
+- Every validation command passes
+- Full test suite green
+- Story acceptance criteria met
+- Code follows project conventions

PRPs/templates/prp_story_task.md

@@ -0,0 +1,178 @@
+---
+name: "Story PRP Template - Task Implementation Focus"
+description: "Template for converting user stories into executable implementation tasks"
+---
+
+## Original Story
+
+Paste in the original story shared by the user below:
+
+```
+[User story/task description from Jira/Linear/etc]
+```
+
+## Story Metadata
+
+**Story Type**: [Feature/Bug/Enhancement/Refactor]
+**Estimated Complexity**: [Low/Medium/High]
+**Primary Systems Affected**: [List of main components/services]
+
+---
+
+## CONTEXT REFERENCES
+
+[Auto-discovered documentation and patterns]
+
+- {file_path} - {Why this pattern/file is relevant}
+- {doc_path} - {Specific sections needed for implementation}
+- {external_url} - {Library documentation or examples}
+
+---
+
+## IMPLEMENTATION TASKS
+
+[Task blocks in dependency order - each block is atomic and testable]
+
+### Guidelines for Tasks
+
+- We are using Information dense keywords to be specific and concise about implementation steps and details.
+- The tasks have to be detailed and specific to ensure clarity and accuracy.
+- The developer who 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.
+### {ACTION} {target_file}:
+
+- {VERB/KEYWORD}: {Specific implementation detail}
+- {PATTERN}: {Existing pattern to follow from codebase}
+- {IMPORTS}: {Required imports or dependencies}
+- {GOTCHA}: {Known issues or constraints to avoid}
+- **VALIDATE**: `{executable validation command}`
+
+### Example Format:
+
+### CREATE services/user_service.py:
+
+- IMPLEMENT: UserService class with async CRUD operations
+- PATTERN: Follow services/product_service.py structure
+- IMPORTS: from models.user import User; from db import get_session
+- GOTCHA: Always use async session context manager
+- **VALIDATE**: ` uv run python -c "from services.user_service import UserService; print('✓ Import successful')"`
+
+### UPDATE api/routes.py:
+
+- ADD: user_router to main router
+- FIND: `app.include_router(product_router)`
+- INSERT: `app.include_router(user_router, prefix="/users", tags=["users"])`
+- **VALIDATE**: `grep -q "user_router" api/routes.py && echo "✓ Router added"`
+
+### ADD tests/
+
+- CREATE: tests/user_service_test.py
+- IMPLEMENT: Test cases for UserService class
+- PATTERN: Follow tests/product_service_test.py structure
+- IMPORTS: from services.user_service import UserService; from models.user import User; from db import get_session
+- GOTCHA: Use async session context manager in tests
+- **VALIDATE**: `uv run python -m pytest tests/user_service_test.py && echo "✓ Tests passed"`
+
+---
+
+## Validation Loop
+
+### Level 1: Syntax & Style (Immediate Feedback)
+
+```bash
+# Run after each file creation - fix before proceeding
+ruff check src/{new_files} --fix     # Auto-format and fix linting issues
+mypy src/{new_files}                 # Type checking with specific files
+ruff format src/{new_files}          # Ensure consistent formatting
+
+# Project-wide validation
+ruff check src/ --fix
+mypy src/
+ruff format src/
+
+# Expected: Zero errors. If errors exist, READ output and fix before proceeding.
+```
+
+### Level 2: Unit Tests (Component Validation)
+
+```bash
+# Test each component as it's created
+uv run pytest src/services/tests/test_{domain}_service.py -v
+uv run pytest src/tools/tests/test_{action}_{resource}.py -v
+
+# Full test suite for affected areas
+uv run pytest src/services/tests/ -v
+uv run pytest src/tools/tests/ -v
+
+# Coverage validation (if coverage tools available)
+uv run pytest src/ --cov=src --cov-report=term-missing
+
+# Expected: All tests pass. If failing, debug root cause and fix implementation.
+```
+
+### Level 3: Integration Testing (System Validation)
+
+```bash
+# Service startup validation
+uv run python main.py &
+sleep 3  # Allow startup time
+
+# Health check validation
+curl -f http://localhost:8000/health || echo "Service health check failed"
+
+# Feature-specific endpoint testing
+curl -X POST http://localhost:8000/{your_endpoint} \
+  -H "Content-Type: application/json" \
+  -d '{"test": "data"}' \
+  | jq .  # Pretty print JSON response
+
+# MCP server validation (if MCP-based)
+# Test MCP tool functionality
+echo '{"method": "tools/call", "params": {"name": "{tool_name}", "arguments": {}}}' | \
+  uv run python -m src.main
+
+# Database validation (if database integration)
+# Verify database schema, connections, migrations
+psql $DATABASE_URL -c "SELECT 1;" || echo "Database connection failed"
+
+# Expected: All integrations working, proper responses, no connection errors
+```
+
+### Level 4: Creative & Domain-Specific Validation
+
+You can use CLI that are installed on the system or MCP servers to extend the validation and self closing loop.
+
+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.
+
+For example:
+
+```bash
+# MCP Server Validation Examples:
+
+# Playwright MCP (for web interfaces)
+playwright-mcp --url http://localhost:8000 --test-user-journey
+
+# Docker MCP (for containerized services)
+docker-mcp --build --test --cleanup
+
+# Database MCP (for data operations)
+database-mcp --validate-schema --test-queries --check-performance
+```
+
+---
+
+## COMPLETION CHECKLIST
+
+- [ ] All tasks completed
+- [ ] Each task validation passed
+- [ ] Full test suite passes
+- [ ] No linting errors
+- [ ] All available validation gates passed
+- [ ] Story acceptance criteria met
+
+---
+
+## Notes
+
+[Any additional context, decisions made, or follow-up items]
+
+<!-- EOF -->