claude-mpm 4.1.1__py3-none-any.whl → 4.1.3__py3-none-any.whl

claude_mpm/core/framework_loader.py

@@ -1,12 +1,10 @@
 """Framework loader for Claude MPM."""
 
 import logging
-import os
-import sys
 import time
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Optional, Set, Tuple
+from typing import Any, Dict, Optional
 
 # Import resource handling for packaged installations
 try:
@@ -28,6 +26,32 @@ AgentRegistryAdapter = safe_import(
     "claude_mpm.core.agent_registry", "core.agent_registry", ["AgentRegistryAdapter"]
 )
 
+# Import the service container and interfaces
+try:
+    from claude_mpm.services.core.cache_manager import CacheManager
+    from claude_mpm.services.core.memory_manager import MemoryManager
+    from claude_mpm.services.core.path_resolver import PathResolver
+    from claude_mpm.services.core.service_container import (
+        ServiceContainer,
+        get_global_container,
+    )
+    from claude_mpm.services.core.service_interfaces import (
+        ICacheManager,
+        IMemoryManager,
+        IPathResolver,
+    )
+except ImportError:
+    # Fallback for development environments
+    from ..services.core.cache_manager import CacheManager
+    from ..services.core.memory_manager import MemoryManager
+    from ..services.core.path_resolver import PathResolver
+    from ..services.core.service_container import ServiceContainer, get_global_container
+    from ..services.core.service_interfaces import (
+        ICacheManager,
+        IMemoryManager,
+        IPathResolver,
+    )
+
 
 class FrameworkLoader:
     """
@@ -38,33 +62,33 @@ class FrameworkLoader:
     2. Loading custom instructions from .claude-mpm/ directories
     3. Preparing agent definitions
     4. Formatting for injection
-    
+
     Custom Instructions Loading:
     The framework loader supports custom instructions through .claude-mpm/ directories.
     It NEVER reads from .claude/ directories to avoid conflicts with Claude Code.
-    
+
     File Loading Precedence (highest to lowest):
-    
+
     INSTRUCTIONS.md:
       1. Project: ./.claude-mpm/INSTRUCTIONS.md
       2. User: ~/.claude-mpm/INSTRUCTIONS.md
       3. System: (built-in framework instructions)
-    
+
     WORKFLOW.md:
       1. Project: ./.claude-mpm/WORKFLOW.md
       2. User: ~/.claude-mpm/WORKFLOW.md
       3. System: src/claude_mpm/agents/WORKFLOW.md
-    
+
     MEMORY.md:
       1. Project: ./.claude-mpm/MEMORY.md
       2. User: ~/.claude-mpm/MEMORY.md
       3. System: src/claude_mpm/agents/MEMORY.md
-    
+
     Actual Memories:
       - User: ~/.claude-mpm/memories/PM_memories.md
       - Project: ./.claude-mpm/memories/PM_memories.md (overrides user)
       - Agent memories: *_memories.md files (only loaded if agent is deployed)
-    
+
     Important Notes:
     - Project-level files always override user-level files
     - User-level files always override system defaults
@@ -73,7 +97,10 @@ class FrameworkLoader:
     """
 
     def __init__(
-        self, framework_path: Optional[Path] = None, agents_dir: Optional[Path] = None
+        self,
+        framework_path: Optional[Path] = None,
+        agents_dir: Optional[Path] = None,
+        service_container: Optional[ServiceContainer] = None,
     ):
         """
         Initialize framework loader.
@@ -81,241 +108,151 @@ class FrameworkLoader:
         Args:
             framework_path: Explicit path to framework (auto-detected if None)
             agents_dir: Custom agents directory (overrides framework agents)
+            service_container: Optional service container for dependency injection
         """
         self.logger = get_logger("framework_loader")
-        self.framework_path = framework_path or self._detect_framework_path()
         self.agents_dir = agents_dir
         self.framework_version = None
         self.framework_last_modified = None
-        
-        # Performance optimization: Initialize caches
-        self._agent_capabilities_cache: Optional[str] = None
-        self._agent_capabilities_cache_time: float = 0
-        self._deployed_agents_cache: Optional[Set[str]] = None
-        self._deployed_agents_cache_time: float = 0
-        self._agent_metadata_cache: Dict[str, Tuple[Optional[Dict[str, Any]], float]] = {}
-        self._memories_cache: Optional[Dict[str, Any]] = None
-        self._memories_cache_time: float = 0
-        
-        # Cache TTL settings (in seconds)
-        self.CAPABILITIES_CACHE_TTL = 60  # 60 seconds for capabilities
-        self.DEPLOYED_AGENTS_CACHE_TTL = 30  # 30 seconds for deployed agents
-        self.METADATA_CACHE_TTL = 60  # 60 seconds for agent metadata
-        self.MEMORIES_CACHE_TTL = 60  # 60 seconds for memories
-        
+
+        # Use provided container or get global container
+        self.container = service_container or get_global_container()
+
+        # Register services if not already registered
+        if not self.container.is_registered(ICacheManager):
+            self.container.register(ICacheManager, CacheManager, True)  # singleton=True
+
+        if not self.container.is_registered(IPathResolver):
+            # PathResolver depends on CacheManager, so resolve it first
+            cache_manager = self.container.resolve(ICacheManager)
+            path_resolver = PathResolver(cache_manager=cache_manager)
+            self.container.register_instance(IPathResolver, path_resolver)
+
+        if not self.container.is_registered(IMemoryManager):
+            # MemoryManager depends on both CacheManager and PathResolver
+            cache_manager = self.container.resolve(ICacheManager)
+            path_resolver = self.container.resolve(IPathResolver)
+            memory_manager = MemoryManager(
+                cache_manager=cache_manager, path_resolver=path_resolver
+            )
+            self.container.register_instance(IMemoryManager, memory_manager)
+
+        # Resolve services from container
+        self._cache_manager = self.container.resolve(ICacheManager)
+        self._path_resolver = self.container.resolve(IPathResolver)
+        self._memory_manager = self.container.resolve(IMemoryManager)
+
+        # Initialize framework path using PathResolver
+        self.framework_path = (
+            framework_path or self._path_resolver.detect_framework_path()
+        )
+
+        # Keep TTL constants for backward compatibility
+        # These are implementation-specific, so we use defaults if not available
+        if hasattr(self._cache_manager, "capabilities_ttl"):
+            self.CAPABILITIES_CACHE_TTL = self._cache_manager.capabilities_ttl
+            self.DEPLOYED_AGENTS_CACHE_TTL = self._cache_manager.deployed_agents_ttl
+            self.METADATA_CACHE_TTL = self._cache_manager.metadata_ttl
+            self.MEMORIES_CACHE_TTL = self._cache_manager.memories_ttl
+        else:
+            # Default TTL values
+            self.CAPABILITIES_CACHE_TTL = 60
+            self.DEPLOYED_AGENTS_CACHE_TTL = 30
+            self.METADATA_CACHE_TTL = 60
+            self.MEMORIES_CACHE_TTL = 60
+
         self.framework_content = self._load_framework_content()
 
         # Initialize agent registry
         self.agent_registry = AgentRegistryAdapter(self.framework_path)
-        
+
         # Initialize output style manager (must be after content is loaded)
         self.output_style_manager = None
         # Defer initialization until first use to ensure content is loaded
-    
+
     def clear_all_caches(self) -> None:
         """Clear all caches to force reload on next access."""
-        self.logger.info("Clearing all framework loader caches")
-        self._agent_capabilities_cache = None
-        self._agent_capabilities_cache_time = 0
-        self._deployed_agents_cache = None
-        self._deployed_agents_cache_time = 0
-        self._agent_metadata_cache.clear()
-        self._memories_cache = None
-        self._memories_cache_time = 0
-    
+        self._cache_manager.clear_all()
+
     def clear_agent_caches(self) -> None:
         """Clear agent-related caches (capabilities, deployed agents, metadata)."""
