claude-mpm 5.4.3__py3-none-any.whl → 5.4.14__py3-none-any.whl

claude_mpm/services/agents/toolchain_detector.py

@@ -160,11 +160,13 @@ class ToolchainDetector:
 
     # Core agents always included (use exact agent IDs from repository)
     CORE_AGENTS = [
+        "engineer",
         "qa-agent",
+        "memory-manager-agent",
+        "local-ops-agent",
         "research-agent",
         "documentation-agent",
-        "ticketing",
-        "local-ops-agent",
+        "security-agent",
     ]
 
     # Directories to exclude from scanning
@@ -366,7 +368,8 @@ class ToolchainDetector:
         """Map detected toolchain to recommended agents.
 
         Combines language-specific, framework-specific, and ops agents with
-        core agents (qa-agent, research-agent, documentation-agent, ticketing, local-ops-agent).
+        core agents (engineer, qa-agent, memory-manager-agent, local-ops-agent, research-agent,
+        documentation-agent, security-agent).
 
         Args:
             toolchain: Detected toolchain dictionary with languages, frameworks, tools

claude_mpm/services/command_deployment_service.py

@@ -23,7 +23,7 @@ class CommandDeploymentService(BaseService):
     DEPRECATED_COMMANDS = [
         "mpm-agents.md",  # Replaced by mpm-agents-list.md
         "mpm-auto-configure.md",  # Replaced by mpm-agents-auto-configure.md
-        "mpm-config.md",  # Replaced by mpm-config-view.md
+        "mpm-config-view.md",  # Replaced by mpm-config.md
         "mpm-resume.md",  # Replaced by mpm-session-resume.md
         "mpm-ticket.md",  # Replaced by mpm-ticket-view.md
     ]
@@ -314,7 +314,7 @@ class CommandDeploymentService(BaseService):
         replacement_map = {
             "mpm-agents.md": "mpm-agents-list.md",
             "mpm-auto-configure.md": "mpm-agents-auto-configure.md",
-            "mpm-config.md": "mpm-config-view.md",
+            "mpm-config-view.md": "mpm-config.md",
             "mpm-resume.md": "mpm-session-resume.md",
             "mpm-ticket.md": "mpm-ticket-view.md",
         }
@@ -343,13 +343,71 @@ class CommandDeploymentService(BaseService):
 
         return removed
 
+    def remove_stale_commands(self) -> int:
+        """Remove stale MPM commands that no longer exist in source.
+
+        This method cleans up deployed commands that have been deleted or renamed
+        in the source directory. It's called automatically on startup to ensure
+        deployed commands stay in sync with source.
+
+        Returns:
+            Number of stale files removed
+        """
+        if not self.target_dir.exists():
+            self.logger.debug(
+                f"Target directory does not exist: {self.target_dir}, skipping stale command cleanup"
+            )
+            return 0
+
+        if not self.source_dir.exists():
+            self.logger.warning(
+                f"Source directory does not exist: {self.source_dir}, cannot detect stale commands"
+            )
+            return 0
+
+        # Get current source commands (ground truth)
+        source_commands = {f.name for f in self.source_dir.glob("mpm*.md")}
+
+        # Get deployed commands
+        deployed_commands = {f.name for f in self.target_dir.glob("mpm*.md")}
+
+        # Find stale commands (deployed but not in source, excluding deprecated)
+        stale_commands = (
+            deployed_commands - source_commands - set(self.DEPRECATED_COMMANDS)
+        )
+
+        if not stale_commands:
+            self.logger.debug("No stale commands found to remove")
+            return 0
+
+        removed = 0
+        self.logger.info(f"Cleaning up {len(stale_commands)} stale command(s)...")
+
+        for stale_cmd in stale_commands:
+            stale_file = self.target_dir / stale_cmd
+            try:
+                stale_file.unlink()
+                self.logger.info(
+                    f"Removed stale command: {stale_cmd} (no longer in source)"
+                )
+                removed += 1
+            except Exception as e:
+                # Log error but don't fail startup - this is non-critical
+                self.logger.warning(f"Failed to remove stale command {stale_cmd}: {e}")
+
+        if removed > 0:
+            self.logger.info(f"Removed {removed} stale command(s)")
+
+        return removed
+
 
 def deploy_commands_on_startup(force: bool = False) -> None:
     """Convenience function to deploy commands during startup.
 
     This function:
     1. Removes deprecated commands that have been replaced
