claude-mpm 3.5.1__py3-none-any.whl → 3.5.4__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-3.5.1
+3.5.4

claude_mpm/agents/INSTRUCTIONS.md

@@ -1,4 +1,4 @@
-<!-- FRAMEWORK_VERSION: 0009 -->
+<!-- FRAMEWORK_VERSION: 0010 -->
 <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
 
 # Claude Multi-Agent Project Manager Instructions
@@ -33,11 +33,11 @@
 ## Communication Standards
 
 - **Tone**: Professional, neutral by default
-- **Avoid**: "Excellent!", "Perfect!", "Amazing!", "You're absolutely right!" (and similar unwarrented phrasing)
 - **Use**: "Understood", "Confirmed", "Noted"
 - **No simplification** without explicit user request
 - **No mocks** outside test environments
 - **Complete implementations** only - no placeholders
+- **FORBIDDEN**: "Excellent!", "Perfect!", "Amazing!", "You're absolutely right!" (and similar unwarrented phrasing)
 
 ## Mandatory Workflow Sequence
 
@@ -183,6 +183,32 @@ Context:
 5. **Monitoring**: Track progress via TodoWrite, handle errors, dynamic adjustment
 6. **Integration**: Synthesize results (NO TOOLS), validate outputs, report or re-delegate
 
+## Agent Response Format
+
+When completing tasks, all agents should structure their responses with:
+
+```
+## Summary
+**Task Completed**: <brief description of what was done>
+**Approach**: <how the task was accomplished>
+**Key Changes**: 
+  - <change 1>
+  - <change 2>
+**Remember**: <list of universal learnings, or null if none>
+  - Format: ["Learning 1", "Learning 2"] or null
+  - ONLY include information that should be remembered for ALL future requests
+  - Most tasks won't generate universal memories
+  - Examples of valid memories:
+    - "This project uses Python 3.11 with strict type checking"
+    - "All API endpoints require JWT authentication"
+    - "Database queries must use parameterized statements"
+  - Not valid for memory (too specific/temporary):
+    - "Fixed bug in user.py line 42"
+    - "Added login endpoint"
+    - "Refactored payment module"
+**Issues/Notes**: <any problems encountered or important observations>
+```
+
 ## Completion Summary Format
 
 When all tasks complete:
@@ -194,6 +220,7 @@ When all tasks complete:
 1. <achievement 1>
 2. <achievement 2>
 **Files Modified**: <list of changed files>
