claude-autopm 2.7.0 → 2.8.1

package/README.md

@@ -15,11 +15,12 @@ Transform your development workflow with intelligent automation, parallel AI age
 
 ClaudeAutoPM is a comprehensive project management and development automation framework designed specifically for [Claude Code](https://claude.ai/code). It combines:
 
-- **112+ CLI commands** for deterministic operations (scaffolding, templates, automation)
+- **136+ CLI commands** including 24 complete PM commands (Issue, Workflow, Context, Utility)
 - **39 specialized AI agents** for intelligent tasks (analysis, design, development)
 - **Dynamic team management** with automatic agent switching
-- **Hybrid execution modes** - choose between templates or AI assistance
+- **Hybrid execution modes** - choose between CLI commands or AI assistance
 - **Full GitHub & Azure DevOps integration** for seamless workflow
+- **TDD-developed** with 168+ tests and 91%+ coverage
 
 ### The Problem We Solve
 
@@ -44,54 +45,141 @@ PRD → Epic Decomposition → Parallel Development → Testing → Production
 
 ## ✨ Key Features
 
-### 🆕 **NEW in v2.1.0: STANDALONE CLI Commands - Direct Service Access!**
+### 🎉 **NEW in v2.8.0-alpha: Complete GitHub Integration!**
 
-**Three New CLI Commands** - Direct access to service layer without AI overhead
-- 🎯 **Deterministic Operations** - Fast, predictable, no AI required
-- 🎨 **Modern UX** - Progress spinners, color-coded output, streaming support
-- ⚡ **High Performance** - Direct service layer access for instant results
-- 🧪 **100% Test Coverage** - 65 CLI tests passing, full TDD methodology
+**Full Bidirectional GitHub Sync** - Seamless integration with GitHub Issues
+- ✅ **GitHubProvider** - Complete GitHub REST API wrapper with 99% test coverage
+- 🔄 **Issue Sync** - Push/pull issues with conflict detection and resolution
+- 📦 **Epic Sync** - Sync epics as GitHub issues with task checkboxes
+- 🎯 **84 Tests** - Comprehensive test coverage (45 + 39 tests)
+- ⚡ **Rate Limiting** - Smart rate limiting with exponential backoff
+- 🔀 **Conflict Resolution** - 5 strategies (local, remote, newest, manual, merge)
 
-**New Commands:**
+**New GitHub Sync Commands:**
 
 ```bash
-# PRD Management
+# Issue Synchronization
+autopm issue sync <number>              # Bidirectional sync
+autopm issue sync <number> --push       # Push local → GitHub
+autopm issue sync <number> --pull       # Pull GitHub → local
+autopm issue sync-status <number>       # Check sync status
+autopm issue sync-resolve <number>      # Resolve conflicts
+  --strategy newest|local|remote
+
+# What Gets Synced:
+# - Issue title, description, status
+# - Labels, assignees, milestones
+# - Comments and updates
+# - Task progress and completion
+```
+
+**Features:**
+- **Smart Conflict Detection**: Timestamp-based with multiple resolution strategies
+- **Sync Mapping**: Bidirectional tracking in `.claude/sync-map.json`
+- **Epic Support**: Epics → GitHub issues with "epic" label, tasks → checkboxes
+- **Rate Limiting**: Respects 5,000 req/hour limit with exponential backoff
+- **Error Handling**: Comprehensive error messages and recovery
+- **Real API Testing**: 17 integration tests with actual GitHub API
+
+**Conflict Resolution UI:**
+```bash
+⚠️  Sync Conflict Detected!
+
+Conflict Details:
+  Local newer:   false
+  Remote newer:  true
+
+Resolution Options:
+  1. Use local:    autopm issue sync-resolve 123 --strategy local
+  2. Use remote:   autopm issue sync-resolve 123 --strategy remote
+  3. Use newest:   autopm issue sync-resolve 123 --strategy newest
+```
+
+**Setup:**
+```bash
+# Configure GitHub credentials
+export GITHUB_TOKEN=ghp_your_personal_access_token
+export GITHUB_OWNER=your_username
+export GITHUB_REPO=your_repository
+
+# Verify connection
+node test/integration/test-github-manual.js
+
+# Start syncing!
+autopm issue sync 123
+```
+
+**Documentation:**
+- [GitHub Testing Guide](docs/GITHUB-TESTING-GUIDE.md) - Complete setup and testing
+- [Phase 1 Summary](docs/PHASE1-GITHUB-INTEGRATION-SUMMARY.md) - Technical details
+- [Phase 1 Complete](docs/PHASE1-COMPLETE.md) - Implementation summary
+
+**What's Next:**
+- Phase 2: Azure DevOps Integration (similar patterns)
+- Webhooks for real-time updates
+- Provider migration tools
+
+---
+
+### 🎉 **v2.7.0: 100% CLI Implementation Complete!**
+
+**All 24 Planned Commands Implemented** - Complete CLI suite for project management
+- ✅ **24/24 Commands** - Full roadmap delivered (Issue, Workflow, Context, Utility)
+- 🎯 **168 Tests** - 91.4% average coverage, 100% function coverage
+- 🎨 **Modern UX** - Progress spinners, color-coded output, intuitive commands
+- ⚡ **TDD Methodology** - Test-driven development throughout
+- 📚 **Context7 Best Practices** - 2025 industry standards applied
+
+**Complete Command Suite:**
+
+```bash
+# Issue Management (6 commands)
+autopm issue show <number>            # Display issue details
+autopm issue start <number>           # Start working on issue
+autopm issue close <number>           # Close completed issue
+autopm issue status <number>          # Check issue status
+autopm issue edit <number>            # Edit issue in editor
+autopm issue sync <number>            # Sync with provider
+
+# Workflow Commands (6 commands)
+autopm pm next                        # Get next priority task
+autopm pm what-next                   # AI-powered suggestions
+autopm pm standup                     # Generate daily standup
+autopm pm status                      # Project status overview
+autopm pm in-progress                 # Show active tasks
+autopm pm blocked                     # List blocked tasks
+
+# Context Management (4 commands)
+autopm context create <type>          # Create context from template
+autopm context prime                  # Generate project snapshot
+autopm context update <type>          # Update existing context
+autopm context show [type]            # Show or list contexts
+
+# Project Utilities (6 commands)
+autopm pm init                        # Initialize PM structure
+autopm pm validate                    # Validate project (--fix for repair)
+autopm pm sync                        # Sync with provider
+autopm pm clean                       # Clean stale artifacts
+autopm pm search <query>              # Search entities (BM25)
+autopm pm import <source>             # Import from external sources
+
+# PRD Management (legacy)
 autopm prd parse my-prd --ai          # AI-powered PRD parsing
-autopm prd parse my-prd --stream      # Real-time streaming output
 autopm prd extract-epics my-prd       # Extract epics from PRD
-autopm prd summarize my-prd           # Generate comprehensive summary
-autopm prd validate my-prd            # Validate structure & quality
-
-# Task Management
-autopm task list epic-001             # Display all tasks from epic
-autopm task prioritize epic-001       # AI-powered prioritization
-
-# Agent Invocation
-autopm agent list                     # Display available agents
-autopm agent search "kubernetes"      # Search agents by keyword
-autopm agent invoke aws-architect "Design VPC"  # Invoke agent with task
-autopm agent invoke --stream agent-name "task"  # Streaming invocation
+autopm prd summarize my-prd           # Generate summary
 ```
 
-**User Experience Features:**
-- 🔄 Progress indicators with ora spinners
-- 🎨 Color-coded output (green=success, red=error, yellow=warning)
-- 📡 Streaming support for real-time AI responses
-- ❌ Comprehensive error handling with user-friendly messages
-- 📋 Consistent patterns across all commands
-
-**Technical Implementation:**
-- Extended PRDService with 4 non-streaming methods
-- All services support both streaming and non-streaming modes
-- Proper separation of concerns (CLI → Service → Provider)
+**Architecture:**
+- 4 Service Layers: IssueService, WorkflowService, ContextService, UtilityService
+- Separation of concerns (CLI → Service → Provider)
 - Zero breaking changes to existing functionality
-- CommonJS compatibility maintained
+- Production-ready implementation
 
-**Test Coverage:**
-- 28 new tests across 3 CLI command suites
-- 65 total CLI tests passing (100% pass rate)
-- Full TDD methodology with Jest
-- Comprehensive coverage of success, error, and streaming scenarios
+**Milestone Achievement:**
+- Phase 1 (v2.5.0): Issue Commands - 6 commands, 54 tests
+- Phase 2 (v2.6.0): Workflow Commands - 6 commands, 39 tests
+- Phase 3 (v2.7.0): Context & Utility - 10 commands, 75 tests
+- **Total: 24 commands, 168 tests, 91.4% coverage** 🎉
 
 ---
 
@@ -208,13 +296,33 @@ Organized into dynamic teams that load based on your work context:
 
 ### 🔄 **Hybrid Execution Model**
 
-Choose the best approach for each task:
+ClaudeAutoPM provides two distinct interfaces optimized for different operations:
 
-| Mode | When to Use | Example |
-|------|-------------|---------|
-| **Deterministic** | Scaffolding, templates, known patterns | `autopm install --preset fullstack` |
-| **AI-Powered** | Analysis, design, complex decisions | `/pm:epic-decompose` |
-| **Hybrid** | Flexible workflows | `autopm config` (CLI) or `/pm:config` (AI) |
+#### 🔧 CLI (`autopm`) - Non-AI Utilities
+Fast, deterministic operations that don't require AI:
+```bash
+autopm install                    # Framework installation
+autopm config set provider github # Configuration management
+autopm team load fullstack        # Load agent teams
+autopm mcp enable context7        # Manage MCP servers
+autopm epic status auth           # View epic progress (read-only)
+```
+
+**When to use:** Setup, configuration, read-only utilities, CI/CD scripts
+
+#### 🤖 Claude Code (`/pm:*`) - AI-Powered Operations
+Intelligent operations leveraging Claude's AI:
+```bash
+/pm:prd-new user-auth            # Create PRD with AI assistance
+/pm:epic-decompose user-auth     # Intelligent task breakdown
+/pm:next                         # Smart task prioritization
+/pm:standup                      # Generate progress summary
+/pm:what-next                    # AI suggests next actions
+```
+
+**When to use:** Creation, modification, intelligent analysis, development workflow
+
+📖 **[Full CLI vs Claude Code Guide](docs/CLI-vs-CLAUDE-CODE.md)**
 
 ### 🎭 **Dynamic Team Management**
 
@@ -297,6 +405,35 @@ claude --dangerously-skip-permissions .
 
 ### Your First Workflow
 
+**Option A: Using New CLI Commands (v2.7.0+)**
+```bash
+# 1. Initialize project structure
+autopm pm init
+
+# 2. Create PRD (in Claude Code or manually)
+/pm:prd-new "Build user authentication system"
+
+# 3. Decompose into epic
+/pm:epic-decompose prd-001-authentication.md
+
+# 4. Check what to do next
+autopm pm what-next
+
+# 5. Start working on next task
+autopm pm next
+autopm issue start 123
+
+# 6. Generate daily standup
+autopm pm standup
+
+# 7. Complete and close issue
+autopm issue close 123
+
+# 8. Sync with provider
+autopm pm sync
+```
+
+**Option B: Classic Claude Code Workflow**
 ```bash
 # 1. Create a PRD (in Claude Code)
 /pm:prd-new "Build user authentication system"
@@ -325,6 +462,7 @@ claude --dangerously-skip-permissions .
 
 ### Core Concepts
 - [Architecture Overview](docs/core-concepts/architecture.md)
+- [CLI vs Claude Code](docs/CLI-vs-CLAUDE-CODE.md) ⭐ **Essential reading**
 - [Hybrid Execution](docs/core-concepts/hybrid-execution.md)
 - [Agent System](docs/core-concepts/agent-system.md)
 - [Team Management](docs/core-concepts/team-management.md)
@@ -457,8 +595,13 @@ claude --dangerously-skip-permissions .
 
 ## 📦 What's Included
 
-### CLI Commands (112 total)
-- **Project Management**: PRD, Epic, Issue, Task management (3 new STANDALONE commands in v2.1.0)
+### CLI Commands (136+ total)
+- **Project Management**: 24 complete PM commands (Issue, Workflow, Context, Utility) ✨ NEW in v2.7.0
+  - Issue Management (6): show, start, close, status, edit, sync
+  - Workflow (6): next, what-next, standup, status, in-progress, blocked
+  - Context (4): create, prime, update, show
+  - Utilities (6): init, validate, sync, clean, search, import
+- **PRD & Epic**: PRD parsing, epic decomposition, task management
 - **Development**: Scaffolding, testing, deployment
 - **Configuration**: Provider setup, team management, MCP servers
 - **DevOps**: Docker, Kubernetes, CI/CD automation

package/autopm/.claude/.env

@@ -0,0 +1,158 @@
+# ============================================
+# MCP (Model Context Protocol) Configuration
+# ============================================
+
+# Context7 MCP Server Configuration
+# ------------------------------------------
+# Get your API key from https://context7.com/account
+CONTEXT7_API_KEY=your-context7-api-key-here
+
+# MCP endpoint URL (default: mcp.context7.com/mcp)
+CONTEXT7_MCP_URL=mcp.context7.com/mcp
+
+# Context7 API URL (default: context7.com/api/v1)
+CONTEXT7_API_URL=context7.com/api/v1
+
+# Your Context7 workspace ID or name
+CONTEXT7_WORKSPACE=your-workspace-id-or-name
+
+# Context mode: documentation or codebase
+# documentation = for accessing docs, codebase = for code context
+CONTEXT7_MODE=documentation
+
+# Cache TTL in seconds (optional, default: 3600)
+CONTEXT7_CACHE_TTL=3600
+
+# ============================================
+# GitHub MCP Server Configuration
+# ============================================
+
+# GitHub Personal Access Token
+# Create at: https://github.com/settings/tokens
+# Required scopes: repo, workflow, read:org
+GITHUB_TOKEN=your-github-personal-access-token
+
+# GitHub API URL (default for public GitHub)
+GITHUB_API_URL=https://api.github.com
+
+# ============================================
+# Playwright MCP Server Configuration
+# ============================================
+
+# Browser to use for Playwright tests (chromium, firefox, webkit)
+PLAYWRIGHT_BROWSER=chromium
+
+# Run browser in headless mode (true/false)
+PLAYWRIGHT_HEADLESS=true
+
+# ============================================
+# Azure DevOps Configuration (Optional)
+# ============================================
+
+# Azure DevOps Personal Access Token
+# Create at: https://dev.azure.com/{yourorganization}/_usersSettings/tokens
+AZURE_DEVOPS_PAT=your-azure-devops-pat
+
+# Azure DevOps Organization
+AZURE_DEVOPS_ORG=your-organization
+
+# Azure DevOps Project
+AZURE_DEVOPS_PROJECT=your-project
+
+# Azure DevOps API URL (optional, for Azure DevOps Server)
+# AZURE_DEVOPS_API_URL=https://dev.azure.com
+
+# ============================================
+# Cloud Provider Credentials (Optional)
+# ============================================
+
+# AWS Configuration
+# ------------------------------------------
+AWS_ACCESS_KEY_ID=your-aws-access-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+AWS_DEFAULT_REGION=us-east-1
+# Optional: AWS profile to use
+# AWS_PROFILE=default
+
+# Azure Cloud Configuration
+# ------------------------------------------
+AZURE_SUBSCRIPTION_ID=your-azure-subscription-id
+AZURE_TENANT_ID=your-azure-tenant-id
+AZURE_CLIENT_ID=your-azure-client-id
+AZURE_CLIENT_SECRET=your-azure-client-secret
+# Optional: Azure Cloud environment (AzureCloud, AzureChinaCloud, AzureUSGovernment, AzureGermanCloud)
+# AZURE_CLOUD_ENVIRONMENT=AzureCloud
+
+# Google Cloud Platform Configuration
+# ------------------------------------------
+GCP_PROJECT_ID=your-gcp-project-id
+# Path to service account key JSON file
+GCP_SERVICE_ACCOUNT_KEY=path/to/service-account-key.json
+# Optional: GCP region
+# GCP_REGION=us-central1
+
+# ============================================
+# AI Provider API Keys (Optional)
+# ============================================
+
+# OpenAI Configuration
+# ------------------------------------------
+OPENAI_API_KEY=your-openai-api-key
+# Optional: OpenAI organization ID
+# OPENAI_ORG_ID=your-org-id
+# Optional: API base URL for custom endpoints
+# OPENAI_API_BASE=https://api.openai.com/v1
+
+# Google Gemini Configuration
+# ------------------------------------------
+GEMINI_API_KEY=your-gemini-api-key
+# Optional: Gemini model to use
+# GEMINI_MODEL=gemini-pro
+
+# ============================================
+# Additional MCP Servers (Optional)
+# ============================================
+
+# Database MCP Server
+# ------------------------------------------
+# DATABASE_MCP_URL=your-database-mcp-url
+# DATABASE_MCP_TOKEN=your-database-token
+
+# Custom MCP Server
+# ------------------------------------------
+# CUSTOM_MCP_URL=your-custom-mcp-url
+# CUSTOM_MCP_API_KEY=your-custom-api-key
+
+# ============================================
+# MCP Context Pool Settings
+# ============================================
+
+# Maximum context pool size for shared contexts
+MCP_CONTEXT_POOL_MAX_SIZE=100MB
+
+# Context retention period (e.g., 7d, 24h, 1w)
+MCP_CONTEXT_RETENTION=7d
+
+# Context refresh interval (daily, hourly, on-change)
+MCP_CONTEXT_REFRESH=daily
+
+# ============================================
+# Development & Testing
+# ============================================
+
+# Enable MCP debug logging (true/false)
+MCP_DEBUG=false
+
+# MCP log level (error, warn, info, debug, trace)
+MCP_LOG_LEVEL=info
+
+# ============================================
+# IMPORTANT SECURITY NOTES
+# ============================================
+# 1. NEVER commit this file to version control
+# 2. This file is already in .gitignore
+# 3. Keep this file secure with proper permissions
+# 4. Rotate API keys regularly
+# 5. Use environment-specific .env files for different environments
+# 6. Consider using a secrets management service for production
+# ============================================

package/autopm/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/rla/Projects/ClaudeAutoPM.wiki/**)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/bin/autopm.js

@@ -321,8 +321,15 @@ function main() {
    autopm team load <name>          # Load specific team (frontend/backend/fullstack/devops)
    autopm team current              # Check currently active team
 
-💡 Claude Code Workflows (In-Editor Commands):
-   /pm:what-next                    # ⭐ Smart suggestions for next steps
+📊 Epic Status (Read-Only Utilities):
+   autopm epic list                 # List all available epics
+   autopm epic status <name>        # Show epic progress and metrics
+   autopm epic breakdown <name>     # Show detailed task breakdown
+
+   💡 Note: To CREATE or MODIFY epics, use Claude Code /pm:* commands
+
+💡 Claude Code PM Commands (AI-Powered):
+   /pm:what-next                    # ⭐ Smart suggestions for what to do next
    /pm:status                       # Project overview and health
    /pm:prd-new <name>               # Create new PRD
    /pm:epic-decompose <name>        # Break PRD into tasks

package/bin/commands/epic.js

@@ -1,6 +1,15 @@
 /**
  * Epic Command for autopm CLI
- * Manages epic status, breakdown, and analysis
+ * Read-only utility for viewing epic status and breakdown
+ *
+ * NOTE: This is a READ-ONLY utility command for viewing epics.
+ * To CREATE or MODIFY epics, use Claude Code commands:
+ *   /pm:prd-new <name>           - Create new PRD
+ *   /pm:epic-decompose <name>    - Decompose PRD into epic
+ *   /pm:epic-sync <name>         - Sync epic with provider
+ *   /pm:epic-edit <name>         - Edit existing epic
+ *
+ * This CLI command is for quick status checks outside of Claude Code.
  */
 
 const path = require('path');
@@ -9,7 +18,7 @@ const fs = require('fs');
 
 module.exports = {
   command: 'epic <action> [name]',
-  describe: 'Manage epics and view epic status',
+  describe: 'View epic status and breakdown (read-only utility)',
 
   builder: (yargs) => {
     return yargs
@@ -30,7 +39,18 @@ module.exports = {
       })
       .example('autopm epic list', 'List all available epics')
       .example('autopm epic status fullstack', 'Show status of fullstack epic')
-      .example('autopm epic breakdown fullstack', 'Show detailed task breakdown');
+      .example('autopm epic breakdown fullstack', 'Show detailed task breakdown')
+      .epilogue(`
+📝 Note: This is a READ-ONLY command for viewing epics.
+
+To create or modify epics, use Claude Code:
+  /pm:prd-new <name>           - Create new PRD
+  /pm:epic-decompose <name>    - Decompose PRD into epic
+  /pm:epic-sync <name>         - Sync epic with provider
+  /pm:epic-edit <name>         - Edit existing epic
+
+Use this CLI command for quick status checks outside Claude Code.
+      `);
   },
 
   handler: async (argv) => {