-    2. Deploys current command files
+    2. Removes stale commands that no longer exist in source
+    3. Deploys current command files
 
     Args:
         force: Force deployment even if files exist
@@ -357,12 +415,17 @@ def deploy_commands_on_startup(force: bool = False) -> None:
     service = CommandDeploymentService()
     logger = get_logger("startup")
 
-    # Clean up deprecated commands BEFORE deploying new ones
-    removed_count = service.remove_deprecated_commands()
-    if removed_count > 0:
-        logger.info(f"Cleaned up {removed_count} deprecated command(s)")
+    # Clean up deprecated commands FIRST (known old commands)
+    deprecated_count = service.remove_deprecated_commands()
+    if deprecated_count > 0:
+        logger.info(f"Cleaned up {deprecated_count} deprecated command(s)")
+
+    # Clean up stale commands SECOND (deployed but not in source anymore)
+    stale_count = service.remove_stale_commands()
+    if stale_count > 0:
+        logger.info(f"Cleaned up {stale_count} stale command(s)")
 
-    # Deploy current commands
+    # Deploy current commands LAST
     result = service.deploy_commands(force=force)
 
     if result["deployed"]:

claude_mpm/services/git/git_operations_service.py

@@ -18,10 +18,13 @@ Example:
     ...     service.commit(Path("~/.claude-mpm/cache/remote-agents"), "feat: improve research agent memory handling")
 """
 
+import logging
 import subprocess
 from pathlib import Path
 from typing import List, Optional, Tuple
 
+logger = logging.getLogger(__name__)
+
 
 # Custom Exceptions
 class GitOperationError(Exception):
@@ -314,7 +317,12 @@ class GitOperationsService:
 
     def pull(self, repo_path: Path, branch: str = "main") -> bool:
         """
-        Pull latest changes from remote.
+        Pull latest changes from remote with automatic divergent branch recovery.
+
+        For cache/sync repositories, automatically handles divergent branches by:
+        1. First attempting git pull --rebase (cleaner history)
+        2. If rebase fails or conflicts exist, hard reset to match remote exactly
+           (cache repos should mirror remote state, local changes are discarded)
 
         Args:
             repo_path: Repository path
@@ -325,21 +333,98 @@ class GitOperationsService:
 
         Raises:
             GitOperationError: If pull fails