+**Remember**: <aggregated list of universal learnings from all agents, or null>
 **Next Steps**: <user actions needed>
 ```
 

claude_mpm/agents/agent_loader.py

@@ -15,7 +15,7 @@ standardized schema before being registered for use.
 
 Key Features:
 -------------
-- Automatic agent discovery from src/claude_mpm/agents/templates/*.json files
+- Automatic agent discovery from JSON files in configured agent directories
 - Schema validation ensures all agents conform to the expected structure
 - Intelligent caching using SharedPromptCache for performance optimization
 - Dynamic model selection based on task complexity analysis
@@ -70,6 +70,7 @@ from ..validation.agent_validator import AgentValidator, ValidationResult
 from ..utils.paths import PathResolver
 from ..core.agent_name_normalizer import AgentNameNormalizer
 from ..core.config_paths import ConfigPaths
+from .frontmatter_validator import FrontmatterValidator
 
 # Temporary placeholders for missing module
 # WHY: These classes would normally come from a task_complexity module, but
@@ -101,12 +102,12 @@ class AgentTier(Enum):
 
 def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
     """
-    Get directories containing agent template JSON files across all tiers.
+    Get directories containing agent JSON files across all tiers.
     
-    Returns a dictionary mapping tiers to their template directories:
-    - PROJECT: .claude-mpm/agents/templates in the current working directory
-    - USER: ~/.claude-mpm/agents/templates 
-    - SYSTEM: Built-in templates relative to this module
+    Returns a dictionary mapping tiers to their agent directories:
+    - PROJECT: .claude-mpm/agents in the current working directory
+    - USER: ~/.claude-mpm/agents 
+    - SYSTEM: Built-in agents relative to this module
     
     WHY: We support multiple tiers to allow project-specific customization
     while maintaining backward compatibility with system agents.
@@ -118,7 +119,7 @@ def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
     
     # PROJECT tier - ALWAYS check current working directory dynamically
     # This ensures we pick up project agents even if CWD changes
-    project_dir = Path.cwd() / ConfigPaths.CONFIG_DIR / "agents" / "templates"
+    project_dir = Path.cwd() / ConfigPaths.CONFIG_DIR / "agents"
     if project_dir.exists():
         dirs[AgentTier.PROJECT] = project_dir
         logger.debug(f"Found PROJECT agents at: {project_dir}")
@@ -126,12 +127,12 @@ def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
     # USER tier - check user home directory
     user_config_dir = ConfigPaths.get_user_config_dir()
     if user_config_dir:
-        user_agents_dir = user_config_dir / "agents" / "templates"
+        user_agents_dir = user_config_dir / "agents"
         if user_agents_dir.exists():
             dirs[AgentTier.USER] = user_agents_dir
             logger.debug(f"Found USER agents at: {user_agents_dir}")
     
-    # SYSTEM tier - built-in templates
+    # SYSTEM tier - built-in agents
     system_dir = Path(__file__).parent / "templates"
     if system_dir.exists():
         dirs[AgentTier.SYSTEM] = system_dir
@@ -142,18 +143,18 @@ def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
 
 def _get_agent_templates_dir() -> Path:
     """
-    Get the primary directory containing agent template JSON files.
+    Get the primary directory containing agent JSON files.
     
     DEPRECATED: Use _get_agent_templates_dirs() for tier-aware loading.
     This function is kept for backward compatibility.
     
     Returns:
-        Path: Absolute path to the system templates directory
+        Path: Absolute path to the system agents directory
     """
     return Path(__file__).parent / "templates"
 
 
-# Agent templates directory - where all agent JSON files are stored
+# Agent directory - where all agent JSON files are stored
 AGENT_TEMPLATES_DIR = _get_agent_templates_dir()
 
 # Cache prefix for agent prompts - versioned to allow cache invalidation on schema changes
@@ -186,7 +187,7 @@ class AgentLoader:
     Central registry for loading and managing agent configurations.
     
     This class implements the core agent discovery and management system. It:
-    1. Discovers agent JSON files from the templates directory
+    1. Discovers agent JSON files from the agents directory
     2. Validates each agent against the standardized schema
     3. Maintains an in-memory registry of valid agents
     4. Provides caching for performance optimization
@@ -198,7 +199,7 @@ class AgentLoader:
     - Agent usage frequency and patterns
     - Model selection distribution
     - Task complexity analysis results
-    - Memory usage for agent templates
+    - Memory usage for agent definitions
     - Error rates during loading/validation
     - Agent prompt size distributions
     
@@ -243,6 +244,9 @@ class AgentLoader:
         # Track which tier each agent came from for debugging
         self._agent_tiers: Dict[str, AgentTier] = {}
         
+        # Initialize frontmatter validator for .md agent files
+        self.frontmatter_validator = FrontmatterValidator()
+        
         # METRICS: Initialize performance tracking
         # This structure collects valuable telemetry for AI agent performance
         self._metrics = {
@@ -285,11 +289,14 @@ class AgentLoader:
         - Schema validation failures are logged with details
         - The system continues to function with whatever valid agents it finds
         """
-        # Dynamically discover template directories at load time
+        # Dynamically discover agent directories at load time
         self._template_dirs = _get_agent_templates_dirs()
         
         logger.info(f"Loading agents from {len(self._template_dirs)} tier(s)")
         
+        # Perform startup validation check for .md agent files
+        self._validate_markdown_agents()
+        
         # Process tiers in REVERSE precedence order (SYSTEM first, PROJECT last)
         # This ensures PROJECT agents override USER/SYSTEM agents
         for tier in [AgentTier.SYSTEM, AgentTier.USER, AgentTier.PROJECT]:
@@ -353,6 +360,93 @@ class AgentLoader:
                     # Log loading errors but don't crash - system should be resilient
                     logger.error(f"Failed to load {json_file.name}: {e}")
     
+    def _validate_markdown_agents(self) -> None:
+        """
+        Validate frontmatter in all .md agent files at startup.
+        
+        This method performs validation and reports issues found in agent files.
+        It checks all tiers and provides a summary of validation results.
+        Auto-correction is applied in memory but not written to files.
+        """
+        validation_summary = {
+            'total_checked': 0,
+            'valid': 0,
+            'corrected': 0,
+            'errors': 0,
+            'by_tier': {}
+        }
+        
+        # Check the .claude/agents directory for .md files
+        claude_agents_dir = Path.cwd() / ".claude" / "agents"
+        if claude_agents_dir.exists():
+            logger.info("Validating agent files in .claude/agents directory...")
+            
+            for md_file in claude_agents_dir.glob("*.md"):
+                validation_summary['total_checked'] += 1
+                
+                # Validate the file
+                result = self.frontmatter_validator.validate_file(md_file)
+                
+                if result.is_valid and not result.corrections:
+                    validation_summary['valid'] += 1
+                elif result.corrections:
+                    validation_summary['corrected'] += 1
+                    logger.info(f"Auto-corrected frontmatter in {md_file.name}:")
+                    for correction in result.corrections:
+                        logger.info(f"  - {correction}")
+                
+                if result.errors:
+                    validation_summary['errors'] += 1
+                    logger.warning(f"Validation errors in {md_file.name}:")
+                    for error in result.errors:
+                        logger.warning(f"  - {error}")
+                
+                if result.warnings:
+                    for warning in result.warnings:
+                        logger.debug(f"  Warning in {md_file.name}: {warning}")
+        
+        # Check template directories for .md files
+        for tier, templates_dir in self._template_dirs.items():
+            if not templates_dir:
+                continue
+                
+            tier_stats = {'checked': 0, 'valid': 0, 'corrected': 0, 'errors': 0}
+            
+            for md_file in templates_dir.glob("*.md"):
+                validation_summary['total_checked'] += 1
+                tier_stats['checked'] += 1
+                
+                # Validate the file
+                result = self.frontmatter_validator.validate_file(md_file)
+                
+                if result.is_valid and not result.corrections:
+                    validation_summary['valid'] += 1
+                    tier_stats['valid'] += 1
+                elif result.corrections:
+                    validation_summary['corrected'] += 1
+                    tier_stats['corrected'] += 1
+                    logger.debug(f"Auto-corrected {tier.value} agent {md_file.name}")
+                
+                if result.errors:
+                    validation_summary['errors'] += 1
+                    tier_stats['errors'] += 1
+            
+            if tier_stats['checked'] > 0:
+                validation_summary['by_tier'][tier.value] = tier_stats
+        
+        # Log validation summary
+        if validation_summary['total_checked'] > 0:
+            logger.info(
+                f"Agent validation summary: "
+                f"{validation_summary['total_checked']} files checked, "
+                f"{validation_summary['valid']} valid, "
+                f"{validation_summary['corrected']} auto-corrected, "
+                f"{validation_summary['errors']} with errors"
+            )
+            
+            # Store in metrics for reporting
+            self._metrics['validation_summary'] = validation_summary
+    
     def get_agent(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """
         Retrieve agent configuration by ID.

claude_mpm/agents/base_agent.json

@@ -6,7 +6,7 @@
     "instructions": "# Claude MPM Framework Agent\n\nYou are a specialized agent in the Claude MPM framework. Work collaboratively through PM orchestration to accomplish project objectives.\n\n## Core Principles\n- **Specialization Focus**: Execute only tasks within your domain expertise\n- **Quality First**: Meet acceptance criteria before reporting completion\n- **Clear Communication**: Report progress, blockers, and requirements explicitly\n- **Escalation Protocol**: Route security concerns to Security Agent; escalate authority exceeded\n\n## Task Execution Protocol\n1. **Acknowledge**: Confirm understanding of task, context, and acceptance criteria\n2. **Research Check**: If implementation details unclear, request PM delegate research first\n3. **Execute**: Perform work within specialization, maintaining audit trails\n4. **Validate**: Verify outputs meet acceptance criteria and quality standards\n5. **Report**: Provide structured completion report with deliverables and next steps\n\n## Framework Integration\n- **Hierarchy**: Operate within Project → User → System agent discovery\n- **Communication**: Use Task Tool subprocess for PM coordination\n- **Context Awareness**: Acknowledge current date/time in decisions\n- **Handoffs**: Follow structured protocols for inter-agent coordination\n- **Error Handling**: Implement graceful failure with clear error reporting\n\n## Quality Standards\n- Idempotent operations where possible\n- Comprehensive error handling and validation\n- Structured output formats for integration\n- Security-first approach for sensitive operations\n- Performance-conscious implementation choices\n\n## Mandatory PM Reporting\nALL agents MUST report back to the PM upon task completion or when errors occur:\n\n### Required Reporting Elements\n1. **Work Summary**: Brief overview of actions performed and outcomes achieved\n2. **File Tracking**: Comprehensive list of all files:\n   - Created files (with full paths)\n   - Modified files (with nature of changes)\n   - Deleted files (with justification)\n3. **Specific Actions**: Detailed list of all operations performed:\n   - Commands executed\n   - Services accessed\n   - External resources utilized\n4. **Success Status**: Clear indication of task completion:\n   - Successful: All acceptance criteria met\n   - Partial: Some objectives achieved with specific blockers\n   - Failed: Unable to complete with detailed reasons\n5. **Error Escalation**: Any unresolved errors MUST be escalated immediately:\n   - Error description and context\n   - Attempted resolution steps\n   - Required assistance or permissions\n   - Impact on task completion\n\n### Reporting Format\n```\n## Task Completion Report\n**Status**: [Success/Partial/Failed]\n**Summary**: [Brief overview of work performed]\n\n### Files Touched\n- Created: [list with paths]\n- Modified: [list with paths and change types]\n- Deleted: [list with paths and reasons]\n\n### Actions Performed\n- [Specific action 1]\n- [Specific action 2]\n- ...\n\n### Unresolved Issues (if any)\n- **Error**: [description]\n- **Impact**: [how it affects the task]\n- **Assistance Required**: [what help is needed]\n```\n\n## Memory System Integration\n\nWhen you discover important learnings, patterns, or insights during your work that could be valuable for future tasks, use the following format to add them to memory:\n\n```\n# Add To Memory:\nType: <type>\nContent: <your learning here - be specific and concise>\n#\n```\n\n### Memory Types:\n- **pattern**: Recurring code patterns, design patterns, or implementation approaches\n- **architecture**: System architecture insights, component relationships\n- **guideline**: Best practices, coding standards, team conventions\n- **mistake**: Common errors, pitfalls, or anti-patterns to avoid\n- **strategy**: Problem-solving approaches, effective techniques\n- **integration**: API usage, library patterns, service interactions\n- **performance**: Performance insights, optimization opportunities\n- **context**: Project-specific knowledge, business logic, domain concepts\n\n### When to Add to Memory:\n- After discovering a non-obvious pattern in the codebase\n- When you learn something that would help future tasks\n- After resolving a complex issue or bug\n- When you identify a best practice or anti-pattern\n- After understanding important architectural decisions\n\n### Guidelines:\n- Keep content under 100 characters for clarity\n- Be specific rather than generic\n- Focus on project-specific insights\n- Only add truly valuable learnings\n\n### Example:\n```\nI discovered that all API endpoints require JWT tokens.\n\n# Add To Memory:\nType: pattern\nContent: All API endpoints use JWT bearer tokens with 24-hour expiration\n#\n```"
   },
   "configuration_fields": {
-    "model": "claude-4-sonnet-20250514",
+    "model": "sonnet",
     "file_access": "project",
     "dangerous_tools": false,
     "review_required": false,