claude-autopm 2.8.2 → 2.8.3

package/packages/plugin-core/hooks/pre-agent-context7.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-Agent Context7 Hook
+ *
+ * MANDATORY: This hook enforces Context7 documentation queries BEFORE agent invocation.
+ *
+ * Workflow:
+ * 1. Intercept agent invocation (e.g., @aws-cloud-architect)
+ * 2. Extract agent file path from .claude/agents/{category}/{agent}.md
+ * 3. Parse "Documentation Queries" section
+ * 4. Query Context7 MCP for each link
+ * 5. Inject results into agent context
+ * 6. Allow agent to proceed with Context7 knowledge
+ *
+ * Zero Tolerance: If Context7 query fails, agent invocation STOPS.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse agent invocation
+ * @param {string} agentInvocation - e.g., "@aws-cloud-architect design VPC"
+ * @returns {object} { agentName, task }
+ */
+function parseAgentInvocation(agentInvocation) {
+  // Remove @ symbol and split
+  const cleaned = agentInvocation.replace(/^@/, '');
+  const parts = cleaned.split(/\s+/);
+  const agentName = parts[0];
+  const task = parts.slice(1).join(' ');
+
+  return {
+    agentName,
+    task,
+    fullInvocation: agentInvocation
+  };
+}
+
+/**
+ * Find agent file in .claude/agents/
+ * @param {string} agentName - Agent name (aws-cloud-architect, test-runner, etc.)
+ * @returns {string|null} - Path to agent file or null
+ */
+function findAgentFile(agentName) {
+  const baseDir = path.join(process.cwd(), '.claude', 'agents');
+
+  // Search recursively in all subdirectories
+  function searchDir(dir) {
+    if (!fs.existsSync(dir)) return null;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const found = searchDir(fullPath);
+        if (found) return found;
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Check if filename matches (with or without .md extension)
+        const basename = path.basename(entry.name, '.md');
+        if (basename === agentName || basename.replace(/-/g, '_') === agentName) {
+          return fullPath;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  return searchDir(baseDir);
+}
+
+/**
+ * Extract Documentation Queries from agent file
+ * @param {string} filePath - Path to agent .md file
+ * @returns {Array<{url: string, description: string}>}
+ */
+function extractDocumentationQueries(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const queries = [];
+
+  // Find the Documentation Queries section (agent format)
+  const querySection = content.match(/\*\*Documentation Queries:\*\*\s*\n([\s\S]*?)(?=\n\n|\*\*|##|$)/);
+
+  if (!querySection) {
+    return queries; // No Documentation Queries section found
+  }
+
+  // Extract each mcp://context7/... line
+  const lines = querySection[1].split('\n');
+  for (const line of lines) {
+    const match = line.match(/`(mcp:\/\/context7\/[^`]+)`\s*-\s*(.+)/);
+    if (match) {
+      queries.push({
+        url: match[1],
+        description: match[2].trim()
+      });
+    }
+  }
+
+  return queries;
+}
+
+/**
+ * Query Context7 MCP server
+ * @param {string} mcpUrl - e.g., "mcp://context7/aws/compute"
+ * @returns {Promise<object>} - Context7 response
+ */
+async function queryContext7(mcpUrl) {
+  // Parse MCP URL: mcp://context7/category/topic
+  const urlMatch = mcpUrl.match(/mcp:\/\/context7\/(.+)/);
+  if (!urlMatch) {
+    throw new Error(`Invalid Context7 URL format: ${mcpUrl}`);
+  }
+
+  const topicPath = urlMatch[1]; // e.g., "aws/compute"
+
+  // In real implementation, this would call the MCP server
+  // For now, return a placeholder that instructs Claude to query
+  return {
+    url: mcpUrl,
+    topic: topicPath,
+    instruction: `MANDATORY: Query Context7 MCP for topic "${topicPath}" before implementing solution.`,
+    placeholder: true
+  };
+}
+
+/**
+ * Main hook execution
+ * @param {string} agentInvocation - Full agent invocation from user
+ */
+async function main(agentInvocation) {
+  console.log('\n🔒 Context7 Pre-Agent Hook Activated\n');
+
+  // Parse agent invocation
+  const { agentName, task, fullInvocation } = parseAgentInvocation(agentInvocation || process.argv[2] || '');
+
+  console.log(`🤖 Agent: @${agentName}`);
+  if (task) {
+    console.log(`   Task: ${task}`);
+  }
+
+  // Find agent file
+  const agentFile = findAgentFile(agentName);
+  if (!agentFile) {
+    console.log(`\n⚠️  Warning: Agent file not found for @${agentName}`);
+    console.log(`   Searched: .claude/agents/**/${agentName}.md`);
+    console.log(`   Proceeding without Context7 enforcement (agent may not exist)\n`);
+    return;
+  }
+
+  console.log(`   File: ${path.relative(process.cwd(), agentFile)}`);
+
+  // Extract Documentation Queries
+  const queries = extractDocumentationQueries(agentFile);
+
+  if (queries.length === 0) {
+    console.log(`\n❌ CRITICAL: No Documentation Queries found in agent file!`);
+    console.log(`   This violates Context7 enforcement policy.`);
+    console.log(`   ALL agents MUST have Documentation Queries section.`);
+    console.log(`\n   Please add to ${path.basename(agentFile)}:`);
+    console.log(`   **Documentation Queries:**`);
+    console.log(`   - \`mcp://context7/...\` - Description`);
+    console.log(`\n   Blocking agent invocation until fixed.\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n📚 Context7 Documentation Queries Required: ${queries.length}\n`);
+
+  // Query Context7 for each link
+  const results = [];
+  for (const query of queries) {
+    console.log(`   ➜ ${query.url}`);
+    console.log(`     ${query.description}`);
+
+    try {
+      const result = await queryContext7(query.url);
+      results.push(result);
+    } catch (error) {
+      console.log(`\n❌ Context7 query FAILED: ${error.message}`);
+      console.log(`   Cannot proceed without Context7 documentation.`);
+      console.log(`   Please ensure Context7 MCP server is running.\n`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n✅ Context7 Queries Complete\n`);
+  console.log(`📖 REMINDER: @${agentName} MUST use Context7 documentation:`);
+  console.log(`   • Apply patterns from Context7 examples`);
+  console.log(`   • Verify API signatures against Context7 results`);
+  console.log(`   • Follow best practices documented in Context7`);
+  console.log(`   • Flag any conflicts between training data and Context7`);
+  console.log(`\n🚀 Proceeding with agent invocation...\n`);
+
+  // In production, this would inject Context7 results into agent's context
+  // For now, we output instruction for Claude to see
+  if (results.length > 0 && results[0].placeholder) {
+    console.log(`⚡ ACTION REQUIRED FOR @${agentName}:`);
+    console.log(`   Before implementing "${task || 'task'}", you MUST:`);
+    for (const result of results) {
+      console.log(`   • ${result.instruction}`);
+    }
+    console.log();
+  }
+}
+
+// Execute if run directly
+if (require.main === module) {
+  const agentInvocation = process.argv.slice(2).join(' ');
+  main(agentInvocation).catch(error => {
+    console.error('\n❌ Hook execution failed:', error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseAgentInvocation,
+  findAgentFile,
+  extractDocumentationQueries,
+  queryContext7
+};

package/packages/plugin-core/hooks/pre-command-context7.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-Command Context7 Hook
+ *
+ * MANDATORY: This hook enforces Context7 documentation queries BEFORE command execution.
+ *
+ * Workflow:
+ * 1. Intercept command execution (e.g., /pm:epic-decompose)
+ * 2. Extract command file path from .claude/commands/{category}/{command}.md
+ * 3. Parse "Documentation Queries" section
+ * 4. Query Context7 MCP for each link
+ * 5. Inject results into execution context
+ * 6. Allow command to proceed with Context7 knowledge
+ *
+ * Zero Tolerance: If Context7 query fails, execution STOPS.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract command metadata from invocation
+ * @param {string} commandInvocation - e.g., "/pm:epic-decompose feature-name"
+ * @returns {object} { category, command, args }
+ */
+function parseCommandInvocation(commandInvocation) {
+  // Remove leading slash and split
+  const cleaned = commandInvocation.replace(/^\//, '');
+  const [categoryCommand, ...args] = cleaned.split(/\s+/);
+  const [category, command] = categoryCommand.split(':');
+
+  return {
+    category: category || 'pm', // Default to pm if no category
+    command: command || categoryCommand,
+    args: args,
+    fullCommand: categoryCommand
+  };
+}
+
+/**
+ * Find command file in .claude/commands/
+ * @param {string} category - Command category (pm, azure, cloud, etc.)
+ * @param {string} command - Command name (epic-decompose, issue-start, etc.)
+ * @returns {string|null} - Path to command file or null
+ */
+function findCommandFile(category, command) {
+  const baseDir = path.join(process.cwd(), '.claude', 'commands');
+
+  // Try exact match first
+  let commandPath = path.join(baseDir, category, `${command}.md`);
+  if (fs.existsSync(commandPath)) {
+    return commandPath;
+  }
+
+  // Try with underscores (epic-decompose → epic_decompose)
+  const underscored = command.replace(/-/g, '_');
+  commandPath = path.join(baseDir, category, `${underscored}.md`);
+  if (fs.existsSync(commandPath)) {
+    return commandPath;
+  }
+
+  // Try without category prefix if command includes it
+  if (command.includes('-')) {
+    const [, actualCommand] = command.split('-', 2);
+    if (actualCommand) {
+      commandPath = path.join(baseDir, category, `${actualCommand}.md`);
+      if (fs.existsSync(commandPath)) {
+        return commandPath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract Documentation Queries from command file
+ * @param {string} filePath - Path to command .md file
+ * @returns {Array<{url: string, description: string}>}
+ */
+function extractDocumentationQueries(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const queries = [];
+
+  // Find the Documentation Queries section
+  const querySection = content.match(/\*\*Documentation Queries:\*\*\s*\n([\s\S]*?)(?=\n\n|\*\*Why This is Required|\n##|$)/);
+
+  if (!querySection) {
+    return queries; // No Documentation Queries section found
+  }
+
+  // Extract each mcp://context7/... line
+  const lines = querySection[1].split('\n');
+  for (const line of lines) {
+    const match = line.match(/`(mcp:\/\/context7\/[^`]+)`\s*-\s*(.+)/);
+    if (match) {
+      queries.push({
+        url: match[1],
+        description: match[2].trim()
+      });
+    }
+  }
+
+  return queries;
+}
+
+/**
+ * Query Context7 MCP server
+ * @param {string} mcpUrl - e.g., "mcp://context7/agile/epic-decomposition"
+ * @returns {Promise<object>} - Context7 response
+ */
+async function queryContext7(mcpUrl) {
+  // Parse MCP URL: mcp://context7/category/topic
+  const urlMatch = mcpUrl.match(/mcp:\/\/context7\/(.+)/);
+  if (!urlMatch) {
+    throw new Error(`Invalid Context7 URL format: ${mcpUrl}`);
+  }
+
+  const topicPath = urlMatch[1]; // e.g., "agile/epic-decomposition"
+
+  // In real implementation, this would call the MCP server
+  // For now, return a placeholder that instructs Claude to query
+  return {
+    url: mcpUrl,
+    topic: topicPath,
+    instruction: `MANDATORY: Query Context7 MCP for topic "${topicPath}" before proceeding with implementation.`,
+    placeholder: true
+  };
+}
+
+/**
+ * Main hook execution
+ * @param {string} commandInvocation - Full command string from user
+ */
+async function main(commandInvocation) {
+  console.log('\n🔒 Context7 Pre-Command Hook Activated\n');
+
+  // Parse command
+  const { category, command, args, fullCommand } = parseCommandInvocation(commandInvocation || process.argv[2] || '');
+
+  console.log(`📋 Command: /${fullCommand}`);
+  console.log(`   Category: ${category}`);
+  console.log(`   Command: ${command}`);
+  if (args.length > 0) {
+    console.log(`   Arguments: ${args.join(' ')}`);
+  }
+
+  // Find command file
+  const commandFile = findCommandFile(category, command);
+  if (!commandFile) {
+    console.log(`\n⚠️  Warning: Command file not found for /${fullCommand}`);
+    console.log(`   Searched: .claude/commands/${category}/${command}.md`);
+    console.log(`   Proceeding without Context7 enforcement (file may not exist yet)\n`);
+    return;
+  }
+
+  console.log(`   File: ${path.relative(process.cwd(), commandFile)}`);
+
+  // Extract Documentation Queries
+  const queries = extractDocumentationQueries(commandFile);
+
+  if (queries.length === 0) {
+    console.log(`\n❌ CRITICAL: No Documentation Queries found in command file!`);
+    console.log(`   This violates Context7 enforcement policy.`);
+    console.log(`   ALL commands MUST have Documentation Queries section.`);
+    console.log(`\n   Please add to ${path.basename(commandFile)}:`);
+    console.log(`   ## Required Documentation Access`);
+    console.log(`   **MANDATORY:** Before [action], query Context7 for best practices:`);
+    console.log(`   **Documentation Queries:**`);
+    console.log(`   - \`mcp://context7/...\` - Description`);
+    console.log(`\n   Blocking execution until fixed.\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n📚 Context7 Documentation Queries Required: ${queries.length}\n`);
+
+  // Query Context7 for each link
+  const results = [];
+  for (const query of queries) {
+    console.log(`   ➜ ${query.url}`);
+    console.log(`     ${query.description}`);
+
+    try {
+      const result = await queryContext7(query.url);
+      results.push(result);
+    } catch (error) {
+      console.log(`\n❌ Context7 query FAILED: ${error.message}`);
+      console.log(`   Cannot proceed without Context7 documentation.`);
+      console.log(`   Please ensure Context7 MCP server is running.\n`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n✅ Context7 Queries Complete\n`);
+  console.log(`📖 REMINDER: You MUST use Context7 documentation in your implementation:`);
+  console.log(`   • Apply patterns from Context7 examples`);
+  console.log(`   • Verify API signatures against Context7 results`);
+  console.log(`   • Follow best practices documented in Context7`);
+  console.log(`   • Flag any conflicts between training data and Context7`);
+  console.log(`\n🚀 Proceeding with command execution...\n`);
+
+  // In production, this would inject Context7 results into Claude's context
+  // For now, we output instruction for Claude to see
+  if (results.length > 0 && results[0].placeholder) {
+    console.log(`⚡ ACTION REQUIRED:`);
+    console.log(`   Before implementing /${fullCommand}, you MUST:`);
+    for (const result of results) {
+      console.log(`   • ${result.instruction}`);
+    }
+    console.log();
+  }
+}
+
+// Execute if run directly
+if (require.main === module) {
+  const commandInvocation = process.argv.slice(2).join(' ');
+  main(commandInvocation).catch(error => {
+    console.error('\n❌ Hook execution failed:', error.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseCommandInvocation,
+  findCommandFile,
+  extractDocumentationQueries,
+  queryContext7
+};

package/packages/plugin-core/hooks/strict-enforce-agents.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+# STRICT MODE: Blocks ALL direct operations except Task tool
+
+TOOL_NAME="$1"
+
+# List of allowed tools when not using agents
+ALLOWED_TOOLS="Task|TodoWrite|ExitPlanMode|WebFetch|WebSearch"
+
+# If tool is not on allowed list
+if ! echo "$TOOL_NAME" | grep -qE "^($ALLOWED_TOOLS)$"; then
+    
+    # Tool to agent mapping
+    case "$TOOL_NAME" in
+        "Bash")
+            echo "❌ BLOCKED: Direct bash execution"
+            echo "✅ USE: Appropriate agent based on task:"
+            echo "   - python-backend-engineer for Python development"
+            echo "   - test-runner for running tests"
+            echo "   - bash-scripting-expert for shell scripts"
+            exit 1
+            ;;
+        "Read"|"Glob"|"Grep")
+            echo "❌ BLOCKED: Direct file operations"
+            echo "✅ USE: code-analyzer or file-analyzer agent"
+            exit 1
+            ;;
+        "Edit"|"Write"|"MultiEdit")
+            echo "❌ BLOCKED: Direct file editing"
+            echo "✅ USE: Appropriate development agent:"
+            echo "   - python-backend-engineer for .py files"
+            echo "   - react-frontend-engineer for .jsx/.tsx files"
+            echo "   - nodejs-backend-engineer for Node.js"
+            exit 1
+            ;;
+    esac
+fi
+
+exit 0

package/packages/plugin-core/hooks/test-hook.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Hook test - call simulation
+echo "Testing hook with different scenarios:"
+echo "======================================"
+
+# Test 1: Direct grep (should be blocked)
+echo -e "\n1. Testing: Bash 'grep -r TODO *.py'"
+./.claude/hooks/enforce-agents.sh "Bash" '{"command": "grep -r TODO *.py"}' || echo "   Result: Blocked ✓"
+
+# Test 2: Task tool (should pass)
+echo -e "\n2. Testing: Task tool usage"
+./.claude/hooks/enforce-agents.sh "Task" '{"agent": "code-analyzer"}' && echo "   Result: Allowed ✓"
+
+# Test 3: Direct tests (should be blocked)
+echo -e "\n3. Testing: Bash 'pytest tests/'"
+./.claude/hooks/enforce-agents.sh "Bash" '{"command": "pytest tests/"}' || echo "   Result: Blocked ✓"
+
+# Test 4: Normal bash command (should pass)
+echo -e "\n4. Testing: Bash 'ls -la'"
+./.claude/hooks/enforce-agents.sh "Bash" '{"command": "ls -la"}' && echo "   Result: Allowed ✓"

package/packages/plugin-core/hooks/unified-context7-enforcement.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Unified Context7 Enforcement Hook
+# Triggered by Claude Code on tool-use events
+# Shows Context7 queries that MUST be performed before command/agent execution
+
+set -e
+
+# Get the user's prompt/command
+PROMPT="${PROMPT:-$1}"
+
+# Check if this is a command invocation (starts with /)
+if [[ "$PROMPT" =~ ^/([a-z-]+):([a-z-]+) ]]; then
+    CATEGORY="${BASH_REMATCH[1]}"
+    COMMAND="${BASH_REMATCH[2]}"
+
+    echo ""
+    echo "🔒 Context7 Enforcement: Command Detected"
+    echo "   Command: /$CATEGORY:$COMMAND"
+    echo ""
+
+    # Run the command hook
+    node .claude/hooks/pre-command-context7.js "$PROMPT"
+
+elif [[ "$PROMPT" =~ ^@([a-z-]+) ]]; then
+    AGENT="${BASH_REMATCH[1]}"
+
+    echo ""
+    echo "🔒 Context7 Enforcement: Agent Detected"
+    echo "   Agent: @$AGENT"
+    echo ""
+
+    # Run the agent hook
+    node .claude/hooks/pre-agent-context7.js "$PROMPT"
+fi
+
+# Always allow execution to continue
+exit 0

package/packages/plugin-core/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@claudeautopm/plugin-core",
+  "version": "2.0.0",
+  "description": "Core framework functionality for ClaudeAutoPM - universal agents, rules, hooks, and utilities",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "claude",
+    "autopm",
+    "core",
+    "framework",
+    "agents",
+    "tdd",
+    "context7",
+    "automation"
+  ],
+  "author": "ClaudeAutoPM Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rafeekpro/ClaudeAutoPM.git",
+    "directory": "packages/plugin-core"
+  },
+  "homepage": "https://github.com/rafeekpro/ClaudeAutoPM#readme",
+  "bugs": {
+    "url": "https://github.com/rafeekpro/ClaudeAutoPM/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "agents/",
+    "commands/",
+    "rules/",
+    "hooks/",
+    "scripts/",
+    "plugin.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}