-            GitConflictError: If merge conflicts detected
+            GitConflictError: If merge conflicts detected and cannot be auto-resolved
         """
         self._validate_repo(repo_path)
 
+        # First, try standard pull
         returncode, _stdout, stderr = self._run_git_command(
             ["git", "pull", "origin", branch], cwd=repo_path
         )
 
-        if returncode != 0:
-            # Check for merge conflicts
-            if "conflict" in stderr.lower():
-                raise GitConflictError(
-                    f"Merge conflicts detected when pulling {branch}: {stderr}"
+        if returncode == 0:
+            return True
+
+        # Check if this is a divergent branch situation
+        is_divergent = any(
+            phrase in stderr.lower()
+            for phrase in [
+                "divergent branches",
+                "need to specify how to reconcile",
+                "have diverged",
+            ]
+        )
+
+        if is_divergent:
+            logger.warning(
+                f"Divergent branches detected in cache repository at {repo_path}. "
+                "Attempting automatic recovery with rebase..."
+            )
+
+            # Strategy 1: Try rebase for cleaner history
+            returncode, _stdout, stderr = self._run_git_command(
+                ["git", "pull", "--rebase", "origin", branch], cwd=repo_path
+            )
+
+            if returncode == 0:
+                logger.info(
+                    f"Successfully resolved divergent branches with rebase for {branch}"
+                )
+                return True
+
+            # Check if rebase had conflicts
+            has_rebase_conflict = any(
+                phrase in stderr.lower()
+                for phrase in ["conflict", "rebase in progress"]
+            )
+
+            if has_rebase_conflict:
+                logger.warning(
+                    "Rebase conflicts detected. Aborting rebase and resetting to remote state..."
                 )
-            raise GitOperationError(f"Failed to pull {branch}: {stderr}")
+                # Abort the rebase
+                self._run_git_command(["git", "rebase", "--abort"], cwd=repo_path)
+
+            # Strategy 2: Hard reset to match remote exactly (cache repos should mirror remote)
+            logger.warning(
+                f"Discarding local changes and resetting to origin/{branch} "
+                "(cache repositories should match remote exactly)"
+            )
+
+            # Fetch latest to ensure we have the remote state
+            returncode, _stdout, stderr = self._run_git_command(
+                ["git", "fetch", "origin", branch], cwd=repo_path
+            )
+
+            if returncode != 0:
+                raise GitOperationError(
+                    f"Failed to fetch from remote during divergent branch recovery: {stderr}"
+                )
+
+            # Hard reset to remote branch
+            returncode, _stdout, stderr = self._run_git_command(
+                ["git", "reset", "--hard", f"origin/{branch}"], cwd=repo_path
+            )
+
+            if returncode != 0:
+                raise GitOperationError(
+                    f"Failed to reset to origin/{branch} during divergent branch recovery: {stderr}"
+                )
+
+            logger.info(
+                f"Successfully reset cache repository to origin/{branch} "
+                "(local changes discarded)"
+            )
+            return True
+
+        # Check for merge conflicts (non-divergent case)
+        if "conflict" in stderr.lower():
+            raise GitConflictError(
+                f"Merge conflicts detected when pulling {branch}: {stderr}"
+            )
+
+        # Other pull errors
+        raise GitOperationError(f"Failed to pull {branch}: {stderr}")
 
         return True
 

claude_mpm/services/self_upgrade_service.py

@@ -3,7 +3,7 @@ Self-Upgrade Service
 ====================
 
 Handles version checking and self-upgrade functionality for claude-mpm.
-Supports pip, pipx, and npm installations with automatic detection.
+Supports pip, pipx, npm, uv tool, and Homebrew installations with automatic detection.
 Also checks Claude Code version compatibility.
 
 WHY: Users should be notified of updates and have an easy way to upgrade
@@ -11,7 +11,7 @@ without manually running installation commands. Claude Code version checking
 ensures compatibility with required features.
 
 DESIGN DECISIONS:
-- Detects installation method (pip/pipx/npm/editable)
+- Detects installation method (pip/pipx/npm/uv_tool/homebrew/editable)
 - Non-blocking version checks with caching
 - Interactive upgrade prompts with confirmation
 - Automatic restart after upgrade
@@ -40,6 +40,8 @@ class InstallationMethod:
     PIP = "pip"
     PIPX = "pipx"
     NPM = "npm"
+    UV_TOOL = "uv_tool"
+    HOMEBREW = "homebrew"
     EDITABLE = "editable"
     UNKNOWN = "unknown"
 
@@ -95,6 +97,14 @@ class SelfUpgradeService:
         """
         Detect how claude-mpm was installed.
 
