claude-autopm 2.8.2 → 2.8.3

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

@@ -0,0 +1,195 @@
+---
+allowed-tools: Bash, Read, Write, LS, Task
+---
+
+# Epic Start
+
+Launch parallel agents to work on epic tasks using the unified branch strategy.
+
+## Usage
+```
+/pm:epic-start <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 epic exists:**
+   ```bash
+   test -f .claude/epics/$ARGUMENTS/epic.md || echo "❌ Epic not found. Run: /pm:prd-parse $ARGUMENTS"
+   ```
+
+2. **Check GitHub sync:**
+   Look for `github:` field in epic frontmatter.
+   If missing: "❌ Epic not synced. Run: /pm:epic-sync $ARGUMENTS first"
+
+3. **Check for branch:**
+   ```bash
+   git branch -a | grep "epic/$ARGUMENTS"
+   ```
+
+4. **Check for uncommitted changes:**
+   ```bash
+   git status --porcelain
+   ```
+   If output is not empty: "❌ You have uncommitted changes. Please commit or stash them before starting an epic"
+
+## ⚠️ TDD REMINDER - READ THIS FIRST
+
+**CRITICAL: This project follows Test-Driven Development (TDD).**
+
+Before ANY coding work begins on this epic, you MUST follow the RED-GREEN-REFACTOR cycle:
+
+1. **RED Phase**: Write failing test that describes the desired behavior
+2. **GREEN Phase**: Write minimum code to make test pass
+3. **REFACTOR Phase**: Clean up code while keeping tests green
+
+**For this epic:**
+- All tasks have TDD requirements section
+- Every agent must start with test creation
+- No implementation without tests first
+
+See `.claude/rules/tdd.enforcement.md` for complete TDD requirements.
+
+---
+
+## Instructions
+
+### 1. Create or Enter Branch
+
+Follow the unified Git strategy in `/rules/git-strategy.md`:
+
+```bash
+# Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+  echo "❌ You have uncommitted changes. Please commit or stash them before starting an epic."
+  exit 1
+fi
+
+# If branch doesn't exist, create it
+if ! git branch -a | grep -q "epic/$ARGUMENTS"; then
+  git checkout main
+  git pull origin main
+  git checkout -b epic/$ARGUMENTS
+  git push -u origin epic/$ARGUMENTS
+  echo "✅ Created branch: epic/$ARGUMENTS"
+else
+  # Branch exists, check it out
+  git checkout epic/$ARGUMENTS
+  git pull origin epic/$ARGUMENTS
+  echo "✅ Using existing branch: epic/$ARGUMENTS"
+fi
+```
+
+### 2. Identify Ready Issues
+
+Read all task files in `.claude/epics/$ARGUMENTS/`:
+- Look for tasks with `status: ready` or `status: in_progress`
+- Group by dependencies
+
+### 3. Launch Parallel Agents
+
+For each ready issue without dependencies:
+
+```bash
+# Example parallel launch
+/agent python-backend-engineer "Work on issue #1234 from epic $ARGUMENTS"
+/agent react-frontend-engineer "Work on issue #1235 from epic $ARGUMENTS"
+```
+
+### 4. Monitor Progress
+
+```bash
+# Check branch status
+git log --oneline -10
+
+# Check CI status
+gh pr checks
+
+# View agent progress
+tail -f .claude/epics/$ARGUMENTS/progress.md
+```
+
+## Parallel Execution Rules
+
+1. **File Coordination**: Agents working on different files can commit simultaneously
+2. **Pull Before Push**: Always `git pull` before pushing changes
+3. **Conflict Resolution**: Human intervention required for merge conflicts
+4. **Commit Frequently**: Small, focused commits reduce conflict risk
+
+## Example Workflow
+
+```bash
+# 1. Start epic
+/pm:epic-start authentication
+
+# 2. Agents work in parallel
+# Agent A: Backend API
+# Agent B: Frontend UI
+# Agent C: Database schema
+
+# 3. Monitor progress
+/pm:epic-status authentication
+
+# 4. When complete
+/pm:epic-merge authentication
+```
+
+## Branch Management
+
+The epic branch (`epic/$ARGUMENTS`) will be:
+- Created if it doesn't exist
+- Checked out if it exists
+- Pulled to get latest changes
+- Ready for parallel agent work
+
+## Important Notes
+
+⚠️ **NO WORKTREES**: This command uses the standard branch strategy. Git worktrees are not supported.
+
+⚠️ **COMMIT BEFORE SWITCHING**: Always commit or stash changes before starting a new epic.
+
+⚠️ **PULL FREQUENTLY**: Agents should pull changes regularly to avoid conflicts.
+
+## Troubleshooting
+
+### "You have uncommitted changes"
+```bash
+# Option 1: Commit changes
+git add -A && git commit -m "WIP: Save work before epic start"
+
+# Option 2: Stash changes
+git stash save "WIP before starting epic"
+```
+
+### "Branch already exists"
+```bash
+# Use existing branch
+git checkout epic/$ARGUMENTS
+git pull origin epic/$ARGUMENTS
+```
+
+### "Merge conflicts"
+```bash
+# Resolve conflicts manually
+git status  # See conflicted files
+# Edit files to resolve
+git add {resolved-files}
+git commit -m "resolve: Merge conflicts"
+```

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

@@ -0,0 +1,28 @@
+---
+allowed-tools: Bash
+---
+
+Run `node .claude/scripts/pm/epic-status.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-sync-modular.md

