claude-autopm 3.1.1 → 3.2.0

package/packages/plugin-pm/commands/pm:epic-decompose.md

@@ -70,6 +70,111 @@ Example:
 **IMPORTANT:** Before executing this command, read and follow:
 - `.claude/rules/datetime.md` - For getting real current date/time
 
+## Agent Selection Strategy
+
+Based on the PRD content and technical requirements, automatically determine which specialized agents should be assigned to tasks.
+
+### Step 1: Analyze PRD for Technology Stack
+
+Read `.claude/prds/$ARGUMENTS.md` and identify:
+- **Programming languages** mentioned (Python, JavaScript/TypeScript, Go, Bash, etc.)
+- **Frameworks** required (React, FastAPI, Next.js, Express, etc.)
+- **Databases** needed (PostgreSQL, MongoDB, Redis, etc.)
+- **Cloud platforms** (AWS, Azure, GCP)
+- **Infrastructure** tools (Docker, Kubernetes, Terraform)
+- **Testing** requirements (unit, integration, E2E)
+- **CI/CD** platforms (GitHub Actions, Azure DevOps, GitLab CI)
+
+### Step 2: Map Technologies to Specialized Agents
+
+**Programming Languages**:
+- Python → `.claude/agents/languages/python-backend-engineer.md`
+- JavaScript/TypeScript/Node.js → `.claude/agents/languages/nodejs-backend-engineer.md`
+- React → `.claude/agents/frontend/react-frontend-engineer.md`
+- Bash/Shell scripting → `.claude/agents/languages/bash-scripting-expert.md`
+
+**Databases**:
+- PostgreSQL → `.claude/agents/databases/postgresql-expert.md`
+- MongoDB → `.claude/agents/databases/mongodb-expert.md`
+- Redis → `.claude/agents/databases/redis-expert.md`
+- Cosmos DB → `.claude/agents/databases/cosmosdb-expert.md`
+
+**Cloud Platforms**:
+- AWS → `.claude/agents/cloud/aws-cloud-architect.md`
+- Azure → `.claude/agents/cloud/azure-cloud-architect.md`
+- GCP → `.claude/agents/cloud/gcp-cloud-architect.md`
+
+**Infrastructure & Containers**:
+- Docker → `.claude/agents/containers/docker-containerization-expert.md`
+- Kubernetes → `.claude/agents/orchestration/kubernetes-orchestrator.md`
+- Terraform → `.claude/agents/infrastructure/terraform-infrastructure-expert.md`
+
+**Testing**:
+- Unit/Integration tests → `.claude/agents/core/test-runner.md`
+- Frontend E2E testing → `.claude/agents/testing/frontend-testing-engineer.md`
+- E2E automation → `.claude/agents/testing/e2e-test-engineer.md`
+
+**DevOps & CI/CD**:
+- GitHub operations → `.claude/agents/devops/github-operations-specialist.md`
+- Azure DevOps → `.claude/agents/devops/azure-devops-specialist.md`
+- Observability → `.claude/agents/devops/observability-engineer.md`
+
+### Step 3: Document Agent Assignments in Epic Frontmatter
+
+Add `required_agents` array to epic.md frontmatter:
+
+```yaml
+---
+name: user-authentication
+prd: user-authentication
+status: backlog
+created: 2025-12-17T10:00:00Z
+updated: 2025-12-17T10:00:00Z
+required_agents:
+  - path: .claude/agents/languages/python-backend-engineer.md
+    role: API implementation
+    tasks: [001, 002, 003]
+  - path: .claude/agents/databases/postgresql-expert.md
+    role: Database schema and migrations
+    tasks: [004, 005]
+  - path: .claude/agents/testing/frontend-testing-engineer.md
+    role: Test suite development
+    tasks: [006, 007]
+  - path: .claude/agents/devops/github-operations-specialist.md
+    role: CI/CD pipeline setup
+    tasks: [008]
+---
+```
+
+### Step 4: Assign Agents to Individual Tasks
+
+Each task file should include `assigned_agent` in frontmatter:
+
+```yaml
+---
+name: Implement JWT authentication endpoints
+status: open
+created: 2025-12-17T10:00:00Z
+updated: 2025-12-17T10:00:00Z
+assigned_agent: .claude/agents/languages/python-backend-engineer.md
+agent_context:
+  framework: fastapi
+  auth_method: jwt
+  libraries: [pyjwt, passlib]
+github: [Will be updated when synced to GitHub]
+depends_on: [004]  # Depends on user schema
+parallel: true
+conflicts_with: []
+---
+```
+
+**Benefits of Agent Assignment**:
+- ✅ Automatic selection of specialized agents based on technology
+- ✅ Clear agent responsibilities per task
+- ✅ Easier task assignment when starting work
+- ✅ Better parallel execution planning with appropriate agents
+- ✅ Consistent expertise application across similar tasks
+
 ## Preflight Checklist
 
 Before proceeding, complete these validation steps.
