claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-pm/commands/azure/us-list.md

@@ -0,0 +1,202 @@
+---
+allowed-tools: Task, Bash, Read, Write, WebFetch, Glob, Grep
+---
+
+# Azure DevOps User Story List
+
+List and filter User Stories from Azure DevOps project.
+
+**Usage**: `/azure:us-list [--status=<state>] [--assigned-to=<user>] [--sprint=<iteration>]`
+
+**Examples**: 
+- `/azure:us-list` - List all User Stories
+- `/azure:us-list --status=Active` - List active User Stories
+- `/azure:us-list --sprint="Sprint 1"` - List stories in specific sprint
+- `/azure:us-list --assigned-to=me` - List my User Stories
+
+## Required Environment Variables
+
+Ensure `.claude/.env` contains:
+
+```bash
+AZURE_DEVOPS_PAT=<your-pat-token>
+AZURE_DEVOPS_ORG=<your-organization>
+AZURE_DEVOPS_PROJECT=<your-project>
+```
+
+## Required Documentation Access
+
+**MANDATORY:** Before Azure DevOps integration and agile workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/azure-devops/boards` - boards best practices
+- `mcp://context7/agile/user-stories` - user stories best practices
+- `mcp://context7/project-management/work-items` - work items best practices
+- `mcp://context7/agile/sprint-planning` - sprint planning best practices
+
+**Why This is Required:**
+- Ensures adherence to current industry standards and best practices
+- Prevents outdated or incorrect implementation patterns
+- Provides access to latest framework/tool documentation
+- Reduces errors from stale knowledge or assumptions
+
+
+## Instructions
+
+### 1. Parse Arguments
+
+Extract filters from arguments:
+- `--status`: Filter by state (New, Active, Resolved, Closed)
+- `--assigned-to`: Filter by assignee (email or "me")
+- `--sprint`: Filter by iteration path
+- `--area`: Filter by area path
+- `--limit`: Maximum number of results (default: 20)
+
+### 2. Query User Stories
+
+Use azure-devops-specialist agent to execute WIQL query:
+
+```sql
+SELECT [System.Id], 
+       [System.Title], 
+       [System.State],
+       [System.AssignedTo],
+       [Microsoft.VSTS.Common.Priority],
+       [Microsoft.VSTS.Scheduling.StoryPoints],
+       [System.IterationPath]
+FROM workitems
+WHERE [System.WorkItemType] = 'User Story'
+  AND [System.TeamProject] = @project
+  [AND additional filters based on arguments]
+ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.Id] DESC
+```
+
+### 3. Display Format
+
+Present results in a clean table format:
+
+```
+📋 User Stories in Speacher
+
+| ID  | Title                          | Status | Points | Assigned To      | Sprint    | Priority |
+|-----|--------------------------------|--------|--------|------------------|-----------|----------|
+| 34  | Implement user password reset  | New    | 8      | Unassigned      | Backlog   | 2        |
+| 33  | Create user profile page       | Active | 5      | john@example.com | Sprint 1  | 1        |
+| 32  | Add OAuth integration          | Active | 13     | jane@example.com | Sprint 1  | 1        |
+| 31  | Implement search functionality | New    | 8      | Unassigned      | Sprint 2  | 3        |
+
+📊 Summary:
+- Total: 4 User Stories
+- Total Points: 34
+- Active: 2 | New: 2 | Resolved: 0 | Closed: 0
+
+Filters applied: None
+
+💡 Tips:
+- View details: /azure:us-show <id>
+- Edit story: /azure:us-edit <id>
+- Parse into tasks: /azure:us-parse <id>
+- Start work: /azure:us-start <id>
+```
+
+### 4. Status Indicators
+
+Use visual indicators for status:
+- 🆕 New
+- 🔄 Active/In Progress
+- ✅ Resolved
+- 🔒 Closed
+- 🚫 Removed
+
+### 5. Sprint Overview Mode
+
+If `--sprint` is specified, show sprint-specific metrics:
+
+```
+🏃 Sprint 1 User Stories
+
+Progress: ████████░░░░░░░░ 45% (9/20 points)
+
+| ID  | Title                    | Points | Status | Assigned  | Tasks  |
+|-----|--------------------------|--------|--------|-----------|--------|
+| 33  | Create user profile page | 5      | 🔄     | John      | 3/5    |
+| 32  | Add OAuth integration    | 13     | 🔄     | Jane      | 2/8    |
+| 30  | Fix login bug           | 2      | ✅     | Mike      | 5/5    |
+
+Sprint Health:
+- On Track: 2 stories
+- At Risk: 1 story (OAuth integration - only 25% tasks complete)
+- Completed: 1 story
+
+Velocity: 2 points completed, 18 remaining
+Sprint ends in: 5 days
+```
+
+### 6. My Work Mode
+
+If `--assigned-to=me` show personalized view:
+
+```
+👤 My User Stories
+
+Active Work:
+| ID  | Title                    | Points | Sprint   | Tasks | Next Task           |
+|-----|--------------------------|--------|----------|-------|---------------------|
+| 33  | Create user profile page | 5      | Sprint 1 | 3/5   | Implement UI (4h)   |
+
+Backlog:
+| ID  | Title                 | Points | Priority | Sprint   |
+|-----|----------------------|--------|----------|----------|
+| 35  | Add notifications    | 8      | 2        | Sprint 2 |
+| 36  | Implement dashboard  | 5      | 3        | Backlog  |
+
+📊 Your Stats:
+- Active: 1 story (5 points)
+- Backlog: 2 stories (13 points)
+- Completed this sprint: 0
+- Average velocity: 8 points/sprint
+```
+
+### 7. Export Options
+
+Add export capability:
+
+```
+Export options:
+- Save as CSV: Add --export=csv
+- Save as JSON: Add --export=json
+- Save as Markdown: Add --export=md
+
+Results saved to: .claude/azure/exports/us-list-[timestamp].[format]
+```
+
+## Advanced Filters
+
+Support complex queries:
+
+```bash
+# Stories with high priority and no assignee
+/azure:us-list --priority=1 --assigned-to=unassigned
+
+# Stories with specific tags
+/azure:us-list --tags="backend,api"
+
+# Stories modified in last 7 days
+/azure:us-list --modified-since=7d
+
+# Stories with story points >= 8
+/azure:us-list --points=">=8"
+```
+
+## Error Handling
+
+- **No results**: Show helpful message with suggestion to adjust filters
+- **Connection error**: Verify credentials and network
+- **Invalid filter**: Show valid filter options
+
+## Local Cache
+
+Cache results locally for quick access:
+- Cache file: `.claude/azure/cache/us-list.json`
+- Cache duration: 5 minutes
+- Force refresh: Add `--refresh` flag

