claude-mpm 4.0.32__py3-none-any.whl → 4.0.34__py3-none-any.whl

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -385,12 +385,23 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             
             if use_multi_source:
                 # Use multi-source deployment to get highest version agents
-                template_files, agent_sources = self._get_multi_source_templates(
+                template_files, agent_sources, cleanup_results = self._get_multi_source_templates(
                     excluded_agents, config, agents_dir, force_rebuild
                 )
                 results["total"] = len(template_files)
                 results["multi_source"] = True
                 results["agent_sources"] = agent_sources
+                results["cleanup"] = cleanup_results
+                
+                # Log cleanup results if any agents were removed
+                if cleanup_results.get("removed"):
+                    self.logger.info(
+                        f"Cleaned up {len(cleanup_results['removed'])} outdated user agents"
+                    )
+                    for removed in cleanup_results["removed"]:
+                        self.logger.debug(
+                            f"  - Removed: {removed['name']} v{removed['version']} ({removed['reason']})"
+                        )
             else:
                 # Get and filter template files from single source
                 template_files = self._get_filtered_templates(excluded_agents, config)
@@ -516,11 +527,11 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                 return False
 
             # Ensure target directory exists
-            agents_dir = target_dir / ".claude" / "agents"
-            agents_dir.mkdir(parents=True, exist_ok=True)
+            # target_dir should already be the agents directory
+            target_dir.mkdir(parents=True, exist_ok=True)
 
             # Build and deploy the agent
-            target_file = agents_dir / f"{agent_name}.md"
+            target_file = target_dir / f"{agent_name}.md"
 
             # Check if update is needed
             if not force_rebuild and target_file.exists():
@@ -618,7 +629,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
 
         deployer = SystemInstructionsDeployer(self.logger, self.working_directory)
         deployer.deploy_system_instructions(
-            target_dir, force_rebuild, results, self._is_project_specific_deployment()
+            target_dir, force_rebuild, results
         )
 
     def deploy_system_instructions_explicit(
@@ -629,11 +640,11 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         
         This method should ONLY be called when the user explicitly requests
         deployment of system instructions through agent-manager commands.
-        It will deploy INSTRUCTIONS.md, MEMORY.md, and WORKFLOW.md to .claude-mpm/
-        directory (not .claude/).
+        It will deploy INSTRUCTIONS.md, MEMORY.md, and WORKFLOW.md to .claude/
+        directory in the project.
         
         Args:
-            target_dir: Target directory for deployment (defaults to .claude-mpm/)
+            target_dir: Target directory for deployment (ignored - always uses .claude/)
             force_rebuild: Force rebuild even if files exist
             
         Returns:
@@ -647,23 +658,19 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         }
         
         try:
-            # Use .claude-mpm/ instead of .claude/
-            if target_dir is None:
-                if self._is_project_specific_deployment():
-                    target_dir = self.working_directory / ".claude-mpm"
-                else:
-                    target_dir = Path.home() / ".claude-mpm"
+            # Always use project's .claude directory
+            target_dir = self.working_directory / ".claude"
             
             # Ensure directory exists
             target_dir.mkdir(parents=True, exist_ok=True)
             
-            # Deploy using the modified deployer (targeting .claude-mpm/)
+            # Deploy using the deployer (targeting .claude/)
             from .system_instructions_deployer import SystemInstructionsDeployer
             deployer = SystemInstructionsDeployer(self.logger, self.working_directory)
             
-            # We'll need to pass .claude-mpm as the target
-            deployer.deploy_system_instructions_to_claude_mpm(
-                target_dir, force_rebuild, results, self._is_project_specific_deployment()
+            # Deploy to .claude directory
+            deployer.deploy_system_instructions(
+                target_dir, force_rebuild, results
             )
             
             self.logger.info(
@@ -764,32 +771,9 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         """Determine the correct agents directory based on input."""
         from .agents_directory_resolver import AgentsDirectoryResolver
 
-        resolver = AgentsDirectoryResolver(
-            self.working_directory,
-            self._is_system_agent_deployment(),
-            self._is_project_specific_deployment(),
-        )
+        resolver = AgentsDirectoryResolver(self.working_directory)
         return resolver.determine_agents_directory(target_dir)
 
-    def _is_system_agent_deployment(self) -> bool:
-        """Check if this is a deployment of system agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_system_agent_deployment(self.templates_dir)
-
-    def _is_project_specific_deployment(self) -> bool:
-        """Check if deploying project-specific agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_project_specific_deployment(
-            self.templates_dir, self.working_directory
-        )
-
-    def _is_user_custom_deployment(self) -> bool:
-        """Check if deploying user custom agents."""
-        from .deployment_type_detector import DeploymentTypeDetector
-
-        return DeploymentTypeDetector.is_user_custom_deployment(self.templates_dir)
 
     def _initialize_deployment_results(
         self, agents_dir: Path, deployment_start_time: float
@@ -1125,7 +1109,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
     def _get_multi_source_templates(
         self, excluded_agents: List[str], config: Config, agents_dir: Path, 
         force_rebuild: bool = False
-    ) -> Tuple[List[Path], Dict[str, str]]:
+    ) -> Tuple[List[Path], Dict[str, str], Dict[str, Any]]:
         """Get agent templates from multiple sources with version comparison.
         
         WHY: This method uses the multi-source service to discover agents
@@ -1135,9 +1119,10 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             excluded_agents: List of agents to exclude
             config: Configuration object
             agents_dir: Target deployment directory
+            force_rebuild: Whether to force rebuild
             
         Returns:
-            Tuple of (template_files, agent_sources)
+            Tuple of (template_files, agent_sources, cleanup_results)
         """
         # Determine source directories
         system_templates_dir = self.templates_dir
@@ -1158,14 +1143,15 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             user_agents_dir = potential_user_dir
             self.logger.info(f"Found user agents at: {user_agents_dir}")
         
-        # Get agents with version comparison
-        agents_to_deploy, agent_sources = self.multi_source_service.get_agents_for_deployment(
+        # Get agents with version comparison and cleanup
+        agents_to_deploy, agent_sources, cleanup_results = self.multi_source_service.get_agents_for_deployment(
             system_templates_dir=system_templates_dir,
             project_agents_dir=project_agents_dir,
             user_agents_dir=user_agents_dir,
             working_directory=self.working_directory,
             excluded_agents=excluded_agents,
-            config=config
+            config=config,
+            cleanup_outdated=True  # Enable cleanup by default
         )
         
         # Compare with deployed versions if agents directory exists
@@ -1206,7 +1192,7 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
         # Convert to list of Path objects
         template_files = list(agents_to_deploy.values())
         
-        return template_files, agent_sources
+        return template_files, agent_sources, cleanup_results
 
     # ================================================================================
     # Interface Adapter Methods

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -148,16 +148,24 @@ class AgentTemplateBuilder:
         else:
             claude_model = "inherit"
 
-        # Determine color based on agent type
-        color_map = {
-            "engineer": "blue",
-            "qa": "green",
-            "security": "red",
-            "research": "purple",
-            "documentation": "orange",
-            "ops": "gray",
-        }
-        color = color_map.get(agent_type, "blue")
+        # Determine color - prefer template's color, fallback to type-based defaults
+        template_metadata = template_data.get("metadata", {})
+        template_color = template_metadata.get("color")
+        
+        if template_color:
+            # Use the color specified in the template
+            color = template_color
+        else:
+            # Fallback to default color map based on agent type
+            color_map = {
+                "engineer": "blue",
+                "qa": "green",
+                "security": "red",
+                "research": "purple",
+                "documentation": "cyan",  # Changed default to match template preference
+                "ops": "gray",
+            }
+            color = color_map.get(agent_type, "blue")
 
         # Check if we should include tools field (only if significantly restricting)
         # Claude Code approach: omit tools field unless specifically restricting

claude_mpm/services/agents/deployment/agents_directory_resolver.py

@@ -15,32 +15,25 @@ class AgentsDirectoryResolver:
     def __init__(
         self,
         working_directory: Path,
-        is_system_deployment: bool,
-        is_project_specific: bool,
     ):
         """
         Initialize the resolver.
 
         Args:
             working_directory: Current working directory
-            is_system_deployment: Whether this is a system agent deployment
-            is_project_specific: Whether this is a project-specific deployment
         """
         self.working_directory = working_directory
-        self.is_system_deployment = is_system_deployment
-        self.is_project_specific = is_project_specific
 
     def determine_agents_directory(self, target_dir: Optional[Path]) -> Path:
         """
         Determine the correct agents directory based on input.
-
-        Different deployment scenarios require different directory
-        structures. This method centralizes the logic for consistency.
-
-        HIERARCHY:
-        - System agents → Deploy to ~/.claude/agents/ (user's home directory)
-        - User custom agents from ~/.claude-mpm/agents/ → Deploy to ~/.claude/agents/
-        - Project-specific agents from <project>/.claude-mpm/agents/ → Deploy to <project>/.claude/agents/
+        
+        MODIFIED: Always deploy to project .claude/agents directory
+        regardless of agent source (system, user, or project).
+        
+        This ensures all agents are deployed at the project level while
+        maintaining discovery from both user (~/.claude-mpm) and project
+        (.claude-mpm) directories.
 
         Args:
             target_dir: Optional target directory
@@ -49,17 +42,9 @@ class AgentsDirectoryResolver:
             Path to agents directory
         """
         if not target_dir:
-            # Default deployment location depends on agent source
-            # Check if we're deploying system agents or user/project agents
-            if self.is_system_deployment:
-                # System agents go to user's home ~/.claude/agents/
-                return Path.home() / ".claude" / "agents"
-            elif self.is_project_specific:
-                # Project agents stay in project directory
-                return self.working_directory / ".claude" / "agents"
-            else:
-                # Default: User custom agents go to home ~/.claude/agents/
-                return Path.home() / ".claude" / "agents"
+            # Always deploy to project directory
+            # This is the key change - all agents go to project .claude/agents
+            return self.working_directory / ".claude" / "agents"
 
         # If target_dir provided, use it directly (caller decides structure)
         target_dir = Path(target_dir)

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -13,6 +13,7 @@ Key Features:
 
 import json
 import logging
+import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -190,8 +191,9 @@ class MultiSourceAgentDeploymentService:
         user_agents_dir: Optional[Path] = None,
         working_directory: Optional[Path] = None,
         excluded_agents: Optional[List[str]] = None,
-        config: Optional[Config] = None
-    ) -> Tuple[Dict[str, Path], Dict[str, str]]:
+        config: Optional[Config] = None,
+        cleanup_outdated: bool = True
+    ) -> Tuple[Dict[str, Path], Dict[str, str], Dict[str, Any]]:
         """Get the highest version agents from all sources for deployment.
         
         Args:
@@ -201,11 +203,13 @@ class MultiSourceAgentDeploymentService:
             working_directory: Current working directory for finding project agents
             excluded_agents: List of agent names to exclude from deployment
             config: Configuration object for additional filtering
+            cleanup_outdated: Whether to cleanup outdated user agents (default: True)
             
         Returns:
             Tuple of:
             - Dictionary mapping agent names to template file paths
             - Dictionary mapping agent names to their source
+            - Dictionary with cleanup results (removed, preserved, errors)
         """
         # Discover all available agents
         agents_by_name = self.discover_agents_from_all_sources(
@@ -218,6 +222,27 @@ class MultiSourceAgentDeploymentService:
         # Select highest version for each agent
         selected_agents = self.select_highest_version_agents(agents_by_name)
         
+        # Clean up outdated user agents if enabled
+        cleanup_results = {"removed": [], "preserved": [], "errors": []}
+        if cleanup_outdated:
+            # Check if cleanup is enabled in config or environment
+            cleanup_enabled = True
+            
+            # Check environment variable first (for CI/CD and testing)
+            env_cleanup = os.environ.get("CLAUDE_MPM_CLEANUP_USER_AGENTS", "").lower()
+            if env_cleanup in ["false", "0", "no", "disabled"]:
+                cleanup_enabled = False
+                self.logger.debug("User agent cleanup disabled via environment variable")
+            
+            # Check config if environment doesn't disable it
+            if cleanup_enabled and config:
+                cleanup_enabled = config.get("agent_deployment.cleanup_outdated_user_agents", True)
+            
+            if cleanup_enabled:
+                cleanup_results = self.cleanup_outdated_user_agents(
+                    agents_by_name, selected_agents
+                )
+        
         # Apply exclusion filters
         if excluded_agents:
             for agent_name in excluded_agents:
@@ -256,7 +281,168 @@ class MultiSourceAgentDeploymentService:
             f"user: {sum(1 for s in agent_sources.values() if s == 'user')})"
         )
         
-        return agents_to_deploy, agent_sources
+        return agents_to_deploy, agent_sources, cleanup_results
+    
+    def cleanup_outdated_user_agents(
+        self,
+        agents_by_name: Dict[str, List[Dict[str, Any]]],
+        selected_agents: Dict[str, Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Remove outdated user agents when project or system agents have higher versions.
+        
+        WHY: When project agents are updated to newer versions, outdated user agent
+        copies should be removed to prevent confusion and ensure the latest version
+        is always used. User agents with same or higher versions are preserved to
+        respect user customizations.
+        
+        Args:
+            agents_by_name: Dictionary mapping agent names to list of agent info from different sources
+            selected_agents: Dictionary mapping agent names to the selected highest version agent
+            
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of removed agent info
+            - preserved: List of preserved agent info with reasons
+            - errors: List of errors during cleanup
+        """
+        cleanup_results = {
+            "removed": [],
+            "preserved": [],
+            "errors": []
+        }
+        
+        # Get user agents directory
+        user_agents_dir = Path.home() / ".claude-mpm" / "agents"
+        
+        # Safety check - only operate on user agents directory
+        if not user_agents_dir.exists():
+            self.logger.debug("User agents directory does not exist, no cleanup needed")
+            return cleanup_results
+        
+        for agent_name, agent_versions in agents_by_name.items():
+            # Skip if only one version exists
+            if len(agent_versions) < 2:
+                continue
+                
+            selected = selected_agents.get(agent_name)
+            if not selected:
+                continue
+            
+            # Process each version of this agent
+            for agent_info in agent_versions:
+                # Only consider user agents for cleanup
+                if agent_info["source"] != "user":
+                    continue
+                
+                # Safety check - ensure path is within user agents directory
+                user_agent_path = Path(agent_info["path"])
+                try:
+                    # Resolve paths to compare them safely
+                    resolved_user_path = user_agent_path.resolve()
+                    resolved_user_agents_dir = user_agents_dir.resolve()
+                    
+                    # Verify the agent is actually in the user agents directory
+                    if not str(resolved_user_path).startswith(str(resolved_user_agents_dir)):
+                        self.logger.warning(
+                            f"Skipping cleanup for {agent_name}: path {user_agent_path} "
+                            f"is not within user agents directory"
+                        )
+                        cleanup_results["errors"].append({
+                            "agent": agent_name,
+                            "error": "Path outside user agents directory"
+                        })
+                        continue
+                except Exception as e:
+                    self.logger.error(f"Error resolving paths for {agent_name}: {e}")
+                    cleanup_results["errors"].append({
+                        "agent": agent_name,
+                        "error": f"Path resolution error: {e}"
+                    })
+                    continue
+                
+                # Compare versions
+                user_version = self.version_manager.parse_version(
+                    agent_info.get("version", "0.0.0")
+                )
+                selected_version = self.version_manager.parse_version(
+                    selected.get("version", "0.0.0")
+                )
+                
+                version_comparison = self.version_manager.compare_versions(
+                    user_version, selected_version
+                )
+                
+                # Determine action based on version comparison and selected source
+                if version_comparison < 0 and selected["source"] in ["project", "system"]:
+                    # User agent has lower version than selected project/system agent - remove it
+                    if user_agent_path.exists():
+                        try:
+                            # Log before removal for audit trail
+                            self.logger.info(
+                                f"Removing outdated user agent: {agent_name} "
+                                f"v{self.version_manager.format_version_display(user_version)} "
+                                f"(superseded by {selected['source']} "
+                                f"v{self.version_manager.format_version_display(selected_version)})"
+                            )
+                            
+                            # Remove the file
+                            user_agent_path.unlink()
+                            
+                            cleanup_results["removed"].append({
+                                "name": agent_name,
+                                "version": self.version_manager.format_version_display(user_version),
+                                "path": str(user_agent_path),
+                                "reason": f"Superseded by {selected['source']} v{self.version_manager.format_version_display(selected_version)}"
+                            })
+                        except PermissionError as e:
+                            error_msg = f"Permission denied removing {agent_name}: {e}"
+                            self.logger.error(error_msg)
+                            cleanup_results["errors"].append({
+                                "agent": agent_name,
+                                "error": error_msg
+                            })
+                        except Exception as e:
+                            error_msg = f"Error removing {agent_name}: {e}"
+                            self.logger.error(error_msg)
+                            cleanup_results["errors"].append({
+                                "agent": agent_name,
+                                "error": error_msg
+                            })
+                else:
+                    # Preserve the user agent
+                    if version_comparison >= 0:
+                        reason = "User version same or higher than selected version"
+                    elif selected["source"] == "user":
+                        reason = "User agent is the selected version"
+                    else:
+                        reason = "User customization preserved"
+                        
+                    cleanup_results["preserved"].append({
+                        "name": agent_name,
+                        "version": self.version_manager.format_version_display(user_version),
+                        "reason": reason
+                    })
+                    
+                    self.logger.debug(
+                        f"Preserving user agent {agent_name} "
+                        f"v{self.version_manager.format_version_display(user_version)}: {reason}"
+                    )
+        
+        # Log cleanup summary
+        if cleanup_results["removed"]:
+            self.logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} outdated user agents"
+            )
+        if cleanup_results["preserved"]:
+            self.logger.debug(
+                f"Preserved {len(cleanup_results['preserved'])} user agents"
+            )
+        if cleanup_results["errors"]:
+            self.logger.warning(
+                f"Encountered {len(cleanup_results['errors'])} errors during cleanup"
+            )
+        
+        return cleanup_results
     
     def _apply_config_filters(
         self, 

claude_mpm/services/agents/deployment/pipeline/steps/target_directory_step.py

@@ -37,8 +37,9 @@ class TargetDirectorySetupStep(BaseDeploymentStep):
                 if context.target_dir:
                     context.actual_target_dir = context.target_dir
                 else:
-                    # Default to user's home .claude/agents directory
-                    context.actual_target_dir = Path.home() / ".claude" / "agents"
+                    # MODIFIED: Default to project .claude/agents directory
+                    # All agents now deploy to the project level
+                    context.actual_target_dir = Path.cwd() / ".claude" / "agents"
 
             # Create target directory if it doesn't exist
             context.actual_target_dir.mkdir(parents=True, exist_ok=True)

claude_mpm/services/agents/deployment/strategies/system_strategy.py

@@ -63,15 +63,22 @@ class SystemAgentDeploymentStrategy(BaseDeploymentStrategy):
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for system agents.
 
-        System agents are always deployed to ~/.claude/agents/
+        MODIFIED: System agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
 
         Args:
             context: Deployment context
 
         Returns:
-            Path to ~/.claude/agents/
+            Path to <project>/.claude/agents/
         """
-        return Path.home() / ".claude" / "agents"
+        # Always deploy to project directory
+        if context.working_directory:
+            return context.working_directory / ".claude" / "agents"
+        else:
+            # Fallback to current working directory if not specified
+            return Path.cwd() / ".claude" / "agents"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for system agents.

claude_mpm/services/agents/deployment/strategies/user_strategy.py

@@ -57,26 +57,22 @@ class UserAgentDeploymentStrategy(BaseDeploymentStrategy):
     def determine_target_directory(self, context: DeploymentContext) -> Path:
         """Determine target directory for user agents.
 
-        User agents can be deployed to various user-specific locations.
+        MODIFIED: User agents are now deployed to project .claude/agents/
+        to maintain consistency with the new deployment behavior.
+        All agents (system, user, project) deploy to the project level.
 
         Args:
             context: Deployment context
 
         Returns:
-            Path to user agents directory
+            Path to <project>/.claude/agents/
         """
-        if context.target_dir:
-            return context.target_dir
-
-        # Check for user-specific environment variable
-        import os
-
-        if "CLAUDE_MPM_USER_PWD" in os.environ:
-            user_pwd = Path(os.environ["CLAUDE_MPM_USER_PWD"])
-            return user_pwd / ".claude" / "agents"
-
-        # Default to user's home directory
-        return Path.home() / ".claude-mpm" / "agents"
+        # Always deploy to project directory
+        if context.working_directory:
+            return context.working_directory / ".claude" / "agents"
+        else:
+            # Fallback to current working directory if not specified
+            return Path.cwd() / ".claude" / "agents"
 
     def get_templates_directory(self, context: DeploymentContext) -> Path:
         """Get templates directory for user agents.