claude-autopm 1.20.1 → 1.22.0

package/autopm/.claude/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/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/autopm/.claude/rules/framework-path-rules.md

@@ -0,0 +1,180 @@
+# Framework Path Rules
+
+## Critical Path Convention
+
+**NEVER** hardcode the `autopm/` directory path in framework files. The `autopm/` directory only exists during development and is **NOT** present after installation in user projects.
+
+## The Problem
+
+During installation, files from `autopm/.claude/` are copied to user projects as `.claude/`. Any references to `autopm/.claude/` or `autopm/scripts/` will be broken after installation.
+
+```
+❌ WRONG (Development structure):
+autopm/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+
+✅ CORRECT (After installation):
+user-project/
+├── .claude/
+│   ├── commands/
+│   ├── scripts/
+│   └── agents/
+```
+
+## Rules
+
+### 1. Use Relative Paths from Project Root
+
+All paths in framework files must be relative to the **user's project root** (where `.claude/` will exist after installation).
+
+**✅ CORRECT:**
+```bash
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node .claude/lib/commands/pm/prdStatus.js
+source .claude/scripts/lib/github-utils.sh
+```
+
+**❌ WRONG:**
+```bash
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "$EPIC_NAME"
+node autopm/.claude/lib/commands/pm/prdStatus.js
+source autopm/.claude/scripts/lib/github-utils.sh
+```
+
+### 2. Exception: Comments and Documentation References
+
+It's acceptable to reference `autopm/` in:
+- Code comments explaining migration history
+- Documentation describing the development structure
+- Git commit messages
+
+**✅ ACCEPTABLE:**
+```javascript
+/**
+ * Migrated from autopm/.claude/scripts/azure/validate.sh to Node.js
+ */
+```
+
+**✅ ACCEPTABLE:**
+```markdown
+## Development Structure
+During development, framework files are in `autopm/.claude/`, but after
+installation they are copied to the user project's `.claude/` directory.
+```
+
+### 3. Files That Must Follow These Rules
+
+- **Commands** (`autopm/.claude/commands/**/*.md`)
+- **Scripts** (`autopm/.claude/scripts/**/*.sh`, `**/*.js`)
+- **Agents** (`autopm/.claude/agents/**/*.md`)
+- **Rules** (`autopm/.claude/rules/**/*.md`)
+- **Templates** (`autopm/.claude/templates/**/*`)
+
+### 4. Environment Variables
+
+If you need to reference the framework location dynamically, use environment variables that work in both contexts:
+
+**✅ CORRECT:**
+```bash
+CLAUDE_DIR="${CLAUDE_DIR:-.claude}"
+bash "${CLAUDE_DIR}/scripts/pm/epic-sync/create-epic-issue.sh"
+```
+
+This allows:
+- Development: `CLAUDE_DIR=autopm/.claude`
+- Production: `CLAUDE_DIR=.claude` (default)
+
+## Validation
+
+### Pre-Commit Hook
+
+A pre-commit hook validates all framework files before commit:
+
+```bash
+# Checks for hardcoded autopm/ paths (excluding comments)
+grep -r "bash autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "node autopm" autopm/.claude --include="*.md" --include="*.sh"
+grep -r "source autopm" autopm/.claude --include="*.md" --include="*.sh"
+```
+
+### Manual Check
+
+Before committing changes to framework files:
+
+```bash
+# Run validation
+npm run validate:paths
+
+# Or manually
+./scripts/validate-framework-paths.sh
+```
+
+## Common Mistakes
+
+### Mistake 1: Copy-Paste from Development Environment
+
+```bash
+# ❌ Copying terminal command that worked in development
+bash autopm/.claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+
+# ✅ Use project-relative path
+bash .claude/scripts/pm/epic-sync/create-epic-issue.sh "feature-name"
+```
+
+### Mistake 2: Documentation Examples
+
+```markdown
+❌ WRONG:
+To run the script:
+`bash autopm/.claude/scripts/pm/issue-sync/preflight-validation.sh`
+
+✅ CORRECT:
+To run the script:
+`bash .claude/scripts/pm/issue-sync/preflight-validation.sh`
+```
+
+### Mistake 3: Relative Imports in Scripts
+
+```bash
+# ❌ WRONG - hardcoded framework path
+source autopm/.claude/scripts/lib/github-utils.sh
+
+# ✅ CORRECT - relative to project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../lib/github-utils.sh"
+
+# ✅ ALSO CORRECT - explicit project root
+source .claude/scripts/lib/github-utils.sh
+```
+
+## Enforcement
+
+This rule is enforced by:
+
+1. **Pre-commit hook** - Blocks commits with hardcoded `autopm/` paths
+2. **CI/CD validation** - GitHub Actions check on every PR
+3. **Installation tests** - Verify all paths work post-installation
+4. **Code review** - Reviewers check for path correctness
+
+## Quick Reference
+
+| Context | Use | Don't Use |
+|---------|-----|-----------|
+| Shell scripts | `.claude/scripts/` | `autopm/.claude/scripts/` |
+| Node.js scripts | `.claude/lib/` | `autopm/.claude/lib/` |
+| Command files | `.claude/commands/` | `autopm/.claude/commands/` |
+| Documentation | `.claude/agents/` | `autopm/.claude/agents/` |
+| Comments | `autopm/` ✅ OK | N/A |
+
+## Related Rules
+
+- `/rules/naming-conventions.md` - File and directory naming
+- `/rules/development-workflow.md` - Development best practices
+- `/rules/golden-rules.md` - Core framework principles
+
+---
+
+**Remember:** If a user installs this framework, the `autopm/` directory will not exist in their project. All paths must work from their project root where `.claude/` is located.