claude-mpm 1.1.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/content_assembler.py

@@ -8,6 +8,12 @@ import hashlib
 from datetime import datetime
 from typing import Dict, List, Optional, Any
 from collections import OrderedDict
+import logging
+
+from claude_mpm.services.deployed_agent_discovery import DeployedAgentDiscovery
+from claude_mpm.services.agent_capabilities_generator import AgentCapabilitiesGenerator
+
+logger = logging.getLogger(__name__)
 
 
 class ContentAssembler:
@@ -16,6 +22,9 @@ class ContentAssembler:
     def __init__(self):
         """Initialize content assembler."""
         self.template_variables = {}
+        self.agent_discovery = DeployedAgentDiscovery()
+        self.capabilities_generator = AgentCapabilitiesGenerator()
+        logger.debug("Initialized ContentAssembler with dynamic agent capabilities support")
     
     def generate_content_hash(self) -> str:
         """
@@ -63,12 +72,32 @@ class ContentAssembler:
         """
         Apply template variable substitution to content.
         
+        WHY: Enhanced to support dynamic agent capabilities generation.
+        - Generates fresh agent capabilities on each call
+        - Provides graceful fallback if generation fails
+        - Ensures INSTRUCTIONS.md always reflects current deployed agents
+        
         Args:
             content: Content with template variables
             
         Returns:
             str: Content with variables substituted
         """
+        # Check if we need to generate dynamic capabilities
+        if "{{capabilities-list}}" in content:
+            try:
+                # Discover deployed agents
+                deployed_agents = self.agent_discovery.discover_deployed_agents()
+                # Generate capabilities content
+                capabilities_content = self.capabilities_generator.generate_capabilities_section(deployed_agents)
+                # Add to template variables
+                self.template_variables['capabilities-list'] = capabilities_content
+                logger.info(f"Generated dynamic capabilities for {len(deployed_agents)} agents")
+            except Exception as e:
+                logger.error(f"Failed to generate dynamic capabilities: {e}")
+                # Fallback is handled by the generator's internal fallback mechanism
+        
+        # Apply all template variables
         for var_name, var_value in self.template_variables.items():
             placeholder = f"{{{{{var_name}}}}}"
             content = content.replace(placeholder, var_value)

claude_mpm/services/framework_claude_md_generator/deployment_manager.py

@@ -35,6 +35,11 @@ class DeploymentManager:
         """
         Deploy generated content to a parent directory.
         
+        WHY: Enhanced to ensure fresh agent capabilities generation on each deployment.
+        - Checks for template variables that need processing
+        - Re-processes content to get current deployed agents
+        - Ensures INSTRUCTIONS.md always reflects latest agent configuration
+        
         Args:
             content: Content to deploy
             parent_path: Path to parent directory
@@ -52,16 +57,33 @@ class DeploymentManager:
         target_file = parent_path / "INSTRUCTIONS.md"
         # TODO: Make this configurable via parameter
         
+        # Check if content contains template variables that need processing
+        if '{{capabilities-list}}' in content:
+            # Content needs processing - let ContentAssembler handle it
+            from .content_assembler import ContentAssembler
+            assembler = ContentAssembler()
+            
+            # Re-process content to get fresh agent data
+            # Pass content as a single section to preserve structure
+            processed_content = assembler.apply_template_variables(content)
+            content = processed_content
+        
         # Validate content before deployment
-        is_valid, issues = self.validator.validate_content(content)
-        if not is_valid:
-            return False, f"Validation failed: {'; '.join(issues)}"
+        # Skip validation for INSTRUCTIONS.md format (different from CLAUDE.md)
+        if "<!-- FRAMEWORK_VERSION:" in content and "# Claude Multi-Agent Project Manager Instructions" in content:
+            # This is INSTRUCTIONS.md format, skip CLAUDE.md validation
+            pass
+        else:
+            # This is CLAUDE.md format, validate normally
+            is_valid, issues = self.validator.validate_content(content)
+            if not is_valid:
+                return False, f"Validation failed: {'; '.join(issues)}"
         
         # Check if file exists and compare versions
         if target_file.exists() and not force:
             with open(target_file, 'r') as f:
                 existing_content = f.read()
-                existing_fw_ver, _ = self.version_manager.parse_current_version(existing_content)
+                existing_fw_ver = self.version_manager.parse_current_version(existing_content)
                 
             if existing_fw_ver == self.version_manager.framework_version:
                 return True, f"Version {existing_fw_ver} already deployed"
@@ -76,8 +98,8 @@ class DeploymentManager:
                 f.write(content)
             
             # Get version info for success message
