claude-autopm 1.15.5 → 1.17.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/autopm/scripts/epic-status.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+
+# Epic Status Checker
+# Part of ClaudeAutoPM Framework
+# Usage: ./scripts/epic-status.sh [epic-name]
+
+EPIC_NAME=${1:-}
+
+if [ -z "$EPIC_NAME" ]; then
+    echo "Usage: $0 <epic-name>"
+    echo ""
+    echo "Available epics:"
+    if [ -d ".claude/epics" ]; then
+        ls -1 .claude/epics/ 2>/dev/null || echo "No epics found"
+    else
+        echo "No .claude/epics directory found"
+    fi
+    exit 1
+fi
+
+EPIC_DIR=".claude/epics/$EPIC_NAME"
+
+if [ ! -d "$EPIC_DIR" ]; then
+    echo "Error: Epic '$EPIC_NAME' not found"
+    echo ""
+    echo "Available epics:"
+    ls -1 .claude/epics/ 2>/dev/null
+    exit 1
+fi
+
+echo "Epic: $EPIC_NAME"
+echo "===================="
+echo ""
+
+# Count total tasks
+total_tasks=$(find "$EPIC_DIR" -maxdepth 2 -name "[0-9][0-9][0-9].md" 2>/dev/null | wc -l | tr -d ' ')
+
+# Count completed tasks (looking for status: completed in frontmatter)
+completed=0
+in_progress=0
+pending=0
+
+for task_file in $(find "$EPIC_DIR" -maxdepth 2 -name "[0-9][0-9][0-9].md" 2>/dev/null); do
+    if grep -q "^status: completed" "$task_file" 2>/dev/null; then
+        completed=$((completed + 1))
+    elif grep -q "^status: in-progress\|^status: in_progress" "$task_file" 2>/dev/null; then
+        in_progress=$((in_progress + 1))
+    else
+        pending=$((pending + 1))
+    fi
+done
+
+# Calculate progress percentage
+if [ "$total_tasks" -gt 0 ]; then
+    progress=$((completed * 100 / total_tasks))
+else
+    progress=0
+fi
+
+echo "Total tasks:     $total_tasks"
+echo "Completed:       $completed ($progress%)"
+echo "In Progress:     $in_progress"
+echo "Pending:         $pending"
+echo ""
+
+# Progress bar
+if [ "$total_tasks" -gt 0 ]; then
+    bar_length=50
+    filled=$((progress * bar_length / 100))
+    empty=$((bar_length - filled))
+
+    printf "Progress: ["
+    printf "%${filled}s" | tr ' ' '='
+    printf "%${empty}s" | tr ' ' '-'
+    printf "] %d%%\n" "$progress"
+    echo ""
+fi
+
+# Show breakdown by sub-epic if they exist
+sub_dirs=$(find "$EPIC_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+
+if [ "$sub_dirs" -gt 0 ]; then
+    echo "Sub-Epic Breakdown:"
+    echo "-------------------"
+
+    for sub_dir in "$EPIC_DIR"/*/; do
+        if [ -d "$sub_dir" ]; then
+            sub_name=$(basename "$sub_dir")
+            sub_count=$(find "$sub_dir" -maxdepth 1 -name "[0-9][0-9][0-9].md" 2>/dev/null | wc -l | tr -d ' ')
+
+            if [ "$sub_count" -gt 0 ]; then
+                # Count completed in sub-epic
+                sub_completed=0
+                for task_file in $(find "$sub_dir" -maxdepth 1 -name "[0-9][0-9][0-9].md" 2>/dev/null); do
+                    if grep -q "^status: completed" "$task_file" 2>/dev/null; then
+                        sub_completed=$((sub_completed + 1))
+                    fi
+                done
+
+                printf "  %-30s %3d tasks (%d completed)\n" "$sub_name" "$sub_count" "$sub_completed"
+            fi
+        fi
+    done
+fi

package/bin/autopm.js

@@ -180,6 +180,8 @@ function main() {
     .command(require('./commands/config'))
     // MCP management command
     .command(require('./commands/mcp'))
+    // Epic management command
+    .command(require('./commands/epic'))
     // Validation command
     .command('validate', 'Validate ClaudeAutoPM configuration and setup',
       (yargs) => {

package/bin/commands/epic.js

@@ -0,0 +1,161 @@
+/**
+ * Epic Command for autopm CLI
+ * Manages epic status, breakdown, and analysis
+ */
+
+const path = require('path');
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+module.exports = {
+  command: 'epic <action> [name]',
+  describe: 'Manage epics and view epic status',
+
+  builder: (yargs) => {
+    return yargs
+      .positional('action', {
+        describe: 'Epic action to perform',
+        type: 'string',
+        choices: ['status', 'list', 'breakdown']
+      })
+      .positional('name', {
+        describe: 'Epic name (for status action)',
+        type: 'string'
+      })
+      .option('detailed', {
+        alias: 'd',
+        describe: 'Show detailed breakdown',
+        type: 'boolean',
+        default: false
+      })
+      .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');
+  },
+
+  handler: async (argv) => {
+    const action = argv.action;
+    const name = argv.name;
+
+    try {
+      switch (action) {
+        case 'list':
+          listEpics();
+          break;
+
+        case 'status':
+          if (!name) {
+            console.error('Error: Epic name required for status action');
+            console.log('Usage: autopm epic status <epic-name>');
+            process.exit(1);
+          }
+          showEpicStatus(name);
+          break;
+
+        case 'breakdown':
+          if (!name) {
+            console.error('Error: Epic name required for breakdown action');
+            console.log('Usage: autopm epic breakdown <epic-name>');
+            process.exit(1);
+          }
+          showEpicBreakdown(name);
+          break;
+
+        default:
+          console.error(`Unknown action: ${action}`);
+          process.exit(1);
+      }
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    }
+  }
+};
+
+function listEpics() {
+  const epicsDir = path.join(process.cwd(), '.claude', 'epics');
+
+  if (!fs.existsSync(epicsDir)) {
+    console.log('No epics found. Create epics with /pm:epic-split or /pm:epic-decompose');
+    return;
+  }
+
+  const epics = fs.readdirSync(epicsDir).filter(f => {
+    return fs.statSync(path.join(epicsDir, f)).isDirectory();
+  });
+
+  if (epics.length === 0) {
+    console.log('No epics found. Create epics with /pm:epic-split or /pm:epic-decompose');
+    return;
+  }
+
+  console.log('Available Epics:');
+  console.log('================\n');
+
+  epics.forEach(epic => {
+    console.log(`  • ${epic}`);
+  });
+
+  console.log('');
+  console.log('Use: autopm epic status <epic-name> to see details');
+}
+
+function showEpicStatus(epicName) {
+  const scriptPath = path.join(process.cwd(), 'scripts', 'epic-status.sh');
+
+  if (!fs.existsSync(scriptPath)) {
+    console.error('Error: epic-status.sh script not found');
+    console.error('Run: autopm install to get the latest scripts');
+    process.exit(1);
+  }
+
+  try {
+    execSync(`bash "${scriptPath}" "${epicName}"`, {
+      stdio: 'inherit',
+      cwd: process.cwd()
+    });
+  } catch (error) {
+    process.exit(error.status || 1);
+  }
+}
+
+function showEpicBreakdown(epicName) {
+  const epicDir = path.join(process.cwd(), '.claude', 'epics', epicName);
+
+  if (!fs.existsSync(epicDir)) {
+    console.error(`Error: Epic '${epicName}' not found`);
+    process.exit(1);
+  }
+
+  console.log(`Epic Breakdown: ${epicName}`);
+  console.log('='.repeat(50));
+  console.log('');
+
+  // Find all task files
+  const findTasks = (dir, prefix = '') => {
+    const items = fs.readdirSync(dir);
+
+    items.forEach(item => {
+      const itemPath = path.join(dir, item);
+      const stat = fs.statSync(itemPath);
+
+      if (stat.isDirectory()) {
+        console.log(`\n${prefix}📁 ${item}`);
+        findTasks(itemPath, prefix + '  ');
+      } else if (item.match(/^\d{3}\.md$/)) {
+        const content = fs.readFileSync(itemPath, 'utf-8');
+        const titleMatch = content.match(/^#\s+(.+)$/m);
+        const statusMatch = content.match(/^status:\s+(.+)$/m);
+
+        const title = titleMatch ? titleMatch[1] : item;
+        const status = statusMatch ? statusMatch[1] : 'pending';
+
+        const icon = status === 'completed' ? '✅' : status === 'in-progress' ? '🔄' : '⚪';
+
+        console.log(`${prefix}  ${icon} ${item}: ${title}`);
+      }
+    });
+  };
+
+  findTasks(epicDir);
+}

package/install/install.js

@@ -38,6 +38,7 @@ class Installer {
       '.claude/agents',
       '.claude/commands',
       '.claude/rules',
+      '.claude/hooks',
       '.claude/scripts',
       '.claude/checklists',
       '.claude/strategies',
@@ -323,7 +324,8 @@ ${this.colors.BOLD}Examples:${this.colors.NC}
       'safe-commit.sh',
       'safe-commit.js',
       'setup-hooks.sh',
-      'setup-hooks.js'
+      'setup-hooks.js',
+      'epic-status.sh'
     ];
 
     for (const script of scripts) {

package/package.json

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