claude-autopm 1.13.2 → 1.13.4

package/README.md

@@ -199,6 +199,42 @@ autopm config switch github
 autopm config validate
 ```
 
+#### 4.6 Verify Installation & Configuration
+
+After installation, verify that everything is properly configured:
+
+```bash
+# Comprehensive configuration check
+autopm validate
+
+# Shows:
+# ✅ Essential Components (.claude directory, config, provider, git)
+# ✅ Optional Components (MCP servers, git hooks, Node.js version)
+# 📋 Next steps for incomplete setup
+```
+
+**Example Output:**
+```
+╔════════════════════════════════════════════════════════════════╗
+║         🔍 ClaudeAutoPM Configuration Status                  ║
+╚════════════════════════════════════════════════════════════════╝
+
+Essential Components:
+  ✅ .claude directory - Framework installed
+  ✅ Configuration file - Provider: github
+  ✅ Provider setup - GitHub (configured)
+  ✅ Git repository - Initialized
+
+Optional Components:
+  ✅ MCP servers - 2 active (context7-docs, github-mcp)
+  ⚠️  Git hooks - Not installed (run: bash scripts/setup-hooks.sh)
+  ✅ Node.js version - v20.10.0 (compatible)
+
+Next Steps:
+  1. Install git hooks: bash scripts/setup-hooks.sh
+  2. Run MCP configuration check: autopm mcp check
+```
+
 #### 4. Ship Your First Feature (90 seconds)
 
 ##### Option A: Using Templates (Works Everywhere)
@@ -353,8 +389,9 @@ autopm mcp tree                # Dependency tree
 
 #### **Configuration & Diagnostics**
 ```bash
+autopm mcp check               # Quick configuration check
 autopm mcp setup               # Interactive API key setup
-autopm mcp diagnose            # Run diagnostics
+autopm mcp diagnose            # Run full diagnostics
 autopm mcp test <server>       # Test server connection
 autopm mcp status              # Show servers status
 ```
@@ -461,6 +498,48 @@ autopm pm:prd-parse user-authentication --overwrite
 autopm pm:epic-close user-auth "All authentication features complete"
 ```
 
