claude-autopm 2.8.2 → 2.8.3

package/packages/plugin-pm/commands/epic-merge.md

@@ -0,0 +1,222 @@
+---
+allowed-tools: Bash, Read, Write
+---
+
+# Epic Merge
+
+Merge completed epic branch back to main branch.
+
+## Usage
+```
+/pm:epic-merge <epic_name>
+```
+
+## Required Documentation Access
+
+**MANDATORY:** Before project management workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/epic-management` - epic management best practices
+- `mcp://context7/project-management/issue-tracking` - issue tracking best practices
+- `mcp://context7/agile/task-breakdown` - task breakdown best practices
+- `mcp://context7/project-management/workflow` - workflow 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
+
+
+## Quick Check
+
+1. **Verify branch exists:**
+   ```bash
+   git branch -a | grep "epic/$ARGUMENTS" || echo "❌ No branch for epic: $ARGUMENTS"
+   ```
+
+2. **Check for active agents:**
+   Read `.claude/epics/$ARGUMENTS/execution-status.md`
+   If active agents exist: "⚠️ Active agents detected. Stop them first with: /pm:epic-close $ARGUMENTS"
+
+## Instructions
+
+### 1. Pre-Merge Validation
+
+Check out branch and check status:
+```bash
+git checkout epic/$ARGUMENTS
+git pull origin epic/$ARGUMENTS
+
+# Check for uncommitted changes
+if [[ $(git status --porcelain) ]]; then
+  echo "⚠️ Uncommitted changes in branch:"
+  git status --short
+  echo "Commit or stash changes before merging"
+  exit 1
+fi
+
+# Check branch status
+git fetch origin
+git status -sb
+```
+
+### 2. Run Tests (Optional but Recommended)
+
+```bash
+# Look for test commands
+if [ -f package.json ]; then
+  npm test || echo "⚠️ Tests failed. Continue anyway? (yes/no)"
+elif [ -f Makefile ]; then
+  make test || echo "⚠️ Tests failed. Continue anyway? (yes/no)"
+fi
+```
+
+### 3. Update Epic Documentation
+
+Get current datetime: `date -u +"%Y-%m-%dT%H:%M:%SZ"`
+
+Update `.claude/epics/$ARGUMENTS/epic.md`:
+- Set status to "completed"
+- Update completion date
+- Add final summary
+
+### 4. Attempt Merge
+
+```bash
+# Ensure main is up to date
+git checkout main
+git pull origin main
+
+# Attempt merge
+echo "Merging epic/$ARGUMENTS to main..."
+git merge epic/$ARGUMENTS --no-ff -m "Merge epic: $ARGUMENTS
+
+Completed features:
+$(cd .claude/epics/$ARGUMENTS && ls *.md | grep -E '^[0-9]+' | while read f; do
+  echo "- $(grep '^name:' $f | cut -d: -f2)"
+done)
+
+Closes epic #$(grep 'github:' .claude/epics/$ARGUMENTS/epic.md | grep -oE '#[0-9]+')"
+```
+
+### 5. Handle Merge Conflicts
+
+If merge fails with conflicts:
+```bash
+# Check conflict status
+git status
+
+echo "
+❌ Merge conflicts detected!
+
+Conflicts in:
+$(git diff --name-only --diff-filter=U)
+
+Options:
+1. Resolve manually:
+   - Edit conflicted files
+   - git add {files}
+   - git commit
+   
+2. Abort merge:
+   git merge --abort
+   
+3. Get help:
+   /pm:epic-close $ARGUMENTS
+
+Branch preserved at: epic/$ARGUMENTS
+"
+exit 1
+```
+
+### 6. Post-Merge Cleanup
+
+If merge succeeds:
+```bash
+# Push to remote
+git push origin main
+
+# Delete branch
+git branch -d epic/$ARGUMENTS
+git push origin --delete epic/$ARGUMENTS 2>/dev/null || true
+
+# Archive epic locally
+mkdir -p .claude/epics/archived/
+mv .claude/epics/$ARGUMENTS .claude/epics/archived/
+echo "✅ Epic archived: .claude/epics/archived/$ARGUMENTS"
+```
+
+### 7. Update GitHub Issues
+
+Close related issues:
+```bash
+# Get issue numbers from epic
+epic_issue=$(grep 'github:' .claude/epics/archived/$ARGUMENTS/epic.md | grep -oE '[0-9]+$')
+
+# Close epic issue
+gh issue close $epic_issue -c "Epic completed and merged to main"
+
+# Close task issues
+for task_file in .claude/epics/archived/$ARGUMENTS/[0-9]*.md; do
+  issue_num=$(grep 'github:' $task_file | grep -oE '[0-9]+$')
+  if [ ! -z "$issue_num" ]; then
+    gh issue close $issue_num -c "Completed in epic merge"
+  fi
+done
+```
+
+### 8. Final Output
+
+```
+✅ Epic Merged Successfully: $ARGUMENTS
+
+Summary:
+  Branch: epic/$ARGUMENTS → main
+  Commits merged: {count}
+  Files changed: {count}
+  Issues closed: {count}
+  
+Cleanup completed:
+  ✓ Worktree removed
+  ✓ Branch deleted
+  ✓ Epic archived
+  ✓ GitHub issues closed
+  
+Next steps:
+  - Deploy changes if needed
+  - Start new epic: /pm:prd-new {feature}
+  - View completed work: git log --oneline -20
+```
+
+## Conflict Resolution Help
+
+If conflicts need resolution:
+```
+The epic branch has conflicts with main.
+
+This typically happens when:
+- Main has changed since epic started
+- Multiple epics modified same files
+- Dependencies were updated
+
+To resolve:
+1. Open conflicted files
+2. Look for <<<<<<< markers
+3. Choose correct version or combine
+4. Remove conflict markers
+5. git add {resolved files}
+6. git commit
+7. git push
+
+Or abort and try later:
+  git merge --abort
+```
+
+## Important Notes
+
+- Always check for uncommitted changes first
+- Run tests before merging when possible
+- Use --no-ff to preserve epic history
+- Archive epic data instead of deleting
+- Close GitHub issues to maintain sync

