claude-autopm 1.13.1 → 1.13.3

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/bin/autopm.js

@@ -180,6 +180,29 @@ function main() {
     .command(require('./commands/config'))
     // MCP management command
     .command(require('./commands/mcp'))
+    // Validation command
+    .command('validate', 'Validate ClaudeAutoPM configuration and setup',
+      (yargs) => {
+        return yargs
+          .example('autopm validate', 'Check all configuration requirements')
+          .example('autopm validate --verbose', 'Show detailed validation info');
+      },
+      async (argv) => {
+        const PostInstallChecker = require('../install/post-install-check.js');
+        const checker = new PostInstallChecker();
+
+        try {
+          await checker.runAllChecks();
+          process.exit(0);
+        } catch (error) {
+          console.error(`❌ Validation error: ${error.message}`);
+          if (argv.debug) {
+            console.error(error.stack);
+          }
+          process.exit(1);
+        }
+      }
+    )
     // Global options
     .option('verbose', {
       type: 'boolean',
@@ -203,6 +226,7 @@ function main() {
     .epilogue(`
 📖 Quick Start:
    autopm install                    # Install ClaudeAutoPM in current directory
+   autopm validate                   # Check configuration status
    autopm update                     # Update to latest framework version
    autopm team load frontend         # Load React/UI development agents
    claude --dangerously-skip-permissions .     # Open Claude Code
@@ -392,7 +416,8 @@ function main() {
    → Updates epic progress tracking
 
 🛠️  Troubleshooting:
-   # Check installation
+   # Check installation and configuration
+   autopm validate                  # Comprehensive status check
    ls -la .claude/                  # Should show: agents/, commands/, config.json
 
    # Verify configuration

package/bin/commands/mcp.js

@@ -7,7 +7,7 @@ const path = require('path');
 const MCPHandler = require('../../scripts/mcp-handler.js');
 
 module.exports = {
-  command: 'mcp <action> [options]',
+  command: 'mcp <action> [name]',
   describe: 'Manage MCP (Model Context Protocol) servers and configuration',
 
   builder: (yargs) => {
@@ -20,6 +20,10 @@ module.exports = {
           'agents', 'agent', 'usage', 'setup', 'check', 'diagnose', 'test', 'tree', 'status'
         ]
       })
+      .positional('name', {
+        describe: 'Server or agent name (for actions that require it)',
+        type: 'string'
+      })
       .option('server', {
         alias: 's',
         describe: 'Server name',
@@ -64,27 +68,27 @@ module.exports = {
           break;
 
         case 'remove':
-          if (!argv.server && !argv._[2]) {
+          if (!argv.name && !argv.server) {
             console.error('❌ Please specify a server name: autopm mcp remove <server-name>');
             process.exit(1);
           }
-          handler.remove(argv.server || argv._[2]);
+          handler.remove(argv.name || argv.server);
           break;
 
         case 'enable':
-          if (!argv.server && !argv._[2]) {
+          if (!argv.name && !argv.server) {
             console.error('❌ Please specify a server name: autopm mcp enable <server-name>');
             process.exit(1);
           }
-          handler.enable(argv.server || argv._[2]);
+          handler.enable(argv.name || argv.server);
           break;
 
         case 'disable':
-          if (!argv.server && !argv._[2]) {
+          if (!argv.name && !argv.server) {
             console.error('❌ Please specify a server name: autopm mcp disable <server-name>');
             process.exit(1);
           }
-          handler.disable(argv.server || argv._[2]);
+          handler.disable(argv.name || argv.server);
           break;
 
         case 'sync':
@@ -96,11 +100,11 @@ module.exports = {
           break;
 
         case 'info':
-          if (!argv.server && !argv._[2]) {
+          if (!argv.name && !argv.server) {
             console.error('❌ Please specify a server name: autopm mcp info <server-name>');
             process.exit(1);
           }
-          handler.info(argv.server || argv._[2]);
+          handler.info(argv.name || argv.server);
           break;
 
         // Agent analysis commands
@@ -109,11 +113,11 @@ module.exports = {
           break;
 
         case 'agent':
-          if (!argv.agent && !argv._[2]) {
+          if (!argv.name && !argv.agent) {
             console.error('❌ Please specify an agent name: autopm mcp agent <agent-name>');
             process.exit(1);
           }
-          handler.mcpAgent(argv.agent || argv._[2]);
+          handler.mcpAgent(argv.name || argv.agent);
           break;
 
         case 'usage':
@@ -134,11 +138,11 @@ module.exports = {
           break;
 
         case 'test':
-          if (!argv.server && !argv._[2]) {
+          if (!argv.name && !argv.server) {
             console.error('❌ Please specify a server name: autopm mcp test <server-name>');
             process.exit(1);
           }
-          const result = await handler.testServer(argv.server || argv._[2]);
+          const result = await handler.testServer(argv.name || argv.server);
           if (result.success) {
             console.log(`✅ ${result.message}`);
           } else {

package/install/install.js

@@ -797,6 +797,18 @@ See: https://github.com/rafeekpro/ClaudeAutoPM
     }
   }
 
+  async runPostInstallCheck() {
+    const PostInstallChecker = require('./post-install-check.js');
+    const checker = new PostInstallChecker();
+
+    try {
+      await checker.runAllChecks();
+    } catch (error) {
+      this.printWarning(`Configuration check failed: ${error.message}`);
+      console.log('You can run the check later with: autopm config validate\n');
+    }
+  }
+
   async run() {
     // Handle help and version
     if (this.options.help) {
@@ -852,14 +864,8 @@ See: https://github.com/rafeekpro/ClaudeAutoPM
     this.printMsg('GREEN', '╚══════════════════════════════════════════╝');
     console.log('');
 
-    this.printSuccess('ClaudeAutoPM has been installed successfully!');
-    console.log('');
-    this.printStep('Next steps:');
-    console.log('  1. Review CLAUDE.md for project configuration');
-    console.log('  2. Run: ./scripts/setup-hooks.sh to setup git hooks');
-    console.log('  3. Open Claude Code in this directory');
-    console.log('  4. In Claude, run: /pm:validate');
-    console.log('');
+    // Run post-installation configuration check
+    await this.runPostInstallCheck();
 
     process.exit(0);
   }

package/install/post-install-check.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+
+/**
+ * Post-Installation Configuration Checker
+ * Validates that all required components are properly configured
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class PostInstallChecker {
+  constructor() {
+    this.projectRoot = process.cwd();
+    this.results = {
+      essential: [],
+      optional: [],
+      nextSteps: []
+    };
+  }
+
+  /**
+   * Run all configuration checks
+   */
+  async runAllChecks() {
+    console.log('\n╔════════════════════════════════════════════════════════════════╗');
+    console.log('║         🔍 ClaudeAutoPM Configuration Status                  ║');
+    console.log('╚════════════════════════════════════════════════════════════════╝\n');
+
+    // Essential checks
+    this.checkClaudeDirectory();
+    this.checkConfigFile();
+    this.checkProvider();
+    this.checkGitRepository();
+
+    // Optional but recommended
+    this.checkMCPConfiguration();
+    this.checkGitHooks();
+    this.checkNodeVersion();
+
+    // Display results
+    this.displayResults();
+    this.displayNextSteps();
+  }
+
+  /**
+   * Check if .claude directory exists
+   */
+  checkClaudeDirectory() {
+    const claudeDir = path.join(this.projectRoot, '.claude');
+    const exists = fs.existsSync(claudeDir);
+
+    this.results.essential.push({
+      name: '.claude directory',
+      status: exists,
+      message: exists
+        ? 'Framework installed'
+        : 'Not found - run: autopm install'
+    });
+
+    if (exists) {
+      // Check subdirectories
+      const subdirs = ['agents', 'commands', 'rules', 'scripts'];
+      subdirs.forEach(dir => {
+        const dirPath = path.join(claudeDir, dir);
+        const dirExists = fs.existsSync(dirPath);
+        this.results.optional.push({
+          name: `  └─ ${dir}/`,
+          status: dirExists,
+          message: dirExists ? 'Present' : 'Missing'
+        });
+      });
+    }
+  }
+
+  /**
+   * Check configuration file
+   */
+  checkConfigFile() {
+    const configPath = path.join(this.projectRoot, '.claude', 'config.json');
+    let config = null;
+
+    if (fs.existsSync(configPath)) {
+      try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        this.results.essential.push({
+          name: 'Configuration file',
+          status: true,
+          message: `Provider: ${config.provider || 'not set'}`
+        });
+        this.config = config;
+      } catch (error) {
+        this.results.essential.push({
+          name: 'Configuration file',
+          status: false,
+          message: 'Invalid JSON format'
+        });
+      }
+    } else {
+      this.results.essential.push({
+        name: 'Configuration file',
+        status: false,
+        message: 'Not found'
+      });
+    }
+  }
+
+  /**
+   * Check provider configuration (GitHub or Azure DevOps)
+   */
+  checkProvider() {
+    if (!this.config) {
+      this.results.essential.push({
+        name: 'Provider setup',
+        status: false,
+        message: 'No configuration file'
+      });
+      this.results.nextSteps.push('Run: autopm config set provider github|azure');
+      return;
+    }
+
+    const provider = this.config.provider;
+
+    if (!provider) {
+      this.results.essential.push({
+        name: 'Provider setup',
+        status: false,
+        message: 'Provider not configured'
+      });
+      this.results.nextSteps.push('Run: autopm config set provider github|azure');
+      return;
+    }
+
+    // Check GitHub configuration
+    if (provider === 'github') {
+      const hasToken = !!process.env.GITHUB_TOKEN;
+      const hasOwner = !!this.config.github?.owner;
+      const hasRepo = !!this.config.github?.repo;
+
+      this.results.essential.push({
+        name: 'GitHub Provider',
+        status: hasToken && hasOwner && hasRepo,
+        message: this.getGitHubStatus(hasToken, hasOwner, hasRepo)
+      });
+
+      if (!hasToken) {
+        this.results.nextSteps.push('Set GITHUB_TOKEN environment variable');
+      }
+      if (!hasOwner || !hasRepo) {
+        this.results.nextSteps.push('Run: autopm config set github.owner <username>');
+        this.results.nextSteps.push('Run: autopm config set github.repo <repository>');
+      }
+    }
+
+    // Check Azure DevOps configuration
+    if (provider === 'azure') {
+      const hasToken = !!process.env.AZURE_DEVOPS_PAT;
+      const hasOrg = !!this.config.azure?.organization;
+      const hasProject = !!this.config.azure?.project;
+
+      this.results.essential.push({
+        name: 'Azure DevOps Provider',
+        status: hasToken && hasOrg && hasProject,
+        message: this.getAzureStatus(hasToken, hasOrg, hasProject)
+      });
+
+      if (!hasToken) {
+        this.results.nextSteps.push('Set AZURE_DEVOPS_PAT environment variable');
+      }
+      if (!hasOrg || !hasProject) {
+        this.results.nextSteps.push('Run: autopm config set azure.organization <org>');
+        this.results.nextSteps.push('Run: autopm config set azure.project <project>');
+      }
+    }
+  }
+
+  /**
+   * Get GitHub configuration status message
+   */
+  getGitHubStatus(hasToken, hasOwner, hasRepo) {
+    if (hasToken && hasOwner && hasRepo) {
+      return `Configured: ${this.config.github.owner}/${this.config.github.repo}`;
+    }
+    const missing = [];
+    if (!hasToken) missing.push('token');
+    if (!hasOwner) missing.push('owner');
+    if (!hasRepo) missing.push('repo');
+    return `Missing: ${missing.join(', ')}`;
+  }
+
+  /**
+   * Get Azure DevOps configuration status message
+   */
+  getAzureStatus(hasToken, hasOrg, hasProject) {
+    if (hasToken && hasOrg && hasProject) {
+      return `Configured: ${this.config.azure.organization}/${this.config.azure.project}`;
+    }
+    const missing = [];
+    if (!hasToken) missing.push('PAT');
+    if (!hasOrg) missing.push('organization');
+    if (!hasProject) missing.push('project');
+    return `Missing: ${missing.join(', ')}`;
+  }
+
+  /**
+   * Check MCP server configuration
+   */
+  checkMCPConfiguration() {
+    const mcpServersPath = path.join(this.projectRoot, '.claude', 'mcp-servers.json');
+    const envPath = path.join(this.projectRoot, '.claude', '.env');
+
+    let mcpConfigured = false;
+    let message = 'Not configured';
+
+    if (fs.existsSync(mcpServersPath)) {
+      try {
+        const mcpConfig = JSON.parse(fs.readFileSync(mcpServersPath, 'utf8'));
+        const serverCount = Object.keys(mcpConfig.mcpServers || {}).length;
+
+        if (serverCount > 0) {
+          mcpConfigured = true;
+          message = `${serverCount} server(s) configured`;
+        } else {
+          message = 'No servers enabled';
+        }
+      } catch (error) {
+        message = 'Invalid configuration';
+      }
+    }
+
+    this.results.optional.push({
+      name: 'MCP Servers',
+      status: mcpConfigured,
+      message: message
+    });
+
+    const hasEnv = fs.existsSync(envPath);
+    this.results.optional.push({
+      name: 'MCP Environment',
+      status: hasEnv,
+      message: hasEnv ? 'Environment file exists' : 'No .env file'
+    });
+
+    if (!mcpConfigured) {
+      this.results.nextSteps.push('Run: autopm mcp check (to see MCP requirements)');
+    }
+  }
+
+  /**
+   * Check Git repository
+   */
+  checkGitRepository() {
+    try {
+      execSync('git rev-parse --is-inside-work-tree', {
+        stdio: 'pipe',
+        cwd: this.projectRoot
+      });
+
+      this.results.essential.push({
+        name: 'Git repository',
+        status: true,
+        message: 'Initialized'
+      });
+    } catch (error) {
+      this.results.essential.push({
+        name: 'Git repository',
+        status: false,
+        message: 'Not initialized'
+      });
+      this.results.nextSteps.push('Run: git init');
+    }
+  }
+
+  /**
+   * Check Git hooks installation
+   */
+  checkGitHooks() {
+    const hooksDir = path.join(this.projectRoot, '.git', 'hooks');
+    const preCommit = path.join(hooksDir, 'pre-commit');
+    const prePush = path.join(hooksDir, 'pre-push');
+
+    const hasPreCommit = fs.existsSync(preCommit);
+    const hasPrePush = fs.existsSync(prePush);
+
+    this.results.optional.push({
+      name: 'Git hooks',
+      status: hasPreCommit || hasPrePush,
+      message: hasPreCommit && hasPrePush
+        ? 'Installed'
+        : hasPreCommit || hasPrePush
+          ? 'Partially installed'
+          : 'Not installed'
+    });
+  }
+
+  /**
+   * Check Node.js version
+   */
+  checkNodeVersion() {
+    const version = process.version;
+    const major = parseInt(version.split('.')[0].substring(1));
+    const isSupported = major >= 18;
+
+    this.results.optional.push({
+      name: 'Node.js version',
+      status: isSupported,
+      message: isSupported
+        ? `${version} (supported)`
+        : `${version} (upgrade recommended)`
+    });
+
+    if (!isSupported) {
+      this.results.nextSteps.push('Upgrade Node.js to v18 or higher');
+    }
+  }
+
+  /**
+   * Display check results
+   */
+  displayResults() {
+    console.log('📋 Essential Components:\n');
+
+    this.results.essential.forEach(check => {
+      const icon = check.status ? '✅' : '❌';
+      const status = check.status ? 'OK' : 'MISSING';
+      console.log(`${icon} ${check.name.padEnd(25)} ${status.padEnd(10)} ${check.message}`);
+    });
+
+    if (this.results.optional.length > 0) {
+      console.log('\n🔧 Optional Components:\n');
+
+      this.results.optional.forEach(check => {
+        const icon = check.status ? '✅' : '⚪';
+        console.log(`${icon} ${check.name.padEnd(25)} ${check.message}`);
+      });
+    }
+
+    console.log('\n' + '─'.repeat(70) + '\n');
+
+    // Overall status
+    const essentialPassed = this.results.essential.every(c => c.status);
+
+    if (essentialPassed) {
+      console.log('✅ All essential components are configured!\n');
+    } else {
+      console.log('⚠️  Some essential components need configuration\n');
+    }
+  }
+
+  /**
+   * Display next steps
+   */
+  displayNextSteps() {
+    if (this.results.nextSteps.length === 0) {
+      console.log('🚀 Ready to start! Try:\n');
+      console.log('   claude --dangerously-skip-permissions .');
+      console.log('   /pm:validate\n');
+      return;
+    }
+
+    console.log('📝 Next Steps:\n');
+
+    this.results.nextSteps.forEach((step, index) => {
+      console.log(`   ${index + 1}. ${step}`);
+    });
+
+    console.log('\n💡 Quick Setup:\n');
+    console.log('   autopm config show        # View current configuration');
+    console.log('   autopm config validate    # Validate settings');
+    console.log('   autopm mcp check          # Check MCP requirements');
+    console.log('   autopm --help             # See all commands\n');
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  const checker = new PostInstallChecker();
+  checker.runAllChecks().catch(error => {
+    console.error('Error during configuration check:', error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = PostInstallChecker;

package/package.json

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