@@ -0,0 +1,338 @@
+---
+allowed-tools: Bash, Read, Write, LS, Task
+---
+
+# Epic Sync - Modular Version
+
+Push epic and tasks to GitHub as issues using modular scripts.
+
+## Usage
+```
+/pm:epic-sync <feature_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
+
+```bash
+# Verify epic exists
+test -f .claude/epics/$ARGUMENTS/epic.md || echo "❌ Epic not found. Run: /pm:prd-parse $ARGUMENTS"
+
+# Count task files
+ls .claude/epics/$ARGUMENTS/*.md 2>/dev/null | grep -v epic.md | wc -l
+```
+
+If no tasks found: "❌ No tasks to sync. Run: /pm:epic-decompose $ARGUMENTS"
+
+## Instructions
+
+The epic sync process is now modularized into 4 specialized scripts that handle different aspects of the synchronization. Each script is designed for reliability, testability, and maintainability.
+
+### 1. Repository Protection Check
+
+This is handled automatically by our modular scripts, but you can run the check manually:
+
+```bash
+# Check repository protection (built into all scripts)
+bash .claude/scripts/lib/github-utils.sh
+```
+
+The scripts will automatically:
+- ✅ Verify GitHub CLI authentication
+- ✅ Check repository protection against template repos
+- ✅ Validate epic structure and inputs
+
+### 2. Create Epic Issue
+
+Create the main GitHub issue for the epic:
+
+```bash
+# Create epic issue with proper stats and labels
+epic_number=$(bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$ARGUMENTS")
+
+echo "✅ Epic issue created: #$epic_number"
+```
+
+This script handles:
+- ✅ Frontmatter stripping and content processing
+- ✅ Epic type detection (bug vs feature)
+- ✅ Statistics calculation (tasks, parallel/sequential breakdown)
+- ✅ GitHub issue creation with proper labels
+- ✅ Epic vs bug labeling based on content analysis
+
+### 3. Create Task Issues
+
+Create GitHub issues for all tasks with automatic parallel processing:
+
+```bash
+# Create task issues (automatically chooses sequential/parallel)
+task_mapping_file=$(bash .claude/scripts/pm/epic-sync/create-task-issues.sh "$ARGUMENTS" "$epic_number")
+
+echo "✅ Task issues created. Mapping: $task_mapping_file"
+```
+
+This script handles:
+- ✅ Automatic strategy selection (sequential < 5 tasks, parallel ≥ 5 tasks)
+- ✅ Sub-issues support (if gh-sub-issue extension available)
+- ✅ Parallel batch processing for large task sets
+- ✅ Proper labeling with `task,epic:$ARGUMENTS`
+- ✅ Error handling and partial failure recovery
+- ✅ Progress reporting and result consolidation
+
+**Environment Configuration:**
+```bash
+# Optional: Set custom parallel threshold
+export AUTOPM_PARALLEL_THRESHOLD=3  # Default: 5
+```
+
+### 4. Update Task References
+
+Update all task dependencies and rename files to use GitHub issue numbers:
+
+```bash
+# Update references and rename files
+bash .claude/scripts/pm/epic-sync/update-references.sh "$ARGUMENTS" "$task_mapping_file"
+
+echo "✅ Task references updated and files renamed"
+```
+
+This script handles:
+- ✅ ID mapping generation (001 → real issue numbers)
+- ✅ Dependency reference updates (`depends_on`, `conflicts_with`)
+- ✅ File renaming (001.md → 123.md)
+- ✅ Frontmatter updates with GitHub URLs
+- ✅ Timestamp updates
+- ✅ Cleanup of old-format files
+
+### 5. Update Epic File
+
+Update the epic.md file with GitHub information and real task IDs:
+
+```bash
+# Update epic file with GitHub info and real task IDs
+bash .claude/scripts/pm/epic-sync/update-epic-file.sh "$ARGUMENTS" "$epic_number"
+
+echo "✅ Epic file updated with GitHub information"
+```
+
+This script handles:
+- ✅ Epic frontmatter updates (GitHub URL, timestamp)
+- ✅ Tasks Created section replacement with real issue numbers
+- ✅ Statistics recalculation
+- ✅ GitHub mapping file creation
+- ✅ Content structure preservation
+
+### 6. Create Development Branch
+
+Follow `/rules/git-strategy.md` to create development branch:
+
+```bash
+# Ensure main is current
+git checkout main
+git pull origin main
+
+# Create branch for epic
+git checkout -b epic/$ARGUMENTS
+git push -u origin epic/$ARGUMENTS
+
+echo "✅ Created branch: epic/$ARGUMENTS"
+```
+
+## Complete Workflow Example
+
+Here's the complete modular epic sync workflow:
+
+```bash
+#!/bin/bash
+# Complete epic sync using modular scripts
+
+EPIC_NAME="$ARGUMENTS"
+
+echo "🚀 Starting modular epic sync for: $EPIC_NAME"
+
+# Step 1: Create epic issue
+echo "📝 Creating epic issue..."
+epic_number=$(bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME")
+
+if [[ -z "$epic_number" ]]; then
+    echo "❌ Failed to create epic issue"
+    exit 1
+fi
+
+echo "✅ Epic issue created: #$epic_number"
+
+# Step 2: Create task issues
+echo "📋 Creating task issues..."
+task_mapping_file=$(bash .claude/scripts/pm/epic-sync/create-task-issues.sh "$EPIC_NAME" "$epic_number")
+
+if [[ ! -f "$task_mapping_file" ]]; then
+    echo "❌ Failed to create task issues"
+    exit 1
+fi
+
+task_count=$(wc -l < "$task_mapping_file")
+echo "✅ Created $task_count task issues"
+
+# Step 3: Update references
+echo "🔗 Updating task references..."
+bash .claude/scripts/pm/epic-sync/update-references.sh "$EPIC_NAME" "$task_mapping_file"
+
+echo "✅ Task references updated"
+
+# Step 4: Update epic file
+echo "📄 Updating epic file..."
+bash .claude/scripts/pm/epic-sync/update-epic-file.sh "$EPIC_NAME" "$epic_number"
+
+echo "✅ Epic file updated"
+
+# Step 5: Create branch
+echo "🌿 Creating development branch..."
+git checkout main
+git pull origin main
+git checkout -b epic/$EPIC_NAME
+git push -u origin epic/$EPIC_NAME
+
+echo "✅ Created branch: epic/$EPIC_NAME"
+
+# Get repository info for final output
+repo=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+
+# Final output
+echo ""
+echo "🎉 Epic sync completed successfully!"
+echo ""
+echo "📊 Summary:"
+echo "  Epic: #$epic_number - $EPIC_NAME"
+echo "  Tasks: $task_count sub-issues created"
+echo "  Branch: epic/$EPIC_NAME"
+echo ""
+echo "🔗 Links:"
+echo "  Epic: https://github.com/$repo/issues/$epic_number"
+echo "  Branch: https://github.com/$repo/tree/epic/$EPIC_NAME"
+echo ""
+echo "📋 Next steps:"
+echo "  - Start parallel execution: /pm:epic-start $EPIC_NAME"
+echo "  - Or work on single issue: /pm:issue-start <issue_number>"
+echo ""
+```
+
+## Benefits of Modular Approach
+
+### ✅ **Reliability**
+- Each script handles one specific responsibility
+- Comprehensive error handling and validation
+- Atomic operations with proper rollback
+
+### ✅ **Performance**
+- Automatic parallel processing for large task sets
+- Configurable thresholds via environment variables
+- Background job management for concurrent operations
+
+### ✅ **Maintainability**
+- Modular scripts are easier to test and debug
+- Shared libraries ensure consistency
+- Clear separation of concerns
+
+### ✅ **Testability**
+- Each script can be tested independently
+- Mock-friendly interfaces
+- TDD-driven development approach
+
+### ✅ **Flexibility**
+- Scripts can be used independently
+- Easy to extend or modify individual components
+- Environment-based configuration
+
+## Error Handling
+
+Each modular script includes comprehensive error handling:
+
+- **Validation**: Input validation before processing
+- **Authentication**: GitHub CLI authentication checks
+- **Repository Protection**: Automatic template repository detection
+- **Partial Failures**: Graceful handling of partial operations
+- **Logging**: Detailed logging with configurable levels
+- **Cleanup**: Automatic temporary file cleanup
+
+## Configuration Options
+
+### Environment Variables
+
+```bash
+# Parallel processing threshold
+export AUTOPM_PARALLEL_THRESHOLD=5  # Default: 5
+
+# Logging level (0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR)
+export AUTOPM_LOG_LEVEL=1  # Default: 1 (INFO)
+```
+
+### GitHub Extensions
+
+The scripts automatically detect and use GitHub CLI extensions:
+
+- **gh-sub-issue**: For hierarchical issue management
+- Fallback to regular issues if extension not available
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"No tasks to sync"**
+   ```bash
+   # Generate tasks first
+   /pm:epic-decompose $ARGUMENTS
+   ```
+
+2. **"GitHub CLI not authenticated"**
+   ```bash
+   gh auth login
+   ```
+
+3. **"Template repository detected"**
+   ```bash
+   git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
+   ```
+
+4. **Partial task creation failure**
+   - Scripts handle partial failures gracefully
+   - Check logs for specific task errors
+   - Retry individual scripts as needed
+
+### Script Debugging
+
+Enable debug logging for detailed troubleshooting:
+
+```bash
+export AUTOPM_LOG_LEVEL=0  # Enable debug logging
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+```
+
+## Migration from Legacy Epic Sync
+
+The modular version is fully backward compatible. To migrate:
+
+1. **No changes required** - existing commands work unchanged
+2. **Optional**: Use individual scripts for fine-grained control
+3. **Optional**: Configure environment variables for optimization
+
+Legacy workflows continue to work, but benefit from improved reliability and performance.
+
+---
+
+*This modular implementation provides the same functionality as the original epic-sync with improved reliability, testability, and maintainability.*