claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-core/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/packages/plugin-core/rules/ai-integration-patterns.md

@@ -0,0 +1,219 @@
+# AI Integration Patterns Rule
+
+> **PURPOSE**: Mandatory patterns for AI API integration and safety practices.
+
+## CRITICAL AI INTEGRATION REQUIREMENTS
+
+### 1. AGENT SELECTION BY USE CASE
+
+**OpenAI Integration** - Use `openai-python-expert`:
+
+- GPT models for text generation and chat
+- Embeddings for semantic search and similarity  
+- Vision API for image analysis and OCR
+- Audio processing (Whisper, TTS)
+- Function calling for tool integration
+
+**Google AI Integration** - Use `gemini-api-expert`:
+
+- Multimodal inputs (text, images, audio, video)
+- Advanced reasoning and analysis
+- Safety-first content filtering
+- Function calling with structured outputs
+- Large context window requirements
+
+**Complex Workflows** - Use `langgraph-workflow-expert`:
+
+- Multi-agent collaboration patterns
+- State management and persistence
+- Conditional routing and decision trees
+- Human-in-the-loop workflows
+- Error handling and recovery
+
+### 2. MANDATORY SAFETY PRACTICES
+
+**Content Filtering** (ALWAYS implement):
+
+- Enable content safety filters on all AI APIs
+- Implement input validation and sanitization
+- Set up output content monitoring
+- Create content moderation workflows
+
+**Rate Limiting** (REQUIRED):
+
+- Implement API rate limiting at application level
+- Set up exponential backoff for retries
+- Monitor usage and costs continuously
+- Implement circuit breakers for failures
+
+**Error Handling** (MANDATORY):
+
+- Graceful degradation when AI APIs fail
+- Fallback responses for service unavailability  
+- Comprehensive logging and monitoring
+- User-friendly error messages
+
+### 3. PRODUCTION DEPLOYMENT PATTERNS
+
+**API Key Management**:
+
+```bash
+# NEVER commit API keys to repository
+# Use environment variables or secret management
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=...
+```
+
+**Configuration Management**:
+
+```python
+# Use configuration classes for API settings
+@dataclass
+class AIConfig:
+    api_key: str
+    model: str
+    temperature: float = 0.1
+    max_tokens: int = 1000
+    safety_settings: Dict[str, str] = field(default_factory=dict)
+```
+
+**Monitoring and Observability**:
+
+- Log all AI API requests and responses
+- Monitor token usage and costs
+- Track response quality and user satisfaction
+- Set up alerts for errors and rate limits
+
+### 4. WORKFLOW ORCHESTRATION PATTERNS
+
+**Simple Chat** → Use `openai-python-expert`:
+
+```python
+# Single model, single turn conversations
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": prompt}]
+)
+```
+
+**Multi-turn Conversations** → Use `openai-python-expert` or `gemini-api-expert`:
+
+```python
+# Conversation history management
+conversation_manager.add_message("user", user_input)
+response = conversation_manager.continue_conversation(conversation_id)
+```
+
+**Complex Workflows** → Use `langgraph-workflow-expert`:
+
+```python
+# Multi-agent workflows with state management
+workflow = StateGraph(WorkflowState)
+workflow.add_node("researcher", research_agent)
+workflow.add_node("analyzer", analysis_agent)
+workflow.add_conditional_edges("researcher", route_to_analyzer)
+```
+
+### 5. INTEGRATION TESTING REQUIREMENTS
+
+**Unit Tests** (MANDATORY):
+
+- Mock AI API responses for consistent testing
+- Test error handling and edge cases
+- Validate input/output processing
+- Test rate limiting and retry logic
+
+**Integration Tests** (REQUIRED):
+
+- Test with real API endpoints (using test keys)
+- Validate end-to-end workflows
+- Test concurrent request handling
+- Verify safety filters and content moderation
+
+**Performance Tests** (REQUIRED):
+
+- Load testing with concurrent requests
+- Token usage optimization testing
+- Response time monitoring
+- Cost optimization validation
+
+### 6. COST OPTIMIZATION STRATEGIES
+
+**Model Selection**:
+
+- Use GPT-3.5-turbo for simple tasks
+- Reserve GPT-4 for complex reasoning
+- Use smaller embedding models when sufficient
+- Implement model switching based on complexity
+
+**Token Management**:
+
+- Implement conversation pruning for long chats
+- Use summarization for context compression
+- Cache frequently requested responses
+- Optimize prompt engineering for token efficiency
+
+**Batch Processing**:
+
+- Group similar requests for batch processing
+- Implement async processing for non-real-time tasks
+- Use streaming for long responses
+- Implement request deduplication
+
+## AGENT COORDINATION RULES
+
+### When to Use Multiple Agents
+
+**OpenAI + LangGraph**: Complex workflows with OpenAI models
+**Gemini + LangGraph**: Multimodal workflows with state management
+**OpenAI + Gemini**: Comparative analysis or model ensemble approaches
+
+### Agent Communication Patterns
+
+```python
+# Use Task tool to coordinate multiple AI agents
+Task 1: "Use openai-python-expert to generate initial response"
+Task 2: "Use gemini-api-expert to analyze and enhance the response"  
+Task 3: "Use langgraph-workflow-expert to orchestrate the full pipeline"
+```
+
+## COMPLIANCE AND GOVERNANCE
+
+### Data Privacy (MANDATORY)
+
+- Never send PII to AI APIs without encryption
+- Implement data retention policies
+- Set up audit logging for AI interactions
+- Comply with GDPR/CCPA requirements
+
+### Model Governance
+
+- Document model versions and capabilities
+- Implement A/B testing for model changes
+- Set up model performance monitoring
+- Create rollback procedures for model issues
+
+### Usage Monitoring
+
+- Track API usage by user/session
+- Monitor response quality metrics
+- Set up cost alerts and budgets
+- Generate usage reports for stakeholders
+
+## VIOLATIONS AND ENFORCEMENT
+
+**CRITICAL VIOLATIONS** (Block deployment):
+
+- API keys committed to repository
+- Missing content safety filters
+- No error handling for AI API failures
+- Unbounded token usage without limits
+
+**MAJOR VIOLATIONS** (Require fixes):
+
+- Missing rate limiting implementation
+- No monitoring or logging setup
+- Inadequate testing coverage
+- Missing cost optimization strategies
+
+These patterns ensure responsible, secure, and cost-effective AI integration across all projects.