-            fw_ver, serial = self.version_manager.parse_current_version(content)
-            version_str = f"{fw_ver}-{serial:03d}"
+            fw_ver = self.version_manager.parse_current_version(content)
+            version_str = fw_ver
             
             return True, f"Successfully deployed version {version_str}"
         except Exception as e:
@@ -101,7 +123,7 @@ class DeploymentManager:
         try:
             with open(target_file, 'r') as f:
                 existing_content = f.read()
-                existing_fw_ver, _ = self.version_manager.parse_current_version(existing_content)
+                existing_fw_ver = self.version_manager.parse_current_version(existing_content)
             
             if existing_fw_ver != self.version_manager.framework_version:
                 return True, f"Version mismatch: {existing_fw_ver} vs {self.version_manager.framework_version}"

claude_mpm/utils/framework_detection.py

@@ -0,0 +1,39 @@
+"""Framework source directory detection utilities.
+
+WHY: This module provides utilities to detect if we're in the framework source directory
+to prevent accidental overwrites of the template files during deployment.
+"""
+
+from pathlib import Path
+from typing import Tuple, List
+
+
+def is_framework_source_directory(path: Path) -> Tuple[bool, List[str]]:
+    """
+    Check if the given path is the framework source directory.
+    
+    WHY: We need to prevent deployment to the framework source directory itself
+    to avoid overwriting template files.
+    
+    Args:
+        path: Path to check
+        
+    Returns:
+        Tuple of (is_framework_source, list of detected markers)
+    """
+    markers = []
+    
+    # Check for framework source markers
+    if (path / "src" / "claude_mpm").exists():
+        markers.append("src/claude_mpm")
+    
+    if (path / "pyproject.toml").exists():
+        markers.append("pyproject.toml")
+    
+    if (path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md").exists():
+        markers.append("framework INSTRUCTIONS.md template")
+    
+    # If we have multiple markers, it's likely the framework source
+    is_framework = len(markers) >= 2
+    
+    return is_framework, markers

claude_mpm/validation/agent_validator.py

@@ -1,15 +1,18 @@
 """
-Agent validation framework inspired by awesome-claude-code validation patterns.
+Agent validation framework using JSON Schema validation.
 
-This module provides comprehensive validation for agent configurations with
-override support, field locking, and detailed error reporting.
+This module provides comprehensive validation for agent configurations
+using the standardized JSON schema with direct validation approach.
 """
 
+import json
 import logging
 from pathlib import Path
-from typing import Dict, List, Tuple, Optional, Set, Any
-import yaml
+from typing import Dict, List, Optional, Any, Tuple
 from dataclasses import dataclass, field
+from datetime import datetime
+import jsonschema
+from jsonschema import validate, ValidationError, Draft7Validator
 
 logger = logging.getLogger(__name__)
 
@@ -20,156 +23,280 @@ class ValidationResult:
     is_valid: bool
     errors: List[str] = field(default_factory=list)
     warnings: List[str] = field(default_factory=list)
-    locked_fields: Set[str] = field(default_factory=set)
-    applied_overrides: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
 
 
 class AgentValidator:
-    """Validates agent configurations with override support."""
+    """Validates agent configurations against JSON schema."""
     
-    REQUIRED_FIELDS = ['name', 'version', 'description', 'agents']
-    AGENT_REQUIRED_FIELDS = ['name', 'role', 'prompt_template']
-    
-    def __init__(self, override_file: Optional[Path] = None):
-        """Initialize the validator with optional override configuration."""
-        self.overrides = {}
-        if override_file and override_file.exists():
-            self.overrides = self._load_overrides(override_file)
+    def __init__(self, schema_path: Optional[Path] = None):
+        """Initialize the validator with the agent schema."""
+        if schema_path is None:
+            schema_path = Path(__file__).parent.parent / "schemas" / "agent_schema.json"
+        
+        self.schema_path = schema_path
+        self.schema = self._load_schema()
+        self.validator = Draft7Validator(self.schema)
     
-    def _load_overrides(self, override_file: Path) -> Dict[str, Any]:
-        """Load override configuration from YAML file."""
+    def _load_schema(self) -> Dict[str, Any]:
+        """Load the JSON schema from file."""
         try:
-            with open(override_file, 'r') as f:
-                data = yaml.safe_load(f)
-                return data.get('overrides', {})
+            with open(self.schema_path, 'r') as f:
+                return json.load(f)
         except Exception as e:
-            logger.warning(f"Failed to load overrides from {override_file}: {e}")
-            return {}
+            logger.error(f"Failed to load schema from {self.schema_path}: {e}")
+            raise
     
-    def validate_agent_config(self, config: Dict[str, Any], agent_id: str) -> ValidationResult:
-        """Validate a single agent configuration."""
+    def validate_agent(self, agent_data: Dict[str, Any]) -> ValidationResult:
+        """
+        Validate a single agent configuration against the schema.
+        
+        Args:
+            agent_data: Agent configuration dictionary
+            
+        Returns:
+            ValidationResult with validation status and any errors/warnings
+        """
         result = ValidationResult(is_valid=True)
         
-        # Apply overrides
-        config, locked_fields, skip_validation = self._apply_overrides(config, agent_id)
-        result.locked_fields = locked_fields
+        # Perform JSON schema validation
+        try:
+            validate(instance=agent_data, schema=self.schema)
+        except ValidationError as e:
+            result.is_valid = False
+            result.errors.append(f"Schema validation error: {e.message}")
+            
+            # Add path information if available
+            if e.path:
+                path = ".".join(str(p) for p in e.path)
+                result.errors.append(f"Error at path: {path}")
         
-        if skip_validation:
-            logger.info(f"Skipping validation for agent {agent_id} - marked as skip_validation")
-            return result
+        # Additional business rule validations
+        if result.is_valid:
+            self._validate_business_rules(agent_data, result)
         
-        # Validate required fields
-        for field in self.AGENT_REQUIRED_FIELDS:
-            if field not in locked_fields and field not in config:
-                result.errors.append(f"Missing required field: {field}")
-                result.is_valid = False
-        
-        # Validate prompt template
-        if 'prompt_template' in config and 'prompt_template' not in locked_fields:
-            template_result = self._validate_prompt_template(config['prompt_template'])
-            if not template_result[0]:
-                result.errors.extend(template_result[1])
-                result.is_valid = False
-        
-        # Validate tools if present
-        if 'tools' in config:
-            tools_result = self._validate_tools(config['tools'])
-            if not tools_result[0]:
-                result.errors.extend(tools_result[1])
-                result.is_valid = False
+        # Add metadata
+        result.metadata = {
+            "validated_at": datetime.utcnow().isoformat(),
+            "schema_version": self.schema.get("version", "1.0.0"),
+            "agent_id": agent_data.get("id", "unknown")
+        }
         
         return result
     
-    def _apply_overrides(self, config: Dict[str, Any], agent_id: str) -> Tuple[Dict[str, Any], Set[str], bool]:
-        """Apply overrides to an agent configuration."""
-        if agent_id not in self.overrides:
-            return config, set(), False
+    def _validate_business_rules(self, agent_data: Dict[str, Any], result: ValidationResult) -> None:
+        """Apply additional business rule validations beyond schema."""
+        
+        # Validate resource tier consistency
+        resource_tier = agent_data.get("capabilities", {}).get("resource_tier")
+        if resource_tier:
+            self._validate_resource_tier_limits(agent_data, resource_tier, result)
+        
+        # Validate instruction length (double-check)
+        instructions = agent_data.get("instructions", "")
+        if len(instructions) > 8000:
+            result.errors.append(f"Instructions exceed 8000 character limit: {len(instructions)} characters")
+            result.is_valid = False
         
-        override_config = self.overrides[agent_id]
-        locked_fields = set()
-        skip_validation = override_config.get('skip_validation', False)
+        # Validate model compatibility with tools
+        self._validate_model_tool_compatibility(agent_data, result)
         
-        # Apply each override
-        for field, value in override_config.items():
-            if field.endswith('_locked'):
-                base_field = field.replace('_locked', '')
-                if override_config.get(field, False):
-                    locked_fields.add(base_field)
-            elif field not in ['notes', 'skip_validation']:
-                config[field] = value
+        # Validate agent ID format (clean IDs without _agent suffix)
+        agent_id = agent_data.get("id", "")
+        if agent_id.endswith("_agent"):
+            result.warnings.append(f"Agent ID '{agent_id}' contains deprecated '_agent' suffix")
         
-        return config, locked_fields, skip_validation
+        # Validate handoff agents exist
+        handoff_agents = agent_data.get("interactions", {}).get("handoff_agents", [])
+        for handoff_id in handoff_agents:
+            if handoff_id == agent_id:
+                result.warnings.append(f"Agent '{agent_id}' references itself in handoff_agents")
     
-    def _validate_prompt_template(self, template: str) -> Tuple[bool, List[str]]:
-        """Validate prompt template format and placeholders."""
-        errors = []
+    def _validate_resource_tier_limits(self, agent_data: Dict[str, Any], tier: str, result: ValidationResult) -> None:
+        """Validate resource limits match the tier constraints."""
+        tier_limits = {
+            "intensive": {
+                "memory_limit": (4096, 8192),
+                "cpu_limit": (60, 100),
+                "timeout": (600, 3600)
+            },
+            "standard": {
+                "memory_limit": (2048, 4096),
+                "cpu_limit": (30, 60),
+                "timeout": (300, 1200)
+            },
+            "lightweight": {
+                "memory_limit": (512, 2048),
+                "cpu_limit": (10, 30),
+                "timeout": (30, 600)
+            }
+        }
         
-        if not template or not isinstance(template, str):
-            errors.append("Prompt template must be a non-empty string")
-            return False, errors
+        if tier not in tier_limits:
+            return
         
-        # Check for common placeholders
-        expected_placeholders = ['{context}', '{task}', '{constraints}']
-        missing_placeholders = []
+        limits = tier_limits[tier]
+        capabilities = agent_data.get("capabilities", {})
         
-        for placeholder in expected_placeholders:
-            if placeholder not in template:
-                missing_placeholders.append(placeholder)
+        # Check memory limit
+        memory = capabilities.get("memory_limit")
+        if memory is not None:
+            min_mem, max_mem = limits["memory_limit"]
+            if not (min_mem <= memory <= max_mem):
+                result.warnings.append(
+                    f"Memory limit {memory}MB outside recommended range "
+                    f"{min_mem}-{max_mem}MB for tier '{tier}'"
+                )
         
-        if missing_placeholders:
-            errors.append(f"Prompt template missing placeholders: {', '.join(missing_placeholders)}")
+        # Check CPU limit
+        cpu = capabilities.get("cpu_limit")
+        if cpu is not None:
+            min_cpu, max_cpu = limits["cpu_limit"]
+            if not (min_cpu <= cpu <= max_cpu):
+                result.warnings.append(
+                    f"CPU limit {cpu}% outside recommended range "
+                    f"{min_cpu}-{max_cpu}% for tier '{tier}'"
+                )
         
-        return len(errors) == 0, errors
+        # Check timeout
+        timeout = capabilities.get("timeout")
+        if timeout is not None:
+            min_timeout, max_timeout = limits["timeout"]
+            if not (min_timeout <= timeout <= max_timeout):
+                result.warnings.append(
+                    f"Timeout {timeout}s outside recommended range "
+                    f"{min_timeout}-{max_timeout}s for tier '{tier}'"
+                )
     
-    def _validate_tools(self, tools: List[str]) -> Tuple[bool, List[str]]:
-        """Validate agent tools configuration."""
-        errors = []
-        
-        if not isinstance(tools, list):
-            errors.append("Tools must be a list")
-            return False, errors
+    def _validate_model_tool_compatibility(self, agent_data: Dict[str, Any], result: ValidationResult) -> None:
+        """Validate that model and tools are compatible."""
+        model = agent_data.get("capabilities", {}).get("model", "")
+        tools = agent_data.get("capabilities", {}).get("tools", [])
         
-        # Known valid tools
-        valid_tools = {
-            'file_operations', 'code_analysis', 'git_operations',
-            'testing', 'documentation', 'security_scan'
-        }
+        # Haiku models shouldn't use resource-intensive tools
+        if "haiku" in model.lower():
+            intensive_tools = {"docker", "kubectl", "terraform", "aws", "gcloud", "azure"}
+            used_intensive = set(tools) & intensive_tools
+            if used_intensive:
+                result.warnings.append(
+                    f"Haiku model '{model}' using resource-intensive tools: {used_intensive}"
+                )
         
-        for tool in tools:
-            if tool not in valid_tools:
-                errors.append(f"Unknown tool: {tool}")
+        # Network access requirement
+        network_tools = {"WebSearch", "WebFetch", "aws", "gcloud", "azure"}
+        needs_network = bool(set(tools) & network_tools)
+        has_network = agent_data.get("capabilities", {}).get("network_access", False)
         
-        return len(errors) == 0, errors
+        if needs_network and not has_network:
+            result.warnings.append(
+                f"Agent uses network tools {set(tools) & network_tools} but network_access is False"
+            )
     
-    def validate_profile(self, profile_path: Path) -> ValidationResult:
-        """Validate an entire agent profile."""
-        result = ValidationResult(is_valid=True)
-        
+    def validate_file(self, file_path: Path) -> ValidationResult:
+        """Validate an agent configuration file."""
         try:
-            with open(profile_path, 'r') as f:
-                profile_data = yaml.safe_load(f)
+            with open(file_path, 'r') as f:
+                agent_data = json.load(f)
+            
+            result = self.validate_agent(agent_data)
+            result.metadata["file_path"] = str(file_path)
+            return result
+            
+        except json.JSONDecodeError as e:
+            result = ValidationResult(is_valid=False)
+            result.errors.append(f"Invalid JSON in {file_path}: {e}")
+            return result
         except Exception as e:
-            result.errors.append(f"Failed to load profile: {e}")
-            result.is_valid = False
+            result = ValidationResult(is_valid=False)
+            result.errors.append(f"Error reading {file_path}: {e}")
             return result
+    
+    def validate_directory(self, directory: Path) -> Dict[str, ValidationResult]:
+        """Validate all agent files in a directory."""
+        results = {}
+        
+        for json_file in directory.glob("*.json"):
+            if json_file.name == "agent_schema.json":
+                continue
+            
+            logger.info(f"Validating {json_file}")
+            results[json_file.name] = self.validate_file(json_file)
         
-        # Validate top-level fields
-        for field in self.REQUIRED_FIELDS:
-            if field not in profile_data:
-                result.errors.append(f"Missing required top-level field: {field}")
-                result.is_valid = False
-        
-        # Validate each agent
-        if 'agents' in profile_data:
-            for agent_config in profile_data['agents']:
-                agent_id = agent_config.get('name', 'unknown')
-                agent_result = self.validate_agent_config(agent_config, agent_id)
-                
-                if not agent_result.is_valid:
-                    result.is_valid = False
-                    result.errors.extend([f"Agent '{agent_id}': {e}" for e in agent_result.errors])
-                
-                result.warnings.extend([f"Agent '{agent_id}': {w}" for w in agent_result.warnings])
-                result.locked_fields.update(agent_result.locked_fields)
-        
-        return result
+        return results
+    
+    def get_schema_info(self) -> Dict[str, Any]:
+        """Get information about the loaded schema."""
+        return {
+            "schema_path": str(self.schema_path),
+            "schema_title": self.schema.get("title", "Unknown"),
+            "schema_description": self.schema.get("description", ""),
+            "required_fields": self.schema.get("required", []),
+            "properties": list(self.schema.get("properties", {}).keys())
+        }
+
+
+def validate_agent_migration(old_agent: Dict[str, Any], new_agent: Dict[str, Any]) -> ValidationResult:
+    """
+    Validate that a migrated agent maintains compatibility.
+    
+    Args:
+        old_agent: Original agent configuration
+        new_agent: Migrated agent configuration
+        
+    Returns:
+        ValidationResult with migration validation results
+    """
+    result = ValidationResult(is_valid=True)
+    
+    # Check that core functionality is preserved
+    old_tools = set(old_agent.get("configuration_fields", {}).get("tools", []))
+    new_tools = set(new_agent.get("capabilities", {}).get("tools", []))
+    
+    if old_tools != new_tools:
+        missing = old_tools - new_tools
+        added = new_tools - old_tools
+        if missing:
+            result.warnings.append(f"Tools removed in migration: {missing}")
+        if added:
+            result.warnings.append(f"Tools added in migration: {added}")
+    
+    # Check instruction preservation
+    old_instructions = old_agent.get("narrative_fields", {}).get("instructions", "")
+    new_instructions = new_agent.get("instructions", "")
+    
+    if old_instructions and not new_instructions:
+        result.errors.append("Instructions lost in migration")
+        result.is_valid = False
+    elif len(old_instructions) > len(new_instructions) * 1.1:  # Allow 10% reduction
+        result.warnings.append("Significant instruction content reduction in migration")
+    
+    return result
+
+
+# Convenience functions
+def validate_agent_file(file_path: Path) -> ValidationResult:
+    """Validate a single agent file."""
+    validator = AgentValidator()
+    return validator.validate_file(file_path)
+
+
+def validate_all_agents(directory: Path) -> Tuple[int, int, List[str]]:
+    """
+    Validate all agents in a directory and return summary.
+    
+    Returns:
+        Tuple of (valid_count, invalid_count, error_messages)
+    """
+    validator = AgentValidator()
+    results = validator.validate_directory(directory)
+    
+    valid_count = sum(1 for r in results.values() if r.is_valid)
+    invalid_count = len(results) - valid_count
+    
+    error_messages = []
+    for filename, result in results.items():
+        if not result.is_valid:
+            for error in result.errors:
+                error_messages.append(f"{filename}: {error}")
+    
+    return valid_count, invalid_count, error_messages