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

claude_mpm/agents/agent_loader.py

@@ -3,19 +3,15 @@
 Unified Agent Loader System
 ==========================
 
-Provides unified loading of agent prompts from JSON template files.
-Integrates with SharedPromptCache for performance optimization.
+Provides unified loading of agent prompts from JSON template files using
+the new standardized schema format.
 
 Key Features:
 - Loads agent prompts from src/claude_mpm/agents/templates/*.json files
 - Handles base_agent.md prepending
 - Provides backward-compatible get_*_agent_prompt() functions
 - Uses SharedPromptCache for performance
-- Special handling for ticketing agent's dynamic CLI help
-
-For advanced agent management features (CRUD, versioning, section updates), use:
-    from claude_pm.agents.agent_loader_integration import get_enhanced_loader
-    from claude_pm.services.agent_management_service import AgentManager
+- Validates agents against schema before loading
 
 Usage:
     from claude_pm.agents.agent_loader import get_documentation_agent_prompt
@@ -24,14 +20,15 @@ Usage:
     prompt = get_documentation_agent_prompt()
 """
 
+import json
 import logging
 import os
 from pathlib import Path
-from typing import Optional, Dict, Any, Tuple, Union
+from typing import Optional, Dict, Any, Tuple, Union, List
 
 from ..services.shared_prompt_cache import SharedPromptCache
 from .base_agent_loader import prepend_base_instructions
-# from ..services.task_complexity_analyzer import TaskComplexityAnalyzer, ComplexityLevel, ModelType
+from ..validation.agent_validator import AgentValidator, ValidationResult
 from ..utils.paths import PathResolver
 
 # Temporary placeholders for missing module
@@ -51,7 +48,6 @@ logger = logging.getLogger(__name__)
 
 def _get_agent_templates_dir() -> Path:
     """Get the agent templates directory."""
-    # Agent templates are now in the agents/templates directory
     return Path(__file__).parent / "templates"
 
 
@@ -59,20 +55,7 @@ def _get_agent_templates_dir() -> Path:
 AGENT_TEMPLATES_DIR = _get_agent_templates_dir()
 
 # Cache prefix for agent prompts
-AGENT_CACHE_PREFIX = "agent_prompt:"
-
-# Agent name mappings (agent name -> JSON file name)
-AGENT_MAPPINGS = {
-    "documentation": "documentation_agent.json",
-    "version_control": "version_control_agent.json",
-    "qa": "qa_agent.json",
-    "research": "research_agent.json",
-    "ops": "ops_agent.json",
-    "security": "security_agent.json",
-    "engineer": "engineer_agent.json",
-    "data_engineer": "data_engineer_agent.json"
-    # Note: pm, orchestrator, and pm_orchestrator agents are handled separately
-}
+AGENT_CACHE_PREFIX = "agent_prompt:v2:"
 
 # Model configuration thresholds
 MODEL_THRESHOLDS = {
@@ -81,99 +64,138 @@ MODEL_THRESHOLDS = {
     ModelType.OPUS: {"min_complexity": 71, "max_complexity": 100}
 }
 
-# Default model for each agent type (fallback when dynamic selection is disabled)
-DEFAULT_AGENT_MODELS = {
-    'orchestrator': 'claude-4-opus',
-    'pm': 'claude-4-opus',
-    'pm_orchestrator': 'claude-4-opus',
-    'engineer': 'claude-4-opus',
-    'architecture': 'claude-4-opus',
-    'documentation': 'claude-sonnet-4-20250514',
-    'version_control': 'claude-sonnet-4-20250514',
-    'qa': 'claude-sonnet-4-20250514',
-    'research': 'claude-sonnet-4-20250514',
-    'ops': 'claude-sonnet-4-20250514',
-    'security': 'claude-sonnet-4-20250514',
-    'data_engineer': 'claude-sonnet-4-20250514'
-}
-
-# Model name mappings for Claude API
+# Model name mappings for Claude API (updated for new schema)
 MODEL_NAME_MAPPINGS = {
     ModelType.HAIKU: "claude-3-haiku-20240307",
     ModelType.SONNET: "claude-sonnet-4-20250514",
-    ModelType.OPUS: "claude-4-opus"
+    ModelType.OPUS: "claude-opus-4-20250514"
 }
 
 
-def load_agent_prompt_from_md(agent_name: str, force_reload: bool = False) -> Optional[str]:
-    """
-    Load agent prompt from JSON template file.
+class AgentLoader:
+    """Loads and manages agent templates with schema validation."""
     
-    Args:
-        agent_name: Agent name (e.g., 'documentation', 'ticketing')
-        force_reload: Force reload from file, bypassing cache
+    def __init__(self):
+        """Initialize the agent loader."""
+        self.validator = AgentValidator()
+        self.cache = SharedPromptCache.get_instance()
+        self._agent_registry: Dict[str, Dict[str, Any]] = {}
+        self._load_agents()
+    
+    def _load_agents(self) -> None:
+        """Load all valid agents from the templates directory."""
+        logger.info(f"Loading agents from {AGENT_TEMPLATES_DIR}")
         
-    Returns:
-        str: Agent prompt content from JSON template, or None if not found
-    """
-    try:
-        # Get cache instance
-        cache = SharedPromptCache.get_instance()
-        cache_key = f"{AGENT_CACHE_PREFIX}{agent_name}:json"
+        for json_file in AGENT_TEMPLATES_DIR.glob("*.json"):
+            if json_file.name == "agent_schema.json":
+                continue
+            
+            try:
+                with open(json_file, 'r') as f:
+                    agent_data = json.load(f)
+                
+                # Validate against schema
+                validation_result = self.validator.validate_agent(agent_data)
+                
+                if validation_result.is_valid:
+                    agent_id = agent_data.get("id")
+                    if agent_id:
+                        self._agent_registry[agent_id] = agent_data
+                        logger.debug(f"Loaded agent: {agent_id}")
+                else:
+                    logger.warning(f"Invalid agent in {json_file.name}: {validation_result.errors}")
+                    
+            except Exception as e:
+                logger.error(f"Failed to load {json_file.name}: {e}")
+    
+    def get_agent(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Get agent data by ID."""
+        return self._agent_registry.get(agent_id)
+    
+    def list_agents(self) -> List[Dict[str, Any]]:
+        """List all available agents."""
+        agents = []
+        for agent_id, agent_data in self._agent_registry.items():
+            agents.append({
+                "id": agent_id,
+                "name": agent_data.get("metadata", {}).get("name", agent_id),
+                "description": agent_data.get("metadata", {}).get("description", ""),
+                "category": agent_data.get("metadata", {}).get("category", ""),
+                "model": agent_data.get("capabilities", {}).get("model", ""),
+                "resource_tier": agent_data.get("capabilities", {}).get("resource_tier", "")
+            })
+        return sorted(agents, key=lambda x: x["id"])
+    
+    def get_agent_prompt(self, agent_id: str, force_reload: bool = False) -> Optional[str]:
+        """Get agent instructions by ID."""
+        cache_key = f"{AGENT_CACHE_PREFIX}{agent_id}"
         
-        # Check cache first (unless force reload)
+        # Check cache first
         if not force_reload:
-            cached_content = cache.get(cache_key)
+            cached_content = self.cache.get(cache_key)
             if cached_content is not None:
-                logger.debug(f"Agent prompt for '{agent_name}' loaded from cache")
+                logger.debug(f"Agent prompt for '{agent_id}' loaded from cache")
                 return str(cached_content)
         
-        # Get JSON file path
-        json_filename = AGENT_MAPPINGS.get(agent_name)
-        if not json_filename:
-            logger.warning(f"No JSON file mapping found for agent: {agent_name}")
-            return None
-        
-        json_path = AGENT_TEMPLATES_DIR / json_filename
-        
-        # Check if file exists
-        if not json_path.exists():
-            logger.warning(f"Agent JSON file not found: {json_path}")
+        # Get agent data
+        agent_data = self.get_agent(agent_id)
+        if not agent_data:
+            logger.warning(f"Agent not found: {agent_id}")
             return None
-            
-        logger.debug(f"Loading agent prompt from: {json_path}")
-        
-        # Load and parse JSON
-        import json
-        with open(json_path, 'r', encoding='utf-8') as f:
-            data = json.load(f)
-        
-        # Extract prompt content from JSON
-        # Check multiple possible locations for instructions/content
-        # Following the same pattern as AgentDeploymentService
-        content = (
-            data.get('instructions') or
-            data.get('narrative_fields', {}).get('instructions') or
-            data.get('content') or
-            ''
-        )
         
-        if not content:
-            logger.warning(f"No content/instructions found in JSON template: {json_path}")
-            logger.debug(f"Checked fields: instructions, narrative_fields.instructions, content")
+        # Extract instructions
+        instructions = agent_data.get("instructions", "")
+        if not instructions:
+            logger.warning(f"No instructions found for agent: {agent_id}")
             return None
         
         # Cache the content with 1 hour TTL
-        cache.set(cache_key, content, ttl=3600)
-        logger.debug(f"Agent prompt for '{agent_name}' cached successfully")
+        self.cache.set(cache_key, instructions, ttl=3600)
+        logger.debug(f"Agent prompt for '{agent_id}' cached successfully")
         
-        return content
+        return instructions
+    
+    def get_agent_metadata(self, agent_id: str) -> Optional[Dict[str, Any]]:
+        """Get agent metadata including capabilities and configuration."""
+        agent_data = self.get_agent(agent_id)
+        if not agent_data:
+            return None
         
-    except Exception as e:
-        logger.error(f"Error loading agent prompt from JSON for '{agent_name}': {e}")
-        return None
+        return {
+            "id": agent_id,
+            "version": agent_data.get("version", "1.0.0"),
+            "metadata": agent_data.get("metadata", {}),
+            "capabilities": agent_data.get("capabilities", {}),
+            "knowledge": agent_data.get("knowledge", {}),
+            "interactions": agent_data.get("interactions", {})
+        }
+
+
+# Global loader instance
+_loader: Optional[AgentLoader] = None
 
 
+def _get_loader() -> AgentLoader:
+    """Get or create the global agent loader instance."""
+    global _loader
+    if _loader is None:
+        _loader = AgentLoader()
+    return _loader
+
+
+def load_agent_prompt_from_md(agent_name: str, force_reload: bool = False) -> Optional[str]:
+    """
+    Load agent prompt from new schema JSON template.
+    
+    Args:
+        agent_name: Agent name (matches agent ID in new schema)
+        force_reload: Force reload from file, bypassing cache
+        
+    Returns:
+        str: Agent instructions from JSON template, or None if not found
+    """
+    loader = _get_loader()
+    return loader.get_agent_prompt(agent_name, force_reload)
 
 
 def _analyze_task_complexity(task_description: str, context_size: int = 0, **kwargs: Any) -> Dict[str, Any]:
@@ -210,13 +232,19 @@ def _get_model_config(agent_name: str, complexity_analysis: Optional[Dict[str, A
     Returns:
         Tuple of (selected_model, model_config)
     """
+    loader = _get_loader()
+    agent_data = loader.get_agent(agent_name)
+    
+    if not agent_data:
+        # Fallback for unknown agents
+        return "claude-sonnet-4-20250514", {"selection_method": "default"}
+    
+    # Get model from agent capabilities
+    default_model = agent_data.get("capabilities", {}).get("model", "claude-sonnet-4-20250514")
+    
     # Check if dynamic model selection is enabled
     enable_dynamic_selection = os.getenv('ENABLE_DYNAMIC_MODEL_SELECTION', 'true').lower() == 'true'
     
-    # Debug logging
-    logger.debug(f"Environment ENABLE_DYNAMIC_MODEL_SELECTION: {os.getenv('ENABLE_DYNAMIC_MODEL_SELECTION')}")
-    logger.debug(f"Enable dynamic selection: {enable_dynamic_selection}")
-    
     # Check for per-agent override in environment
     agent_override_key = f"CLAUDE_PM_{agent_name.upper()}_MODEL_SELECTION"
     agent_override = os.getenv(agent_override_key, '').lower()
@@ -226,44 +254,24 @@ def _get_model_config(agent_name: str, complexity_analysis: Optional[Dict[str, A
     elif agent_override == 'false':
         enable_dynamic_selection = False
     
-    # Log model selection decision
-    logger.info(f"Model selection for {agent_name}: dynamic={enable_dynamic_selection}, "
-                f"complexity_available={complexity_analysis is not None}")
-    
     # Dynamic model selection based on complexity
     if enable_dynamic_selection and complexity_analysis:
         recommended_model = complexity_analysis.get('recommended_model', ModelType.SONNET)
-        selected_model = MODEL_NAME_MAPPINGS.get(recommended_model, DEFAULT_AGENT_MODELS.get(agent_name, 'claude-sonnet-4-20250514'))
+        selected_model = MODEL_NAME_MAPPINGS.get(recommended_model, default_model)
         
         model_config = {
             "selection_method": "dynamic_complexity_based",
             "complexity_score": complexity_analysis.get('complexity_score', 50),
             "complexity_level": complexity_analysis.get('complexity_level', ComplexityLevel.MEDIUM).value,
             "optimal_prompt_size": complexity_analysis.get('optimal_prompt_size', (700, 1000)),
-            "scoring_breakdown": complexity_analysis.get('scoring_breakdown', {}),
-            "analysis_details": complexity_analysis.get('analysis_details', {})
+            "default_model": default_model
         }
-        
-        # Log metrics
-        logger.info(f"Dynamic model selection for {agent_name}: "
-                    f"model={selected_model}, "
-                    f"complexity_score={model_config['complexity_score']}, "
-                    f"complexity_level={model_config['complexity_level']}")
-        
-        # Track model selection metrics
-        log_model_selection(
-            agent_name=agent_name,
-            selected_model=selected_model,
-            complexity_score=model_config['complexity_score'],
-            selection_method=model_config['selection_method']
-        )
-        
     else:
-        # Use default model mapping
-        selected_model = DEFAULT_AGENT_MODELS.get(agent_name, 'claude-sonnet-4-20250514')
+        selected_model = default_model
         model_config = {
-            "selection_method": "default_mapping",
-            "reason": "dynamic_selection_disabled" if not enable_dynamic_selection else "no_complexity_analysis"
+            "selection_method": "agent_default",
+            "reason": "dynamic_selection_disabled" if not enable_dynamic_selection else "no_complexity_analysis",
+            "default_model": default_model
         }
     
     return selected_model, model_config
@@ -274,24 +282,23 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
     Get agent prompt from JSON template with optional dynamic model selection.
     
     Args:
-        agent_name: Agent name (e.g., 'documentation', 'ticketing')
+        agent_name: Agent name (agent ID in new schema)
         force_reload: Force reload from source, bypassing cache
         return_model_info: If True, returns tuple (prompt, model, config)
         **kwargs: Additional arguments including:
             - task_description: Description of the task for complexity analysis
             - context_size: Size of context for complexity analysis
             - enable_complexity_analysis: Override for complexity analysis
-            - Additional complexity factors (file_count, integration_points, etc.)
         
     Returns:
         str or tuple: Complete agent prompt with base instructions prepended,
                       or tuple of (prompt, selected_model, model_config) if return_model_info=True
     """
-    # Load from JSON template
+    # Load from new schema JSON template
     prompt = load_agent_prompt_from_md(agent_name, force_reload)
     
     if prompt is None:
-        raise ValueError(f"No agent prompt JSON template found for: {agent_name}")
+        raise ValueError(f"No agent found with ID: {agent_name}")
     
     # Analyze task complexity if task description is provided
     complexity_analysis = None
@@ -299,38 +306,15 @@ def get_agent_prompt(agent_name: str, force_reload: bool = False, return_model_i
     enable_analysis = kwargs.get('enable_complexity_analysis', True)
     
     if task_description and enable_analysis:
-        # Remove already specified parameters from kwargs to avoid duplicates
-        analysis_kwargs = {k: v for k, v in kwargs.items() 
-                          if k not in ['task_description', 'context_size']}
         complexity_analysis = _analyze_task_complexity(
             task_description=task_description,
             context_size=kwargs.get('context_size', 0),
-            **analysis_kwargs
+            **{k: v for k, v in kwargs.items() if k not in ['task_description', 'context_size']}
         )
     
-    # Get model configuration (always happens, even without complexity analysis)
+    # Get model configuration
     selected_model, model_config = _get_model_config(agent_name, complexity_analysis)
     
-    # Always store model selection info in kwargs for potential use by callers
-    kwargs['_selected_model'] = selected_model
-    kwargs['_model_config'] = model_config
-    
-    # Handle dynamic template formatting if needed
-    if "{dynamic_help}" in prompt:
-        try:
-            # Import CLI helper module to get dynamic help
-            from ..orchestration.ai_trackdown_tools import CLIHelpFormatter
-            
-            # Create a CLI helper instance
-            cli_helper = CLIHelpFormatter()
-            help_content, _ = cli_helper.get_cli_help()
-            dynamic_help = cli_helper.format_help_for_prompt(help_content)
-            prompt = prompt.format(dynamic_help=dynamic_help)
-        except Exception as e:
-            logger.warning(f"Could not format dynamic help for ticketing agent: {e}")
-            # Remove the placeholder if we can't fill it
-            prompt = prompt.replace("{dynamic_help}", "")
-    
     # Add model selection metadata to prompt if dynamic selection is enabled
     if selected_model and model_config.get('selection_method') == 'dynamic_complexity_based':
         model_metadata = f"\n<!-- Model Selection: {selected_model} (Complexity: {model_config.get('complexity_level', 'UNKNOWN')}) -->\n"
@@ -355,7 +339,6 @@ def get_documentation_agent_prompt() -> str:
     return prompt
 
 
-
 def get_version_control_agent_prompt() -> str:
     """Get the complete Version Control Agent prompt with base instructions."""
     prompt = get_agent_prompt("version_control", return_model_info=False)
@@ -410,43 +393,54 @@ def get_agent_prompt_with_model_info(agent_name: str, force_reload: bool = False
     Get agent prompt with model selection information.
     
     Args:
-        agent_name: Agent name (e.g., 'documentation', 'ticketing')
+        agent_name: Agent name (agent ID)
         force_reload: Force reload from source, bypassing cache
         **kwargs: Additional arguments for prompt generation and model selection
         
     Returns:
         Tuple of (prompt, selected_model, model_config)
     """
-    # Use get_agent_prompt with return_model_info=True
     result = get_agent_prompt(agent_name, force_reload, return_model_info=True, **kwargs)
     
-    # If result is a tuple, return it directly
+    # Ensure we have a tuple
     if isinstance(result, tuple):
         return result
     
     # Fallback (shouldn't happen)
-    return result, DEFAULT_AGENT_MODELS.get(agent_name, 'claude-sonnet-4-20250514'), {"selection_method": "default"}
+    loader = _get_loader()
+    agent_data = loader.get_agent(agent_name)
+    default_model = "claude-sonnet-4-20250514"
+    if agent_data:
+        default_model = agent_data.get("capabilities", {}).get("model", default_model)
+    
+    return result, default_model, {"selection_method": "default"}
 
 
 # Utility functions
 def list_available_agents() -> Dict[str, Dict[str, Any]]:
     """
-    List all available agents with their sources.
+    List all available agents with their metadata.
     
     Returns:
-        dict: Agent information including JSON template path
+        dict: Agent information including capabilities and metadata
     """
+    loader = _get_loader()
     agents = {}
     
-    for agent_name, json_filename in AGENT_MAPPINGS.items():
-        json_path = AGENT_TEMPLATES_DIR / json_filename
+    for agent_info in loader.list_agents():
+        agent_id = agent_info["id"]
+        metadata = loader.get_agent_metadata(agent_id)
         
-        agents[agent_name] = {
-            "json_file": json_filename if json_path.exists() else None,
-            "json_path": str(json_path) if json_path.exists() else None,
-            "has_template": json_path.exists(),
-            "default_model": DEFAULT_AGENT_MODELS.get(agent_name, 'claude-sonnet-4-20250514')
-        }
+        if metadata:
+            agents[agent_id] = {
+                "name": metadata["metadata"].get("name", agent_id),
+                "description": metadata["metadata"].get("description", ""),
+                "category": metadata["metadata"].get("category", ""),
+                "version": metadata["version"],
+                "model": metadata["capabilities"].get("model", ""),
+                "resource_tier": metadata["capabilities"].get("resource_tier", ""),
+                "tools": metadata["capabilities"].get("tools", [])
+            }
     
     return agents
 
@@ -462,13 +456,14 @@ def clear_agent_cache(agent_name: Optional[str] = None) -> None:
         cache = SharedPromptCache.get_instance()
         
         if agent_name:
-            cache_key = f"{AGENT_CACHE_PREFIX}{agent_name}:json"
+            cache_key = f"{AGENT_CACHE_PREFIX}{agent_name}"
             cache.invalidate(cache_key)
             logger.debug(f"Cache cleared for agent: {agent_name}")
         else:
             # Clear all agent caches
-            for name in AGENT_MAPPINGS:
-                cache_key = f"{AGENT_CACHE_PREFIX}{name}:json"
+            loader = _get_loader()
+            for agent_id in loader._agent_registry.keys():
+                cache_key = f"{AGENT_CACHE_PREFIX}{agent_id}"
                 cache.invalidate(cache_key)
             logger.debug("All agent caches cleared")
             
@@ -478,120 +473,31 @@ def clear_agent_cache(agent_name: Optional[str] = None) -> None:
 
 def validate_agent_files() -> Dict[str, Dict[str, Any]]:
     """
-    Validate that all expected agent files exist.
+    Validate all agent files in the templates directory.
     
     Returns:
         dict: Validation results for each agent
     """
+    validator = AgentValidator()
     results = {}
     
-    for agent_name, json_filename in AGENT_MAPPINGS.items():
-        json_path = AGENT_TEMPLATES_DIR / json_filename
-        results[agent_name] = {
-            "template_exists": json_path.exists(),
-            "template_path": str(json_path)
+    for json_file in AGENT_TEMPLATES_DIR.glob("*.json"):
+        if json_file.name == "agent_schema.json":
+            continue
+        
+        validation_result = validator.validate_file(json_file)
+        results[json_file.stem] = {
+            "valid": validation_result.is_valid,
+            "errors": validation_result.errors,
+            "warnings": validation_result.warnings,
+            "file_path": str(json_file)
         }
     
     return results
 
 
-def get_model_selection_metrics() -> Dict[str, Any]:
-    """
-    Get metrics about model selection usage.
-    
-    Returns:
-        dict: Metrics including feature flag status and selection counts
-    """
-    # Check feature flag status
-    global_enabled = os.getenv('ENABLE_DYNAMIC_MODEL_SELECTION', 'true').lower() == 'true'
-    
-    # Check per-agent overrides
-    agent_overrides = {}
-    for agent_name in AGENT_MAPPINGS.keys():
-        override_key = f"CLAUDE_PM_{agent_name.upper()}_MODEL_SELECTION"
-        override_value = os.getenv(override_key, '')
-        if override_value:
-            agent_overrides[agent_name] = override_value.lower() == 'true'
-    
-    # Get cache instance to check for cached metrics
-    try:
-        cache = SharedPromptCache.get_instance()
-        selection_stats = cache.get("agent_loader:model_selection_stats") or {}
-    except Exception:
-        selection_stats = {}
-    
-    return {
-        "feature_flag": {
-            "global_enabled": global_enabled,
-            "agent_overrides": agent_overrides
-        },
-        "model_thresholds": {
-            model_type.value: thresholds 
-            for model_type, thresholds in MODEL_THRESHOLDS.items()
-        },
-        "default_models": DEFAULT_AGENT_MODELS,
-        "selection_stats": selection_stats
-    }
-
-
-def log_model_selection(agent_name: str, selected_model: str, complexity_score: int, selection_method: str) -> None:
-    """
-    Log model selection for metrics tracking.
-    
-    Args:
-        agent_name: Name of the agent
-        selected_model: Model that was selected
-        complexity_score: Complexity score from analysis
-        selection_method: Method used for selection
-    """
-    try:
-        # Get cache instance
-        cache = SharedPromptCache.get_instance()
-        
-        # Get existing stats
-        stats_key = "agent_loader:model_selection_stats"
-        stats = cache.get(stats_key) or {
-            "total_selections": 0,
-            "by_model": {},
-            "by_agent": {},
-            "by_method": {},
-            "complexity_distribution": {
-                "0-30": 0,
-                "31-70": 0,
-                "71-100": 0
-            }
-        }
-        
-        # Update stats
-        stats["total_selections"] += 1
-        
-        # By model
-        if selected_model not in stats["by_model"]:
-            stats["by_model"][selected_model] = 0
-        stats["by_model"][selected_model] += 1
-        
-        # By agent
-        if agent_name not in stats["by_agent"]:
-            stats["by_agent"][agent_name] = {}
-        if selected_model not in stats["by_agent"][agent_name]:
-            stats["by_agent"][agent_name][selected_model] = 0
-        stats["by_agent"][agent_name][selected_model] += 1
-        
-        # By method
-        if selection_method not in stats["by_method"]:
-            stats["by_method"][selection_method] = 0
-        stats["by_method"][selection_method] += 1
-        
-        # Complexity distribution
-        if complexity_score <= 30:
-            stats["complexity_distribution"]["0-30"] += 1
-        elif complexity_score <= 70:
-            stats["complexity_distribution"]["31-70"] += 1
-        else:
-            stats["complexity_distribution"]["71-100"] += 1
-        
-        # Store updated stats with 24 hour TTL
-        cache.set(stats_key, stats, ttl=86400)
-        
-    except Exception as e:
-        logger.warning(f"Failed to log model selection metrics: {e}")
+def reload_agents() -> None:
+    """Force reload all agents from disk."""
+    global _loader
+    _loader = None
+    logger.info("Agent registry cleared, will reload on next access")

claude_mpm/agents/base_agent.json

@@ -2,7 +2,7 @@
   "version": 2,
   "agent_type": "base",
   "narrative_fields": {
-    "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"
+    "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```"
   },
   "configuration_fields": {
     "model": "claude-4-sonnet-20250514",