@@ -139,35 +244,81 @@ You are decomposing epic(s) into specific, actionable tasks for: **$ARGUMENTS**
 - Understand the technical approach and requirements
 - Review the task breakdown preview
 
-### 2. Analyze for Parallel Creation
+### 3. Analyze PRD and Select Agents
+
+**IMPORTANT**: Before creating tasks, determine which specialized agents should be used:
+
+1. **Read the PRD** from `.claude/prds/$ARGUMENTS.md` (or linked PRD in epic frontmatter)
+
+2. **Identify Technology Stack**:
+   - Scan for programming languages (Python, JavaScript, Go, etc.)
+   - Find frameworks (React, FastAPI, Django, Express, etc.)
+   - Note databases (PostgreSQL, MongoDB, Redis, etc.)
+   - Identify cloud platforms (AWS, Azure, GCP)
+   - Check for infrastructure tools (Docker, K8s, Terraform)
+
+3. **Map to Specialized Agents** using the Agent Selection Strategy section above:
+   - **Backend tasks** → `python-backend-engineer` or `nodejs-backend-engineer`
+   - **Frontend tasks** → `react-frontend-engineer` or `javascript-frontend-engineer`
+   - **Database tasks** → `postgresql-expert`, `mongodb-expert`, or `redis-expert`
+   - **Cloud tasks** → `aws-cloud-architect`, `azure-cloud-architect`, or `gcp-cloud-architect`
+   - **Container tasks** → `docker-containerization-expert`
+   - **Orchestration** → `kubernetes-orchestrator`
+   - **IaC tasks** → `terraform-infrastructure-expert`
+   - **Testing** → `test-runner`, `frontend-testing-engineer`, `e2e-test-engineer`
+   - **CI/CD** → `github-operations-specialist` or `azure-devops-specialist`
+
+4. **Update Epic Frontmatter** with `required_agents` array (see Agent Selection Strategy section)
+
+5. **Prepare Agent Assignments** for each task to be created
+
+**Example**:
+```markdown
+Technology Stack Detected:
+- Backend: Python + FastAPI
+- Database: PostgreSQL
+- Testing: pytest
+- Deployment: Docker
+
+Agent Mapping:
+- Tasks 001-003 (API): python-backend-engineer
+- Tasks 004-005 (Database): postgresql-expert
+- Tasks 006-007 (Tests): test-runner
+- Task 008 (Docker): docker-containerization-expert
+```
+
+### 4. Analyze for Parallel Creation
 
 Determine if tasks can be created in parallel:
 - If tasks are mostly independent: Create in parallel using Task agents
 - If tasks have complex dependencies: Create sequentially
 - For best results: Group independent tasks for parallel creation
 
-### 3. Parallel Task Creation (When Possible)
+### 5. Parallel Task Creation (When Possible)
 
-If tasks can be created in parallel, spawn sub-agents:
+If tasks can be created in parallel, spawn sub-agents.
 
