claude-autopm 1.13.3 → 1.13.5

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.3",
+  "version": "1.13.5",
   "description": "Autonomous Project Management Framework for Claude Code - Advanced AI-powered development automation",
   "main": "bin/autopm.js",
   "bin": {

package/scripts/mcp-handler.js

@@ -228,35 +228,39 @@ class MCPHandler {
     const config = this.loadConfig();
     const activeServers = config.mcp?.activeServers || [];
 
-    // Ensure .claude directory exists even if no servers
+    // Ensure .claude directory exists
     this.ensureClaudeDir();
 
+    // Read existing mcp-servers.json to preserve all servers
+    let existingMcpConfig = { mcpServers: {}, contextPools: {}, documentationSources: {} };
+    if (fs.existsSync(this.mcpServersPath)) {
+      try {
+        const content = fs.readFileSync(this.mcpServersPath, 'utf8');
+        existingMcpConfig = JSON.parse(content);
+      } catch (error) {
+        console.log('⚠️  Could not read existing mcp-servers.json, creating new');
+      }
+    }
+
     if (activeServers.length === 0) {
-      console.log('ℹ️ No active servers to sync');
-      // Still create empty mcp-servers.json
-      const emptyConfig = {
-        mcpServers: {},
-        contextPools: config.mcp?.contextPools || {},
-        documentationSources: config.mcp?.documentationSources || {}
-      };
-      fs.writeFileSync(
-        this.mcpServersPath,
-        JSON.stringify(emptyConfig, null, 2)
-      );
+      console.log('ℹ️ No active servers in config.json');
+      console.log('💡 Preserving existing servers in mcp-servers.json');
+      console.log(`📊 Existing servers: ${Object.keys(existingMcpConfig.mcpServers).length}`);
       return;
     }
 
+    // Start with existing configuration
     const mcpConfig = {
-      mcpServers: {},
-      contextPools: config.mcp?.contextPools || {},
-      documentationSources: config.mcp?.documentationSources || {}
+      mcpServers: existingMcpConfig.mcpServers || {},
+      contextPools: existingMcpConfig.contextPools || {},
+      documentationSources: existingMcpConfig.documentationSources || {}
     };
 
-    // Process each active server
+    // Update active servers from registry
     activeServers.forEach(serverName => {
       const server = this.getServer(serverName);
       if (!server) {
-        console.log(`  ⚠️ Server '${serverName}' not found, skipping`);
+        console.log(`  ⚠️ Server '${serverName}' not found in registry, skipping`);
         return;
       }
 
@@ -278,6 +282,7 @@ class MCPHandler {
 
     console.log(`\n✅ Configuration synced to ${this.mcpServersPath}`);
     console.log(`📊 Active servers: ${activeServers.length}`);
+    console.log(`📦 Total servers in file: ${Object.keys(mcpConfig.mcpServers).length}`);
   }
 
   /**
@@ -1098,13 +1103,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 +1182,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