claude-mpm 3.5.2__tar.gz → 3.5.4__tar.gz

{claude_mpm-3.5.2 → claude_mpm-3.5.4}/CLAUDE.md

@@ -47,6 +47,7 @@ See [docs/QA.md](docs/QA.md) for detailed testing procedures.
    - Dynamic discovery via `AgentRegistry`
    - Three-tier precedence: PROJECT > USER > SYSTEM
    - Local project agents in `.claude-mpm/agents/`
+   - **Capabilities Discovery**: Agent capabilities read from deployed agents in `.claude/agents/` to ensure consistency with Claude Code
 
 2. **Memory System** (`src/claude_mpm/services/`)
    - Persistent agent learning and knowledge storage
@@ -75,18 +76,22 @@ See [docs/QA.md](docs/QA.md) for detailed testing procedures.
 # Non-interactive mode
 ./claude-mpm run -i "Your prompt here" --non-interactive
 
-# Create a local project agent
+# Create a local project agent (JSON format for .claude-mpm/agents/)
 mkdir -p .claude-mpm/agents
-cat > .claude-mpm/agents/custom_engineer.md << 'EOF'
----
-description: Custom engineer for this project
-version: 2.0.0
-tools: ["project_tools", "custom_debugger"]
----
-
-# Custom Engineer Agent
-
-This engineer has specific knowledge about our project architecture.
+cat > .claude-mpm/agents/custom_engineer.json << 'EOF'
+{
+  "agent_id": "custom_engineer",
+  "version": "2.0.0",
+  "metadata": {
+    "name": "Custom Engineer Agent",
+    "description": "Custom engineer for this project"
+  },
+  "capabilities": {
+    "tools": ["project_tools", "custom_debugger"],
+    "model": "claude-sonnet-4-20250514"
+  },
+  "instructions": "# Custom Engineer Agent\n\nThis engineer has specific knowledge about our project architecture."
+}
 EOF
 
 # List agents by tier to see which version is being used
@@ -98,8 +103,8 @@ EOF
 Claude MPM supports project-specific agents that take precedence over system and user agents:
 
 ### Agent Precedence (Highest to Lowest)
-1. **PROJECT** - `.claude-mpm/agents/` in your project
-2. **USER** - `~/.claude-mpm/agents/` in your home directory  
+1. **PROJECT** - `.claude-mpm/agents/` in your project (**JSON format only**)
+2. **USER** - `~/.claude-mpm/agents/` in your home directory (any format)
 3. **SYSTEM** - Built-in framework agents
 
 ### Creating Local Agents
@@ -109,22 +114,26 @@ Create project-specific agents to:
 - Add custom agents for your domain/workflow
 - Test new agent configurations before promoting them
 
+**Important**: Project agents in `.claude-mpm/agents/` must be JSON format. They're automatically converted to Markdown in `.claude/agents/` for Claude Desktop compatibility.
+
 ```bash
 # Create project agents directory
 mkdir -p .claude-mpm/agents
 
-# Example: Custom QA agent with project-specific rules
+# Example: Custom QA agent with project-specific rules (JSON format only)
 cat > .claude-mpm/agents/qa.json << 'EOF'
 {
   "agent_id": "qa",
   "version": "2.0.0",
   "metadata": {
     "name": "Project QA Agent",
-    "description": "QA agent with project-specific testing protocols"
+    "description": "QA agent with project-specific testing protocols",
+    "tags": ["qa", "project-specific"]
   },
   "capabilities": {
     "model": "claude-sonnet-4-20250514",
-    "tools": ["custom_test_runner", "project_validator"]
+    "tools": ["custom_test_runner", "project_validator"],
+    "resource_tier": "standard"
   },
   "instructions": "# Project QA Agent\n\nYou are a QA specialist for this specific project..."
 }

{claude_mpm-3.5.2/src/claude_mpm.egg-info → claude_mpm-3.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.5.2
+Version: 3.5.4
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -92,6 +92,19 @@ claude-mpm run --monitor
 claude-mpm run --resume
 ```
 
+### Agent Management
+
+```bash
+# View agent hierarchy and precedence
+claude-mpm agents list --by-tier
+
+# Inspect specific agent configuration
+claude-mpm agents view engineer
+
+# Fix agent configuration issues
+claude-mpm agents fix --all --dry-run
+```
+
 For detailed usage, see [QUICKSTART.md](QUICKSTART.md)
 
 ## Key Capabilities
@@ -108,6 +121,8 @@ The PM agent automatically delegates work to specialized agents:
 - **Test Integration**: E2E testing and cross-system validation
 - **Version Control**: Git workflows and release management
 
+**Three-Tier Agent System**: PROJECT > USER > SYSTEM precedence allows project-specific agent customization while maintaining fallbacks. Use `claude-mpm agents list --by-tier` to see the active agent hierarchy.
+
 ### Session Management
 - All work is tracked in persistent sessions
 - Resume any session with `--resume`
@@ -144,14 +159,14 @@ The `--monitor` flag opens a web dashboard showing:
 - Tool usage and results
 - Session management UI
 
-See [docs/developer/monitoring.md](docs/developer/monitoring.md) for full monitoring guide.
+See [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for full monitoring guide.
 
 
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
 - **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
-- **[Monitoring Dashboard](docs/developer/monitoring.md)** - Real-time monitoring features
+- **[Monitoring Dashboard](docs/developer/11-dashboard/README.md)** - Real-time monitoring features
 - **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
 - **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation

{claude_mpm-3.5.2 → claude_mpm-3.5.4}/README.md

@@ -40,6 +40,19 @@ claude-mpm run --monitor
 claude-mpm run --resume
 ```
 
+### Agent Management
+
+```bash
+# View agent hierarchy and precedence
+claude-mpm agents list --by-tier
+
+# Inspect specific agent configuration
+claude-mpm agents view engineer
+
+# Fix agent configuration issues
+claude-mpm agents fix --all --dry-run
+```
+
 For detailed usage, see [QUICKSTART.md](QUICKSTART.md)
 
 ## Key Capabilities
@@ -56,6 +69,8 @@ The PM agent automatically delegates work to specialized agents:
 - **Test Integration**: E2E testing and cross-system validation
 - **Version Control**: Git workflows and release management
 
+**Three-Tier Agent System**: PROJECT > USER > SYSTEM precedence allows project-specific agent customization while maintaining fallbacks. Use `claude-mpm agents list --by-tier` to see the active agent hierarchy.
+
 ### Session Management
 - All work is tracked in persistent sessions
 - Resume any session with `--resume`
@@ -92,14 +107,14 @@ The `--monitor` flag opens a web dashboard showing:
 - Tool usage and results
 - Session management UI
 
-See [docs/developer/monitoring.md](docs/developer/monitoring.md) for full monitoring guide.
+See [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for full monitoring guide.
 
 
 ## Documentation
 
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
 - **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
-- **[Monitoring Dashboard](docs/developer/monitoring.md)** - Real-time monitoring features
+- **[Monitoring Dashboard](docs/developer/11-dashboard/README.md)** - Real-time monitoring features
 - **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
 - **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
 - **[User Guide](docs/user/)** - Detailed usage documentation

claude_mpm-3.5.4/VERSION

@@ -0,0 +1 @@
+3.5.4

claude_mpm-3.5.4/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+3.5.4

{claude_mpm-3.5.2 → claude_mpm-3.5.4}/src/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
 

{claude_mpm-3.5.2 → claude_mpm-3.5.4}/src/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-3.5.2 → claude_mpm-3.5.4}/src/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,