-        self.logger.info("Clearing agent-related caches")
-        self._agent_capabilities_cache = None
-        self._agent_capabilities_cache_time = 0
-        self._deployed_agents_cache = None
-        self._deployed_agents_cache_time = 0
-        self._agent_metadata_cache.clear()
-    
+        self._cache_manager.clear_agent_caches()
+
     def clear_memory_caches(self) -> None:
         """Clear memory-related caches."""
-        self.logger.info("Clearing memory caches")
-        self._memories_cache = None
-        self._memories_cache_time = 0
+        self._cache_manager.clear_memory_caches()
 
     def _initialize_output_style(self) -> None:
         """Initialize output style management and deploy if applicable."""
         try:
             from claude_mpm.core.output_style_manager import OutputStyleManager
-            
+
             self.output_style_manager = OutputStyleManager()
-            
+
             # Log detailed output style status
             self._log_output_style_status()
-            
+
             # Extract and save output style content (pass self to reuse loaded content)
-            output_style_content = self.output_style_manager.extract_output_style_content(framework_loader=self)
-            output_style_path = self.output_style_manager.save_output_style(output_style_content)
-            
+            output_style_content = (
+                self.output_style_manager.extract_output_style_content(
+                    framework_loader=self
+                )
+            )
+            self.output_style_manager.save_output_style(output_style_content)
+
             # Deploy to Claude Code if supported
-            deployed = self.output_style_manager.deploy_output_style(output_style_content)
-            
+            deployed = self.output_style_manager.deploy_output_style(
+                output_style_content
+            )
+
             if deployed:
                 self.logger.info("✅ Output style deployed to Claude Code >= 1.0.83")
             else:
-                self.logger.info("📝 Output style will be injected into instructions for older Claude versions")
-                
+                self.logger.info(
+                    "📝 Output style will be injected into instructions for older Claude versions"
+                )
+
         except Exception as e:
             self.logger.warning(f"❌ Failed to initialize output style manager: {e}")
             # Continue without output style management
-    
+
     def _log_output_style_status(self) -> None:
         """Log comprehensive output style status information."""
         if not self.output_style_manager:
             return
-            
+
         # Claude version detection
         claude_version = self.output_style_manager.claude_version
         if claude_version:
             self.logger.info(f"Claude Code version detected: {claude_version}")
-            
+
             # Check if version supports output styles
             if self.output_style_manager.supports_output_styles():
                 self.logger.info("✅ Claude Code supports output styles (>= 1.0.83)")
-                
+
                 # Check deployment status
                 output_style_path = self.output_style_manager.output_style_path
                 if output_style_path.exists():
-                    self.logger.info(f"📁 Output style file exists: {output_style_path}")
+                    self.logger.info(
+                        f"📁 Output style file exists: {output_style_path}"
+                    )
                 else:
-                    self.logger.info(f"📝 Output style will be created at: {output_style_path}")
-                    
+                    self.logger.info(
+                        f"📝 Output style will be created at: {output_style_path}"
+                    )
+
             else:
-                self.logger.info(f"⚠️ Claude Code {claude_version} does not support output styles (< 1.0.83)")
-                self.logger.info("📝 Output style content will be injected into framework instructions")
+                self.logger.info(
+                    f"⚠️ Claude Code {claude_version} does not support output styles (< 1.0.83)"
+                )
+                self.logger.info(
+                    "📝 Output style content will be injected into framework instructions"
+                )
         else:
             self.logger.info("⚠️ Claude Code not detected or version unknown")