package/packages/plugin-pm/commands/epic-oneshot.md

@@ -0,0 +1,119 @@
+---
+allowed-tools: Read, LS
+---
+
+# Epic Oneshot
+
+Decompose epic into tasks and sync to GitHub in one operation.
+
+## Usage
+```
+/pm:epic-oneshot <feature_name>
+```
+
+## ⚠️ TDD REMINDER
+
+**CRITICAL: All tasks generated will include TDD requirements.**
+
+This command will create tasks that REQUIRE Test-Driven Development:
+- Each task includes TDD Requirements section
+- Definition of Done starts with "Tests written FIRST"
+- All agents must follow RED-GREEN-REFACTOR cycle
+
+See `.claude/rules/tdd.enforcement.md` for complete requirements.
+
+---
+
+## Required Documentation Access
+
+**MANDATORY:** Before project management workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/epic-management` - epic management best practices
+- `mcp://context7/project-management/issue-tracking` - issue tracking best practices
+- `mcp://context7/agile/task-breakdown` - task breakdown best practices
+- `mcp://context7/project-management/workflow` - workflow 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. Validate Prerequisites
+
+Check that epic exists and hasn't been processed:
+```bash
+# Epic must exist
+test -f .claude/epics/$ARGUMENTS/epic.md || echo "❌ Epic not found. Run: /pm:prd-parse $ARGUMENTS"
+
+# Check for existing tasks
+if ls .claude/epics/$ARGUMENTS/[0-9]*.md 2>/dev/null | grep -q .; then
+  echo "⚠️ Tasks already exist. This will create duplicates."
+  echo "Delete existing tasks or use /pm:epic-sync instead."
+  exit 1
+fi
+
+# Check if already synced
+if grep -q "github:" .claude/epics/$ARGUMENTS/epic.md; then
+  echo "⚠️ Epic already synced to GitHub."
+  echo "Use /pm:epic-sync to update."
+  exit 1
+fi
+```
+
+### 2. Execute Decompose
+
+Simply run the decompose command:
+```
+Running: /pm:epic-decompose $ARGUMENTS
+```
+
+This will:
+- Read the epic
+- Create task files (using parallel agents if appropriate)
+- Update epic with task summary
+
+### 3. Execute Sync
+
+Immediately follow with sync:
+```
+Running: /pm:epic-sync $ARGUMENTS
+```
+
+This will:
+- Create epic issue on GitHub
+- Create sub-issues (using parallel agents if appropriate)
+- Rename task files to issue IDs
+- Create epic branch
+
+### 4. Output
+
+```
+🚀 Epic Oneshot Complete: $ARGUMENTS
+
+Step 1: Decomposition ✓
+  - Tasks created: {count}
+  
+Step 2: GitHub Sync ✓
+  - Epic: #{number}
+  - Sub-issues created: {count}
+  - Branch: epic/$ARGUMENTS
+
+Ready for development!
+  Start work: /pm:epic-start $ARGUMENTS
+  Or single task: /pm:issue-start {task_number}
+```
+
+## Important Notes
+
+This is simply a convenience wrapper that runs:
+1. `/pm:epic-decompose` 
+2. `/pm:epic-sync`
+
+Both commands handle their own error checking, parallel execution, and validation. This command just orchestrates them in sequence.
+
+Use this when you're confident the epic is ready and want to go from epic to GitHub issues in one step.