+        Detection priority:
+        1. Editable (skip auto-upgrade)
+        2. UV Tool
+        3. Homebrew
+        4. Pipx
+        5. NPM
+        6. Pip (default)
+
         Returns:
             Installation method constant
         """
@@ -105,6 +115,14 @@ class SelfUpgradeService:
         ]:
             return InstallationMethod.EDITABLE
 
+        # Check for UV tool installation
+        if self._check_uv_tool_installation():
+            return InstallationMethod.UV_TOOL
+
+        # Check for Homebrew installation
+        if self._check_homebrew_installation():
+            return InstallationMethod.HOMEBREW
+
         # Check for pipx by looking at executable path
         executable = sys.executable
         if "pipx" in executable:
@@ -127,6 +145,85 @@ class SelfUpgradeService:
         # Default to pip
         return InstallationMethod.PIP
 
+    def _check_uv_tool_installation(self) -> bool:
+        """
+        Check if claude-mpm is installed via uv tool.
+
+        Detection methods:
+        1. Check UV_TOOL_DIR environment variable
+        2. Check if executable path contains .local/share/uv/tools/
+        3. Fallback: Run `uv tool list` and check for claude-mpm
+
+        Returns:
+            True if UV tool installation detected
+        """
+        # Method 1: Check UV_TOOL_DIR environment variable
+        uv_tool_dir = os.environ.get("UV_TOOL_DIR")
+        if uv_tool_dir and "claude-mpm" in uv_tool_dir:
+            return True
+
+        # Method 2: Check executable path
+        executable = sys.executable
+        if ".local/share/uv/tools/" in executable or "uv/tools/" in executable:
+            return True
+
+        # Method 3: Fallback to `uv tool list` command
+        try:
+            result = subprocess.run(
+                ["uv", "tool", "list"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0 and "claude-mpm" in result.stdout:
+                return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            # uv not installed or command failed
+            pass
+        except Exception as e:
+            self.logger.debug(f"UV tool check failed: {e}")
+
+        return False
+
+    def _check_homebrew_installation(self) -> bool:
+        """
+        Check if claude-mpm is installed via Homebrew.
+
+        Detection methods:
+        1. Check if executable path starts with /opt/homebrew/ or /usr/local/Cellar/
+        2. Fallback: Run `brew list claude-mpm` to verify
+
+        Returns:
+            True if Homebrew installation detected
+        """
+        # Method 1: Check executable path
+        executable = sys.executable
+        if executable.startswith("/opt/homebrew/") or executable.startswith(
+            "/usr/local/Cellar/"
+        ):
+            return True
+
+        # Method 2: Fallback to `brew list` command
+        try:
+            result = subprocess.run(
+                ["brew", "list", "claude-mpm"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            # brew list returns 0 if package is installed
+            if result.returncode == 0:
+                return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            # brew not installed or command failed
+            pass
+        except Exception as e:
+            self.logger.debug(f"Homebrew check failed: {e}")
+
+        return False
+
     def _get_claude_code_version(self) -> Optional[str]:
         """
         Get the installed Claude Code version.