package/packages/plugin-core/rules/command-pipelines.md

@@ -0,0 +1,208 @@
+# Command Pipeline Specifications
+
+> **CRITICAL**: Follow these exact command sequences for each workflow.
+
+## Command Categories
+
+### Context Management (`/context:*`)
+
+- `/context:create` - Build initial project documentation
+- `/context:update` - Refresh context with recent changes  
+- `/context:prime` - Load context into conversation
+
+### Testing (`/testing:*`)
+
+- `/testing:prime` - Configure testing framework and detect test runner
+- `/testing:run` - Execute tests via test-runner agent
+
+### Project Management (`/pm:*`)
+
+#### System Management
+
+- `/pm:init` - Initialize PM system (REQUIRED FIRST)
+- `/pm:status` - Show current PM status
+- `/pm:standup` - Daily standup report
+- `/pm:validate` - Validate PM structure
+- `/pm:sync` - Sync with external systems
+
+#### PRD Management
+
+- `/pm:prd-new` - Create new Product Requirements Document
+- `/pm:prd-parse` - Convert PRD to technical epic
+- `/pm:prd-edit` - Edit existing PRD
+- `/pm:prd-status` - Show PRD status
+
+#### Epic Management
+
+- `/pm:epic-decompose` - Break epic into tasks
+- `/pm:epic-start` - Launch parallel agents for epic
+- `/pm:epic-status` - Show execution status
+- `/pm:epic-merge` - Merge epic branch
+- `/pm:epic-close` - Close completed epic
+
+#### Issue Management
+
+- `/pm:issue-analyze` - Identify parallel work streams
+- `/pm:issue-start` - Begin work on issue
+- `/pm:issue-status` - Show issue status
+- `/pm:issue-close` - Mark issue complete
+- `/pm:import` - Import GitHub issues
+
+#### Workflow Navigation
+
+- `/pm:next` - Get next task recommendation
+- `/pm:in-progress` - Show current work
+- `/pm:blocked` - Show blocked tasks
+- `/pm:search` - Search PM system
+
+### Utilities
+
+- `/prompt` - Handle complex prompts with @ references
+- `/re-init` - Update CLAUDE.md with PM rules
+- `/code-rabbit` - Process CodeRabbit review comments
+
+## Mandatory Command Pipelines
+
+### 1. NEW PROJECT INITIALIZATION
+
+```
+REQUIRED SEQUENCE:
+1. /pm:init           → Initialize PM system
+2. /context:create    → Build project documentation
+3. /testing:prime     → Configure test framework
+4. /context:prime     → Load context for work
+```
+
+### 2. FEATURE DEVELOPMENT PIPELINE
+
+```
+REQUIRED SEQUENCE:
+1. /pm:prd-new <name>        → Create requirements document
+2. /pm:prd-parse <name>      → Convert to technical epic
+3. /pm:epic-decompose <name> → Break into parallel tasks
+4. /pm:epic-sync <name>      → Sync with GitHub
+5. /pm:epic-start <name>     → Launch parallel agents:
+   - Each agent follows TDD cycle
+   - Agents work in shared branch
+   - Progress tracked in execution-status.md
+6. /pm:epic-status <name>    → Monitor progress
+7. /pm:epic-merge <name>     → Merge when complete
+```
+
+### 3. ISSUE RESOLUTION PIPELINE
+
+```
+REQUIRED SEQUENCE:
+1. /pm:import                → Import from GitHub
+2. /pm:issue-analyze <id>    → Identify work streams
+3. /pm:issue-start <id>      → Begin implementation:
+   - Spawns parallel-worker agent
+   - Creates sub-agents per stream
+   - Follows TDD for each fix
+4. /pm:issue-status <id>     → Check progress
+5. /pm:issue-close <id>      → Mark complete
+```
+
+### 4. DAILY WORKFLOW PIPELINE
+
+```
+MORNING SEQUENCE:
+1. /context:prime       → Load project context
+2. /pm:standup         → Review status & blockers
+3. /pm:next            → Get task recommendation
+
+DURING WORK:
+- Use agents for all searches/analysis
+- Follow TDD cycle for changes
+- Run /testing:run after implementations
+
+END OF DAY SEQUENCE:
+1. /testing:run        → Verify all tests pass
+2. /context:update     → Update project context
+3. /pm:status          → Review accomplishments
+```
+
+### 5. CODE REVIEW PIPELINE
+
+```
+REQUIRED SEQUENCE:
+1. /code-rabbit        → Paste review comments
+2. code-analyzer       → Analyze each suggestion
+3. Implement fixes following TDD
+4. test-runner         → Verify all changes
+5. Update PR with fixes
+```
+
+## Command Prerequisites
+
+### PM Commands
+
+- Require `/pm:init` first
+- Must have `.pm/` directory structure
+
+### Epic Commands
+
+- Require PRD to exist
+- Must have parsed epic file
+
+### Issue Commands
+
+- Require GitHub integration
+- Must have valid issue ID
+
+### Testing Commands
+
+- Require framework detection
+- Must have test configuration
+
+### Context Commands
+
+- Require `.claude/` directory
+- Must have project structure
+
+## Command Execution Rules
+
+### All Commands MUST
+
+1. Validate prerequisites before execution
+2. Use real datetime (`date -u +"%Y-%m-%dT%H:%M:%SZ"`)
+3. Ask before overwriting data
+4. Provide detailed execution summaries
+5. Delegate to specialized agents
+
+### Agent Delegation Rules
+
+- **Always use test-runner** for test execution
+- **Always use file-analyzer** for reading logs/outputs
+- **Always use code-analyzer** for code search/analysis
+- **Always use parallel-worker** for multi-file operations
+
+## Command Anti-Patterns
+
+### NEVER DO
+
+- ❌ Running tests without `/testing:prime`
+- ❌ Starting epics without decomposition
+- ❌ Closing issues without verification
+- ❌ Skipping context updates
+- ❌ Direct command execution without agents
+- ❌ Manual datetime entry
+- ❌ Ignoring command prerequisites
+
+## Success Verification
+
+### Command Success Indicators
+
+- ✅ Prerequisites validated
+- ✅ Agents properly delegated
+- ✅ Real datetime used
+- ✅ Summary provided
+- ✅ Next steps clear
+
+### Pipeline Completion
+
+- ✅ All steps executed in order
+- ✅ No steps skipped
+- ✅ Tests passing
+- ✅ Documentation updated
+- ✅ Context preserved