+##### **Splitting Large PRDs into Multiple Epics**
+
+For complex features, you can split a single PRD into multiple focused epics:
+
+```bash
+# 1. Create a comprehensive PRD
+autopm pm:prd-new payment-system --template
+
+# 2. Split into focused epics using AI analysis
+/pm:prd-split payment-system
+
+# This creates multiple epics from one PRD:
+# ├─ payment-system-backend     (API, database, payment gateway integration)
+# ├─ payment-system-frontend    (UI components, checkout flow)
+# └─ payment-system-security    (PCI compliance, encryption, audit logging)
+
+# 3. Work on each epic independently
+/pm:epic-decompose payment-system-backend
+/pm:epic-sync payment-system-backend
+
+# 4. Track overall PRD progress
+autopm pm:prd-status payment-system
+# Shows:
+#   Epic: payment-system-backend  [████████░░] 80% (8/10 tasks)
+#   Epic: payment-system-frontend [████░░░░░░] 40% (4/10 tasks)
+#   Epic: payment-system-security [░░░░░░░░░░]  0% (0/8 tasks)
+#   Overall: 44% complete (12/28 tasks)
+```
+
+**When to split PRDs:**
+- ✅ Feature requires multiple specialized teams (frontend, backend, DevOps)
+- ✅ Different components have separate deployment timelines
+- ✅ Epic would exceed 15-20 tasks (becomes hard to manage)
+- ✅ Clear architectural boundaries exist (UI, API, infrastructure)
+
+**Best practices:**
+- 📝 Keep original PRD as the source of truth
+- 🏷️ Use consistent naming: `<prd-name>-<component>`
+- 🔗 Link epics back to parent PRD in description
+- 📊 Track overall progress across all child epics
+- 🎯 Each epic should be independently deployable when possible
+
 #### **Issue Lifecycle**
 ```bash
 # Start working on an issue

package/autopm/.claude/mcp/context7-docs.md

@@ -3,11 +3,26 @@ name: context7-docs
 command: npx
 args: ["@context7/mcp-server"]
 env:
-  CONTEXT7_API_KEY: "${CONTEXT7_API_KEY:-}"
-  CONTEXT7_MCP_URL: "${CONTEXT7_MCP_URL:-mcp.context7.com/mcp}"
-  CONTEXT7_API_URL: "${CONTEXT7_API_URL:-context7.com/api/v1}"
-  CONTEXT7_WORKSPACE: "${CONTEXT7_WORKSPACE:-}"
-  CONTEXT7_MODE: "documentation"
+  CONTEXT7_API_KEY:
+    default: ""
+    description: "Your Context7 API key"
+    required: true
+  CONTEXT7_MCP_URL:
+    default: "https://mcp.context7.com/mcp"
+    description: "MCP endpoint URL"
+    required: false
+  CONTEXT7_API_URL:
+    default: "https://context7.com/api/v1"
+    description: "API endpoint URL"
+    required: false
+  CONTEXT7_WORKSPACE:
+    default: "default"
+    description: "Your workspace identifier (uses default workspace if not set)"
+    required: false
+  CONTEXT7_MODE:
+    default: "documentation"
+    description: "Server mode"
+    required: false
 envFile: .claude/.env
 description: Context7 documentation server for accessing technical documentation
 category: documentation

package/autopm/.claude/scripts/pm/prd-new.js

@@ -94,12 +94,8 @@ class PrdCreator {
       console.log('\n✅ PRD created successfully!');
       console.log(`📄 File: ${prdFile}`);
 
-      // Show next steps
-      console.log('\n💡 Next Steps:');
-      console.log(`  1. Review PRD file: .claude/prds/${prdName}.md`);
-      console.log(`  2. Convert to epic: /pm:prd-parse ${prdName}`);
-      console.log(`  3. Check status: /pm:prd-status ${prdName}`);
-      console.log(`  4. List all PRDs: /pm:prd-list`);
+      // Show comprehensive next steps
+      this.showNextSteps(prdName);
 
     } finally {
       rl.close();
@@ -108,6 +104,46 @@ class PrdCreator {
     return true;
   }
 
+  showNextSteps(prdName) {
+    console.log('\n' + '═'.repeat(60));
+    console.log('📋 What You Can Do Next:');
+    console.log('═'.repeat(60) + '\n');
+
+    console.log('🎯 Option 1: Quick Start (Recommended for Simple Features)');
+    console.log('   One command to parse, decompose, and sync to GitHub:');
+    console.log(`   /pm:epic-oneshot ${prdName}`);
+    console.log('   ✨ This creates epic + tasks + GitHub issues automatically\n');
+
+    console.log('🔀 Option 2: Split into Multiple Epics (For Complex Features)');
+    console.log('   Break down large PRD into focused sub-epics:');
+    console.log(`   /pm:prd-split ${prdName}`);
+    console.log('   Example: payment-system → backend, frontend, security');
+    console.log('   📚 See README section "Splitting Large PRDs into Multiple Epics"\n');
+
+    console.log('🛠️  Option 3: Step-by-Step Workflow (Full Control)');
+    console.log('   a) Convert PRD to epic:');
+    console.log(`      /pm:prd-parse ${prdName}`);
+    console.log('   b) Break epic into tasks:');
+    console.log(`      /pm:epic-decompose ${prdName}`);
+    console.log('   c) Push to GitHub/Azure:');
+    console.log(`      /pm:epic-sync ${prdName}\n`);
+
+    console.log('📝 Option 4: Review & Edit First');
+    console.log('   Review and refine the PRD before processing:');
+    console.log(`   nano .claude/prds/${prdName}.md`);
+    console.log('   Then use any option above\n');
+
+    console.log('📊 Option 5: Check Status');
+    console.log('   View PRD and track progress:');
+    console.log(`   /pm:prd-status ${prdName}\n`);
+
+    console.log(`💡 Don't know which to choose?`);
+    console.log('   • Small feature (< 10 tasks)? → Use Option 1 (/pm:epic-oneshot)');
+    console.log('   • Large feature (15+ tasks)? → Use Option 2 (/pm:prd-split)');
+    console.log('   • Need full control? → Use Option 3 (step-by-step)');
+    console.log('');
+  }
+
   generatePrdContent(name, data) {
     const timestamp = new Date().toISOString();
     const author = process.env.USER || 'unknown';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-autopm",
-  "version": "1.13.2",
+  "version": "1.13.4",
   "description": "Autonomous Project Management Framework for Claude Code - Advanced AI-powered development automation",
   "main": "bin/autopm.js",
   "bin": {

package/scripts/mcp-handler.js

@@ -1098,13 +1098,74 @@ This server can be integrated with various agents and context pools.
       console.log();
     }
 
-    // Show missing env vars details
+    // Show missing env vars details with help
     if (checkResult.missingEnvVars.length > 0) {
-      console.log('🔑 Missing Environment Variables:\n');
+      console.log('🔑 Environment Variables Status:\n');
       const byServer = Object.groupBy(checkResult.missingEnvVars, ({ server }) => server);
-      Object.entries(byServer).forEach(([server, entries]) => {
-        console.log(`   ${server}:`);
-        entries.forEach(({ variable }) => console.log(`      - ${variable}`));
+
+      Object.entries(byServer).forEach(([serverName, entries]) => {
+        const server = this.getServer(serverName);
+        console.log(`   📦 ${serverName}:`);
+
+        // Categorize as required or optional
+        const required = [];
+        const optional = [];
+
+        entries.forEach(({ variable }) => {
+          const envDef = server?.metadata?.env?.[variable];
+          if (this._hasNonEmptyDefault(envDef)) {
+            optional.push({ name: variable, default: envDef.default, desc: envDef.description });
+          } else {
+            required.push({ name: variable, desc: envDef?.description || 'No description' });
+          }
+        });
+
+        if (required.length > 0) {
+          console.log('      ❌ REQUIRED (must be set):');
+          required.forEach(v => {
+            console.log(`         • ${v.name}`);
+            if (v.desc) console.log(`           ${v.desc}`);
+          });
+        }
+
+        if (optional.length > 0) {
+          console.log('      ⚠️  OPTIONAL (have defaults):');
+          optional.forEach(v => {
+            console.log(`         • ${v.name} = ${v.default}`);
+            if (v.desc) console.log(`           ${v.desc}`);
+          });
+        }
+        console.log();
+      });
+
+      // Show configuration instructions
+      console.log('📝 How to Configure:\n');
+      console.log('   1. Edit file: .claude/.env\n');
+      console.log('   2. Add required variables:\n');
+
+      Object.entries(byServer).forEach(([serverName, entries]) => {
+        const server = this.getServer(serverName);
+        console.log(`      # ${serverName}`);
+        entries.forEach(({ variable }) => {
+          const envDef = server?.metadata?.env?.[variable];
+          if (this._hasNonEmptyDefault(envDef)) {
+            console.log(`      # ${variable}=${envDef.default}  (optional)`);
+          } else {
+            const example = this._getEnvVarExample(serverName, variable);
+            console.log(`      ${variable}=${example}`);
+          }
+        });
+        console.log();
+      });
+
+      // Show where to get credentials
+      console.log('🔐 Where to Get API Keys:\n');
+      Object.keys(byServer).forEach(serverName => {
+        const info = this._getCredentialInfo(serverName);
+        if (info) {
+          console.log(`   ${serverName}:`);
+          console.log(`      ${info}`);
+        }
       });
       console.log();
     }
@@ -1116,19 +1177,73 @@ This server can be integrated with various agents and context pools.
       console.log();
     }
 
-    console.log('🔧 Quick Fix:');
+    // Step-by-step fix
+    console.log('🛠️  Step-by-Step Fix:\n');
+    let step = 1;
+
     if (Array.isArray(checkResult.disabledServers) && checkResult.disabledServers.length > 0) {
+      console.log(`   ${step}. Enable MCP server(s):`);
       checkResult.disabledServers.forEach(server => {
-        console.log(`   autopm mcp enable ${server.name}`);
+        console.log(`      autopm mcp enable ${server.name}`);
       });
+      step++;
     }
+
     if (checkResult.missingEnvVars.length > 0) {
-      console.log(`   autopm mcp setup`);
+      console.log(`   ${step}. Edit .claude/.env and add required variables`);
+      console.log(`      nano .claude/.env  # or use your editor`);
+      step++;
     }
-    console.log(`   autopm mcp sync`);
+
+    console.log(`   ${step}. Sync MCP configuration:`);
+    console.log(`      autopm mcp sync`);
+    step++;
+
+    console.log(`   ${step}. Verify everything works:`);
+    console.log('      autopm mcp check');
     console.log();
   }
 
+  /**
+   * Get example value for environment variable
+   * @private
+   */
+  _getEnvVarExample(serverName, varName) {
+    const examples = {
+      'CONTEXT7_API_KEY': 'ctx7_1234567890abcdef',
+      'CONTEXT7_WORKSPACE': 'my-workspace-id',
+      'GITHUB_TOKEN': 'ghp_xxxxxxxxxxxxxxxxxxxx',
+      'AZURE_DEVOPS_PAT': 'your-pat-token-here'
+    };
+    return examples[varName] || 'your-value-here';
+  }
+
+  /**
+   * Get information about where to obtain credentials
+   * @private
+   */
+  _getCredentialInfo(serverName) {
+    const info = {
+      'context7-docs': '→ Sign up at https://context7.com and get API key from dashboard',
+      'context7-codebase': '→ Same credentials as context7-docs',
+      'github-mcp': '→ Generate token at https://github.com/settings/tokens',
+      'playwright-mcp': '→ No credentials needed - uses local Playwright installation'
+    };
+    return info[serverName] || '→ Check server documentation: autopm mcp info ' + serverName;
+  }
+
+  /**
+   * Check if environment variable definition has a non-empty default value
+   * @private
+   * @param {Object} envDef - Environment variable definition
+   * @returns {boolean} True if has non-empty default
+   */
+  _hasNonEmptyDefault(envDef) {
+    if (!envDef?.default) return false;
+    const defaultValue = String(envDef.default).trim();
+    return defaultValue !== '';
+  }
+
   /**
    * Run comprehensive MCP diagnostics
    * @returns {Object} Diagnostic results