@@ -257,6 +354,8 @@ class SelfUpgradeService:
         if self.installation_method in [
             InstallationMethod.PIP,
             InstallationMethod.PIPX,
+            InstallationMethod.UV_TOOL,
+            InstallationMethod.HOMEBREW,
         ]:
             result = await self.version_checker.check_for_update(
                 "claude-mpm", self.current_version, cache_ttl
@@ -313,15 +412,18 @@ class SelfUpgradeService:
         Returns:
             Shell command string to upgrade claude-mpm
         """
-        if self.installation_method == InstallationMethod.PIPX:
-            return "pipx upgrade claude-mpm"
-        if self.installation_method == InstallationMethod.NPM:
-            return "npm update -g claude-mpm"
-        if self.installation_method == InstallationMethod.PIP:
-            return f"{sys.executable} -m pip install --upgrade claude-mpm"
-        if self.installation_method == InstallationMethod.EDITABLE:
-            return "git pull && pip install -e ."
-        return "pip install --upgrade claude-mpm"
+        upgrade_commands = {
+            InstallationMethod.UV_TOOL: "uv tool upgrade claude-mpm",
+            InstallationMethod.HOMEBREW: "brew upgrade claude-mpm",
+            InstallationMethod.PIPX: "pipx upgrade claude-mpm",
+            InstallationMethod.NPM: "npm update -g claude-mpm",
+            InstallationMethod.PIP: f"{sys.executable} -m pip install --upgrade claude-mpm",
+            InstallationMethod.EDITABLE: "git pull && pip install -e .",
+        }
+
+        return upgrade_commands.get(
+            self.installation_method, "pip install --upgrade claude-mpm"
+        )
 
     def prompt_for_upgrade(self, update_info: Dict[str, any]) -> bool:
         """
@@ -432,7 +534,13 @@ class SelfUpgradeService:
             args = sys.argv[:]
 
             # Replace current process with new one
-            if self.installation_method == InstallationMethod.PIPX:
+            if self.installation_method == InstallationMethod.UV_TOOL:
+                # Use uv run
+                os.execvp("uv", ["uv", "tool", "run", "claude-mpm", *args[1:]])
+            elif self.installation_method == InstallationMethod.HOMEBREW:
+                # Use direct executable (installed to PATH by Homebrew)
+                os.execvp("claude-mpm", args)
+            elif self.installation_method == InstallationMethod.PIPX:
                 # Use pipx run
                 os.execvp("pipx", ["pipx", "run", "claude-mpm", *args[1:]])
             elif self.installation_method == InstallationMethod.NPM:

claude_mpm/services/skills/__init__.py

@@ -3,6 +3,7 @@
 This package provides services for Git-based skills management:
 - GitSkillSourceManager: Multi-repository orchestration with priority resolution
 - SkillDiscoveryService: Parse skills from Git repositories (Markdown with YAML frontmatter)
+- SkillToAgentMapper: Map skills to agents using YAML configuration
 """
 
 from claude_mpm.services.skills.git_skill_source_manager import GitSkillSourceManager
@@ -10,9 +11,11 @@ from claude_mpm.services.skills.skill_discovery_service import (
     SkillDiscoveryService,
     SkillMetadata,
 )
+from claude_mpm.services.skills.skill_to_agent_mapper import SkillToAgentMapper
 
 __all__ = [
     "GitSkillSourceManager",
     "SkillDiscoveryService",
     "SkillMetadata",
+    "SkillToAgentMapper",
 ]

claude_mpm/services/skills/git_skill_source_manager.py

@@ -20,7 +20,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone
 from pathlib import Path
 from threading import Lock
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 from claude_mpm.config.skill_sources import SkillSource, SkillSourceConfiguration
 from claude_mpm.core.logging_config import get_logger
@@ -989,6 +989,7 @@ class GitSkillSourceManager:
         target_dir: Optional[Path] = None,
         force: bool = False,
         progress_callback=None,
+        skill_filter: Optional[Set[str]] = None,
     ) -> Dict[str, Any]:
         """Deploy skills from cache to target directory with flat structure.
 
@@ -1004,6 +1005,9 @@ class GitSkillSourceManager:
             target_dir: Target deployment directory (default: ~/.claude/skills/)
             force: Overwrite existing skills
             progress_callback: Optional callback(increment: int) called for each skill deployed
+            skill_filter: Optional set of skill names to deploy (selective deployment).
+                         If None, deploys all skills. If provided, only deploys skills
+                         whose name matches an entry in the filter set.
 
         Returns:
             Dict with deployment results:
@@ -1013,13 +1017,19 @@ class GitSkillSourceManager:
                 "failed_count": int,
                 "deployed_skills": List[str],
                 "skipped_skills": List[str],
-                "errors": List[str]
+                "errors": List[str],
+                "filtered_count": int  # Number of skills filtered out
             }
 
         Example:
             >>> manager = GitSkillSourceManager(config)
             >>> result = manager.deploy_skills()
             >>> print(f"Deployed {result['deployed_count']} skills")
+
+            # Selective deployment based on agent requirements:
+            >>> required = {"typescript-core", "react-patterns"}
+            >>> result = manager.deploy_skills(skill_filter=required)
+            >>> print(f"Deployed {result['deployed_count']} of {len(required)} required skills")
         """
         if target_dir is None:
             target_dir = Path.home() / ".claude" / "skills"
@@ -1029,10 +1039,29 @@ class GitSkillSourceManager:
         deployed = []
         skipped = []
         errors = []
+        filtered_count = 0
 
         # Get all skills from all sources
         all_skills = self.get_all_skills()
 
+        # Apply skill filter if provided (selective deployment)
+        if skill_filter is not None:
+            original_count = len(all_skills)
+            # Normalize filter to lowercase for case-insensitive matching
+            normalized_filter = {s.lower() for s in skill_filter}
+            # Match against deployment_name (not display name) since skill_filter contains
+            # deployment-style names like "toolchains-python-frameworks-django"
+            all_skills = [
+                s
+                for s in all_skills
+                if s.get("deployment_name", "").lower() in normalized_filter
+            ]
+            filtered_count = original_count - len(all_skills)
+            self.logger.info(
+                f"Selective deployment: {len(all_skills)} of {original_count} skills "
+                f"match agent requirements ({filtered_count} filtered out)"
+            )
+
         self.logger.info(
             f"Deploying {len(all_skills)} skills to {target_dir} (force={force})"
         )
@@ -1083,6 +1112,7 @@ class GitSkillSourceManager:
             "deployed_skills": deployed,
             "skipped_skills": skipped,
             "errors": errors,
+            "filtered_count": filtered_count,
         }
 
     def _deploy_single_skill(