package/packages/plugin-pm/commands/azure/us-new.md

@@ -0,0 +1,265 @@
+---
+allowed-tools: Task, Bash, Read, Write, Edit, WebFetch, Glob, Grep
+---
+
+# Azure DevOps User Story New
+
+Create a new User Story in Azure DevOps with comprehensive planning and task breakdown.
+
+**Usage**: `/azure:us-new <story-name>`
+
+**Example**: `/azure:us-new user-authentication`
+
+## Required Environment Variables
+
+Ensure `.claude/.env` contains:
+
+```bash
+AZURE_DEVOPS_PAT=<your-pat-token>
+AZURE_DEVOPS_ORG=<your-organization>
+AZURE_DEVOPS_PROJECT=<your-project>
+```
+
+## Preflight Checklist
+
+### Input Validation
+
+1. **Validate story name format:**
+   - Must contain only lowercase letters, numbers, and hyphens
+   - Must start with a letter
+   - No spaces or special characters allowed
+   - If invalid, tell user: "❌ Story name must be kebab-case (lowercase letters, numbers, hyphens only). Examples: user-auth, payment-v2, notification-system"
+
+2. **Check Azure DevOps connectivity:**
+   - Verify PAT token is valid
+   - Verify organization and project exist
+   - If connection fails, provide specific error message
+
+3. **Check for duplicates:**
+   - Search for existing User Stories with similar titles
+   - If found, ask: "⚠️ Similar User Story found: [title]. Continue anyway? (yes/no)"
+
+## Required Documentation Access
+
+**MANDATORY:** Before creating user stories, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/user-stories` - user stories best practices
+- `mcp://context7/agile/invest-criteria` - invest criteria best practices
+- `mcp://context7/azure-devops/user-stories` - user stories best practices
+- `mcp://context7/requirements/writing` - writing best practices
+
+**Why This is Required:**
+- Ensures adherence to current industry standards and best practices
+- Prevents outdated or incorrect implementation patterns
+- Provides access to latest framework/tool documentation
+- Reduces errors from stale knowledge or assumptions
+
+
+## Instructions
+
+**CRITICAL**: This command MUST use the azure-devops-specialist agent for all Azure DevOps operations.
+
+### Command Execution Pattern
+
+```bash
+# Use the Task tool to invoke the azure-devops-specialist agent
+Task(subagent_type="azure-devops-specialist", 
+     description="Create Azure DevOps User Story",
+     prompt="Create a comprehensive User Story in Azure DevOps for: **$ARGUMENTS**
+     
+Follow the complete workflow:
+1. Requirements gathering and discovery
+2. User Story structure creation
+3. Task breakdown and planning
+4. Azure DevOps API integration
+5. Local documentation and confirmation")
+```
+
+### Agent Instructions
+
+You are acting as the azure-devops-specialist agent to create a comprehensive User Story in Azure DevOps for: **$ARGUMENTS**
+
+#### 1. Discovery & Requirements Gathering
+
+Engage in a structured conversation to gather:
+
+- **User perspective**: Who is the user? What do they need?
+- **Business value**: Why is this important?
+- **Acceptance criteria**: How will we know it's done?
+- **Technical considerations**: Any constraints or dependencies?
+- **Scope boundaries**: What's included and excluded?
+
+### 2. User Story Structure
+
+Create the User Story with these components:
+
+#### Title Format
+
+`As a [user type], I want [functionality] so that [benefit]`
+
+#### Description Structure
+
+```markdown
+## Story Overview
+[Brief context and background]
+
+## User Story
+As a [specific user role]
+I want [specific functionality]
+So that [specific business value]
+
+## Acceptance Criteria
+- [ ] Given [context], when [action], then [expected result]
+- [ ] Given [context], when [action], then [expected result]
+- [ ] [Additional criteria as needed]
+
+## Technical Notes
+- [Architecture considerations]
+- [Integration points]
+- [Performance requirements]
+
+## Dependencies
+- [List any blocking dependencies]
+- [Required services or APIs]
+
+## Out of Scope
+- [What we're explicitly NOT doing in this story]
+
+## Definition of Done
+- [ ] Code complete and reviewed
+- [ ] Unit tests written and passing
+- [ ] Integration tests passing
+- [ ] Documentation updated
+- [ ] Deployed to staging environment
+- [ ] Product Owner acceptance
+```
+
+### 3. Task Breakdown
+
+Automatically create child Tasks for the User Story:
+
+#### Standard Task Template
+
+Each User Story should have these tasks at minimum:
+
+1. **Technical Design** - Create technical design document
+2. **Implementation** - Core functionality development
+3. **Unit Tests** - Write and pass unit tests
+4. **Integration Tests** - Write and pass integration tests
+5. **Documentation** - Update relevant documentation
+6. **Code Review** - Peer review and feedback incorporation
+7. **Testing** - Manual testing and bug fixes
+8. **Deployment** - Deploy to staging/production
+
+#### Additional Tasks Based on Story Type
+
+- **Frontend Stories**: UI/UX design, responsive testing, accessibility
+- **Backend Stories**: API design, database schema, performance testing
+- **Infrastructure Stories**: Security review, monitoring setup, scaling tests
+
+#### 4. Azure DevOps Integration
+
+Execute the Azure DevOps API operations:
+
+1. **Create User Story Work Item:**
+
+   ```bash
+   # Example API call structure
+   POST https://dev.azure.com/{org}/{project}/_apis/wit/workitems/$User Story?api-version=7.0
+   
+   [
+     {
+       "op": "add",
+       "path": "/fields/System.Title",
+       "value": "[Story Title]"
+     },
+     {
+       "op": "add",
+       "path": "/fields/System.Description",
+       "value": "[Full Description with Markdown]"
+     },
+     {
+       "op": "add",
+       "path": "/fields/Microsoft.VSTS.Common.AcceptanceCriteria",
+       "value": "[Acceptance Criteria]"
+     },
+     {
+       "op": "add",
+       "path": "/fields/System.Tags",
+       "value": "[Relevant Tags]"
+     }
+   ]
+   ```
+
+2. **Create Child Tasks:**
+   - Each task linked as child to the User Story
+   - Estimated hours for each task
+   - Proper assignment if team members are known
+
+3. **Set Metadata:**
+   - Area Path: Based on project structure
+   - Iteration Path: Current or next sprint
+   - Priority: Based on discussion
+   - Story Points: Estimated complexity
+
+### 5. Local Documentation
+
+Save a local copy to: `.claude/azure/user-stories/$ARGUMENTS.md` with:
+
+```markdown
+---
+azure_id: [Work Item ID from Azure DevOps]
+name: $ARGUMENTS
+type: user-story
+status: new
+created: [Current ISO date/time]
+story_points: [Estimated points]
+sprint: [Target sprint]
+---
+
+# User Story: $ARGUMENTS
+
+## Azure DevOps Details
+- **Work Item ID**: [ID]
+- **URL**: https://dev.azure.com/{org}/{project}/_workitems/edit/[ID]
+- **Status**: New
+- **Assigned To**: [Assignee if known]
+
+[Rest of the User Story content...]
+
+## Tasks
+1. [Task Title] - ID: [Azure Task ID] - [Estimated Hours]h
+2. [Task Title] - ID: [Azure Task ID] - [Estimated Hours]h
+[...]
+```
+
+### 6. Success Confirmation
+
+After creation:
+
+1. Provide Azure DevOps Work Item URL
+2. Show summary of User Story and Tasks created
+3. Display total estimated hours
+4. Suggest next steps:
+   - "✅ User Story created with [N] tasks"
+   - "📋 View in Azure DevOps: [URL]"
+   - "🚀 Ready to start? Run: /azure:us-start $ARGUMENTS"
+
+## Error Handling
+
+- If Azure DevOps API fails: Retry with exponential backoff
+- If authentication fails: Guide user to refresh PAT token
+- If project not found: List available projects
+- Always save local backup before API calls
+
+## Quality Gates
+
+Before creating in Azure DevOps, verify:
+
+- [ ] Story follows "As a... I want... So that..." format
+- [ ] At least 3 acceptance criteria defined
+- [ ] All standard tasks included
+- [ ] Story points estimated
+- [ ] Dependencies identified
+- [ ] Definition of Done included

