claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-core/rules/context-optimization.md

@@ -0,0 +1,176 @@
+# Context Optimization Strategies
+
+> **CRITICAL**: Preserve conversation context through intelligent agent delegation.
+
+## Core Philosophy
+
+**Context Management**: Use specialized agents to preserve conversation context
+**Information Hierarchy**: Only critical information in main thread
+**Efficiency Target**: Agents return <20% of processed data
+
+## Agent Usage Requirements
+
+### ALWAYS USE file-analyzer WHEN
+
+- Reading any log file
+- Analyzing test outputs  
+- Reviewing configuration files
+- Summarizing verbose outputs
+- Reading multiple files for comparison
+- Extracting key information from large files
+
+### ALWAYS USE code-analyzer WHEN
+
+- Searching for code patterns
+- Tracing logic flow
+- Investigating bugs
+- Reviewing code changes
+- Finding security vulnerabilities
+- Analyzing dependencies
+- Understanding code structure
+
+### ALWAYS USE test-runner WHEN
+
+- Running any tests
+- Validating implementations
+- Checking for regressions
+- Debugging test failures
+- Verifying fixes
+
+### ALWAYS USE parallel-worker WHEN
+
+- Implementing features with multiple components
+- Working on multiple files simultaneously
+- Decomposing epics into parallel tasks
+- Handling independent work streams
+
+### ALWAYS USE fastapi-expert WHEN
+
+- Building FastAPI endpoints
+- Implementing API authentication
+- Optimizing API performance
+- Adding WebSocket functionality
+- Debugging FastAPI-specific issues
+
+## Context Firewall Pattern
+
+### Main Thread (High-Level Only)
+
+- Task coordination
+- Critical decisions
+- User interaction
+- Success/failure reporting
+- Next step determination
+
+### Agent Threads (Heavy Lifting)
+
+- File reading and analysis
+- Code searching and parsing
+- Test execution and analysis
+- Multi-file operations
+- Verbose processing
+
+### Information Return Rules
+
+- Return only actionable insights
+- Summarize findings to 10-20% of original
+- Focus on decisions needed
+- Exclude implementation details
+- Never dump raw output
+
+## Batch Operation Strategies
+
+### Parallel Execution
+
+- Use parallel-worker for multi-file changes
+- Group related tests in test-runner
+- Combine searches in code-analyzer
+- Batch similar operations together
+
+### Sequential When Required
+
+- Dependencies between operations
+- State changes affecting next steps
+- User approval needed between steps
+
+## Anti-Patterns to Avoid
+
+### NEVER DO
+
+- ❌ Direct grep/find/cat usage
+- ❌ Reading files without file-analyzer
+- ❌ Running tests without test-runner
+- ❌ Searching code without code-analyzer
+- ❌ Dumping verbose output to main thread
+- ❌ Processing logs in main conversation
+
+### Context Waste Examples
+
+```
+BAD: Dumping entire log file to main thread
+GOOD: Use file-analyzer to extract key errors
+
+BAD: Running grep directly and showing all matches
+GOOD: Use code-analyzer to find and summarize patterns
+
+BAD: Showing full test output in conversation
+GOOD: Use test-runner to run and summarize results
+```
+
+## Information Hierarchy
+
+### Priority 1: Critical (Main Thread)
+
+- Blocking errors
+- Security vulnerabilities
+- Data loss risks
+- User decisions required
+
+### Priority 2: Important (Agent Summary)
+
+- Test failures
+- Performance issues
+- Code quality problems
+- Configuration errors
+
+### Priority 3: Verbose (Agent Internal)
+
+- Detailed logs
+- Full test output
+- Complete search results
+- Implementation details
+
+## Success Metrics
+
+### Context Efficiency
+
+- ✅ All agents return <20% of processed data
+- ✅ No raw logs in main thread
+- ✅ No direct file reads without agents
+- ✅ Batch operations when possible
+- ✅ Clear summaries over raw data
+
+### Agent Utilization
+
+- ✅ 100% file reads through file-analyzer
+- ✅ 100% code search through code-analyzer
+- ✅ 100% test runs through test-runner
+- ✅ Multi-file work through parallel-worker
+
+## Enforcement
+
+### Violation Detection
+
+If context wastage detected:
+
+1. Stop current approach
+2. Identify appropriate agent
+3. Delegate task to agent
+4. Resume with summary only
+
+### Continuous Improvement
+
+- Monitor context usage
+- Identify patterns for new agents
+- Update agent capabilities
+- Document new patterns in CLAUDE.md

package/packages/plugin-core/rules/context7-enforcement.md

