claude-autopm 1.16.0 → 1.18.0

package/autopm/.claude/rules/agent-mandatory.md

@@ -0,0 +1,170 @@
+# Agent Usage - MANDATORY
+
+**🚨 CRITICAL: This rule has HIGHEST PRIORITY and MUST be followed for ALL tasks.**
+
+## Core Requirement
+
+**YOU MUST USE SPECIALIZED AGENTS FOR ALL NON-TRIVIAL TASKS.**
+
+Do NOT perform complex tasks yourself. Use the Task tool to delegate to appropriate agents.
+
+## When to Use Agents
+
+### ✅ ALWAYS Use Agents For:
+
+1. **Writing Code** (any language)
+   - Use: `python-backend-engineer`, `react-frontend-engineer`, `nodejs-backend-engineer`
+   - Example: "I need to create an API endpoint" → Use python-backend-engineer
+
+2. **Testing**
+   - Use: `test-runner`, `frontend-testing-engineer`, `e2e-test-engineer`
+   - Example: "Run the test suite" → Use test-runner
+
+3. **Infrastructure/DevOps**
+   - Use: `kubernetes-orchestrator`, `docker-containerization-expert`, `terraform-infrastructure-expert`
+   - Example: "Deploy to Kubernetes" → Use kubernetes-orchestrator
+
+4. **Database Work**
+   - Use: `postgresql-expert`, `mongodb-expert`, `bigquery-expert`
+   - Example: "Design database schema" → Use postgresql-expert
+
+5. **Code Analysis**
+   - Use: `code-analyzer`
+   - Example: "Review this code for bugs" → Use code-analyzer
+
+6. **GitHub/Azure DevOps Operations**
+   - Use: `github-operations-specialist`, `azure-devops-specialist`
+   - Example: "Create a PR" → Use github-operations-specialist
+
+7. **Large File Analysis**
+   - Use: `file-analyzer`
+   - Example: "Summarize this 10k line log file" → Use file-analyzer
+
+### ⚪ Can Do Yourself:
+
+1. **Simple file reads** (1-2 files, quick lookup)
+2. **Simple bash commands** (ls, pwd, basic git commands)
+3. **Answering questions** about existing code/documentation
+4. **Creating todo lists** with TodoWrite
+
+## Agent Selection Guide
+
+### By Task Type
+
+| Task | Agent | Example |
+|------|-------|---------|
+| Python API development | `python-backend-engineer` | Build FastAPI endpoint |
+| React component | `react-frontend-engineer` | Create dashboard UI |
+| Database schema | `postgresql-expert` | Design user tables |
+| Kubernetes deployment | `kubernetes-orchestrator` | Deploy to K8s cluster |
+| Docker container | `docker-containerization-expert` | Create Dockerfile |
+| GitHub workflow | `github-operations-specialist` | Setup CI/CD |
+| Code review | `code-analyzer` | Find bugs in PR |
+| Test execution | `test-runner` | Run test suite |
+| Log analysis | `file-analyzer` | Parse 50MB log file |
+
+### By Technology
+
+| Technology | Primary Agent | Secondary Agent |
+|------------|---------------|-----------------|
+| Python/FastAPI | `python-backend-engineer` | `postgresql-expert` for DB |
+| React/Next.js | `react-frontend-engineer` | `tailwindcss-expert` for styles |
+| Node.js/Express | `nodejs-backend-engineer` | `mongodb-expert` for DB |
+| TypeScript | `javascript-frontend-engineer` | Language-specific |
+| Kubernetes | `kubernetes-orchestrator` | `docker-containerization-expert` |
+| Terraform | `terraform-infrastructure-expert` | Cloud-specific architects |
+| Testing | `test-runner` | `frontend-testing-engineer` |
+
+## Violation Examples
+
+### ❌ WRONG - Doing It Yourself:
+
+```
+User: "Create a FastAPI endpoint for user registration"
+You: *writes Python code directly*
+```
+
+### ✅ CORRECT - Using Agent:
+
+```
+User: "Create a FastAPI endpoint for user registration"
+You: "I'll use the python-backend-engineer agent to create this endpoint"
+*Uses Task tool with python-backend-engineer*
+```
+
+### ❌ WRONG - Not Using Agent for Analysis:
+
+```
+User: "Review this 5000 line file for security issues"
+You: *reads file and tries to analyze*
+```
+
+### ✅ CORRECT - Using Agent:
+
+```
+User: "Review this 5000 line file for security issues"
+You: "I'll use the code-analyzer agent to review this file"
+*Uses Task tool with code-analyzer*
+```
+
+## How to Use Agents
+
+### Single Task:
+
+```markdown
+I'll use the [agent-name] agent to [task description].
+```
+
+Then invoke Task tool:
+- `subagent_type`: Agent name (e.g., "python-backend-engineer")
+- `description`: Short task description
+- `prompt`: Detailed task requirements
+
+### Multiple Parallel Tasks:
+
+```markdown
+I'll launch multiple agents in parallel:
+1. python-backend-engineer - Create API endpoints
+2. react-frontend-engineer - Build dashboard UI
+3. postgresql-expert - Design database schema
+```
+
+Then invoke multiple Task tools IN SINGLE MESSAGE.
+
+## Active Team Agents
+
+**Check the "Active Team Agents" section at the top of CLAUDE.md** for the current list of available agents in this project.
+
+If you need an agent that's not listed, you can still use any agent from the registry. The active team list is just a convenience reference.
+
+## Common Mistakes to Avoid
+
+1. ❌ **Not reading Active Team Agents section** - Always check what agents are available
+2. ❌ **Writing code yourself for non-trivial tasks** - Use appropriate agent
+3. ❌ **Not using parallel agents** - Launch multiple agents when tasks are independent
+4. ❌ **Using wrong agent for task** - Match agent specialty to task type
+5. ❌ **Forgetting file-analyzer for large files** - Use it for files >1000 lines or logs
+
+## Enforcement
+
+This rule is enforced through:
+
+1. **Git Hooks** - Pre-commit checks for agent usage patterns
+2. **Code Review** - Human reviewers check for proper agent delegation
+3. **Self-Monitoring** - You must self-enforce and explain why you're using/not using agents
+
+## Questions?
+
+If you're unsure whether to use an agent:
+- **Default: YES, use an agent**
+- When in doubt, delegate to specialist
+- Better to over-use agents than under-use them
+
+## Summary
+
+**Before doing ANY complex task, ask yourself:**
+1. Is there a specialized agent for this?
+2. Would an agent do this better/faster/more thoroughly?
+3. Am I trying to do something I should delegate?
+
+**If answer is YES to any → USE THE AGENT!**