-```yaml
-Task:
-  description: "Create task files batch {X}"
-  subagent_type: "general-purpose"
-  prompt: |
-    Create task files for epic: $ARGUMENTS
-
-    Tasks to create:
-    - {list of 3-4 tasks for this batch}
-
-    For each task:
-    1. Create file: .claude/epics/$ARGUMENTS/{number}.md
-    2. Use exact format with frontmatter and all sections
-    3. Follow task breakdown from epic
-    4. Set parallel/depends_on fields appropriately
-    5. Number sequentially (001.md, 002.md, etc.)
-
-    Return: List of files created
+**IMPORTANT**: Do NOT use generic "general-purpose" agents. Task creation should be done directly by Claude Code, not delegated to sub-agents, as it requires careful analysis of PRD, agent selection, and proper frontmatter generation.
+
+**Task Creation Process**:
+1. For each task, determine the appropriate `assigned_agent` based on PRD analysis
+2. Create task file with complete frontmatter including agent assignment
+3. Generate proper task content with all required sections
+4. Ensure sequential numbering (001.md, 002.md, etc.)
+
+**Example Task Creation**:
+```markdown
+Creating task 001 (API endpoint):
+- assigned_agent: .claude/agents/languages/python-backend-engineer.md
+- agent_context: {framework: "fastapi", auth: "jwt"}
+- File: .claude/epics/$ARGUMENTS/001.md
+✓ Created
+
+Creating task 002 (Database schema):
+- assigned_agent: .claude/agents/databases/postgresql-expert.md
+- agent_context: {orm: "sqlalchemy", migrations: "alembic"}
+- File: .claude/epics/$ARGUMENTS/002.md
+✓ Created
 ```
 
 ### 4. Task File Format with Frontmatter
@@ -179,6 +330,11 @@ name: [Task Title]
 status: open
 created: [Current ISO date/time]
 updated: [Current ISO date/time]
+assigned_agent: .claude/agents/{category}/{agent-name}.md  # Specialized agent for this task
+agent_context:  # Optional: Agent-specific configuration
+  framework: [framework_name]
+  language: [language_name]
+  approach: [implementation_approach]
 github: [Will be updated when synced to GitHub]
 depends_on: []  # List of task numbers this depends on, e.g., [001, 002]
 parallel: true  # Can this run in parallel with other tasks?
@@ -245,6 +401,15 @@ Example: `.claude/epics/ecommerce/01-infrastructure/001.md`
 - **status**: Always start with "open" for new tasks
 - **created**: Get REAL current datetime by running: `date -u +"%Y-%m-%dT%H:%M:%SZ"`
 - **updated**: Use the same real datetime as created for new tasks
+- **assigned_agent**: Path to specialized agent file (e.g., `.claude/agents/languages/python-backend-engineer.md`)
+  - Select based on technology stack from PRD
+  - Use most specific agent for the task type
+  - See Agent Selection Strategy section for mapping
+- **agent_context**: Optional object with agent-specific configuration
+  - **framework**: Specific framework being used (e.g., "fastapi", "react", "express")
+  - **language**: Programming language if multiple options (e.g., "python", "typescript")
+  - **approach**: Implementation approach or pattern to use
+  - Add any task-specific parameters the agent needs
 - **github**: Leave placeholder text - will be updated during sync
 - **depends_on**: List task numbers that must complete before this can start (e.g., [001, 002])
 - **parallel**: Set to true if this can run alongside other tasks without conflicts

package/packages/plugin-pm/commands/pm:prd-new.md

@@ -4,11 +4,11 @@ allowed-tools: Bash, Read, Write, LS
 
 # PRD New
 
-Launch interactive brainstorming session for new product requirement document.
+Create new product requirement document - interactively or from existing content.
 
 ## Usage
 ```