@@ -0,0 +1,327 @@
+# Context7 Documentation Enforcement
+
+> **CRITICAL**: This rule has HIGHEST PRIORITY. ALL commands and agents MUST query Context7 before execution.
+
+---
+
+## 🔴 VISUAL REMINDER FOR EVERY COMMAND/AGENT
+
+**WHEN YOU SEE:** User writes `/pm:epic-decompose` or `@aws-cloud-architect`
+
+**YOU MUST IMMEDIATELY:**
+
+1. 📖 **ANNOUNCE**: "I will now query Context7 for required documentation..."
+2. 🔍 **READ** the command/agent file to extract Documentation Queries
+3. 🌐 **QUERY** Context7 MCP for EACH listed topic using mcp__context7__get-library-docs
+4. 📝 **SUMMARIZE** key findings from Context7 results
+5. ✅ **CONFIRM**: "Context7 verification complete. Proceeding with [command/agent]..."
+
+**VISUAL OUTPUT FOR USER:**
+
+```
+🔒 Context7 Enforcement Active
+
+📋 Command: /pm:epic-decompose
+📚 Querying Context7 for required documentation...
+
+   ➜ mcp://context7/agile/epic-decomposition
+   ➜ mcp://context7/agile/task-sizing
+   ➜ mcp://context7/agile/user-stories
+   ➜ mcp://context7/project-management/task-breakdown
+
+✅ Context7 queries complete
+📖 Key findings: [summarize what you learned]
+
+Proceeding with epic decomposition using Context7 best practices...
+```
+
+---
+
+## 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/packages/plugin-core/rules/datetime.md

@@ -0,0 +1,122 @@
+# DateTime Rule
+
+## Getting Current Date and Time
+
+When any command requires the current date/time (for frontmatter, timestamps, or logs), you MUST obtain the REAL current date/time from the system rather than estimating or using placeholder values.
+
+### How to Get Current DateTime
+
+Use the `date` command to get the current ISO 8601 formatted datetime:
+
+```bash
+# Get current datetime in ISO 8601 format (works on Linux/Mac)
+date -u +"%Y-%m-%dT%H:%M:%SZ"
+
+# Alternative for systems that support it
+date --iso-8601=seconds
+
+# For Windows (if using PowerShell)
+Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"
+```
+
+### Required Format
+
+All dates in frontmatter MUST use ISO 8601 format with UTC timezone:
+
+- Format: `YYYY-MM-DDTHH:MM:SSZ`
+- Example: `2024-01-15T14:30:45Z`
+
+### Usage in Frontmatter
+
+When creating or updating frontmatter in any file (PRD, Epic, Task, Progress), always use the real current datetime:
+
+```yaml
+---
+name: feature-name
+created: 2024-01-15T14:30:45Z  # Use actual output from date command
+updated: 2024-01-15T14:30:45Z  # Use actual output from date command
+---
+```
+
+### Implementation Instructions
+
+1. **Before writing any file with frontmatter:**
+   - Run: `date -u +"%Y-%m-%dT%H:%M:%SZ"`
+   - Store the output
+   - Use this exact value in the frontmatter
+
+2. **For commands that create files:**
+   - PRD creation: Use real date for `created` field
+   - Epic creation: Use real date for `created` field
+   - Task creation: Use real date for both `created` and `updated` fields
+   - Progress tracking: Use real date for `started` and `last_sync` fields
+
+3. **For commands that update files:**
+   - Always update the `updated` field with current real datetime
+   - Preserve the original `created` field
+   - For sync operations, update `last_sync` with real datetime
+
+### Examples
+
+**Creating a new PRD:**
+
+```bash
+# First, get current datetime
+CURRENT_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+# Output: 2024-01-15T14:30:45Z
+
+# Then use in frontmatter:
+---
+name: user-authentication
+description: User authentication and authorization system
+status: backlog
+created: 2024-01-15T14:30:45Z  # Use the actual $CURRENT_DATE value
+---
+```
+
+**Updating an existing task:**
+
+```bash
+# Get current datetime for update
+UPDATE_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Update only the 'updated' field:
+---
+name: implement-login-api
+status: in-progress
+created: 2024-01-10T09:15:30Z  # Keep original
+updated: 2024-01-15T14:30:45Z  # Use new $UPDATE_DATE value
+---
+```
+
+### Important Notes
+
+- **Never use placeholder dates** like `[Current ISO date/time]` or `YYYY-MM-DD`
+- **Never estimate dates** - always get the actual system time
+- **Always use UTC** (the `Z` suffix) for consistency across timezones
+- **Preserve timezone consistency** - all dates in the system use UTC
+
+### Cross-Platform Compatibility
+
+If you need to ensure compatibility across different systems:
+
+```bash
+# Try primary method first
+date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+# Fallback for systems without -u flag
+date +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || \
+# Last resort: use Python if available
+python3 -c "from datetime import datetime; print(datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null || \
+python -c "from datetime import datetime; print(datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null
+```
+
+## Rule Priority
+
+This rule has **HIGHEST PRIORITY** and must be followed by all commands that:
+
+- Create new files with frontmatter
+- Update existing files with frontmatter
+- Track timestamps or progress
+- Log any time-based information
+
+Commands affected: prd-new, prd-parse, epic-decompose, epic-sync, issue-start, issue-sync, and any other command that writes timestamps.