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

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

{claude_mpm-1.1.0.dist-info → claude_mpm-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 1.1.0
+Version: 2.0.0
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -46,8 +46,104 @@ Dynamic: requires-python
 
 > **Note**: This project is a fork of [claude-multiagent-pm](https://github.com/kfsone/claude-multiagent-pm), enhanced to integrate with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v1.0.60+'s native agent system. This integration enables seamless orchestration of Claude Code's built-in agents (research, engineer, qa, documentation, security, ops, version_control, data_engineer) through a unified project management interface.
 
+> **⚠️ Version 2.0.0 Breaking Changes**: Agent schema has been standardized. Agent IDs no longer use the `_agent` suffix (e.g., `research_agent` → `research`). See the [migration guide](docs/user/05-migration/schema-standardization-migration.md) for details.
+
 A framework for Claude that enables multi-agent workflows and extensible capabilities through a modular architecture.
 
+## Quick Start
+
+### Why Interactive Mode?
+**Interactive mode is significantly more performant** than non-interactive commands. It maintains context between requests and avoids the overhead of repeatedly launching Claude, making your development workflow much faster and more efficient.
+
+### Installation
+
+```bash
+# Install globally via npm (recommended)
+npm install -g @bobmatnyc/claude-mpm
+
+# Or use npx for one-time usage
+npx @bobmatnyc/claude-mpm
+```
+
+### Three Essential Use Cases
+
+#### 1. 🔍 **Understand Your Codebase**
+Start with codebase exploration - perfect for onboarding or getting oriented:
+
+```bash
+# Launch interactive mode
+claude-mpm
+
+# Then ask:
+> Explain the codebase structure. What are the main components, how do they interact, and what architectural patterns are used?
+```
+
+#### 2. 🚀 **Build a New Project** 
+For greenfield development, use detailed, AI-generated prompts for best results:
+
+```bash
+claude-mpm
+
+# Example detailed prompt (AI-generated prompts work best):
+> Create a modern web application with the following requirements:
+> - Next.js 14 with TypeScript and Tailwind CSS
+> - Authentication using NextAuth.js with GitHub provider
+> - PostgreSQL database with Prisma ORM
+> - User dashboard with CRUD operations for "projects"
+> - API routes following REST conventions
+> - Responsive design with dark/light mode toggle
+> - Form validation using react-hook-form and zod
+> - Include proper error handling and loading states
+> - Set up ESLint, Prettier, and basic testing with Jest
+> - Generate a complete project structure with all necessary files
+```
+
+#### 3. 🔧 **Enhance Existing Code**
+For working on your current codebase, provide rich context:
+
+```bash
+claude-mpm
+
+# Example detailed enhancement prompt:
+> I need to add real-time notifications to my existing Next.js application. Current tech stack:
+> - Next.js 13 with app router
+> - TypeScript
+> - Tailwind CSS
+> - PostgreSQL with Prisma
+> - User authentication already implemented
+> 
+> Requirements:
+> - WebSocket-based real-time notifications
+> - Toast notifications in the UI
+> - Database table to store notification history
+> - Mark as read/unread functionality
+> - Different notification types (info, warning, success, error)
+> - Admin panel to send system-wide notifications
+> - Email fallback for offline users
+> 
+> Please analyze my current codebase structure and implement this feature following my existing patterns and conventions.
+```
+
+### 💡 Pro Tips for Better Results
+
+1. **Use AI to generate your prompts**: Ask ChatGPT or Claude to help you create detailed, specific prompts for your use case
+2. **Provide context**: Include your tech stack, requirements, and any constraints
+3. **Stay interactive**: Keep the conversation going to refine and iterate on solutions
+4. **Ask for explanations**: Request explanations of architectural decisions and trade-offs
+
+### Alternative: Non-Interactive Mode
+For automation or simple one-off tasks:
+
+```bash
+# Quick analysis
+claude-mpm run -i "What testing frameworks are used in this project?" --non-interactive
+
+# With subprocess orchestration for complex tasks
+claude-mpm run --subprocess -i "Audit this codebase for security vulnerabilities" --non-interactive
+```
+
+**Note**: Non-interactive mode has higher overhead and is less efficient for multi-step development workflows.
+
 
 ## 📚 Documentation
 
@@ -119,9 +215,9 @@ Claude MPM provides a modular framework for extending Claude's capabilities:
 
 ## Installation
 
-### Quick Install Options
+### Other Installation Methods
 
-#### Option 1: Using UV (Recommended - Fast)
+#### Using UV (Recommended - Fast)
 UV is a lightning-fast Python package manager written in Rust, offering 10-100x speed improvements over pip.
 
 ```bash
@@ -135,7 +231,7 @@ uv pip install claude-mpm
 uv pip install git+https://github.com/bobmatnyc/claude-mpm.git
 ```
 
-#### Option 2: Using pip (Traditional)
+#### Using pip (Traditional)
 ```bash
 # Install from PyPI
 pip install claude-mpm
@@ -144,13 +240,6 @@ pip install claude-mpm
 pip install git+https://github.com/bobmatnyc/claude-mpm.git
 ```
 
-#### Option 3: Using npm (Wrapper)
-**Note**: This installs a wrapper that still requires Python. It's provided for convenience but the Python package is the primary distribution method.
-
-```bash
-npm install -g @bobmatnyc/claude-mpm
-```
-
 ### From Source (Development)
 
 ```bash
@@ -218,21 +307,6 @@ Commands:
   info                 Show framework and configuration info
 ```
 
-## Quick Start
-
-```bash
-# 1. Clone and install
-git clone https://github.com/yourusername/claude-mpm.git
-cd claude-mpm
-./install_dev.sh
-source venv/bin/activate
-
-# 2. Run interactive session
-claude-mpm
-
-# 3. Or run a single command
-claude-mpm run -i "Explain the codebase structure" --non-interactive
-```
 
 
 ## Architecture