claude-autopm 1.21.0 → 1.22.0

package/autopm/.claude/rules/context7-enforcement.md

@@ -0,0 +1,292 @@
+# Context7 Documentation Enforcement
+
+> **CRITICAL**: This rule has HIGHEST PRIORITY. ALL commands and agents MUST query Context7 before execution.
+
+## Core Context7 Philosophy
+
+**Prime Directive**: Query live documentation from Context7 MCP BEFORE implementing any solution.
+**Zero Tolerance**: No implementation without Context7 query. No reliance on training data. No shortcuts.
+
+## Why This is Critical
+
+### Problems We Solve
+
+- **Hallucinations**: AI training data becomes stale, leading to outdated patterns
+- **API Changes**: Frameworks evolve - training data doesn't reflect latest versions
+- **Best Practices Drift**: Industry standards change faster than model retraining
+- **Version Conflicts**: Code suggestions may target wrong framework versions
+
+### Context7 Benefits
+
+- **Always Current**: Live documentation reflects latest releases
+- **Verified Patterns**: Real code examples from official sources
+- **API Accuracy**: Current function signatures, parameters, return types
+- **Breaking Changes**: Immediate awareness of deprecated patterns
+
+## The Context7 Cycle
+
+### 1. QUERY Phase (Before Implementation)
+
+**MANDATORY Steps:**
+1. Read command/agent file to extract `**Documentation Queries:**` section
+2. Query EACH Context7 MCP link listed
+3. Analyze results for relevant patterns, APIs, and best practices
+4. Summarize key findings before proceeding
+
+**Required Information:**
+- Current API signatures and parameters
+- Recommended patterns and anti-patterns
+- Breaking changes from recent versions
+- Official code examples
+
+### 2. IMPLEMENT Phase (Using Context7 Knowledge)
+
+**Requirements:**
+- Apply patterns EXACTLY as documented in Context7 results
+- Use API signatures from Context7 (not from training data)
+- Follow architectural recommendations from live docs
+- Reference Context7 findings in code comments where applicable
+
+**Verification:**
+- Cross-check implementation against Context7 examples
+- Validate parameters match current API documentation
+- Ensure no deprecated patterns are used
+
+### 3. VALIDATE Phase (Post-Implementation)
+
+**Mandatory Checks:**
+- Implementation matches Context7 best practices
+- No training data hallucinations introduced
+- Code follows latest framework conventions
+- All deprecation warnings addressed
+
+## Enforcement Rules
+
+### ABSOLUTE REQUIREMENTS
+
+**For ALL Commands:**
+- MUST read `## Required Documentation Access` section
+- MUST query EVERY `mcp://context7/...` link before execution
+- MUST summarize Context7 findings before proceeding
+- MUST apply Context7 guidance in implementation
+
+**For ALL Agents:**
+- MUST read `**Documentation Queries:**` section
+- MUST query Context7 before making technical decisions
+- MUST verify API signatures against live documentation
+- MUST flag conflicts between training data and Context7
+
+**For ALL Implementations:**
+- NO code based solely on training data for technical specifics
+- NO assumptions about API signatures without Context7 verification
+- NO "I think this is how it works" - VERIFY with Context7
+- NO skipping Context7 "because it's a small change"
+
+### PROHIBITED PRACTICES
+
+- ❌ Implementing without querying Context7 first
+- ❌ "I remember how this works" - training data is stale
+- ❌ Skipping Context7 for "simple" or "obvious" tasks
+- ❌ Using cached knowledge instead of live documentation
+- ❌ Proceeding when Context7 query fails (STOP and report)
+- ❌ Ignoring Context7 guidance because training data "seems better"
+
+## Query Quality Standards
+
+### Effective Context7 Queries
+
+**DO:**
+- ✅ Query ALL links in Documentation Queries section
+- ✅ Request specific topics relevant to the task
+- ✅ Ask for code examples and patterns
+- ✅ Verify API signatures and parameters
+- ✅ Check for breaking changes and migrations
+
+**DON'T:**
+- ❌ Skip queries assuming training data is sufficient
+- ❌ Query only one link when multiple are listed
+- ❌ Accept generic results - request specifics
+- ❌ Ignore version mismatches in results
+
+### Coverage Requirements
+
+- **100% Query Rate**: Every command/agent execution queries Context7
+- **Complete Coverage**: ALL listed Context7 links must be queried
+- **Result Validation**: Verify Context7 returned relevant information
+- **Fallback Protocol**: If Context7 fails, STOP and report (don't proceed with stale data)
+
+## Integration with Workflow
+
+### Command Execution Flow
+
+```
+User executes command: /pm:epic-decompose feature-name
+
+BEFORE execution:
+1. Read .claude/commands/pm/epic-decompose.md
+2. Extract Documentation Queries section:
+   - mcp://context7/agile/epic-decomposition
+   - mcp://context7/agile/task-sizing
+   - mcp://context7/agile/user-stories
+   - mcp://context7/project-management/task-breakdown
+3. Query Context7 for EACH link
+4. Summarize findings: "Context7 confirms INVEST criteria for user stories..."
+5. PROCEED with command execution using Context7 guidance
+
+DURING execution:
+- Apply Context7 patterns
+- Reference Context7 examples
+- Follow Context7 best practices
+
+AFTER execution:
+- Validate against Context7 standards
+- Flag any deviations from documentation
+```
+
+### Agent Invocation Flow
+
+```
+User invokes agent: @aws-cloud-architect design VPC
+
+BEFORE invocation:
+1. Read .claude/agents/cloud/aws-cloud-architect.md
+2. Extract Documentation Queries section:
+   - mcp://context7/aws/compute
+   - mcp://context7/aws/networking
+   - mcp://context7/terraform/aws
+3. Query Context7 for EACH link
+4. Summarize: "Context7 shows VPC best practices: /16 for staging, /20 for prod..."
+5. PROCEED with agent work using Context7 knowledge
+
+DURING agent work:
+- Use current AWS API patterns from Context7
+- Apply Terraform AWS provider patterns from Context7
+- Follow networking best practices from Context7
+
+AFTER agent work:
+- Cross-check VPC design against Context7 recommendations
+- Ensure no deprecated patterns used
+```
+
+## Violation Consequences
+
+**If Context7 enforcement is violated:**
+
+### Immediate Actions
+
+1. **STOP** execution immediately
+2. **IDENTIFY** what was implemented without Context7 verification
+3. **DELETE** code based on potentially stale training data
+4. **QUERY** Context7 for the relevant documentation
+5. **REIMPLEMENT** using Context7 guidance
+6. **DOCUMENT** violation and correction
+
+### Severity Levels
+
+**Level 1 - Minor (Warning):**
+- Partial Context7 queries (some links skipped)
+- Action: Complete missing queries, validate implementation
+
+**Level 2 - Moderate (Correction Required):**
+- No Context7 queries performed
+- Action: Stop, query Context7, review implementation
+
+**Level 3 - Critical (Revert and Redo):**
+- Implementation contradicts Context7 documentation
+- Action: Delete code, start over with Context7 guidance
+
+### No Exceptions Policy
+
+- NO "small changes" exceptions
+- NO "I'm confident this is right" exceptions
+- NO "Context7 is slow" exceptions
+- NO "training data matches Context7" assumptions
+
+## Success Metrics
+
+### Compliance Indicators
+
+- ✅ 100% of commands query Context7 before execution
+- ✅ 100% of agents query Context7 before implementation
+- ✅ Zero implementations based solely on training data
+- ✅ All API signatures verified against live documentation
+- ✅ No deprecated patterns in codebase
+- ✅ Context7 findings documented in comments/commits
+
+### Quality Indicators
+
+- ✅ Implementation matches Context7 examples
+- ✅ No "unexpected behavior" due to API changes
+- ✅ Code follows latest framework conventions
+- ✅ Breaking changes identified and addressed proactively
+
+## Automation and Enforcement
+
+### Pre-Command Hook
+
+File: `.claude/hooks/pre-command-context7.js`
+
+**Purpose**: Automatically extract and query Context7 before command execution
+
+**Behavior**:
+1. Intercept command execution
+2. Read command file from `.claude/commands/{category}/{command}.md`
+3. Extract `**Documentation Queries:**` section
+4. Query Context7 MCP for each link
+5. Inject results into command context
+6. Proceed with execution
+
+### Pre-Agent Hook
+
+File: `.claude/hooks/pre-agent-context7.js`
+
+**Purpose**: Automatically extract and query Context7 before agent invocation
+
+**Behavior**:
+1. Intercept agent invocation
+2. Read agent file from `.claude/agents/{category}/{agent}.md`
+3. Extract `**Documentation Queries:**` section
+4. Query Context7 MCP for each link
+5. Inject results into agent context
+6. Proceed with agent work
+
+### Validation Rule
+
+File: `.claude/rules/context7-enforcement.md` (this file)
+
+**Purpose**: Remind Claude to ALWAYS query Context7
+
+**Enforcement**:
+- Read by Claude on every session start
+- Highest priority in rule hierarchy
+- Zero tolerance for violations
+
+## Emergency Fallback
+
+**If Context7 MCP is unavailable:**
+
+1. **ALERT** user immediately: "⚠️ Context7 MCP unavailable - cannot verify documentation"
+2. **REQUEST** user decision:
+   - WAIT for Context7 to become available (RECOMMENDED)
+   - PROCEED with explicit user acknowledgment and risk acceptance
+3. **DOCUMENT** in code: `// WARNING: Implemented without Context7 verification - Context7 MCP was unavailable`
+4. **FLAG** for review: Add TODO to re-verify with Context7 when available
+
+**DO NOT:**
+- ❌ Silently proceed without Context7
+- ❌ Assume training data is sufficient
+- ❌ Skip documentation queries
+
+## Related Rules
+
+- **TDD Enforcement** (`.claude/rules/tdd.enforcement.md`) - Tests first, always
+- **Agent Usage** (`.claude/rules/agent-usage.md`) - When to use specialized agents
+- **Code Quality** (`.claude/rules/code-quality.md`) - Standards and anti-patterns
+
+## Final Reminder
+
+> **Context7 is NOT optional. It is MANDATORY for EVERY command and agent execution.**
+>
+> Training data becomes stale. APIs change. Best practices evolve.
+>
+> Context7 keeps us current. Query it. Every. Single. Time.

package/package.json

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

package/scripts/add-context7-to-commands.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+/**
+ * Automatically add "Required Documentation Access" section to all commands
+ * that don't already have it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Command categories with their Context7 topic mappings
+const CATEGORY_MAPPINGS = {
+  'ai': {
+    topics: ['ai/llm-integration', 'ai/workflow-orchestration', 'openai/api', 'langchain/agents'],
+    description: 'AI integration and LLM workflows'
+  },
+  'azure': {
+    topics: ['azure-devops/boards', 'agile/user-stories', 'project-management/work-items', 'agile/sprint-planning'],
+    description: 'Azure DevOps integration and agile workflows'
+  },
+  'cloud': {
+    topics: ['cloud/infrastructure', 'devops/deployment', 'terraform/best-practices', 'cloud/security'],
+    description: 'cloud infrastructure deployment'
+  },
+  'config': {
+    topics: ['configuration-management/best-practices', 'devops/feature-flags'],
+    description: 'configuration management'
+  },
+  'context': {
+    topics: ['ai/context-management', 'llm/prompt-engineering', 'ai/rag-systems'],
+    description: 'AI context management'
+  },
+  'github': {
+    topics: ['github/workflows', 'ci-cd/github-actions', 'devops/automation'],
+    description: 'GitHub workflow creation'
+  },
+  'infrastructure': {
+    topics: ['security/ssh-hardening', 'infrastructure/reverse-proxy', 'security/best-practices', 'devops/traefik'],
+    description: 'infrastructure setup and security'
+  },
+  'kubernetes': {
+    topics: ['kubernetes/deployment', 'kubernetes/best-practices', 'devops/container-orchestration'],
+    description: 'Kubernetes deployment'
+  },
+  'mcp': {
+    topics: ['mcp/protocol', 'mcp/servers', 'ai/context-management', 'mcp/integration'],
+    description: 'MCP server setup and documentation'
+  },
+  'playwright': {
+    topics: ['playwright/testing', 'testing/e2e', 'testing/best-practices', 'playwright/patterns'],
+    description: 'Playwright test scaffolding'
+  },
+  'pm': {
+    topics: ['agile/epic-management', 'project-management/issue-tracking', 'agile/task-breakdown', 'project-management/workflow'],
+    description: 'project management workflows'
+  },
+  'python': {
+    topics: ['python/api-development', 'fastapi/best-practices', 'python/documentation', 'api-design/rest'],
+    description: 'Python API development'
+  },
+  'react': {
+    topics: ['react/application-setup', 'react/best-practices', 'frontend/architecture', 'react/tooling'],
+    description: 'React application scaffolding'
+  },
+  'testing': {
+    topics: ['testing/strategy', 'testing/automation', 'tdd/workflow', 'testing/best-practices'],
+    description: 'testing workflows'
+  },
+  'ui': {
+    topics: ['ui/bootstrap', 'ui/tailwind', 'frontend/design-systems', 'css/frameworks'],
+    description: 'UI framework setup'
+  }
+};
+
+// Special mappings for specific commands
+const COMMAND_SPECIFIC_MAPPINGS = {
+  'epic-decompose': {
+    topics: ['agile/epic-decomposition', 'agile/task-sizing', 'agile/user-stories', 'project-management/task-breakdown'],
+    description: 'decomposing epics'
+  },
+  'epic-split': {
+    topics: ['agile/epic-splitting', 'project-management/dependency-mapping', 'agile/priority-frameworks', 'architecture/component-analysis'],
+    description: 'splitting PRDs into epics'
+  },
+  'issue-analyze': {
+    topics: ['agile/issue-analysis', 'agile/parallel-work', 'project-management/task-dependencies', 'agile/estimation'],
+    description: 'analyzing issues'
+  },
+  'issue-start': {
+    topics: ['agile/issue-planning', 'tdd/workflow', 'git/branching', 'collaboration/parallel-work'],
+    description: 'starting work on issues'
+  },
+  'prd-new': {
+    topics: ['product-management/prd-templates', 'product-management/requirements', 'agile/user-stories', 'product-management/success-metrics'],
+    description: 'creating PRDs'
+  },
+  'prd-parse': {
+    topics: ['product-management/prd-to-epic', 'agile/epic-structure', 'architecture/technical-design', 'project-management/task-breakdown'],
+    description: 'converting PRDs to epics'
+  },
+  'feature-decompose': {
+    topics: ['agile/feature-breakdown', 'azure-devops/features', 'agile/task-sizing', 'project-management/work-breakdown'],
+    description: 'decomposing Azure features'
+  },
+  'us-new': {
+    topics: ['agile/user-stories', 'agile/invest-criteria', 'azure-devops/user-stories', 'requirements/writing'],
+    description: 'creating user stories'
+  },
+  'task-analyze': {
+    topics: ['agile/task-analysis', 'project-management/task-planning', 'agile/estimation', 'azure-devops/tasks'],
+    description: 'analyzing tasks'
+  },
+  'workflow-create': {
+    topics: ['github/workflows', 'ci-cd/github-actions', 'devops/pipeline-design', 'ci-cd/best-practices'],
+    description: 'creating GitHub workflows'
+  },
+  'infra-deploy': {
+    topics: ['infrastructure/deployment', 'cloud/best-practices', 'devops/automation', 'infrastructure/configuration'],
+    description: 'deploying infrastructure'
+  },
+  'ssh-security': {
+    topics: ['security/ssh-hardening', 'security/authentication', 'infrastructure/security', 'security/best-practices'],
+    description: 'SSH security hardening'
+  },
+  'traefik-setup': {
+    topics: ['infrastructure/reverse-proxy', 'traefik/configuration', 'devops/networking', 'security/tls'],
+    description: 'Traefik setup'
+  },
+  'test-scaffold': {
+    topics: ['playwright/scaffolding', 'testing/e2e', 'testing/page-objects', 'playwright/best-practices'],
+    description: 'scaffolding Playwright tests'
+  },
+  'api-scaffold': {
+    topics: ['python/api-scaffolding', 'fastapi/structure', 'api-design/rest', 'python/best-practices'],
+    description: 'scaffolding Python APIs'
+  },
+  'app-scaffold': {
+    topics: ['react/project-setup', 'react/application-structure', 'frontend/tooling', 'react/best-practices'],
+    description: 'scaffolding React applications'
+  }
+};
+
+function getCommandCategory(filePath) {
+  const parts = filePath.split('/');
+  const commandsIndex = parts.indexOf('commands');
+  if (commandsIndex >= 0 && commandsIndex < parts.length - 1) {
+    return parts[commandsIndex + 1];
+  }
+  return null;
+}
+
+function getCommandName(filePath) {
+  return path.basename(filePath, '.md');
+}
+
+function getTopicsForCommand(filePath) {
+  const commandName = getCommandName(filePath);
+  const category = getCommandCategory(filePath);
+
+  // Check for command-specific mapping first
+  if (COMMAND_SPECIFIC_MAPPINGS[commandName]) {
+    return COMMAND_SPECIFIC_MAPPINGS[commandName];
+  }
+
+  // Fall back to category mapping
+  if (category && CATEGORY_MAPPINGS[category]) {
+    return CATEGORY_MAPPINGS[category];
+  }
+
+  // Default generic topics
+  return {
+    topics: ['best-practices/general', 'development/workflow'],
+    description: 'executing this command'
+  };
+}
+
+function generateContext7Section(filePath) {
+  const mapping = getTopicsForCommand(filePath);
+  const { topics, description } = mapping;
+
+  const documentationQueries = topics
+    .map(topic => `- \`mcp://context7/${topic}\` - ${topic.split('/').pop().replace(/-/g, ' ')} best practices`)
+    .join('\n');
+
+  return `## Required Documentation Access
+
+**MANDATORY:** Before ${description}, query Context7 for best practices:
+
+**Documentation Queries:**
+${documentationQueries}
+
+**Why This is Required:**
+- Ensures adherence to current industry standards and best practices
+- Prevents outdated or incorrect implementation patterns
+- Provides access to latest framework/tool documentation
+- Reduces errors from stale knowledge or assumptions
+
+`;
+}
+
+function shouldProcessFile(filePath) {
+  const fileName = path.basename(filePath);
+
+  // Skip non-command files
+  const skipFiles = [
+    'README.md',
+    'COMMANDS.md',
+    'COMMAND_MAPPING.md',
+    'INTEGRATION_FIX.md',
+    'ui-framework-commands.md',
+    'ux-design-commands.md',
+    'code-rabbit.md',
+    'prompt.md',
+    're-init.md'
+  ];
+
+  return !skipFiles.includes(fileName);
+}
+
+function hasContext7Section(content) {
+  return content.includes('## Required Documentation Access');
+}
+
+function findInsertionPoint(content) {
+  const lines = content.split('\n');
+
+  // Look for common section headers where we should insert BEFORE
+  const beforeSections = [
+    '## Instructions',
+    '## Required Rules',
+    '## Quick Check',
+    '## Description',
+    '## Usage Examples',
+    '## Overview',
+    '## Pre-flight Checks',
+    '## Validation',
+    '## Steps'
+  ];
+
+  for (let i = 0; i < lines.length; i++) {
+    for (const section of beforeSections) {
+      if (lines[i].trim().startsWith(section)) {
+        return i;
+      }
+    }
+  }
+
+  // If no known section found, insert after usage block (usually has ```)
+  let usageEndIndex = -1;
+  let inUsageBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes('## Usage') || lines[i].includes('## Example')) {
+      inUsageBlock = true;
+    }
+    if (inUsageBlock && lines[i].trim() === '```') {
+      usageEndIndex = i + 1;
+      break;
+    }
+  }
+
+  if (usageEndIndex > 0) {
+    return usageEndIndex;
+  }
+
+  // Last resort: insert after first heading block (after frontmatter and title)
+  let headingCount = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith('#')) {
+      headingCount++;
+      if (headingCount >= 2) {
+        return i;
+      }
+    }
+  }
+
+  return 10; // Fallback to line 10
+}
+
+function addContext7Section(filePath) {
+  let content = fs.readFileSync(filePath, 'utf8');
+
+  if (hasContext7Section(content)) {
+    return { modified: false, reason: 'already has section' };
+  }
+
+  const context7Section = generateContext7Section(filePath);
+  const insertionLine = findInsertionPoint(content);
+
+  const lines = content.split('\n');
+  lines.splice(insertionLine, 0, context7Section);
+
+  const newContent = lines.join('\n');
+  fs.writeFileSync(filePath, newContent, 'utf8');
+
+  return { modified: true, insertionLine };
+}
+
+function main() {
+  const commandsDir = path.join(__dirname, '../autopm/.claude/commands');
+
+  // Find all .md files recursively
+  const findCommand = `find "${commandsDir}" -name "*.md" -type f`;
+  const files = execSync(findCommand, { encoding: 'utf8' })
+    .trim()
+    .split('\n')
+    .filter(f => f.length > 0);
+
+  console.log(`\n📋 Found ${files.length} command files\n`);
+
+  const results = {
+    modified: [],
+    skipped: [],
+    alreadyHas: []
+  };
+
+  for (const file of files) {
+    const fileName = path.relative(commandsDir, file);
+
+    if (!shouldProcessFile(file)) {
+      results.skipped.push(fileName);
+      continue;
+    }
+
+    const result = addContext7Section(file);
+
+    if (result.modified) {
+      results.modified.push({ file: fileName, line: result.insertionLine });
+      console.log(`✅ Added to: ${fileName} (line ${result.insertionLine})`);
+    } else {
+      results.alreadyHas.push(fileName);
+      console.log(`⏭️  Skip: ${fileName} (${result.reason})`);
+    }
+  }
+
+  console.log(`\n📊 Summary:`);
+  console.log(`   Modified: ${results.modified.length}`);
+  console.log(`   Already has Context7: ${results.alreadyHas.length}`);
+  console.log(`   Skipped (non-command files): ${results.skipped.length}`);
+  console.log(`   Total processed: ${files.length}\n`);
+
+  if (results.modified.length > 0) {
+    console.log(`✨ Successfully added Context7 sections to ${results.modified.length} commands!\n`);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { addContext7Section, getTopicsForCommand };