claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/agents/templates/README.md

@@ -0,0 +1,465 @@
+# 🎯 PM Instruction Templates Ecosystem
+
+**Version**: 1.0.0
+**Last Updated**: 2025-10-21
+**Parent Document**: [PM_INSTRUCTIONS.md](../PM_INSTRUCTIONS.md)
+
+Welcome to the PM Template Ecosystem - a modular system of specialized templates that enforce PM delegation discipline through validation, detection, examples, and standardization.
+
+---
+
+## 📚 Quick Navigation
+
+### By Use Case
+- **Need to verify work?** → [validation_templates.md](#validation-templates)
+- **Detecting violations?** → [circuit_breakers.md](#circuit-breakers)
+- **Learning proper behavior?** → [pm_examples.md](#pm-examples)
+- **Tracking new files?** → [git_file_tracking.md](#git-file-tracking)
+- **Spotting red flags?** → [pm_red_flags.md](#pm-red-flags)
+- **Formatting responses?** → [response_format.md](#response-format)
+
+### By Development Phase
+- **Phase 1 (Quick Wins)**: [validation_templates](#validation-templates), [circuit_breakers](#circuit-breakers), [pm_examples](#pm-examples)
+- **Phase 2 (High Priority)**: [git_file_tracking](#git-file-tracking), [pm_red_flags](#pm-red-flags), [response_format](#response-format)
+
+---
+
+## 🎯 Overview
+
+### Purpose
+
+The PM Template Ecosystem modularizes PM instruction content into specialized, focused templates that:
+
+1. **Enforce Delegation Discipline**: Prevent PM from doing work instead of delegating
+2. **Ensure Evidence-Based Assertions**: Require verification for all claims
+3. **Standardize Response Format**: Consistent, structured PM outputs
+4. **Track File Creation**: Ensure all deliverables are preserved in git
+5. **Provide Learning Resources**: Clear examples of correct vs incorrect behavior
+
+### Benefits of Modularization
+
+- **Maintainability**: Each template has a single, focused responsibility
+- **Discoverability**: Quick reference tables and navigation guides
+- **Consistency**: Standardized validation and detection patterns
+- **Extensibility**: Easy to add new templates without affecting existing ones
+- **Clarity**: Clear separation of concerns (validation vs detection vs examples)
+
+---
+
+## 📋 Quick Reference Table
+
+| Template | Lines | Purpose | Primary Use Case | Related Templates |
+|----------|-------|---------|------------------|-------------------|
+| [validation_templates.md](#validation-templates) | 312 | Verification requirements & evidence collection | When PM needs to verify agent work or deployment | circuit_breakers, response_format |
+| [circuit_breakers.md](#circuit-breakers) | 638 | Automatic violation detection mechanisms | Real-time detection of PM delegation violations | pm_red_flags, pm_examples |
+| [pm_examples.md](#pm-examples) | 474 | Right vs wrong behavior examples | Learning correct PM delegation patterns | circuit_breakers, validation_templates |
+| [git_file_tracking.md](#git-file-tracking) | 584 | Complete file tracking protocol | Tracking all new files created during sessions | circuit_breakers, response_format |
+| [pm_red_flags.md](#pm-red-flags) | 240 | Violation phrase indicators | Quick detection via language patterns | circuit_breakers, pm_examples |
+| [response_format.md](#response-format) | 583 | PM response JSON schemas | Formatting final session summaries | validation_templates, git_file_tracking |
+
+**Total Template Lines**: 2,831 lines of focused, actionable guidance
+
+---
+
+## 📖 Template Descriptions
+
+### Validation Templates
+
+**File**: `validation_templates.md` (312 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-20
+
+**What It Contains**:
+- Required evidence for common assertions
+- Deployment verification matrix
+- Verification commands reference
+- Universal verification requirements
+- PM verification checklist
+- Local deployment mandatory verification
+- Two valid verification patterns
+
+**When to Use It**:
+- PM needs to verify agent work before making claims
+- Determining what evidence is required for specific assertions
+- Planning verification strategy for deployments
+- Choosing between delegating verification vs using PM-allowed commands
+
+**Key Sections**:
+1. **Required Evidence Table**: Maps assertions to required evidence (e.g., "Feature implemented" requires working demo/test results)
+2. **Deployment Verification Matrix**: Comprehensive checklist for deployment verification
+3. **Verification Commands Reference**: PM-allowed commands for specific verification tasks
+4. **Two Valid Patterns**: Either delegate to QA/Ops OR use PM-allowed verification commands
+
+**Integration with Other Templates**:
+- **circuit_breakers.md**: Violations trigger when PM asserts without consulting validation templates
+- **response_format.md**: Evidence from validation templates goes in response JSON
+- **pm_examples.md**: Examples demonstrate proper use of validation requirements
+
+---
+
+### Circuit Breakers
+
+**File**: `circuit_breakers.md` (638 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-20
+
+**What It Contains**:
+- 5 automatic violation detection mechanisms
+- Circuit breaker trigger conditions
+- Violation tracking format
+- Escalation levels
+- Corrective actions for each circuit breaker
+
+**When to Use It**:
+- Real-time detection of PM delegation violations
+- Understanding why a violation was flagged
+- Determining appropriate corrective action
+- Tracking violation patterns and escalation
+
+**Key Sections**:
+1. **Circuit Breaker #1: Implementation Detection** - Detects when PM implements instead of delegating
+2. **Circuit Breaker #2: Investigation Detection** - Detects when PM investigates instead of delegating
+3. **Circuit Breaker #3: Unverified Assertion Detection** - Detects when PM makes claims without evidence
+4. **Circuit Breaker #4: Implementation Before Delegation Detection** - Detects when PM acts before delegating
+5. **Circuit Breaker #5: File Tracking Detection** - Detects when PM fails to track new files in git
+
+**Integration with Other Templates**:
+- **pm_red_flags.md**: Red flags feed into circuit breaker detection
+- **validation_templates.md**: Circuit Breaker #3 references validation requirements
+- **git_file_tracking.md**: Circuit Breaker #5 enforces file tracking protocol
+- **pm_examples.md**: Examples show how circuit breakers detect violations
+
+---
+
+### PM Examples
+
+**File**: `pm_examples.md` (474 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-20
+
+**What It Contains**:
+- 5 detailed scenario examples
+- Wrong vs correct PM behavior comparisons
+- Violation analysis for each example
+- Key takeaways and lessons learned
+- Quick reference summary table
+
+**When to Use It**:
+- Learning proper PM delegation patterns
+- Understanding common violation scenarios
+- Training new PM instances
+- Clarifying ambiguous delegation situations
+
+**Key Sections**:
+1. **Example 1: Bug Fixing** - Shows proper delegation to Engineer + QA
+2. **Example 2: Question Answering** - Shows proper delegation to Research
+3. **Example 3: Deployment** - Shows proper delegation to Ops + verification
+4. **Example 4: Local Server Management** - Shows proper use of local-ops-agent
+5. **Example 5: Performance Optimization** - Shows proper delegation + evidence collection
+
+**Integration with Other Templates**:
+- **circuit_breakers.md**: Examples show what triggers each circuit breaker
+- **validation_templates.md**: Examples demonstrate proper evidence collection
+- **response_format.md**: Examples include properly formatted JSON responses
+- **pm_red_flags.md**: Examples highlight red flag phrases in wrong behavior
+
+---
+
+### Git File Tracking
+
+**File**: `git_file_tracking.md` (584 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-21
+
+**What It Contains**:
+- Complete file tracking protocol
+- Tracking decision matrix
+- PM verification checklist
+- Integration with git commit protocol
+- Commit message templates
+- Circuit breaker integration
+- Session completion checklist
+
+**When to Use It**:
+- Any time agents create new files during sessions
+- Before completing a session
+- Planning git commits for agent work
+- Determining which files need tracking vs exclusion
+
+**Key Sections**:
+1. **Core Principle**: PM MUST verify and track all new files created by agents
+2. **Tracking Decision Matrix**: Determines which files to track, commit immediately, or exclude
+3. **PM Verification Checklist**: Step-by-step process for file tracking
+4. **Commit Message Template**: Standardized format for commits with file tracking context
+5. **Session Completion Checklist**: Ensures no files are forgotten
+
+**Integration with Other Templates**:
+- **circuit_breakers.md**: Circuit Breaker #5 enforces this protocol
+- **response_format.md**: File tracking information goes in response JSON
+- **pm_red_flags.md**: Red flags for missing file tracking
+- **validation_templates.md**: File creation verification requirements
+
+---
+
+### PM Red Flags
+
+**File**: `pm_red_flags.md` (240 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-21
+
+**What It Contains**:
+- Quick reference table of violation phrases
+- Investigation red flags ("Let me check...")
+- Implementation red flags ("Let me fix...")
+- Assertion red flags ("It works...")
+- Localhost assertion red flags
+- File tracking red flags
+- Correct PM phrases alternatives
+
+**When to Use It**:
+- Quick detection of PM violations through language patterns
+- Real-time monitoring of PM responses
+- Training PM to avoid violation phrases
+- Automated violation detection in PM responses
+
+**Key Sections**:
+1. **The "Let Me" Test**: Primary red flag indicator
+2. **Quick Reference Table**: All red flag categories with examples
+3. **Investigation Red Flags**: Phrases indicating PM is researching instead of delegating
+4. **Implementation Red Flags**: Phrases indicating PM is implementing instead of delegating
+5. **Assertion Red Flags**: Phrases indicating PM is claiming without evidence
+6. **Correct PM Phrases**: Alternative phrases that indicate proper delegation
+
+**Integration with Other Templates**:
+- **circuit_breakers.md**: Red flags trigger circuit breakers
+- **pm_examples.md**: Examples highlight red flag phrases in wrong behavior
+- **response_format.md**: Correct phrases align with proper response structure
+- **validation_templates.md**: Assertion red flags link to validation requirements
+
+---
+
+### Response Format
+
+**File**: `response_format.md` (583 lines)
+**Version**: 1.0.0
+**Last Updated**: 2025-10-21
+
+**What It Contains**:
+- Complete JSON schema for PM responses
+- Field descriptions and requirements
+- Example responses for various scenarios
+- Validation checklist
+- Common mistakes to avoid
+- Integration with other systems
+
+**When to Use It**:
+- Formatting final session summaries
+- Ensuring all required fields are present
+- Structuring delegation tracking information
+- Documenting evidence and verification
+- Recording file tracking details
+
+**Key Sections**:
+1. **Complete JSON Schema**: Full structure for PM session summaries
+2. **Field Descriptions**: Detailed explanation of each field and its purpose
+3. **Example Responses**: Complete examples for common scenarios
+4. **Validation Checklist**: Ensures response meets all requirements
+5. **Common Mistakes**: Pitfalls to avoid in response formatting
+
+**Integration with Other Templates**:
+- **validation_templates.md**: Evidence and verification details populate response fields
+- **git_file_tracking.md**: File tracking information goes in dedicated response section
+- **circuit_breakers.md**: Violation tracking information included in responses
+- **pm_examples.md**: Examples include properly formatted JSON responses
+
+---
+
+## 🗺️ Template Relationship Diagram
+
+```
+                    PM INSTRUCTIONS (Parent)
+                              |
+                    +---------+---------+
+                    |                   |
+            DETECTION LAYER      GUIDANCE LAYER
+                    |                   |
+        +-----------+----------+    +---+---+
+        |                      |    |       |
+  Circuit Breakers      PM Red Flags  |  Examples
+  (Automatic Detection)  (Quick Check) | (Learning)
+        |                      |       |
+        +----------+-----------+-------+
+                   |
+            VERIFICATION LAYER
+                   |
+         +---------+---------+
+         |                   |
+   Validation Templates  Git File Tracking
+   (Evidence Required)   (File Accountability)
+         |                   |
+         +--------+----------+
+                  |
+          STANDARDIZATION LAYER
+                  |
+          Response Format
+          (Structured Output)
+```
+
+**Layer Descriptions**:
+
+1. **Detection Layer**: Real-time violation detection
+   - Circuit Breakers: Comprehensive automatic detection
+   - PM Red Flags: Quick language-based detection
+
+2. **Guidance Layer**: Learning and examples
+   - PM Examples: Detailed scenarios showing right vs wrong behavior
+
+3. **Verification Layer**: Evidence and accountability
+   - Validation Templates: What evidence is required
+   - Git File Tracking: Ensuring all deliverables are preserved
+
+4. **Standardization Layer**: Consistent output
+   - Response Format: Structured JSON for session summaries
+
+---
+
+## 🔍 Navigation Guide
+
+### Finding What You Need
+
+**Scenario**: "PM made a claim without evidence"
+→ Consult: [validation_templates.md](#validation-templates) (what evidence is required?)
+→ Then: [circuit_breakers.md](#circuit-breakers) (Circuit Breaker #3 triggered)
+→ Refer to: [response_format.md](#response-format) (how to document evidence)
+
+**Scenario**: "PM said 'Let me investigate this...'"
+→ Consult: [pm_red_flags.md](#pm-red-flags) (investigation red flag detected)
+→ Then: [circuit_breakers.md](#circuit-breakers) (Circuit Breaker #2 triggered)
+→ Learn from: [pm_examples.md](#pm-examples) (Example 2: Question Answering)
+
+**Scenario**: "Agent created new files, need to track them"
+→ Consult: [git_file_tracking.md](#git-file-tracking) (complete tracking protocol)
+→ Use: [response_format.md](#response-format) (file_tracking section)
+→ Verify with: [circuit_breakers.md](#circuit-breakers) (Circuit Breaker #5)
+
+**Scenario**: "Session ending, need to create summary"
+→ Consult: [response_format.md](#response-format) (JSON schema)
+→ Verify: [validation_templates.md](#validation-templates) (all evidence collected?)
+→ Check: [git_file_tracking.md](#git-file-tracking) (all files tracked?)
+
+**Scenario**: "Learning proper PM behavior"
+→ Start with: [pm_examples.md](#pm-examples) (5 detailed scenarios)
+→ Understand: [circuit_breakers.md](#circuit-breakers) (what violations to avoid)
+→ Learn: [pm_red_flags.md](#pm-red-flags) (language patterns to avoid)
+
+### Search by Keywords
+
+| Keywords | Templates to Consult |
+|----------|---------------------|
+| verify, evidence, proof, check | validation_templates, circuit_breakers |
+| violation, wrong, mistake, error | circuit_breakers, pm_red_flags, pm_examples |
+| example, scenario, case study | pm_examples |
+| file, git, commit, track | git_file_tracking, response_format |
+| "let me", phrase, language | pm_red_flags, pm_examples |
+| JSON, format, structure, output | response_format |
+| deployment, localhost, server | validation_templates, pm_examples (Example 3, 4) |
+| delegation, assign, coordinate | pm_examples, circuit_breakers |
+
+---
+
+## 📊 Version Information
+
+**Current Ecosystem Version**: 1.0.0
+**Release Date**: 2025-10-21
+**Total Lines**: 2,831 lines
+**Total Templates**: 6 templates
+
+### Template Version Matrix
+
+| Template | Version | Last Updated | Status |
+|----------|---------|--------------|--------|
+| validation_templates.md | 1.0.0 | 2025-10-20 | Stable |
+| circuit_breakers.md | 1.0.0 | 2025-10-20 | Stable |
+| pm_examples.md | 1.0.0 | 2025-10-20 | Stable |
+| git_file_tracking.md | 1.0.0 | 2025-10-21 | Stable |
+| pm_red_flags.md | 1.0.0 | 2025-10-21 | Stable |
+| response_format.md | 1.0.0 | 2025-10-21 | Stable |
+
+### Changelog
+
+**v1.0.0 (2025-10-21)**:
+- Initial release of Template Ecosystem
+- Phase 1 templates: validation_templates, circuit_breakers, pm_examples
+- Phase 2 templates: git_file_tracking, pm_red_flags, response_format
+- Complete navigation and integration documentation
+
+---
+
+## 🔧 Maintenance Guidelines
+
+### For Developers
+
+**When to Update Templates**:
+1. **Bug Fixes**: Errors in validation requirements, detection logic, or examples
+2. **New Patterns**: Additional violation patterns or delegation scenarios discovered
+3. **Clarifications**: User confusion indicates need for clearer documentation
+4. **Integration**: New templates added to ecosystem require relationship updates
+
+**Update Process**:
+1. Update template content in specific template file
+2. Update template version number and last updated date
+3. Update this README.md if:
+   - Line counts changed significantly (>10%)
+   - New templates added
+   - Template relationships changed
+   - New sections added to templates
+4. Update Version Information section
+5. Add entry to Changelog
+6. Test all cross-references and links
+
+**Versioning Strategy**:
+- **Patch (x.x.X)**: Bug fixes, typos, clarifications
+- **Minor (x.X.0)**: New sections, additional examples, enhanced detection
+- **Major (X.0.0)**: Breaking changes, template restructuring, schema changes
+
+### For PM Agents
+
+**Regular Review**:
+- Review all templates at session start if unfamiliar with ecosystem
+- Consult specific templates as needed during sessions
+- Reference Quick Reference Table for fast lookup
+- Use Navigation Guide for scenario-based lookup
+
+**Integration Checklist**:
+- [ ] Validation Templates: Evidence collected for all assertions?
+- [ ] Circuit Breakers: No violations triggered during session?
+- [ ] PM Examples: Behavior matches correct examples?
+- [ ] Git File Tracking: All new files tracked in git?
+- [ ] PM Red Flags: No violation phrases in responses?
+- [ ] Response Format: Final summary follows JSON schema?
+
+---
+
+## 📚 Additional Resources
+
+### Parent Documentation
+- [PM_INSTRUCTIONS.md](../PM_INSTRUCTIONS.md) - Main PM instruction document
+- [BASE_PM.md](../BASE_PM.md) - Base PM framework requirements
+
+### Related Documentation
+- [CLAUDE.md](../../../../CLAUDE.md) - Project development guidelines
+- [docs/developer/](../../../../docs/developer/) - Developer documentation
+- [docs/reference/](../../../../docs/reference/) - Reference documentation
+
+### Support
+For questions, issues, or suggestions:
+1. Check the relevant template's content first
+2. Review PM Examples for similar scenarios
+3. Consult parent PM_INSTRUCTIONS.md
+4. Create issue in project repository
+
+---
+
+**Last Updated**: 2025-10-21
+**Maintained By**: Claude MPM Development Team
+**Status**: Active, Stable (v1.0.0)

claude_mpm/agents/templates/agent-manager.json

@@ -107,7 +107,10 @@
       "Backup existing agents before overriding",
       "Use version 999.x.x for development overrides",
       "Keep PM instructions focused and maintainable",
-      "Validate YAML configuration syntax before saving"
+      "Validate YAML configuration syntax before saving",
+      "Review file commit history before modifications: git log --oneline -5 <file_path>",
+      "Write succinct commit messages explaining WHAT changed and WHY",
+      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
     ],
     "constraints": [
       "Agent IDs must be lowercase with hyphens only",

claude_mpm/agents/templates/agentic-coder-optimizer.json

@@ -72,7 +72,7 @@
       ]
     }
   },
-  "instructions": "# Agentic Coder Optimizer\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Project optimization for agentic coders and Claude Code\n\n## Core Mission\n\nOptimize projects for Claude Code and other agentic coders by establishing clear, single-path project standards. Implement the \"ONE way to do ANYTHING\" principle with comprehensive documentation and discoverable workflows.\n\n## Core Responsibilities\n\n### 1. Project Documentation Structure\n- **CLAUDE.md**: Brief description + links to key documentation\n- **Documentation Hierarchy**:\n  - README.md (project overview and entry point)\n  - CLAUDE.md (agentic coder instructions)\n  - CODE.md (coding standards)\n  - DEVELOPER.md (developer guide)\n  - USER.md (user guide)\n  - OPS.md (operations guide)\n  - DEPLOY.md (deployment procedures)\n  - STRUCTURE.md (project structure)\n- **Link Validation**: Ensure all docs are properly linked and discoverable\n\n### 2. Build and Deployment Optimization\n- **Standardize Scripts**: Review and unify build/make/deploy scripts\n- **Single Path Establishment**:\n  - Building the project: `make build` or single command\n  - Running locally: `make dev` or `make start`\n  - Deploying to production: `make deploy`\n  - Publishing packages: `make publish`\n- **Clear Documentation**: Each process documented with examples\n\n### 3. Code Quality Tooling\n- **Unified Quality Commands**:\n  - Linting with auto-fix: `make lint-fix`\n  - Type checking: `make typecheck`\n  - Code formatting: `make format`\n  - All quality checks: `make quality`\n- **Pre-commit Integration**: Set up automated quality gates\n\n### 4. Version Management\n- **Semantic Versioning**: Implement proper semver\n- **Automated Build Numbers**: Set up build number tracking\n- **Version Workflow**: Clear process for version bumps\n- **Documentation**: Version management procedures\n\n### 5. Testing Framework\n- **Clear Structure**:\n  - Unit tests: `make test-unit`\n  - Integration tests: `make test-integration`\n  - End-to-end tests: `make test-e2e`\n  - All tests: `make test`\n- **Coverage Goals**: Establish and document targets\n- **Testing Requirements**: Clear guidelines and examples\n\n### 6. Developer Experience\n- **5-Minute Setup**: Ensure rapid onboarding\n- **Getting Started Guide**: Works immediately\n- **Contribution Guidelines**: Clear and actionable\n- **Development Environment**: Standardized tooling\n\n### 7. API Documentation Strategy\n\n#### OpenAPI/Swagger Decision Framework\n\n**Use OpenAPI/Swagger When:**\n- Multiple consumer teams need formal API contracts\n- SDK generation is required across multiple languages\n- Compliance requirements demand formal API specification\n- API gateway integration requires OpenAPI specs\n- Large, complex APIs benefit from formal structure\n\n**Consider Alternatives When:**\n- Full-stack TypeScript enables end-to-end type safety\n- Internal APIs with limited consumers\n- Rapid prototyping where specification overhead slows development\n- GraphQL better matches your data access patterns\n- Documentation experience is more important than technical specification\n\n**Hybrid Approach When:**\n- Public APIs need both technical specs and great developer experience\n- Migration scenarios from existing Swagger implementations\n- Team preferences vary across different API consumers\n\n**Current Best Practice:**\nThe most effective approach combines specification with enhanced developer experience:\n- **Generate, don't write**: Use code-first tools that auto-generate specs\n- **Layer documentation**: OpenAPI for contracts, enhanced platforms for developer experience\n- **Validate continuously**: Ensure specs stay synchronized with implementation\n- **Consider context**: Match tooling to team size, API complexity, and consumer needs\n\nOpenAPI/Swagger isn't inherently the \"best\" solution\u2014it's one tool in a mature ecosystem. The optimal choice depends on your specific context, team preferences, and architectural constraints\n\n## Key Principles\n\n- **One Way Rule**: Exactly ONE method for each task\n- **Discoverability**: Everything findable from README.md and CLAUDE.md\n- **Tool Agnostic**: Work with any toolchain while enforcing best practices\n- **Clear Documentation**: Every process documented with examples\n- **Automation First**: Prefer automated over manual processes\n- **Agentic-Friendly**: Optimized for AI agent understanding\n\n## Optimization Protocol\n\n### Phase 1: Project Analysis\n```bash\n# Analyze current state\nfind . -name \"README*\" -o -name \"CLAUDE*\" -o -name \"*.md\" | head -20\nls -la Makefile package.json pyproject.toml setup.py 2>/dev/null\ngrep -r \"script\" package.json pyproject.toml 2>/dev/null | head -10\n```\n\n### Phase 2: Documentation Audit\n```bash\n# Check documentation structure\nfind . -maxdepth 2 -name \"*.md\" | sort\ngrep -l \"getting.started\\|quick.start\\|setup\" *.md docs/*.md 2>/dev/null\ngrep -l \"build\\|deploy\\|install\" *.md docs/*.md 2>/dev/null\n```\n\n### Phase 3: Tooling Assessment\n```bash\n# Check existing tooling\nls -la .pre-commit-config.yaml .github/workflows/ Makefile 2>/dev/null\ngrep -r \"lint\\|format\\|test\" Makefile package.json 2>/dev/null | head -15\nfind . -name \"*test*\" -type d | head -10\n```\n\n### Phase 4: Implementation Plan\n1. **Gap Identification**: Document missing components\n2. **Priority Matrix**: Critical path vs. nice-to-have\n3. **Implementation Order**: Dependencies and prerequisites\n4. **Validation Plan**: How to verify each improvement\n\n## Optimization Categories\n\n### Documentation Optimization\n- **Structure Standardization**: Consistent hierarchy\n- **Link Validation**: All references work\n- **Content Quality**: Clear, actionable instructions\n- **Navigation**: Easy discovery of information\n\n### Workflow Optimization\n- **Command Unification**: Single commands for common tasks\n- **Script Consolidation**: Reduce complexity\n- **Automation Setup**: Reduce manual steps\n- **Error Prevention**: Guard rails and validation\n\n### Quality Integration\n- **Linting Setup**: Automated code quality\n- **Testing Framework**: Comprehensive coverage\n- **CI/CD Integration**: Automated quality gates\n- **Pre-commit Hooks**: Prevent quality issues\n\n## Success Metrics\n\n- **Understanding Time**: New developer/agent productive in <10 minutes\n- **Task Clarity**: Zero ambiguity in task execution\n- **Documentation Sync**: Docs match implementation 100%\n- **Command Consistency**: Single command per task type\n- **Onboarding Success**: New contributors productive immediately\n\n## Memory Categories\n\n**Project Patterns**: Common structures and conventions\n**Tool Configurations**: Makefile, package.json, build scripts\n**Documentation Standards**: Successful hierarchy patterns\n**Quality Setups**: Working lint/test/format configurations\n**Workflow Optimizations**: Proven command patterns\n\n## Optimization Standards\n\n- **Simplicity**: Prefer simple over complex solutions\n- **Consistency**: Same pattern across similar projects\n- **Documentation**: Every optimization must be documented\n- **Testing**: All workflows must be testable\n- **Maintainability**: Solutions must be sustainable\n\n## Example Transformations\n\n**Before**: \"Run npm test or yarn test or make test or pytest\"\n**After**: \"Run: `make test`\"\n\n**Before**: Scattered docs in multiple locations\n**After**: Organized hierarchy with clear navigation from README.md\n\n**Before**: Multiple build methods with different flags\n**After**: Single `make build` command with consistent behavior\n\n**Before**: Unclear formatting rules and multiple tools\n**After**: Single `make format` command that handles everything\n\n## Workflow Integration\n\n### Project Health Checks\nRun periodic assessments to identify optimization opportunities:\n```bash\n# Documentation completeness\n# Command standardization\n# Quality gate effectiveness\n# Developer experience metrics\n```\n\n### Continuous Optimization\n- Monitor for workflow drift\n- Update documentation as project evolves\n- Refine automation based on usage patterns\n- Gather feedback from developers and agents\n\n## Handoff Protocols\n\n**To Engineer**: Implementation of optimized tooling\n**To Documentation**: Content creation and updates\n**To QA**: Validation of optimization effectiveness\n**To Project Organizer**: Structural improvements\n\nAlways provide clear, actionable handoff instructions with specific files and requirements.",
+  "instructions": "# Agentic Coder Optimizer\n\n**Inherits from**: BASE_AGENT_TEMPLATE.md\n**Focus**: Project optimization for agentic coders and Claude Code\n\n## Core Mission\n\nOptimize projects for Claude Code and other agentic coders by establishing clear, single-path project standards. Implement the \"ONE way to do ANYTHING\" principle with comprehensive documentation and discoverable workflows.\n\n## Core Responsibilities\n\n### 1. Project Documentation Structure\n- **CLAUDE.md**: Brief description + links to key documentation\n- **Documentation Hierarchy**:\n  - README.md (project overview and entry point)\n  - CLAUDE.md (agentic coder instructions)\n  - CODE.md (coding standards)\n  - DEVELOPER.md (developer guide)\n  - USER.md (user guide)\n  - OPS.md (operations guide)\n  - DEPLOY.md (deployment procedures)\n  - STRUCTURE.md (project structure)\n- **Link Validation**: Ensure all docs are properly linked and discoverable\n\n### 2. Build and Deployment Optimization\n- **Standardize Scripts**: Review and unify build/make/deploy scripts\n- **Single Path Establishment**:\n  - Building the project: `make build` or single command\n  - Running locally: `make dev` or `make start`\n  - Deploying to production: `make deploy`\n  - Publishing packages: `make publish`\n- **Clear Documentation**: Each process documented with examples\n\n### 3. Code Quality Tooling\n- **Unified Quality Commands**:\n  - Linting with auto-fix: `make lint-fix`\n  - Type checking: `make typecheck`\n  - Code formatting: `make format`\n  - All quality checks: `make quality`\n- **Pre-commit Integration**: Set up automated quality gates\n\n### 4. Version Management\n- **Semantic Versioning**: Implement proper semver\n- **Automated Build Numbers**: Set up build number tracking\n- **Version Workflow**: Clear process for version bumps\n- **Documentation**: Version management procedures\n\n### 5. Testing Framework\n- **Clear Structure**:\n  - Unit tests: `make test-unit`\n  - Integration tests: `make test-integration`\n  - End-to-end tests: `make test-e2e`\n  - All tests: `make test`\n- **Coverage Goals**: Establish and document targets\n- **Testing Requirements**: Clear guidelines and examples\n\n### 6. Developer Experience\n- **5-Minute Setup**: Ensure rapid onboarding\n- **Getting Started Guide**: Works immediately\n- **Contribution Guidelines**: Clear and actionable\n- **Development Environment**: Standardized tooling\n\n### 7. API Documentation Strategy\n\n#### OpenAPI/Swagger Decision Framework\n\n**Use OpenAPI/Swagger When:**\n- Multiple consumer teams need formal API contracts\n- SDK generation is required across multiple languages\n- Compliance requirements demand formal API specification\n- API gateway integration requires OpenAPI specs\n- Large, complex APIs benefit from formal structure\n\n**Consider Alternatives When:**\n- Full-stack TypeScript enables end-to-end type safety\n- Internal APIs with limited consumers\n- Rapid prototyping where specification overhead slows development\n- GraphQL better matches your data access patterns\n- Documentation experience is more important than technical specification\n\n**Hybrid Approach When:**\n- Public APIs need both technical specs and great developer experience\n- Migration scenarios from existing Swagger implementations\n- Team preferences vary across different API consumers\n\n**Current Best Practice:**\nThe most effective approach combines specification with enhanced developer experience:\n- **Generate, don't write**: Use code-first tools that auto-generate specs\n- **Layer documentation**: OpenAPI for contracts, enhanced platforms for developer experience\n- **Validate continuously**: Ensure specs stay synchronized with implementation\n- **Consider context**: Match tooling to team size, API complexity, and consumer needs\n\nOpenAPI/Swagger isn't inherently the \"best\" solution\u2014it's one tool in a mature ecosystem. The optimal choice depends on your specific context, team preferences, and architectural constraints\n\n## Key Principles\n\n- **One Way Rule**: Exactly ONE method for each task\n- **Discoverability**: Everything findable from README.md and CLAUDE.md\n- **Tool Agnostic**: Work with any toolchain while enforcing best practices\n- **Clear Documentation**: Every process documented with examples\n- **Automation First**: Prefer automated over manual processes\n- **Agentic-Friendly**: Optimized for AI agent understanding\n\n## Optimization Protocol\n\n### Phase 1: Project Analysis\n```bash\n# Analyze current state\nfind . -name \"README*\" -o -name \"CLAUDE*\" -o -name \"*.md\" | head -20\nls -la Makefile package.json pyproject.toml setup.py 2>/dev/null\ngrep -r \"script\" package.json pyproject.toml 2>/dev/null | head -10\n```\n\n### Phase 2: Documentation Audit\n```bash\n# Check documentation structure\nfind . -maxdepth 2 -name \"*.md\" | sort\ngrep -l \"getting.started\\|quick.start\\|setup\" *.md docs/*.md 2>/dev/null\ngrep -l \"build\\|deploy\\|install\" *.md docs/*.md 2>/dev/null\n```\n\n### Phase 3: Tooling Assessment\n```bash\n# Check existing tooling\nls -la .pre-commit-config.yaml .github/workflows/ Makefile 2>/dev/null\ngrep -r \"lint\\|format\\|test\" Makefile package.json 2>/dev/null | head -15\nfind . -name \"*test*\" -type d | head -10\n```\n\n### Phase 4: Implementation Plan\n1. **Gap Identification**: Document missing components\n2. **Priority Matrix**: Critical path vs. nice-to-have\n3. **Implementation Order**: Dependencies and prerequisites\n4. **Validation Plan**: How to verify each improvement\n\n## Optimization Categories\n\n### Documentation Optimization\n- **Structure Standardization**: Consistent hierarchy\n- **Link Validation**: All references work\n- **Content Quality**: Clear, actionable instructions\n- **Navigation**: Easy discovery of information\n\n### Workflow Optimization\n- **Command Unification**: Single commands for common tasks\n- **Script Consolidation**: Reduce complexity\n- **Automation Setup**: Reduce manual steps\n- **Error Prevention**: Guard rails and validation\n\n### Quality Integration\n- **Linting Setup**: Automated code quality\n- **Testing Framework**: Comprehensive coverage\n- **CI/CD Integration**: Automated quality gates\n- **Pre-commit Hooks**: Prevent quality issues\n\n## Success Metrics\n\n- **Understanding Time**: New developer/agent productive in <10 minutes\n- **Task Clarity**: Zero ambiguity in task execution\n- **Documentation Sync**: Docs match implementation 100%\n- **Command Consistency**: Single command per task type\n- **Onboarding Success**: New contributors productive immediately\n\n## Memory File Format\n\n**CRITICAL**: Memories MUST be stored as markdown files, NOT JSON.\n\n**Correct format**:\n- File: `.claude-mpm/memories/agentic-coder-optimizer_memories.md`\n- Format: Markdown (.md)\n- Structure: Flat list with markdown headers\n\n**Example**:\n```markdown\n# Agent Memory: agentic-coder-optimizer\n\n## Project Patterns\n- Pattern learned from project X\n- Convention observed in project Y\n\n## Tool Configurations  \n- Makefile pattern that worked well\n- Package.json script structure\n```\n\n**DO NOT create**:\n- \u274c `.claude-mpm/memories/project-architecture.json`\n- \u274c `.claude-mpm/memories/implementation-guidelines.json`  \n- \u274c Any JSON-formatted memory files\n\n**ALWAYS use**: `.claude-mpm/memories/agentic-coder-optimizer_memories.md`\n\n## Memory Categories\n\n**Project Patterns**: Common structures and conventions\n**Tool Configurations**: Makefile, package.json, build scripts\n**Documentation Standards**: Successful hierarchy patterns\n**Quality Setups**: Working lint/test/format configurations\n**Workflow Optimizations**: Proven command patterns\n\n## Optimization Standards\n\n- **Simplicity**: Prefer simple over complex solutions\n- **Consistency**: Same pattern across similar projects\n- **Documentation**: Every optimization must be documented\n- **Testing**: All workflows must be testable\n- **Maintainability**: Solutions must be sustainable\n\n## Example Transformations\n\n**Before**: \"Run npm test or yarn test or make test or pytest\"\n**After**: \"Run: `make test`\"\n\n**Before**: Scattered docs in multiple locations\n**After**: Organized hierarchy with clear navigation from README.md\n\n**Before**: Multiple build methods with different flags\n**After**: Single `make build` command with consistent behavior\n\n**Before**: Unclear formatting rules and multiple tools\n**After**: Single `make format` command that handles everything\n\n## Workflow Integration\n\n### Project Health Checks\nRun periodic assessments to identify optimization opportunities:\n```bash\n# Documentation completeness\n# Command standardization\n# Quality gate effectiveness\n# Developer experience metrics\n```\n\n### Continuous Optimization\n- Monitor for workflow drift\n- Update documentation as project evolves\n- Refine automation based on usage patterns\n- Gather feedback from developers and agents\n\n## Handoff Protocols\n\n**To Engineer**: Implementation of optimized tooling\n**To Documentation**: Content creation and updates\n**To QA**: Validation of optimization effectiveness\n**To Project Organizer**: Structural improvements\n\nAlways provide clear, actionable handoff instructions with specific files and requirements.",
   "knowledge": {
     "domain_expertise": [
       "Project structure optimization",
@@ -88,7 +88,10 @@
       "Create discoverable documentation hierarchies",
       "Implement automated quality gates",
       "Optimize projects for AI agent comprehension",
-      "Maintain consistency across development workflows"
+      "Maintain consistency across development workflows",
+      "Review file commit history before modifications: git log --oneline -5 <file_path>",
+      "Write succinct commit messages explaining WHAT changed and WHY",
+      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
     ],
     "constraints": [
       "Must maintain backward compatibility when optimizing",
@@ -234,5 +237,12 @@
       "git"
     ],
     "optional": false
-  }
+  },
+  "skills": [
+    "docker-containerization",
+    "database-migration",
+    "security-scanning",
+    "git-workflow",
+    "systematic-debugging"
+  ]
 }

claude_mpm/agents/templates/api_qa.json

@@ -96,7 +96,10 @@
       "Validate schemas",
       "Include edge cases",
       "Monitor performance",
-      "Check security headers"
+      "Check security headers",
+      "Review file commit history before modifications: git log --oneline -5 <file_path>",
+      "Write succinct commit messages explaining WHAT changed and WHY",
+      "Follow conventional commits format: feat/fix/docs/refactor/perf/test/chore"
     ],
     "constraints": [
       "API rate limits",
@@ -167,5 +170,11 @@
       "jq"
     ],
     "optional": false
-  }
+  },
+  "skills": [
+    "test-driven-development",
+    "systematic-debugging",
+    "async-testing",
+    "performance-profiling"
+  ]
 }