package/packages/plugin-pm/commands/epic-refresh.md

@@ -0,0 +1,119 @@
+---
+allowed-tools: Read, Write, LS
+---
+
+# Epic Refresh
+
+Update epic progress based on task states.
+
+## Usage
+```
+/pm:epic-refresh <epic_name>
+```
+
+## Required Documentation Access
+
+**MANDATORY:** Before project management workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/epic-management` - epic management best practices
+- `mcp://context7/project-management/issue-tracking` - issue tracking best practices
+- `mcp://context7/agile/task-breakdown` - task breakdown best practices
+- `mcp://context7/project-management/workflow` - workflow 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. Count Task Status
+
+Scan all task files in `.claude/epics/$ARGUMENTS/`:
+- Count total tasks
+- Count tasks with `status: closed`
+- Count tasks with `status: open`
+- Count tasks with work in progress
+
+### 2. Calculate Progress
+
+```
+progress = (closed_tasks / total_tasks) * 100
+```
+
+Round to nearest integer.
+
+### 3. Update GitHub Task List
+
+If epic has GitHub issue, sync task checkboxes:
+
+```bash
+# Get epic issue number from epic.md frontmatter
+epic_issue={extract_from_github_field}
+
+if [ ! -z "$epic_issue" ]; then
+  # Get current epic body
+  gh issue view $epic_issue --json body -q .body > /tmp/epic-body.md
+  
+  # For each task, check its status and update checkbox
+  for task_file in .claude/epics/$ARGUMENTS/[0-9]*.md; do
+    task_issue=$(grep 'github:' $task_file | grep -oE '[0-9]+$')
+    task_status=$(grep 'status:' $task_file | cut -d: -f2 | tr -d ' ')
+    
+    if [ "$task_status" = "closed" ]; then
+      # Mark as checked
+      sed -i "s/- \[ \] #$task_issue/- [x] #$task_issue/" /tmp/epic-body.md
+    else
+      # Ensure unchecked (in case manually checked)
+      sed -i "s/- \[x\] #$task_issue/- [ ] #$task_issue/" /tmp/epic-body.md
+    fi
+  done
+  
+  # Update epic issue
+  gh issue edit $epic_issue --body-file /tmp/epic-body.md
+fi
+```
+
+### 4. Determine Epic Status
+
+- If progress = 0% and no work started: `backlog`
+- If progress > 0% and < 100%: `in-progress`
+- If progress = 100%: `completed`
+
+### 5. Update Epic
+
+Get current datetime: `date -u +"%Y-%m-%dT%H:%M:%SZ"`
+
+Update epic.md frontmatter:
+```yaml
+status: {calculated_status}
+progress: {calculated_progress}%
+updated: {current_datetime}
+```
+
+### 6. Output
+
+```
+🔄 Epic refreshed: $ARGUMENTS
+
+Tasks:
+  Closed: {closed_count}
+  Open: {open_count}
+  Total: {total_count}
+  
+Progress: {old_progress}% → {new_progress}%
+Status: {old_status} → {new_status}
+GitHub: Task list updated ✓
+
+{If complete}: Run /pm:epic-close $ARGUMENTS to close epic
+{If in progress}: Run /pm:next to see priority tasks
+```
+
+## Important Notes
+
+This is useful after manual task edits or GitHub sync.
+Don't modify task files, only epic status.
+Preserve all other frontmatter fields.

package/packages/plugin-pm/commands/epic-show.md

@@ -0,0 +1,28 @@
+---
+allowed-tools: Bash
+---
+
+Run `node .claude/scripts/pm/epic-show.js $ARGUMENTS` using the Bash tool and show me the complete output.
+
+- DO NOT truncate.
+- DO NOT collapse.
+- DO NOT abbreviate.
+- Show ALL lines in full.
+## Required Documentation Access
+
+**MANDATORY:** Before project management workflows, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/epic-management` - epic management best practices
+- `mcp://context7/project-management/issue-tracking` - issue tracking best practices
+- `mcp://context7/agile/task-breakdown` - task breakdown best practices
+- `mcp://context7/project-management/workflow` - workflow 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
+
+
+- DO NOT print any other comments.