package/autopm/.claude/templates/claude-templates/base.md

@@ -2,6 +2,26 @@
 
 > Think carefully and implement the most concise solution that changes as little code as possible.
 
+## 🚨 AGENT USAGE - MANDATORY
+
+**CRITICAL: You MUST use specialized agents for ALL non-trivial tasks.**
+
+See: `.claude/rules/agent-mandatory.md` for complete enforcement rules.
+
+### Quick Reference - When to Use Agents:
+
+| Task Type | Agent | Example |
+|-----------|-------|---------|
+| Python code | `python-backend-engineer` | Build FastAPI endpoint |
+| React/UI | `react-frontend-engineer` | Create dashboard component |
+| Testing | `test-runner` | Run test suite |
+| Database | `postgresql-expert`, `mongodb-expert` | Design schema |
+| DevOps | `kubernetes-orchestrator`, `docker-containerization-expert` | Deploy app |
+| Code review | `code-analyzer` | Find bugs/security issues |
+| Large files | `file-analyzer` | Parse logs >1000 lines |
+
+**Before doing ANY complex task**: Check if there's a specialized agent. If YES → USE IT!
+
 ## Active Team Agents
 
 <!-- AGENTS_START -->
@@ -13,10 +33,14 @@
 
 All rule files in `.claude/rules/` define mandatory behaviors and must be followed:
 
-### Core Development Rules
+### 🚨 HIGHEST PRIORITY Rules
 
-- **tdd.enforcement.md** - Test-Driven Development cycle (RED-GREEN-REFACTOR). HIGHEST PRIORITY for all code changes
+- **agent-mandatory.md** - MANDATORY agent usage for all non-trivial tasks. READ THIS FIRST!
+- **tdd.enforcement.md** - Test-Driven Development cycle (RED-GREEN-REFACTOR)
 - **pipeline-mandatory.md** - Required pipelines for errors, features, bugs, code search, and log analysis