package/packages/plugin-pm/commands/azure/us-parse.md

@@ -0,0 +1,253 @@
+---
+allowed-tools: Task, Bash, Read, Write, Edit, WebFetch, Glob, Grep
+---
+
+# Azure DevOps User Story Parse
+
+Parse a User Story into Tasks with automatic creation in Azure DevOps.
+
+**Usage**: `/azure:us-parse <user-story-id>`
+
+**Example**: `/azure:us-parse 34`
+
+## Required Environment Variables
+
+Ensure `.claude/.env` contains:
+
+```bash
+AZURE_DEVOPS_PAT=<your-pat-token>
+AZURE_DEVOPS_ORG=<your-organization>
+AZURE_DEVOPS_PROJECT=<your-project>
+```
+
+## Preflight Checklist
+
+### Input Validation
+
+1. **Validate User Story ID:**
+   - Must be a valid number
+   - If invalid, tell user: "❌ Invalid User Story ID. Please provide a numeric ID."
+
+2. **Verify User Story exists:**
+   - Fetch User Story from Azure DevOps
+   - If not found, tell user: "❌ User Story #$ARGUMENTS not found in Azure DevOps"
+   - If found, display title and current status
+
+3. **Check for existing Tasks:**
+   - Query for child Tasks of this User Story
+   - If Tasks exist, ask: "⚠️ User Story already has [N] tasks. Create additional tasks? (yes/no)"
+
+## Required Documentation Access
+
+**MANDATORY:** Before Azure DevOps integration and agile workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/azure-devops/boards` - boards best practices
+- `mcp://context7/agile/user-stories` - user stories best practices
+- `mcp://context7/project-management/work-items` - work items best practices
+- `mcp://context7/agile/sprint-planning` - sprint planning best practices
+
+**Why This is Required:**
+- Ensures adherence to current industry standards and best practices
+- Prevents outdated or incorrect implementation patterns
+- Provides access to latest framework/tool documentation
+- Reduces errors from stale knowledge or assumptions
+
+
+## Instructions
+
+### 1. Fetch User Story Details
+
+Use azure-devops-specialist agent to:
+- Get User Story title, description, and acceptance criteria
+- Analyze the content to identify required tasks
+- Check story points for complexity assessment
+
+### 2. Analyze and Generate Tasks
+
+Based on User Story analysis, generate tasks:
+
+#### Standard Task Set
+
+Every User Story should have these core tasks:
+
+1. **Technical Design** (2-4h)
+   - Create technical approach document
+   - Define interfaces and data models
+   - Review with team
+
+2. **Implementation** (8-16h based on complexity)
+   - Core functionality development
+   - Unit tests creation
+   - Self-review
+
+3. **Integration Testing** (4-8h)
+   - Integration test development
+   - End-to-end testing
+   - Bug fixes
+
+4. **Documentation** (2-4h)
+   - Code documentation
+   - API documentation if applicable
+   - Update README/wiki
+
+5. **Code Review** (2h)
+   - Peer review
+   - Address feedback
+   - Final approval
+
+6. **Deployment Preparation** (2h)
+   - Configuration updates
+   - Migration scripts if needed
+   - Deployment checklist
+
+#### Context-Specific Tasks
+
+Analyze the User Story to add specific tasks:
+
+**For "password reset" example:**
+- Design email template (2h)
+- Implement token generation (4h)
+- Create reset UI components (6h)
+- Add security logging (2h)
+- Configure email service (2h)
+
+**For API stories:**
+- Define OpenAPI spec (2h)
+- Create API endpoints (8h)
+- Add rate limiting (2h)
+- Generate client SDK (2h)
+
+**For UI stories:**
+- Create mockups/wireframes (4h)
+- Implement components (8h)
+- Add responsive design (4h)
+- Accessibility testing (2h)
+
+### 3. Task Creation Process
+
+Use azure-devops-specialist agent to create each task:
+
+```json
+{
+  "op": "add",
+  "path": "/fields/System.Title",
+  "value": "[Task Title]"
+},
+{
+  "op": "add",
+  "path": "/fields/System.Description",
+  "value": "[Task Description]"
+},
+{
+  "op": "add",
+  "path": "/fields/Microsoft.VSTS.Scheduling.RemainingWork",
+  "value": [Hours]
+},
+{
+  "op": "add",
+  "path": "/relations/-",
+  "value": {
+    "rel": "System.LinkTypes.Hierarchy-Reverse",
+    "url": "https://dev.azure.com/{org}/{project}/_apis/wit/workItems/{parent_id}"
+  }
+}
+```
+
+### 4. Task Organization
+
+Group tasks by phase:
+- **Analysis & Design**: Technical design, mockups, API specs
+- **Development**: Implementation, unit tests
+- **Testing**: Integration tests, user testing
+- **Finalization**: Documentation, review, deployment
+
+### 5. Output Format
+
+After parsing and creating tasks:
+
+```
+✅ User Story #$ARGUMENTS parsed successfully!
+
+📋 User Story: [Title]
+Story Points: [N]
+
+📝 Created Tasks:
+
+Analysis & Design:
+  ✓ Task #101: Technical Design (4h)
+  ✓ Task #102: Create mockups (2h)
+
+Development:
+  ✓ Task #103: Implementation (12h)
+  ✓ Task #104: Unit tests (4h)
+
+Testing:
+  ✓ Task #105: Integration testing (6h)
+  ✓ Task #106: User acceptance testing (2h)
+
+Finalization:
+  ✓ Task #107: Documentation (3h)
+  ✓ Task #108: Code review (2h)
+  ✓ Task #109: Deployment prep (2h)
+
+📊 Summary:
+- Total Tasks: 9
+- Total Hours: 37h
+- Ready for sprint planning
+
+🔗 View in Azure DevOps:
+https://dev.azure.com/{org}/{project}/_workitems/edit/{story_id}
+
+🚀 Next steps:
+- Assign tasks to team members: /azure:task-assign
+- Start work on first task: /azure:task-start [task-id]
+- View task board: /azure:task-list {story_id}
+```
+
+### 6. Smart Parsing Features
+
+#### Acceptance Criteria Analysis
+- Each acceptance criterion → potential task
+- Group related criteria into single tasks
+- Identify testing tasks from criteria
+
+#### Complexity-Based Hours
+- Simple story (1-3 points): 20-30h total
+- Medium story (5-8 points): 30-50h total  
+- Complex story (13+ points): 50-80h total
+
+#### Dependency Detection
+- Identify tasks that block others
+- Set predecessor/successor relationships
+- Flag external dependencies
+
+## Error Handling
+
+- **API failures**: Retry with exponential backoff
+- **Partial success**: Report created tasks, list failures
+- **Invalid story**: Provide guidance on story structure
+
+## Local Tracking
+
+Save parsing results to `.claude/azure/parsed/{story_id}.md`:
+
+```markdown
+# Parsed: User Story #[ID]
+
+Date: [ISO timestamp]
+Title: [Story Title]
+
+## Created Tasks
+| ID | Title | Hours | Status |
+|----|-------|-------|--------|
+| 101 | Technical Design | 4h | New |
+| 102 | Implementation | 12h | New |
+...
+
+## Parsing Rules Applied
+- Standard task set: Yes
+- API-specific tasks: No
+- UI-specific tasks: Yes
+- Total hours: 37h
+```