package/packages/plugin-pm/commands/epic-split.md

@@ -0,0 +1,120 @@
+---
+name: epic-split
+type: epic-management
+category: pm
+---
+
+# Epic Split
+
+Automatically split a PRD into multiple logical epics based on content analysis.
+
+## Usage
+```bash
+/pm:epic-split <feature_name>
+```
+
+## Required Documentation Access
+
+**MANDATORY:** Before splitting PRDs into epics, query Context7 for best practices:
+
+**Documentation Queries:**
+- `mcp://context7/agile/epic-splitting` - Epic decomposition strategies
+- `mcp://context7/project-management/dependency-mapping` - Dependency analysis patterns
+- `mcp://context7/agile/priority-frameworks` - Priority assessment (P0, P1, P2)
+- `mcp://context7/architecture/component-analysis` - Component identification
+- `mcp://context7/agile/parallel-planning` - Parallel work planning
+
+**Why This is Required:**
+- Ensures logical epic boundaries following proven patterns
+- Applies industry-standard dependency mapping techniques
+- Validates priority assignments against frameworks (MoSCoW, RICE)
+- Prevents inefficient epic structures and bottlenecks
+
+## Description
+This command analyzes a PRD and automatically splits it into multiple epics based on:
+- Technical components (frontend, backend, infrastructure)
+- Feature areas (auth, dashboard, API, etc.)
+- Complexity and dependencies
+- Priority levels (P0, P1, P2)
+
+## How It Works
+
+1. **PRD Analysis**: Scans the PRD for keywords and patterns
+2. **Epic Identification**: Matches content against epic templates
+3. **Dependency Mapping**: Determines logical dependencies between epics
+4. **Structure Creation**: Creates organized epic folders with metadata
+
+## Epic Types Detected
+
+- **Infrastructure Foundation** - Docker, DB, monitoring
+- **Authentication Backend** - JWT, users, RBAC
+- **Authentication UI** - Login/register forms
+- **API Core Services** - REST endpoints
+- **Frontend Foundation** - React/Vue/Angular setup
+- **Dashboard & UX** - Main application UI
+- **Data Layer** - Database models, migrations
+- **Testing & Quality** - Test suites, TDD
+- **Deployment & DevOps** - CI/CD, production
+- **Security & Compliance** - OWASP, hardening
+
+## Output Structure
+
+```
+.claude/epics/<feature_name>/
+├── meta.yaml                    # Multi-epic metadata
+├── 01-infrastructure/           # Epic 1
+│   └── epic.md
+├── 02-auth_backend/            # Epic 2
+│   └── epic.md
+├── 03-frontend_foundation/     # Epic 3
+│   └── epic.md
+└── ...
+```
+
+## Example
+
+```bash
+# Split a complex PRD into epics
+/pm:epic-split frontend-backend-db-base
+
+# Output:
+✓ Identified 6 epics
+✓ Epic 1: Infrastructure Foundation (P0, 1w)
+✓ Epic 2: Authentication Backend (P0, 2w)
+✓ Epic 3: Frontend Foundation (P0, 1w)
+✓ Epic 4: Authentication UI (P0, 2w)
+✓ Epic 5: Dashboard & UX (P1, 2w)
+✓ Epic 6: Testing & Quality (P1, 1w)
+
+Total Estimated Effort: 9 weeks
+```
+
+## Benefits
+
+- **Automatic Analysis**: No manual epic creation needed
+- **Dependency Detection**: Understands epic relationships
+- **Priority Sorting**: P0 epics come first
+- **Parallel Work**: Identifies what can be done simultaneously
+- **Time Estimates**: Provides week-level estimates
+
+## Next Steps After Split
+
+1. Review the epic breakdown
+2. Decompose each epic into tasks: `/pm:epic-decompose <feature>/<epic_number>`
+3. Sync to GitHub: `/pm:epic-sync <feature>`
+4. Start implementation on parallel epics
+
+## When to Use
+
+- PRDs with multiple components (frontend + backend + infra)
+- Complex features requiring phased delivery
+- Large teams needing parallel work streams
+- Projects requiring clear milestone tracking
+
+## Manual Override
+
+If the automatic split isn't perfect, you can:
+1. Edit the generated epic files
+2. Adjust dependencies in meta.yaml
+3. Merge or split epics further
+4. Update time estimates