+
+### Core Development Rules
+
 - **naming-conventions.md** - Naming standards, code quality requirements, and prohibited patterns
 - **context-optimization.md** - Agent usage patterns for context preservation (<20% data return)
 - **development-workflow.md** - Development patterns, search-before-create, and best practices

package/bin/commands/team.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const MCPHandler = require('../../scripts/mcp-handler.js');
 
 // Paths
 const projectRoot = process.cwd();
@@ -68,6 +69,69 @@ function validateAgentFiles(agents, projectRoot) {
   return missingAgents;
 }
 
+// Helper function to validate MCP dependencies for agents
+function validateAgentMCPDependencies(agents, projectRoot) {
+  const warnings = [];
+
+  try {
+    const mcpHandler = new MCPHandler();
+    const config = mcpHandler.loadConfig();
+    const activeServers = config.mcp?.activeServers || [];
+
+    // Track all required MCP servers across all agents
+    const requiredServers = new Map(); // server -> [agents that need it]
+
+    agents.forEach(agentPath => {
+      // Extract agent name from path
+      // Handle both "core/test-runner.md" and "test-runner.md" formats
+      let agentName = agentPath;
+      if (agentName.endsWith('.md')) {
+        agentName = agentName.slice(0, -3); // Remove .md extension
+      }
+      // Get just the filename without directory
+      agentName = path.basename(agentName);
+
+      // Get MCP dependencies for this agent
+      const agentMCP = mcpHandler.getAgentMCP(agentName);
+
+      if (agentMCP.found && agentMCP.mcpServers.length > 0) {
+        agentMCP.mcpServers.forEach(serverName => {
+          if (!requiredServers.has(serverName)) {
+            requiredServers.set(serverName, []);
+          }
+          requiredServers.get(serverName).push(agentName);
+        });
+      }
+    });
+
+    // Check which required servers are missing or inactive
+    requiredServers.forEach((agentNames, serverName) => {
+      const isActive = activeServers.includes(serverName);
+      const serverExists = mcpHandler.getServer(serverName);
+
+      if (!serverExists) {
+        warnings.push({
+          type: 'not_installed',
+          server: serverName,
+          agents: agentNames
+        });
+      } else if (!isActive) {
+        warnings.push({
+          type: 'not_active',
+          server: serverName,
+          agents: agentNames
+        });
+      }
+    });
+
+  } catch (error) {
+    // If MCP validation fails, just warn but don't block
+    console.warn('⚠️  Warning: Could not validate MCP dependencies');
+  }
+
+  return warnings;
+}
+
 // Helper function to generate agent include list in Markdown format
 function generateAgentIncludes(agents) {
   return agents
@@ -216,6 +280,28 @@ const commands = {
         });
       }
 
+      // Validate MCP dependencies
+      const mcpWarnings = validateAgentMCPDependencies(agents, projectRoot);
+      if (mcpWarnings.length > 0) {
+        console.warn('\n⚠️  MCP Dependency Warnings:\n');
+
+        mcpWarnings.forEach(warning => {
+          if (warning.type === 'not_installed') {
+            console.warn(`❌ MCP server '${warning.server}' is NOT INSTALLED`);
+            console.warn(`   Required by: ${warning.agents.join(', ')}`);
+            console.warn(`   Fix: autopm mcp install ${warning.server}`);
+          } else if (warning.type === 'not_active') {
+            console.warn(`⚪ MCP server '${warning.server}' is NOT ACTIVE`);
+            console.warn(`   Required by: ${warning.agents.join(', ')}`);
+            console.warn(`   Fix: autopm mcp enable ${warning.server}`);
+          }
+          console.warn('');
+        });
+
+        console.warn('💡 Tip: Run "autopm mcp list" to see all MCP servers');
+        console.warn('💡 Tip: Run "autopm mcp setup" for interactive configuration\n');
+      }
+
       // Update CLAUDE.md with the new agent list
       updateClaudeMd(agents);
       console.log('✓ Updated CLAUDE.md with team agents');

package/install/install.js

@@ -38,6 +38,7 @@ class Installer {
       '.claude/agents',
       '.claude/commands',
       '.claude/rules',
+      '.claude/hooks',
       '.claude/scripts',
       '.claude/checklists',
       '.claude/strategies',

package/package.json

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