-            self.logger.info("📝 Output style content will be injected into framework instructions as fallback")
-
-    def _detect_framework_path(self) -> Optional[Path]:
-        """Auto-detect claude-mpm framework using unified path management."""
-        try:
-            # Use the unified path manager for consistent detection
-            from ..core.unified_paths import get_path_manager, DeploymentContext
-
-            path_manager = get_path_manager()
-            deployment_context = path_manager._deployment_context
-
-            # Check if we're in a packaged installation
-            if deployment_context in [DeploymentContext.PIP_INSTALL, DeploymentContext.PIPX_INSTALL, DeploymentContext.SYSTEM_PACKAGE]:
-                self.logger.info(f"Running from packaged installation (context: {deployment_context})")
-                # Return a marker path to indicate packaged installation
-                return Path("__PACKAGED__")
-            elif deployment_context == DeploymentContext.DEVELOPMENT:
-                # Development mode - use framework root
-                framework_root = path_manager.framework_root
-                if (framework_root / "src" / "claude_mpm" / "agents").exists():
-                    self.logger.info(f"Using claude-mpm development installation at: {framework_root}")
-                    return framework_root
-            elif deployment_context == DeploymentContext.EDITABLE_INSTALL:
-                # Editable install - similar to development
-                framework_root = path_manager.framework_root
-                if (framework_root / "src" / "claude_mpm" / "agents").exists():
-                    self.logger.info(f"Using claude-mpm editable installation at: {framework_root}")
-                    return framework_root
-
-        except Exception as e:
-            self.logger.warning(f"Failed to use unified path manager for framework detection: {e}")
-            # Fall back to original detection logic
-            pass
-
-        # Fallback: Original detection logic for compatibility
-        try:
-            # Check if the package is installed
-            import claude_mpm
-            package_file = Path(claude_mpm.__file__)
-
-            # For packaged installations, we don't need a framework path
-            # since we'll use importlib.resources to load files
-            if 'site-packages' in str(package_file) or 'dist-packages' in str(package_file):
-                self.logger.info(f"Running from packaged installation at: {package_file.parent}")
-                # Return a marker path to indicate packaged installation
-                return Path("__PACKAGED__")
-        except ImportError:
-            pass
-
-        # Then check if we're in claude-mpm project (development mode)
-        current_file = Path(__file__)
-        if "claude-mpm" in str(current_file):
-            # We're running from claude-mpm, use its agents
-            for parent in current_file.parents:
-                if parent.name == "claude-mpm":
-                    if (parent / "src" / "claude_mpm" / "agents").exists():
-                        self.logger.info(f"Using claude-mpm at: {parent}")
-                        return parent
-                    break
-
-        # Otherwise check common locations for claude-mpm
-        candidates = [
-            # Current directory (if we're already in claude-mpm)
-            Path.cwd(),
-            # Development location
-            Path.home() / "Projects" / "claude-mpm",
-            # Current directory subdirectory
-            Path.cwd() / "claude-mpm",
-        ]
-
-        for candidate in candidates:
-            if candidate and candidate.exists():
-                # Check for claude-mpm agents directory
-                if (candidate / "src" / "claude_mpm" / "agents").exists():
-                    self.logger.info(f"Found claude-mpm at: {candidate}")
-                    return candidate
-
-        self.logger.warning("Framework not found, will use minimal instructions")
-        return None
-
-    def _get_npm_global_path(self) -> Optional[Path]:
-        """Get npm global installation path."""
-        try:
-            import subprocess
-
-            result = subprocess.run(
-                ["npm", "root", "-g"], capture_output=True, text=True, timeout=5
+            self.logger.info(
+                "📝 Output style content will be injected into framework instructions as fallback"
             )
-            if result.returncode == 0:
-                npm_root = Path(result.stdout.strip())
-                return npm_root / "@bobmatnyc" / "claude-multiagent-pm"
-        except:
-            pass
-        return None
-
-    def _discover_framework_paths(
-        self,
-    ) -> tuple[Optional[Path], Optional[Path], Optional[Path]]:
-        """
-        Discover agent directories based on priority.
-
-        Returns:
-            Tuple of (agents_dir, templates_dir, main_dir)
-        """
-        agents_dir = None
-        templates_dir = None
-        main_dir = None
-
-        if self.agents_dir and self.agents_dir.exists():
-            agents_dir = self.agents_dir
-            self.logger.info(f"Using custom agents directory: {agents_dir}")
-        elif self.framework_path and self.framework_path != Path("__PACKAGED__"):
-            # Prioritize templates directory over main agents directory
-            templates_dir = (
-                self.framework_path / "src" / "claude_mpm" / "agents" / "templates"
-            )
-            main_dir = self.framework_path / "src" / "claude_mpm" / "agents"
-
-            if templates_dir.exists() and any(templates_dir.glob("*.md")):
-                agents_dir = templates_dir
-                self.logger.info(f"Using agents from templates directory: {agents_dir}")
-            elif main_dir.exists() and any(main_dir.glob("*.md")):
-                agents_dir = main_dir
-                self.logger.info(f"Using agents from main directory: {agents_dir}")
-
-        return agents_dir, templates_dir, main_dir
 
     def _try_load_file(self, file_path: Path, file_type: str) -> Optional[str]:
         """
@@ -361,29 +298,6 @@ class FrameworkLoader:
                 self.logger.error(f"Failed to load {file_type}: {e}")
             return None
 
-    def _migrate_memory_file(self, old_path: Path, new_path: Path) -> None:
-        """
-        Migrate memory file from old naming convention to new.
-        
-        WHY: Supports backward compatibility by automatically migrating from
-        the old {agent_id}_agent.md and {agent_id}.md formats to the new {agent_id}_memories.md format.
-        
-        Args:
-            old_path: Path to the old file
-            new_path: Path to the new file
-        """
-        if old_path.exists() and not new_path.exists():
-            try:
-                # Read content from old file
-                content = old_path.read_text(encoding="utf-8")
-                # Write to new file
-                new_path.write_text(content, encoding="utf-8")
-                # Remove old file
-                old_path.unlink()
-                self.logger.info(f"Migrated memory file from {old_path.name} to {new_path.name}")
-            except Exception as e:
-                self.logger.error(f"Failed to migrate memory file {old_path.name}: {e}")
-
     def _load_instructions_file(self, content: Dict[str, Any]) -> None:
         """
         Load custom INSTRUCTIONS.md from .claude-mpm directories.
@@ -391,7 +305,7 @@ class FrameworkLoader:
         Precedence (highest to lowest):
         1. Project-specific: ./.claude-mpm/INSTRUCTIONS.md
         2. User-specific: ~/.claude-mpm/INSTRUCTIONS.md
-        
+
         NOTE: We do NOT load CLAUDE.md files since Claude Code already picks them up automatically.
         This prevents duplication of instructions.
 
@@ -407,9 +321,11 @@ class FrameworkLoader:
             if loaded_content:
                 content["custom_instructions"] = loaded_content
                 content["custom_instructions_level"] = "project"
-                self.logger.info("Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md")
+                self.logger.info(
+                    "Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md"
+                )
                 return
-        
+
         # Check for user-specific INSTRUCTIONS.md
         user_instructions_path = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
         if user_instructions_path.exists():
@@ -419,7 +335,9 @@ class FrameworkLoader:
             if loaded_content:
                 content["custom_instructions"] = loaded_content
                 content["custom_instructions_level"] = "user"
-                self.logger.info("Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md")
+                self.logger.info(
+                    "Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md"
+                )
                 return
 
     def _load_workflow_instructions(self, content: Dict[str, Any]) -> None:
@@ -430,7 +348,7 @@ class FrameworkLoader:
         1. Project-specific: ./.claude-mpm/WORKFLOW.md
         2. User-specific: ~/.claude-mpm/WORKFLOW.md
         3. System default: src/claude_mpm/agents/WORKFLOW.md or packaged
-        
+
         NOTE: We do NOT load from .claude/ directories to avoid conflicts.
 
         Args:
@@ -445,9 +363,11 @@ class FrameworkLoader:
             if loaded_content:
                 content["workflow_instructions"] = loaded_content
                 content["workflow_instructions_level"] = "project"
-                self.logger.info("Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md")
+                self.logger.info(
+                    "Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md"
+                )
                 return
-        
+
         # Check for user-specific WORKFLOW.md (medium priority)
         user_workflow_path = Path.home() / ".claude-mpm" / "WORKFLOW.md"
         if user_workflow_path.exists():
@@ -457,7 +377,9 @@ class FrameworkLoader:
             if loaded_content:
                 content["workflow_instructions"] = loaded_content
                 content["workflow_instructions_level"] = "user"
-                self.logger.info("Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md")
+                self.logger.info(
+                    "Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md"
+                )
                 return
 
         # Fall back to system workflow (lowest priority)
@@ -482,7 +404,7 @@ class FrameworkLoader:
         1. Project-specific: ./.claude-mpm/MEMORY.md
         2. User-specific: ~/.claude-mpm/MEMORY.md
         3. System default: src/claude_mpm/agents/MEMORY.md or packaged
-        
+
         NOTE: We do NOT load from .claude/ directories to avoid conflicts.
 
         Args:
@@ -497,9 +419,11 @@ class FrameworkLoader:
             if loaded_content:
                 content["memory_instructions"] = loaded_content
                 content["memory_instructions_level"] = "project"
-                self.logger.info("Using project-specific memory instructions from .claude-mpm/MEMORY.md")
+                self.logger.info(
+                    "Using project-specific memory instructions from .claude-mpm/MEMORY.md"
+                )
                 return
-        
+
         # Check for user-specific MEMORY.md (medium priority)
         user_memory_path = Path.home() / ".claude-mpm" / "MEMORY.md"
         if user_memory_path.exists():
@@ -509,7 +433,9 @@ class FrameworkLoader:
             if loaded_content:
                 content["memory_instructions"] = loaded_content
                 content["memory_instructions_level"] = "user"
-                self.logger.info("Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md")
+                self.logger.info(
+                    "Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md"
+                )
                 return
 
         # Fall back to system memory instructions (lowest priority)
@@ -525,357 +451,65 @@ class FrameworkLoader:
                     content["memory_instructions"] = loaded_content
                     content["memory_instructions_level"] = "system"
                     self.logger.info("Using system memory instructions")
-    
+
     def _get_deployed_agents(self) -> set:
         """
         Get a set of deployed agent names from .claude/agents/ directories.
         Uses caching to avoid repeated filesystem scans.
-        
+
         Returns:
             Set of agent names (file stems) that are deployed
         """
-        # Check if cache is valid
-        current_time = time.time()
-        if (self._deployed_agents_cache is not None and 
-            current_time - self._deployed_agents_cache_time < self.DEPLOYED_AGENTS_CACHE_TTL):
-            self.logger.debug(f"Using cached deployed agents (age: {current_time - self._deployed_agents_cache_time:.1f}s)")
-            return self._deployed_agents_cache
-        
+        # Try to get from cache first
+        cached = self._cache_manager.get_deployed_agents()
+        if cached is not None:
+            return cached
+
         # Cache miss or expired - perform actual scan
         self.logger.debug("Scanning for deployed agents (cache miss or expired)")
         deployed = set()
-        
+
         # Check multiple locations for deployed agents
         agents_dirs = [
             Path.cwd() / ".claude" / "agents",  # Project-specific agents
             Path.home() / ".claude" / "agents",  # User's system agents
         ]
-        
+
         for agents_dir in agents_dirs:
             if agents_dir.exists():
                 for agent_file in agents_dir.glob("*.md"):
                     if not agent_file.name.startswith("."):
                         # Use stem to get agent name without extension
                         deployed.add(agent_file.stem)
-                        self.logger.debug(f"Found deployed agent: {agent_file.stem} in {agents_dir}")
-        
+                        self.logger.debug(
+                            f"Found deployed agent: {agent_file.stem} in {agents_dir}"
+                        )
+
         self.logger.debug(f"Total deployed agents found: {len(deployed)}")
-        
+
         # Update cache
-        self._deployed_agents_cache = deployed
-        self._deployed_agents_cache_time = current_time
-        
+        self._cache_manager.set_deployed_agents(deployed)
+
         return deployed
-    
+
     def _load_actual_memories(self, content: Dict[str, Any]) -> None:
         """
-        Load actual memories from both user and project directories.
-        Uses caching to avoid repeated file I/O operations.
-        
-        Loading order:
-        1. User-level memories from ~/.claude-mpm/memories/ (global defaults)
-        2. Project-level memories from ./.claude-mpm/memories/ (overrides user)
-        
-        This loads:
-        1. PM memories from PM_memories.md (always loaded)
-        2. Agent memories from <agent>_memories.md (only if agent is deployed)
-        
+        Load actual memories using the MemoryManager service.
+
+        This method delegates all memory loading operations to the MemoryManager,
+        which handles caching, aggregation, deduplication, and legacy format migration.
+
         Args:
             content: Dictionary to update with actual memories
         """
-        # Check if cache is valid
-        current_time = time.time()
-        if (self._memories_cache is not None and 
-            current_time - self._memories_cache_time < self.MEMORIES_CACHE_TTL):
-            cache_age = current_time - self._memories_cache_time
-            self.logger.debug(f"Using cached memories (age: {cache_age:.1f}s)")
-            
-            # Apply cached memories to content
-            if "actual_memories" in self._memories_cache:
-                content["actual_memories"] = self._memories_cache["actual_memories"]
-            if "agent_memories" in self._memories_cache:
-                content["agent_memories"] = self._memories_cache["agent_memories"]
-            return
-        
-        # Cache miss or expired - perform actual loading
-        self.logger.debug("Loading memories from disk (cache miss or expired)")
-        
-        # Define memory directories in priority order (user first, then project)
-        user_memories_dir = Path.home() / ".claude-mpm" / "memories"
-        project_memories_dir = Path.cwd() / ".claude-mpm" / "memories"
-        
-        # Check for deployed agents
-        deployed_agents = self._get_deployed_agents()
-        
-        # Track loading statistics
-        loaded_count = 0
-        skipped_count = 0
-        
-        # Dictionary to store aggregated memories
-        pm_memories = []
-        agent_memories_dict = {}
-        
-        # Load memories from user directory first
-        if user_memories_dir.exists():
-            self.logger.info(f"Loading user-level memory files from: {user_memories_dir}")
-            loaded, skipped = self._load_memories_from_directory(
-                user_memories_dir, deployed_agents, pm_memories, agent_memories_dict, "user"
-            )
-            loaded_count += loaded
-            skipped_count += skipped
-        else:
-            self.logger.debug(f"No user memories directory found at: {user_memories_dir}")
-        
-        # Load memories from project directory (overrides user memories)
-        if project_memories_dir.exists():
-            self.logger.info(f"Loading project-level memory files from: {project_memories_dir}")
-            loaded, skipped = self._load_memories_from_directory(
-                project_memories_dir, deployed_agents, pm_memories, agent_memories_dict, "project"
-            )
-            loaded_count += loaded
-            skipped_count += skipped
-        else:
-            self.logger.debug(f"No project memories directory found at: {project_memories_dir}")
-        
-        # Aggregate PM memories
-        if pm_memories:
-            aggregated_pm = self._aggregate_memories(pm_memories)
-            content["actual_memories"] = aggregated_pm
-            memory_size = len(aggregated_pm.encode('utf-8'))
-            self.logger.info(f"Aggregated PM memory ({memory_size:,} bytes) from {len(pm_memories)} source(s)")
-        
-        # Store agent memories (already aggregated per agent)
-        if agent_memories_dict:
-            content["agent_memories"] = agent_memories_dict
-            for agent_name, memory_content in agent_memories_dict.items():
-                memory_size = len(memory_content.encode('utf-8'))
-                self.logger.debug(f"Aggregated {agent_name} memory: {memory_size:,} bytes")
-        
-        # Update cache with loaded memories
-        self._memories_cache = {}
-        if "actual_memories" in content:
-            self._memories_cache["actual_memories"] = content["actual_memories"]
-        if "agent_memories" in content:
-            self._memories_cache["agent_memories"] = content["agent_memories"]
-        self._memories_cache_time = current_time
-        
-        # Log detailed summary
-        if loaded_count > 0 or skipped_count > 0:
-            # Count unique agents with memories
-            agent_count = len(agent_memories_dict) if agent_memories_dict else 0
-            pm_loaded = bool(content.get("actual_memories"))
-            
-            summary_parts = []
-            if pm_loaded:
-                summary_parts.append("PM memory loaded")
-            if agent_count > 0:
-                summary_parts.append(f"{agent_count} agent memories loaded")
-            if skipped_count > 0:
-                summary_parts.append(f"{skipped_count} non-deployed agent memories skipped")
-            
-            self.logger.info(f"Memory loading complete: {' | '.join(summary_parts)}")
-            
-            # Log deployed agents for reference
-            if len(deployed_agents) > 0:
-                self.logger.debug(f"Deployed agents available for memory loading: {', '.join(sorted(deployed_agents))}")
-    
-    def _load_memories_from_directory(
-        self,
-        memories_dir: Path,
-        deployed_agents: set,
-        pm_memories: list,
-        agent_memories_dict: dict,
-        source: str
-    ) -> tuple[int, int]:
-        """
-        Load memories from a specific directory.
-        
-        Args:
-            memories_dir: Directory to load memories from
-            deployed_agents: Set of deployed agent names
-            pm_memories: List to append PM memories to
-            agent_memories_dict: Dict to store agent memories
-            source: Source label ("user" or "project")
-        
-        Returns:
-            Tuple of (loaded_count, skipped_count)
-        """
-        loaded_count = 0
-        skipped_count = 0
-        
-        # Load PM memories (always loaded)
-        # Support migration from both old formats
-        pm_memory_path = memories_dir / "PM_memories.md"
-        old_pm_path = memories_dir / "PM.md"
-        
-        # Migrate from old PM.md if needed
-        if not pm_memory_path.exists() and old_pm_path.exists():
-            try:
-                old_pm_path.rename(pm_memory_path)
-                self.logger.info(f"Migrated PM.md to PM_memories.md")
-            except Exception as e:
-                self.logger.error(f"Failed to migrate PM.md: {e}")
-                pm_memory_path = old_pm_path  # Fall back to old path
-        if pm_memory_path.exists():
-            loaded_content = self._try_load_file(
-                pm_memory_path, f"PM memory ({source})"
-            )
-            if loaded_content:
-                pm_memories.append({
-                    "source": source,
-                    "content": loaded_content,
-                    "path": pm_memory_path
-                })
-                memory_size = len(loaded_content.encode('utf-8'))
-                self.logger.info(f"Loaded {source} PM memory: {pm_memory_path} ({memory_size:,} bytes)")
-                loaded_count += 1
-        
-        # First, migrate any old format memory files to new format
-        # This handles backward compatibility for existing installations
-        for old_file in memories_dir.glob("*.md"):
-            # Skip files already in correct format and special files
-            if old_file.name.endswith("_memories.md") or old_file.name in ["PM.md", "README.md"]:
-                continue
-            
-            # Determine new name based on old format
-            if old_file.stem.endswith("_agent"):
-                # Old format: {agent_name}_agent.md -> {agent_name}_memories.md
-                agent_name = old_file.stem[:-6]  # Remove "_agent" suffix
-                new_path = memories_dir / f"{agent_name}_memories.md"
-                if not new_path.exists():
-                    self._migrate_memory_file(old_file, new_path)
-            else:
-                # Intermediate format: {agent_name}.md -> {agent_name}_memories.md
-                agent_name = old_file.stem
-                new_path = memories_dir / f"{agent_name}_memories.md"
-                if not new_path.exists():
-                    self._migrate_memory_file(old_file, new_path)
-        
-        # Load agent memories (only for deployed agents)
-        # Only process *_memories.md files to avoid README.md and other docs
-        for memory_file in memories_dir.glob("*_memories.md"):
-            # Skip PM_memories.md as we already handled it
-            if memory_file.name == "PM_memories.md":
-                continue
-            
-            # Extract agent name from file (remove "_memories" suffix)
-            agent_name = memory_file.stem[:-9]  # Remove "_memories" suffix
-            
-            # Check if agent is deployed
-            if agent_name in deployed_agents:
-                loaded_content = self._try_load_file(
-                    memory_file, f"agent memory: {agent_name} ({source})"
-                )
-                if loaded_content:
-                    # Store or merge agent memories
-                    if agent_name not in agent_memories_dict:
-                        agent_memories_dict[agent_name] = []
-                    
-                    # If it's a list, append the new memory entry
-                    if isinstance(agent_memories_dict[agent_name], list):
-                        agent_memories_dict[agent_name].append({
-                            "source": source,
-                            "content": loaded_content,
-                            "path": memory_file
-                        })
-                    
-                    memory_size = len(loaded_content.encode('utf-8'))
-                    self.logger.info(f"Loaded {source} memory for {agent_name}: {memory_file.name} ({memory_size:,} bytes)")
-                    loaded_count += 1
-            else:
-                # Provide more detailed logging about why the memory was skipped
-                self.logger.info(f"Skipped {source} memory: {memory_file.name} (agent '{agent_name}' not deployed)")
-                # Also log a debug message with available agents for diagnostics
-                if agent_name.replace('_', '-') in deployed_agents or agent_name.replace('-', '_') in deployed_agents:
-                    # Detect naming mismatches
-                    alt_name = agent_name.replace('_', '-') if '_' in agent_name else agent_name.replace('-', '_')
-                    if alt_name in deployed_agents:
-                        self.logger.warning(
-                            f"Naming mismatch detected: Memory file uses '{agent_name}' but deployed agent is '{alt_name}'. "
-                            f"Consider renaming {memory_file.name} to {alt_name}_memories.md"
-                        )
-                skipped_count += 1
-        
-        # After loading all memories for this directory, aggregate agent memories
-        for agent_name in list(agent_memories_dict.keys()):
-            if isinstance(agent_memories_dict[agent_name], list) and agent_memories_dict[agent_name]:
-                # Aggregate memories for this agent
-                aggregated = self._aggregate_memories(agent_memories_dict[agent_name])
-                agent_memories_dict[agent_name] = aggregated
-        
-        return loaded_count, skipped_count
-    
-    def _aggregate_memories(self, memory_entries: list) -> str:
-        """
-        Aggregate multiple memory entries into a single memory string.
-        
-        Strategy:
-        - Simplified to support list-based memories only
-        - Preserve all unique bullet-point items (lines starting with -)
-        - Remove exact duplicates
-        - Project-level memories take precedence over user-level
-        
-        Args:
-            memory_entries: List of memory entries with source, content, and path
-        
-        Returns:
-            Aggregated memory content as a string
-        """
-        if not memory_entries:
-            return ""
-        
-        # If only one entry, return it as-is
-        if len(memory_entries) == 1:
-            return memory_entries[0]["content"]
-        
-        # Parse all memories into a simple list
-        all_items = {}  # Dict to track items and their source
-        metadata_lines = []
-        agent_id = None
-        
-        for entry in memory_entries:
-            content = entry["content"]
-            source = entry["source"]
-            
-            for line in content.split('\n'):
-                # Check for header to extract agent_id
-                if line.startswith('# Agent Memory:'):
-                    agent_id = line.replace('# Agent Memory:', '').strip()
-                # Check for metadata lines
-                elif line.startswith('<!-- ') and line.endswith(' -->'):
-                    # Only keep metadata from project source or if not already present
-                    if source == "project" or line not in metadata_lines:
-                        metadata_lines.append(line)
-                # Check for list items
-                elif line.strip().startswith('-'):
-                    # Normalize the item for comparison
-                    item_text = line.strip()
-                    normalized = item_text.lstrip('- ').strip().lower()
-                    
-                    # Add item if new or if project source overrides user source
-                    if normalized not in all_items or source == "project":
-                        all_items[normalized] = (item_text, source)
-        
-        # Build aggregated content as simple list
-        lines = []
-        
-        # Add header
-        if agent_id:
-            lines.append(f"# Agent Memory: {agent_id}")
-        else:
-            lines.append("# Agent Memory")
-        
-        # Add latest timestamp from metadata
-        from datetime import datetime
-        lines.append(f"<!-- Last Updated: {datetime.now().isoformat()}Z -->")
-        lines.append("")
-        
-        # Add all unique items (sorted for consistency)
-        for normalized_key in sorted(all_items.keys()):
-            item_text, source = all_items[normalized_key]
-            lines.append(item_text)
-        
-        return '\n'.join(lines)
+        # Use MemoryManager to load all memories
+        memories = self._memory_manager.load_memories()
+
+        # Apply loaded memories to content
+        if "actual_memories" in memories:
+            content["actual_memories"] = memories["actual_memories"]
+        if "agent_memories" in memories:
+            content["agent_memories"] = memories["agent_memories"]
 
     def _load_single_agent(
         self, agent_file: Path
@@ -972,7 +606,7 @@ class FrameworkLoader:
 
         if not self.framework_path:
             return content
-            
+
         # Check if this is a packaged installation
         if self.framework_path == Path("__PACKAGED__"):
             # Load files using importlib.resources for packaged installations
@@ -981,7 +615,11 @@ class FrameworkLoader:
             # Load from filesystem for development mode
             # Load framework's INSTRUCTIONS.md
             framework_instructions_path = (
-                self.framework_path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md"
+                self.framework_path
+                / "src"
+                / "claude_mpm"
+                / "agents"
+                / "INSTRUCTIONS.md"
             )
             if framework_instructions_path.exists():
                 loaded_content = self._try_load_file(
@@ -993,12 +631,14 @@ class FrameworkLoader:
                     # Add framework version to content
                     if self.framework_version:
                         content["instructions_version"] = self.framework_version
-                        content[
-                            "version"
-                        ] = self.framework_version  # Update main version key
+                        content["version"] = (
+                            self.framework_version
+                        )  # Update main version key
                     # Add modification timestamp to content
                     if self.framework_last_modified:
-                        content["instructions_last_modified"] = self.framework_last_modified
+                        content["instructions_last_modified"] = (
+                            self.framework_last_modified
+                        )
 
             # Load BASE_PM.md for core framework requirements
             base_pm_path = (
@@ -1016,33 +656,40 @@ class FrameworkLoader:
 
         # Load MEMORY.md - check for project-specific first, then system
         self._load_memory_instructions(content)
-        
+
         # Load actual memories from .claude-mpm/memories/PM_memories.md
         self._load_actual_memories(content)
 
-        # Discover agent directories
-        agents_dir, templates_dir, main_dir = self._discover_framework_paths()
+        # Discover agent directories using PathResolver
+        agents_dir, templates_dir, main_dir = self._path_resolver.discover_agent_paths(
+            agents_dir=self.agents_dir, framework_path=self.framework_path
+        )
 
         # Load agents from discovered directory
         self._load_agents_directory(content, agents_dir, templates_dir, main_dir)
 
         return content
-    
+
     def _load_packaged_framework_content(self, content: Dict[str, Any]) -> None:
         """Load framework content from packaged installation using importlib.resources."""
         if not files:
-            self.logger.warning("importlib.resources not available, cannot load packaged framework")
+            self.logger.warning(
+                "importlib.resources not available, cannot load packaged framework"
+            )
             self.logger.debug(f"files variable is: {files}")
             # Try alternative import methods
             try:
                 from importlib import resources
+
                 self.logger.info("Using importlib.resources as fallback")
                 self._load_packaged_framework_content_fallback(content, resources)
                 return
             except ImportError:
-                self.logger.error("No importlib.resources available, using minimal framework")
+                self.logger.error(
+                    "No importlib.resources available, using minimal framework"
+                )
                 return
-            
+
         try:
             # Load INSTRUCTIONS.md
             instructions_content = self._load_packaged_file("INSTRUCTIONS.md")
@@ -1050,43 +697,51 @@ class FrameworkLoader:
                 content["framework_instructions"] = instructions_content
                 content["loaded"] = True
                 # Extract and store version/timestamp metadata
-                self._extract_metadata_from_content(instructions_content, "INSTRUCTIONS.md")
+                self._extract_metadata_from_content(
+                    instructions_content, "INSTRUCTIONS.md"
+                )
                 if self.framework_version:
                     content["instructions_version"] = self.framework_version
                     content["version"] = self.framework_version
                 if self.framework_last_modified:
                     content["instructions_last_modified"] = self.framework_last_modified
-            
+
             # Load BASE_PM.md
             base_pm_content = self._load_packaged_file("BASE_PM.md")
             if base_pm_content:
                 content["base_pm_instructions"] = base_pm_content
-                
+
             # Load WORKFLOW.md
             workflow_content = self._load_packaged_file("WORKFLOW.md")
             if workflow_content:
                 content["workflow_instructions"] = workflow_content
                 content["project_workflow"] = "system"
-                
+
             # Load MEMORY.md
             memory_content = self._load_packaged_file("MEMORY.md")
             if memory_content:
                 content["memory_instructions"] = memory_content
                 content["project_memory"] = "system"
-                
+
         except Exception as e:
             self.logger.error(f"Failed to load packaged framework content: {e}")
 
-    def _load_packaged_framework_content_fallback(self, content: Dict[str, Any], resources) -> None:
+    def _load_packaged_framework_content_fallback(
+        self, content: Dict[str, Any], resources
+    ) -> None:
         """Load framework content using importlib.resources fallback."""
         try:
             # Load INSTRUCTIONS.md
-            instructions_content = self._load_packaged_file_fallback("INSTRUCTIONS.md", resources)
+            instructions_content = self._load_packaged_file_fallback(
+                "INSTRUCTIONS.md", resources
+            )
             if instructions_content:
                 content["framework_instructions"] = instructions_content
                 content["loaded"] = True
                 # Extract and store version/timestamp metadata
-                self._extract_metadata_from_content(instructions_content, "INSTRUCTIONS.md")
+                self._extract_metadata_from_content(
+                    instructions_content, "INSTRUCTIONS.md"
+                )
                 if self.framework_version:
                     content["instructions_version"] = self.framework_version
                     content["version"] = self.framework_version
@@ -1099,7 +754,9 @@ class FrameworkLoader:
                 content["base_pm_instructions"] = base_pm_content
 
             # Load WORKFLOW.md
-            workflow_content = self._load_packaged_file_fallback("WORKFLOW.md", resources)
+            workflow_content = self._load_packaged_file_fallback(
+                "WORKFLOW.md", resources
+            )
             if workflow_content:
                 content["workflow_instructions"] = workflow_content
                 content["project_workflow"] = "system"
@@ -1111,7 +768,9 @@ class FrameworkLoader:
                 content["project_memory"] = "system"
 
         except Exception as e:
-            self.logger.error(f"Failed to load packaged framework content with fallback: {e}")
+            self.logger.error(
+                f"Failed to load packaged framework content with fallback: {e}"
+            )
 
     def _load_packaged_file_fallback(self, filename: str, resources) -> Optional[str]:
         """Load a file from the packaged installation using importlib.resources fallback."""
@@ -1119,52 +778,52 @@ class FrameworkLoader:
             # Try different resource loading methods
             try:
                 # Method 1: resources.read_text (Python 3.9+)
-                content = resources.read_text('claude_mpm.agents', filename)
+                content = resources.read_text("claude_mpm.agents", filename)
                 self.logger.info(f"Loaded {filename} from package using read_text")
                 return content
             except AttributeError:
                 # Method 2: resources.files (Python 3.9+)
-                agents_files = resources.files('claude_mpm.agents')
+                agents_files = resources.files("claude_mpm.agents")
                 file_path = agents_files / filename
                 if file_path.is_file():
                     content = file_path.read_text()
                     self.logger.info(f"Loaded {filename} from package using files")
                     return content
-                else:
-                    self.logger.warning(f"File {filename} not found in package")
-                    return None
+                self.logger.warning(f"File {filename} not found in package")
+                return None
         except Exception as e:
-            self.logger.error(f"Failed to load {filename} from package with fallback: {e}")
+            self.logger.error(
+                f"Failed to load {filename} from package with fallback: {e}"
+            )
             return None
 
     def _load_packaged_file(self, filename: str) -> Optional[str]:
         """Load a file from the packaged installation."""
         try:
             # Use importlib.resources to load file from package
-            agents_package = files('claude_mpm.agents')
+            agents_package = files("claude_mpm.agents")
             file_path = agents_package / filename
-            
+
             if file_path.is_file():
                 content = file_path.read_text()
                 self.logger.info(f"Loaded {filename} from package")
                 return content
-            else:
-                self.logger.warning(f"File {filename} not found in package")
-                return None
+            self.logger.warning(f"File {filename} not found in package")
+            return None
         except Exception as e:
             self.logger.error(f"Failed to load {filename} from package: {e}")
             return None
-            
+
     def _extract_metadata_from_content(self, content: str, filename: str) -> None:
         """Extract metadata from content string."""
         import re
-        
+
         # Extract version
         version_match = re.search(r"<!-- FRAMEWORK_VERSION: (\d+) -->", content)
         if version_match and "INSTRUCTIONS.md" in filename:
             self.framework_version = version_match.group(1)
             self.logger.info(f"Framework version: {self.framework_version}")
-            
+
         # Extract timestamp
         timestamp_match = re.search(r"<!-- LAST_MODIFIED: ([^>]+) -->", content)
         if timestamp_match and "INSTRUCTIONS.md" in filename:
@@ -1178,12 +837,58 @@ class FrameworkLoader:
         Returns:
             Complete framework instructions ready for injection
         """
+        # Import LogManager for prompt logging
+        try:
+            from .log_manager import get_log_manager
+
+            log_manager = get_log_manager()
+        except ImportError:
+            log_manager = None
+
+        # Generate the instructions
         if self.framework_content["loaded"]:
             # Build framework from components
-            return self._format_full_framework()
+            instructions = self._format_full_framework()
         else:
             # Use minimal fallback
-            return self._format_minimal_framework()
+            instructions = self._format_minimal_framework()
+
+        # Log the system prompt if LogManager is available
+        if log_manager:
+            try:
+                import asyncio
+                import os
+
+                # Get or create event loop
+                try:
+                    loop = asyncio.get_running_loop()
+                except RuntimeError:
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+
+                # Prepare metadata
+                metadata = {
+                    "framework_version": self.framework_version,
+                    "framework_loaded": self.framework_content.get("loaded", False),
+                    "session_id": os.environ.get("CLAUDE_SESSION_ID", "unknown"),
+                    "instructions_length": len(instructions),
+                }
+
+                # Log the prompt asynchronously
+                if loop.is_running():
+                    asyncio.create_task(
+                        log_manager.log_prompt("system_prompt", instructions, metadata)
+                    )
+                else:
+                    loop.run_until_complete(
+                        log_manager.log_prompt("system_prompt", instructions, metadata)
+                    )
+
+                self.logger.debug("System prompt logged to prompts directory")
+            except Exception as e:
+                self.logger.debug(f"Could not log system prompt: {e}")
+
+        return instructions
 
     def _strip_metadata_comments(self, content: str) -> str:
         """Strip metadata HTML comments from content.
@@ -1201,12 +906,10 @@ class FrameworkLoader:
             content,
         )
         # Also remove any leading blank lines that might result
-        cleaned = cleaned.lstrip("\n")
-        return cleaned
+        return cleaned.lstrip("\n")
 
     def _format_full_framework(self) -> str:
         """Format full framework instructions."""
-        from datetime import datetime
 
         # Initialize output style manager on first use (ensures content is loaded)
         if self.output_style_manager is None:
@@ -1217,7 +920,9 @@ class FrameworkLoader:
         if self.output_style_manager:
             inject_output_style = self.output_style_manager.should_inject_content()
             if inject_output_style:
-                self.logger.info("Injecting output style content into instructions for Claude < 1.0.83")
+                self.logger.info(
+                    "Injecting output style content into instructions for Claude < 1.0.83"
+                )
 
         # If we have the full framework INSTRUCTIONS.md, use it
         if self.framework_content.get("framework_instructions"):
@@ -1227,10 +932,12 @@ class FrameworkLoader:
 
             # Note: We don't add working directory CLAUDE.md here since Claude Code
             # already picks it up automatically. This prevents duplication.
-            
+
             # Add custom INSTRUCTIONS.md if present (overrides or extends framework instructions)
             if self.framework_content.get("custom_instructions"):
-                level = self.framework_content.get("custom_instructions_level", "unknown")
+                level = self.framework_content.get(
+                    "custom_instructions_level", "unknown"
+                )
                 instructions += f"\n\n## Custom PM Instructions ({level} level)\n\n"
                 instructions += "**The following custom instructions override or extend the framework defaults:**\n\n"
                 instructions += self._strip_metadata_comments(
@@ -1243,7 +950,9 @@ class FrameworkLoader:
                 workflow_content = self._strip_metadata_comments(
                     self.framework_content["workflow_instructions"]
                 )
-                level = self.framework_content.get("workflow_instructions_level", "system")
+                level = self.framework_content.get(
+                    "workflow_instructions_level", "system"
+                )
                 if level != "system":
                     instructions += f"\n\n## Workflow Instructions ({level} level)\n\n"
                     instructions += "**The following workflow instructions override system defaults:**\n\n"
@@ -1254,26 +963,28 @@ class FrameworkLoader:
                 memory_content = self._strip_metadata_comments(
                     self.framework_content["memory_instructions"]
                 )
-                level = self.framework_content.get("memory_instructions_level", "system")
+                level = self.framework_content.get(
+                    "memory_instructions_level", "system"
+                )
                 if level != "system":
                     instructions += f"\n\n## Memory Instructions ({level} level)\n\n"
                     instructions += "**The following memory instructions override system defaults:**\n\n"
                 instructions += f"{memory_content}\n"
-            
+
             # Add actual PM memories after memory instructions
             if self.framework_content.get("actual_memories"):
                 instructions += "\n\n## Current PM Memories\n\n"
                 instructions += "**The following are your accumulated memories and knowledge from this project:**\n\n"
                 instructions += self.framework_content["actual_memories"]
                 instructions += "\n"
-            
+
             # Add agent memories if available
             if self.framework_content.get("agent_memories"):
                 agent_memories = self.framework_content["agent_memories"]
                 if agent_memories:
                     instructions += "\n\n## Agent Memories\n\n"
                     instructions += "**The following are accumulated memories from specialized agents:**\n\n"
-                    
+
                     for agent_name in sorted(agent_memories.keys()):
                         memory_content = agent_memories[agent_name]
                         if memory_content:
@@ -1296,10 +1007,12 @@ class FrameworkLoader:
                     self.framework_content["base_pm_instructions"]
                 )
                 instructions += f"\n\n{base_pm}"
-            
+
             # Inject output style content if needed (for Claude < 1.0.83)
             if inject_output_style and self.output_style_manager:
-                output_style_content = self.output_style_manager.get_injectable_content(framework_loader=self)
+                output_style_content = self.output_style_manager.get_injectable_content(
+                    framework_loader=self
+                )
                 if output_style_content:
                     instructions += "\n\n## Output Style Configuration\n"
                     instructions += "**Note: The following output style is injected for Claude < 1.0.83**\n\n"
@@ -1307,9 +1020,7 @@ class FrameworkLoader:
                     instructions += "\n"
 
             # Clean up any trailing whitespace
-            instructions = instructions.rstrip() + "\n"
-
-            return instructions
+            return instructions.rstrip() + "\n"
 
         # Otherwise fall back to generating framework
         instructions = """# Claude MPM Framework Instructions
@@ -1432,23 +1143,21 @@ Extract tickets from these patterns:
     def _generate_agent_capabilities_section(self) -> str:
         """Generate dynamic agent capabilities section from deployed agents.
         Uses caching to avoid repeated file I/O and parsing operations."""
-        
-        # Check if cache is valid
+
+        # Try to get from cache first
+        cached_capabilities = self._cache_manager.get_capabilities()
+        if cached_capabilities is not None:
+            return cached_capabilities
+
+        # Will be used for updating cache later
         current_time = time.time()
-        if (self._agent_capabilities_cache is not None and 
-            current_time - self._agent_capabilities_cache_time < self.CAPABILITIES_CACHE_TTL):
-            cache_age = current_time - self._agent_capabilities_cache_time
-            self.logger.debug(f"Using cached agent capabilities (age: {cache_age:.1f}s)")
-            return self._agent_capabilities_cache
-        
+
         # Cache miss or expired - generate capabilities
         self.logger.debug("Generating agent capabilities (cache miss or expired)")
-        
+
         try:
             from pathlib import Path
 
-            import yaml
-
             # Read directly from deployed agents in .claude/agents/
             # Check multiple locations for deployed agents
             # Priority order: project > user home > fallback
@@ -1456,47 +1165,55 @@ Extract tickets from these patterns:
                 Path.cwd() / ".claude" / "agents",  # Project-specific agents
                 Path.home() / ".claude" / "agents",  # User's system agents
             ]
-            
+
             # Collect agents from all directories with proper precedence
             # Project agents override user agents with the same name
             all_agents = {}  # key: agent_id, value: (agent_data, priority)
-            
+
             for priority, potential_dir in enumerate(agents_dirs):
                 if potential_dir.exists() and any(potential_dir.glob("*.md")):
                     self.logger.debug(f"Found agents directory at: {potential_dir}")
-                    
+
                     # Collect agents from this directory
                     for agent_file in potential_dir.glob("*.md"):
                         if agent_file.name.startswith("."):
                             continue
-                        
+
                         # Parse agent metadata (with caching)
                         agent_data = self._parse_agent_metadata(agent_file)
                         if agent_data:
                             agent_id = agent_data["id"]
                             # Only add if not already present (project has priority 0, user has priority 1)
                             # Lower priority number wins (project > user)
-                            if agent_id not in all_agents or priority < all_agents[agent_id][1]:
+                            if (
+                                agent_id not in all_agents
+                                or priority < all_agents[agent_id][1]
+                            ):
                                 all_agents[agent_id] = (agent_data, priority)
-                                self.logger.debug(f"Added/Updated agent {agent_id} from {potential_dir} (priority {priority})")
+                                self.logger.debug(
+                                    f"Added/Updated agent {agent_id} from {potential_dir} (priority {priority})"
+                                )
 
             if not all_agents:
                 self.logger.warning(f"No agents found in any location: {agents_dirs}")
                 result = self._get_fallback_capabilities()
                 # Cache the fallback result too
-                self._agent_capabilities_cache = result
-                self._agent_capabilities_cache_time = current_time
+                self._cache_manager.set_capabilities(result)
                 return result
-            
+
             # Log agent collection summary
             project_agents = [aid for aid, (_, pri) in all_agents.items() if pri == 0]
             user_agents = [aid for aid, (_, pri) in all_agents.items() if pri == 1]
-            
+
             if project_agents:
-                self.logger.info(f"Loaded {len(project_agents)} project agents: {', '.join(sorted(project_agents))}")
+                self.logger.info(
+                    f"Loaded {len(project_agents)} project agents: {', '.join(sorted(project_agents))}"
+                )
             if user_agents:
-                self.logger.info(f"Loaded {len(user_agents)} user agents: {', '.join(sorted(user_agents))}")
-            
+                self.logger.info(
+                    f"Loaded {len(user_agents)} user agents: {', '.join(sorted(user_agents))}"
+                )
+
             # Build capabilities section
             section = "\n\n## Available Agent Capabilities\n\n"
 
@@ -1506,8 +1223,7 @@ Extract tickets from these patterns:
             if not deployed_agents:
                 result = self._get_fallback_capabilities()
                 # Cache the fallback result
-                self._agent_capabilities_cache = result
-                self._agent_capabilities_cache_time = current_time
+                self._cache_manager.set_capabilities(result)
                 return result
 
             # Sort agents alphabetically by ID
@@ -1528,6 +1244,33 @@ Extract tickets from these patterns:
                 section += f"\n### {display_name} (`{agent['id']}`)\n"
                 section += f"{agent['description']}\n"
 
+                # Add routing information if available
+                if agent.get("routing"):
+                    routing = agent["routing"]
+
+                    # Format routing hints for PM usage
+                    routing_hints = []
+
+                    if routing.get("keywords"):
+                        # Show first 5 keywords for brevity
+                        keywords = routing["keywords"][:5]
+                        routing_hints.append(f"Keywords: {', '.join(keywords)}")
+
+                    if routing.get("paths"):
+                        # Show first 3 paths for brevity
+                        paths = routing["paths"][:3]
+                        routing_hints.append(f"Paths: {', '.join(paths)}")
+
+                    if routing.get("priority"):
+                        routing_hints.append(f"Priority: {routing['priority']}")
+
+                    if routing_hints:
+                        section += f"- **Routing**: {' | '.join(routing_hints)}\n"
+
+                    # Add when_to_use if present
+                    if routing.get("when_to_use"):
+                        section += f"- **When to use**: {routing['when_to_use']}\n"
+
                 # Add any additional metadata if present
                 if agent.get("authority"):
                     section += f"- **Authority**: {agent['authority']}\n"
@@ -1556,10 +1299,11 @@ Extract tickets from these patterns:
             section += f"\n**Total Available Agents**: {len(deployed_agents)}\n"
 
             # Cache the generated capabilities
-            self._agent_capabilities_cache = section
-            self._agent_capabilities_cache_time = current_time
-            self.logger.debug(f"Cached agent capabilities section ({len(section)} chars)")
-            
+            self._cache_manager.set_capabilities(section)
+            self.logger.debug(
+                f"Cached agent capabilities section ({len(section)} chars)"
+            )
+
             return section
 
         except Exception as e:
@@ -1582,22 +1326,24 @@ Extract tickets from these patterns:
             cache_key = str(agent_file)
             file_mtime = agent_file.stat().st_mtime
             current_time = time.time()
-            
-            # Check if we have cached data for this file
-            if cache_key in self._agent_metadata_cache:
-                cached_data, cached_mtime = self._agent_metadata_cache[cache_key]
+
+            # Try to get from cache first
+            cached_result = self._cache_manager.get_agent_metadata(cache_key)
+            if cached_result is not None:
+                cached_data, cached_mtime = cached_result
                 # Use cache if file hasn't been modified and cache isn't too old
-                if (cached_mtime == file_mtime and 
-                    current_time - cached_mtime < self.METADATA_CACHE_TTL):
+                if cached_mtime == file_mtime:
                     self.logger.debug(f"Using cached metadata for {agent_file.name}")
                     return cached_data
-            
+
             # Cache miss or expired - parse the file
-            self.logger.debug(f"Parsing metadata for {agent_file.name} (cache miss or expired)")
-            
+            self.logger.debug(
+                f"Parsing metadata for {agent_file.name} (cache miss or expired)"
+            )
+
             import yaml
 
-            with open(agent_file, "r") as f:
+            with open(agent_file) as f:
                 content = f.read()
 
             # Default values
@@ -1632,15 +1378,89 @@ Extract tickets from these patterns:
                         # IMPORTANT: Do NOT add spaces to tools field - it breaks deployment!
                         # Tools must remain as comma-separated without spaces: "Read,Write,Edit"
 
+            # Try to load routing metadata from JSON template if not in YAML frontmatter
+            if "routing" not in agent_data:
+                routing_data = self._load_routing_from_template(agent_file.stem)
+                if routing_data:
+                    agent_data["routing"] = routing_data
+
             # Cache the parsed metadata
-            self._agent_metadata_cache[cache_key] = (agent_data, file_mtime)
-            
+            self._cache_manager.set_agent_metadata(cache_key, agent_data, file_mtime)
+
             return agent_data
 
         except Exception as e:
             self.logger.debug(f"Could not parse metadata from {agent_file}: {e}")
             return None
 
+    def _load_routing_from_template(self, agent_name: str) -> Optional[Dict[str, Any]]:
+        """Load routing metadata from agent JSON template.
+
+        Args:
+            agent_name: Name of the agent (stem of the file)
+
+        Returns:
+            Dictionary with routing metadata or None if not found
+        """
+        try:
+            import json
+
+            # Check if we have a framework path
+            if not self.framework_path or self.framework_path == Path("__PACKAGED__"):
+                # For packaged installations, try to load from package resources
+                if files:
+                    try:
+                        templates_package = files("claude_mpm.agents.templates")
+                        template_file = templates_package / f"{agent_name}.json"
+
+                        if template_file.is_file():
+                            template_content = template_file.read_text()
+                            template_data = json.loads(template_content)
+                            return template_data.get("routing")
+                    except Exception as e:
+                        self.logger.debug(
+                            f"Could not load routing from packaged template for {agent_name}: {e}"
+                        )
+                return None
+
+            # For development mode, load from filesystem
+            templates_dir = (
+                self.framework_path / "src" / "claude_mpm" / "agents" / "templates"
+            )
+            template_file = templates_dir / f"{agent_name}.json"
+
+            if template_file.exists():
+                with open(template_file) as f:
+                    template_data = json.load(f)
+                    return template_data.get("routing")
+
+            # Also check for variations in naming (underscore vs dash)
+            # Handle common naming variations between deployed .md files and .json templates
+            # Remove duplicates by using a set
+            alternative_names = list(
+                {
+                    agent_name.replace("-", "_"),  # api-qa -> api_qa
+                    agent_name.replace("_", "-"),  # api_qa -> api-qa
+                    agent_name.replace("-", ""),  # api-qa -> apiqa
+                    agent_name.replace("_", ""),  # api_qa -> apiqa
+                }
+            )
+
+            for alt_name in alternative_names:
+                if alt_name != agent_name:
+                    alt_file = templates_dir / f"{alt_name}.json"
+                    if alt_file.exists():
+                        with open(alt_file) as f:
+                            template_data = json.load(f)
+                            return template_data.get("routing")
+
+            self.logger.debug(f"No JSON template found for agent: {agent_name}")
+            return None
+
+        except Exception as e:
+            self.logger.debug(f"Could not load routing metadata for {agent_name}: {e}")
+            return None
+
     def _generate_agent_selection_guide(self, deployed_agents: list) -> str:
         """Generate Context-Aware Agent Selection guide from deployed agents.
 
@@ -1660,55 +1480,55 @@ Extract tickets from these patterns:
             if "implementation" in desc_lower or (
                 "engineer" in agent_id and "data" not in agent_id
             ):
-                selection_map[
-                    "Implementation tasks"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Implementation tasks"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "codebase analysis" in desc_lower or "research" in agent_id:
-                selection_map[
-                    "Codebase analysis"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Codebase analysis"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "testing" in desc_lower or "qa" in agent_id:
-                selection_map[
-                    "Testing/quality"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Testing/quality"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "documentation" in desc_lower:
-                selection_map[
-                    "Documentation"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Documentation"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "security" in desc_lower or "sast" in desc_lower:
-                selection_map[
-                    "Security operations"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Security operations"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if (
                 "deployment" in desc_lower
                 or "infrastructure" in desc_lower
                 or "ops" in agent_id
             ):
-                selection_map[
-                    "Deployment/infrastructure"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Deployment/infrastructure"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "data" in desc_lower and (
                 "pipeline" in desc_lower or "etl" in desc_lower
             ):
-                selection_map[
-                    "Data pipeline/ETL"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Data pipeline/ETL"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "git" in desc_lower or "version control" in desc_lower:
-                selection_map[
-                    "Version control"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Version control"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "ticket" in desc_lower or "epic" in desc_lower:
-                selection_map[
-                    "Ticket/issue management"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Ticket/issue management"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "browser" in desc_lower or "e2e" in desc_lower:
-                selection_map[
-                    "Browser/E2E testing"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Browser/E2E testing"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
             if "frontend" in desc_lower or "ui" in desc_lower or "html" in desc_lower:
-                selection_map[
-                    "Frontend/UI development"
-                ] = f"{agent['display_name']} (`{agent_id}`)"
+                selection_map["Frontend/UI development"] = (
+                    f"{agent['display_name']} (`{agent_id}`)"
+                )
 
         # Always include PM questions
         selection_map["PM questions"] = "Answer directly (only exception)"