-/pm:prd-new <feature_name> [--local]
+/pm:prd-new <feature_name> [options]
 ```
 
 ## Flags
@@ -19,11 +19,72 @@ Launch interactive brainstorming session for new product requirement document.
 : No GitHub/Azure synchronization required
 : Ideal for working offline or without remote provider configured
 
-Example:
+`--content`, `-c`
+: PRD content for non-interactive mode
+: Use `@filepath` to read from file (e.g., `--content @/path/to/draft.md`)
+: Use inline text for short content (e.g., `--content "# My PRD..."`)
+: Skips LLM generation completely
+: Ideal for importing existing PRDs or automated workflows
+
+`--interactive`, `-i`
+: Use interactive terminal prompts (requires interactive terminal)
+: NOT compatible with Claude Code (use default LLM generation instead)
+: Launches traditional brainstorming wizard with readline prompts
+
+`--force`, `-f`
+: Overwrite existing PRD file if it exists
+
+`--priority`, `-p`
+: Set PRD priority (P0/P1/P2/P3, default: P2)
+
+`--timeline`
+: Set PRD timeline (e.g., "Q1 2025")
+
+## Examples
+
+### LLM-assisted generation (default - works in Claude Code)
+```
+/pm:prd-new user-authentication
+```
+
+### Interactive terminal mode (requires interactive terminal)
+```
+/pm:prd-new user-authentication --interactive
+```
+
+### Local mode
 ```
 /pm:prd-new user-authentication --local
 ```
 
+### From existing file
+```
+/pm:prd-new payment-gateway --content @docs/drafts/payment-prd.md
+```
+
+### From clipboard/inline content
+```
+/pm:prd-new api-v2 --content "# API v2 Redesign
+
+## Problem Statement
+Current API has performance issues...
+
+## Goals
+1. Improve response times
+2. Better error handling
+"
+```
+
+### With metadata
+```
+/pm:prd-new critical-fix --content @bug-report.md --priority P0 --timeline "This Sprint"
+```
+
+### Force overwrite
+```
+/pm:prd-new existing-feature --content @updated-prd.md --force
+```
+
 ## Required Documentation Access
 
 **MANDATORY:** Before creating PRDs, query Context7 for best practices:
@@ -42,6 +103,303 @@ Example:
 
 ## Instructions
 
+### Mode Detection
+
+Parse the arguments to detect the mode:
+- If `--interactive` flag is present → **Interactive Terminal Mode**
+- If `--content @<filepath>` is present → **Content from File Mode**
+- If `--content "<text>"` is present → **Content from Inline Text Mode**
+- Otherwise → **LLM-Assisted Generation Mode** (default)
+
+### LLM-Assisted Generation Mode (DEFAULT - works in Claude Code)
+
+#### Phase 0: Codebase Analysis (MANDATORY)
+
+**CRITICAL**: Before creating any PRD, perform comprehensive codebase analysis to prevent duplicate implementations and identify reusable components.
+
+1. **Search for Existing Functionality**
+
+   Use code-analyzer agent to search the entire codebase:
+
+   ```markdown
+   Task:
+     subagent_type: "code-analyzer"
+     description: "Search for existing '<feature_name>' functionality"
+     prompt: |
+       Search the entire codebase for anything related to: <feature_name>
+
+       Search criteria:
+       - Function names containing: <feature_name> (or related terms)
+       - File names related to: <feature_name>
+       - Class/module names similar to: <feature_name>
+       - Comments/documentation mentioning: <feature_name>
+       - Similar patterns or implementations
+       - Related API endpoints or routes
+       - Database models/schemas related to feature
+
+       Return findings in this format:
+
+       ## Existing Implementations Found
+       - File: [path] - [brief description]
+       - Function: [name] - [what it does]
+       - Component: [name] - [purpose]
+
+       ## Similar Patterns
+       - [description of similar functionality]
+
+       ## Recommendation
+       ✅ Safe to create new PRD (no conflicts found)
+       OR
+       ⚠️ Existing functionality detected - review before proceeding
+
+       ## Reusable Components
+       - [list components that can be reused]
+       - [list utilities that apply]
+   ```
+
+2. **Analyze Dependencies and Integration Points**
+
+   Use code-analyzer agent to identify dependencies:
+
+   ```markdown
+   Task:
+     subagent_type: "code-analyzer"
+     description: "Identify dependencies for '<feature_name>'"
+     prompt: |
+       Identify systems that '<feature_name>' would interact with:
+
+       - **Databases**: What tables/collections would be needed?
+       - **APIs**: Which endpoints would be affected/created?
+       - **External Services**: Third-party integrations needed?
+       - **Internal Modules**: Which existing modules would be used?
+       - **Authentication**: Auth/authorization requirements?
+       - **State Management**: Frontend state considerations?
+
+       Return integration points and potential conflicts.
+   ```
+
+3. **Present Findings to User**
+
+   Format the analysis results for user review:
+
+   ```markdown
+   🔍 **Codebase Analysis Results for: <feature_name>**
+   ═══════════════════════════════════════════════════
+
+   ### Existing Implementations
+   [If found, list each with file path and purpose]
+   [If none found: "✅ No existing implementations detected"]
+
+   ### Dependencies Identified
+   [List each dependency type and specific items]
+
+   ### Reusable Components
+   [List components that can be leveraged]
+   [If none: "No directly reusable components found"]
+
+   ### Potential Conflicts
+   [List any naming conflicts, duplicate logic, etc.]
+   [If none: "✅ No conflicts detected"]
+
+   ### Technology Stack Detected
+   - Backend: [detected frameworks]
+   - Frontend: [detected frameworks]
+   - Database: [detected systems]
+   - Testing: [detected tools]
+
+   ───────────────────────────────────────────────────
+
+   ## Recommendation
+
+   Based on this analysis:
+
+   ✅ **OPTION 1: Create New PRD**
+      No conflicts found. Safe to proceed with new feature.
+
+   ⚠️ **OPTION 2: Extend Existing Feature**
+      Similar functionality found at [path]. Consider extending instead.
+
+   🔄 **OPTION 3: Refactor Existing Code**
+      Duplication detected. Consider refactoring before adding new feature.
+
+   ───────────────────────────────────────────────────
+
+   **Next Step**: Review the analysis above and confirm your choice:
+   - To proceed: Continue with PRD creation
+   - To abort: Stop here and investigate findings
+   ```
+
+4. **User Decision Point**
+
+   After presenting findings, ask user to confirm:
+   ```markdown
+   Based on the codebase analysis above, do you want to:
+
+   1. ✅ Proceed with new PRD (no conflicts found)
+   2. 🔍 Investigate existing implementations first
+   3. ❌ Cancel PRD creation
+
+   [Wait for user response before continuing]
+   ```
+
+#### Phase 1: PRD Existence Check
+
+1. **Pre-check**: Verify PRD doesn't already exist
+   ```bash
+   if [ -f .claude/prds/<feature_name>.md ]; then
+     echo "❌ PRD already exists: <feature_name>"
+     echo "💡 Use --force to overwrite or edit: /pm:prd-edit <feature_name>"
+     exit 1
+   fi
+   ```
+
+#### Phase 2: Generate PRD Content
+
+1. **Generate PRD Content**: Create a comprehensive PRD based on:
+   - Feature name: `<feature_name>`
+   - **Codebase analysis findings** from Phase 0 (existing implementations, dependencies, conflicts)
+   - Project context (analyze existing codebase structure)
+   - Technology stack (detect from package.json, requirements.txt, etc.)
+   - Existing patterns (check similar features)
+   - **Reusable components** identified in analysis
+   - **Integration points** from dependency analysis
+
+3. **PRD Structure**: Use this template:
+   ```markdown
+   ---
+   title: <Title Case Feature Name>
+   status: draft
+   priority: <from --priority or P2>
+   created: <current ISO timestamp>
+   author: <from git config or "claude">
+   timeline: <from --timeline or "TBD">
+   ---
+
+   # PRD: <feature_name>
+
+   ## Executive Summary
+   [Brief overview of the feature - 2-3 sentences]
+
+   ## Codebase Analysis
+   ### Existing Implementations
+   [List any existing functionality found during pre-analysis]
+   [If none: "✅ No existing implementations detected"]
+
+   ### Reusable Components
+   [List components that can be leveraged from existing codebase]
+   [If none: "No directly reusable components found"]
+
+   ### Integration Points
+   [List systems this feature will interact with]
+   - Database: [tables/models needed]
+   - APIs: [endpoints affected]
+   - External Services: [third-party integrations]
+   - Internal Modules: [existing modules to use]
+
+   ### Potential Conflicts
+   [List any naming conflicts or duplicate logic concerns]
+   [If none: "✅ No conflicts detected"]
+
+   ## Problem Statement
+   ### Background
+   [Context and why this feature is needed]
+
+   ### Current State
+   [What exists today and its limitations]
+
+   ### Desired State
+   [What the solution will provide]
+
+   ## Target Users
+   [Who will use this feature]
+
+   ### User Personas
+   - **Primary Users**: [Main user segment]
+   - **Secondary Users**: [Additional beneficiaries]
+
+   ### User Stories
+   - As a [user type], I want to [action], so that [benefit]
+   - As a [user type], I want to [action], so that [benefit]
+
+   ## Key Features
+   ### Must Have (P0)
+   - [ ] [Core feature 1]
+   - [ ] [Core feature 2]
+
+   ### Should Have (P1)
+   - [ ] [Important feature 1]
+   - [ ] [Important feature 2]
+
+   ### Nice to Have (P2)
+   - [ ] [Enhancement 1]
+   - [ ] [Enhancement 2]
+
+   ## Success Metrics
+   ### Key Performance Indicators (KPIs)
+   - **Adoption Rate**: [Target percentage]
+   - **User Satisfaction**: [Target score]
+   - **Performance**: [Response time targets]
+   - **Quality**: [Error rate targets]
+
+   ## Technical Requirements
+   ### Architecture Considerations
+   [System components affected, integration points, data flow]
+
+   ### Non-Functional Requirements
+   - **Performance**: [Specific targets]
+   - **Scalability**: [Capacity requirements]
+   - **Security**: [Auth/authorization requirements]
+   - **Reliability**: [Uptime targets]
+
+   ### Dependencies
+   - [External services or APIs]
+   - [Internal systems or components]
+   - [Third-party libraries or tools]
+
+   ## Implementation Plan
+   ### Phase 1: Foundation
+   - [ ] [Initial tasks]
+
+   ### Phase 2: Core Features
+   - [ ] [Main development]
+
+   ### Phase 3: Enhancement
+   - [ ] [Additional features]
+
+   ### Phase 4: Release
+   - [ ] [Final testing and deployment]
+
+   ## Risks and Mitigation
+   ### Technical Risks
+   - **Risk 1**: [Description and mitigation]
+
+   ### Business Risks
+   - **Risk 1**: [Impact and contingency]
+
+   ## Open Questions
+   - [ ] [Question requiring clarification]
+   - [ ] [Question needing stakeholder input]
+
+   ## Appendix
+   ### References
+   - [Related documentation]
+
+   ### Changelog
+   - [timestamp]: Initial PRD created
+   ```
+
+4. **Write PRD File**:
+   ```bash
+   mkdir -p .claude/prds
+   # Use Write tool to create .claude/prds/<feature_name>.md
+   ```
+
+5. **Confirm Success**: Show next steps
+
+### Interactive Terminal Mode (`--interactive`)
+
+**⚠️ WARNING**: This mode requires an interactive terminal and **will NOT work in Claude Code**.
+
 Run `node .claude/scripts/pm/prd-new.js $ARGUMENTS` using the Bash tool and show me the complete output.
 
 This will launch an interactive brainstorming session that will:
@@ -52,4 +410,44 @@ This will launch an interactive brainstorming session that will:
 5. Capture technical considerations
 6. Generate a comprehensive PRD with proper frontmatter
 
-The script handles all validation, creates the necessary directories, and saves the PRD to `.claude/prds/$ARGUMENTS.md`.
+The script handles all validation, creates the necessary directories, and saves the PRD to `.claude/prds/<feature_name>.md`.
+
+### Content from File Mode (`--content @filepath`)
+
+1. Extract the file path from `--content @<filepath>` argument
+2. Use the Read tool to read the source file content
+3. Check if target PRD already exists at `.claude/prds/<feature_name>.md`
+   - If exists and `--force` not provided → Error and stop
+   - If exists and `--force` provided → Continue (will overwrite)
+4. Prepare the PRD content:
+   - If source content starts with `---` (has frontmatter) → Use as-is
+   - If no frontmatter → Add frontmatter with:
+     ```yaml
+     ---
+     title: <feature_name>
+     status: draft
+     priority: <from --priority or P2>
+     created: <current ISO timestamp>
+     author: <from git config or "unknown">
+     timeline: <from --timeline or "TBD">
+     ---
+     ```
+5. Create directory `.claude/prds/` if it doesn't exist (use Bash: `mkdir -p .claude/prds`)
+6. Write the PRD file using the Write tool to `.claude/prds/<feature_name>.md`
+7. Confirm success and show next steps
+
+### Content from Inline Text Mode (`--content "text"`)
+
+Same as file mode, but use the inline text directly instead of reading from file.
+
+## Output
+
+After successful PRD creation, show:
+```
+✅ PRD created: .claude/prds/<feature_name>.md
+
+📋 Next steps:
+  1. Review: /pm:prd-show <feature_name>
+  2. Edit:   /pm:prd-edit <feature_name>
+  3. Parse:  /pm:prd-parse <feature_name>
+```