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

claude_mpm/init.py

@@ -141,25 +141,6 @@ class ProjectInitializer:
             if not gitignore.exists():
                 gitignore.write_text("logs/\n*.log\n*.pyc\n__pycache__/\n")
 
-            # Also ensure MCP directories are in main project .gitignore
-            try:
-                from claude_mpm.services.project.project_organizer import (
-                    ProjectOrganizer,
-                )
-
-                # Check if we're in a git repository
-                if (project_root / ".git").exists():
-                    organizer = ProjectOrganizer(project_root)
-                    # This will add MCP directories and other standard patterns
-                    organizer.update_gitignore()
-                    self.logger.debug(
-                        "Updated project .gitignore with MCP and standard patterns"
-                    )
-            except Exception as e:
-                self.logger.debug(
-                    f"Could not update project gitignore with MCP patterns: {e}"
-                )
-
             # Log successful creation with details
             self.logger.info(f"Initialized project directory at {self.project_dir}")
             self.logger.debug("Created directories: agents, config, responses, logs")

claude_mpm/scripts/claude-hook-handler.sh

@@ -88,18 +88,21 @@ fi
 #
 # STRATEGY:
 # This function implements a fallback chain to find Python with claude-mpm dependencies:
-# 1. Project-specific virtual environments (venv, .venv)
-# 2. Currently active virtual environment ($VIRTUAL_ENV)
-# 3. System python3 (may lack dependencies)
-# 4. System python (last resort)
+# 1. UV-managed projects (uv.lock detected) - uses "uv run python"
+# 2. pipx installations - uses pipx venv Python
+# 3. Project-specific virtual environments (venv, .venv)
+# 4. Currently active virtual environment ($VIRTUAL_ENV)
+# 5. System python3 (may lack dependencies)
+# 6. System python (last resort)
 #
 # WHY THIS APPROACH:
 # - Claude MPM requires specific packages (socketio, eventlet) not in system Python
-# - Virtual environments ensure dependency isolation and availability
+# - UV and virtual environments ensure dependency isolation and availability
 # - Multiple naming conventions supported (venv vs .venv)
 # - Graceful degradation to system Python if no venv found
 #
 # ACTIVATION STRATEGY:
+# - UV projects: use "uv run python" to execute in UV-managed environment
 # - Sources activate script to set up environment variables
 # - Returns specific Python path for exec (not just 'python')
 # - Maintains environment in same shell process
@@ -110,10 +113,18 @@ fi
 # - Caches result in process environment
 #
 # RETURNS:
-# Absolute path to Python executable with claude-mpm dependencies
+# Absolute path to Python executable with claude-mpm dependencies, or "uv run python" for UV projects
 #
 find_python_command() {
-    # 1. Check if we're in a pipx installation first
+    # 1. Check for UV project first (uv.lock or pyproject.toml with uv)
+    if [ -f "$CLAUDE_MPM_ROOT/uv.lock" ]; then
+        if command -v uv &> /dev/null; then
+            echo "uv run python"
+            return
+        fi
+    fi
+
+    # 2. Check if we're in a pipx installation
     if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
         # pipx installation - use the pipx venv's Python directly
         if [ -f "$CLAUDE_MPM_ROOT/bin/python" ]; then
@@ -122,7 +133,7 @@ find_python_command() {
         fi
     fi
 
-    # 2. Check for project-local virtual environment (common in development)
+    # 3. Check for project-local virtual environment (common in development)
     if [ -f "$CLAUDE_MPM_ROOT/venv/bin/activate" ]; then
         source "$CLAUDE_MPM_ROOT/venv/bin/activate"
         echo "$CLAUDE_MPM_ROOT/venv/bin/python"
@@ -173,15 +184,44 @@ fi
 # Set Socket.IO configuration for hook events
 export CLAUDE_MPM_SOCKETIO_PORT="${CLAUDE_MPM_SOCKETIO_PORT:-8765}"
 
-# Run the Python hook handler with all input
-# Use exec to replace the shell process with Python
-if ! exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log; then
-    # If the Python handler fails, always return continue to not block Claude
+# Function for debug logging
+log_debug() {
     if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
-        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
-        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] $1" >> /tmp/claude-mpm-hook.log
+    fi
+}
+
+# Test Python works and module exists
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    if ! uv run python -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
+    fi
+else
+    if ! $PYTHON_CMD -c "import claude_mpm" 2>/dev/null; then
+        log_debug "claude_mpm module not available, continuing without hook"
+        echo '{"action": "continue"}'
+        exit 0
     fi
-    # Return continue action to prevent blocking Claude Code
-    echo '{"action": "continue"}'
-    exit 0
-fi
+fi
+
+# Run the Python hook handler with all input
+# Use exec to replace the shell process with Python
+# Handle UV's multi-word command specially
+if [[ "$PYTHON_CMD" == "uv run python" ]]; then
+    exec uv run python -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+else
+    exec "$PYTHON_CMD" -m claude_mpm.hooks.claude_hooks.hook_handler "$@" 2>/tmp/claude-mpm-hook-error.log
+fi
+
+# Note: exec replaces the shell process, so code below only runs if exec fails
+# If we reach here, the Python handler failed
+if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Hook handler failed, see /tmp/claude-mpm-hook-error.log" >> /tmp/claude-mpm-hook.log
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] Error: $(cat /tmp/claude-mpm-hook-error.log 2>/dev/null | head -5)" >> /tmp/claude-mpm-hook.log
+fi
+# Return continue action to prevent blocking Claude Code
+echo '{"action": "continue"}'
+exit 0

claude_mpm/services/agents/agent_recommendation_service.py

@@ -9,8 +9,8 @@ to specific engineer agents, plus always includes core agents.
 
 Architecture:
 - Toolchain-based recommendations: Python → python-engineer, etc.
-- Core agents (always recommended): qa-agent, research-agent, documentation-agent,
-  ticketing, local-ops-agent, version-control, security
+- Core agents (always recommended): engineer, qa-agent, memory-manager-agent, local-ops-agent,
+  research-agent, documentation-agent, security-agent
 - Confidence-based filtering: Only recommend high-confidence detections
 """
 
@@ -33,14 +33,13 @@ class AgentRecommendationService:
     # Core agents always included - matches ToolchainDetector.CORE_AGENTS
     # Uses exact agent IDs from repository for consistency
     CORE_AGENTS = {
+        "engineer",
         "qa-agent",
+        "memory-manager-agent",
+        "local-ops-agent",
         "research-agent",
         "documentation-agent",
-        "ticketing",
-        "local-ops-agent",
-        # Keep version-control and security as universal recommended agents
-        "version-control",
-        "security",
+        "security-agent",
     }
 
     # Map detected languages to recommended engineer agents

claude_mpm/services/agents/agent_review_service.py

@@ -0,0 +1,280 @@
+"""Agent review service for comparing project agents with managed agents.
+
+WHY: This service helps users maintain a clean agent directory by:
+1. Identifying which agents are managed vs custom
+2. Detecting outdated versions of managed agents
+3. Finding unused agents that don't match the detected toolchain
+4. Safely archiving unnecessary agents instead of deleting them
+
+DESIGN DECISIONS:
+- Archive to .claude/agents/unused/ instead of deleting (safe, recoverable)
+- Add timestamps to archived files to prevent conflicts
+- Preserve custom user agents (not in managed set)
+- Compare versions to detect outdated managed agents
+"""
+
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from claude_mpm.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentReviewService:
+    """Service for reviewing and managing project agents.
+
+    This service analyzes the relationship between project agents and managed
+    agents from the claude-mpm-agents repository, categorizing them as:
+    - Managed: In sync with managed agents
+    - Outdated: Older version of managed agent exists
+    - Custom: User-created agents not in managed set
+    - Unused: Not recommended for this project's toolchain
+    """
+
+    def __init__(self):
+        """Initialize the agent review service."""
+        self.logger = get_logger(__name__)
+
+    def review_project_agents(
+        self,
+        project_agents_dir: Path,
+        managed_agents: List[Dict[str, Any]],
+        recommended_agent_ids: Set[str],
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """Review existing project agents and categorize them.
+
+        Args:
+            project_agents_dir: Directory containing project agents (.claude/agents/)
+            managed_agents: List of managed agent dicts from cache
+            recommended_agent_ids: Set of agent IDs recommended for this toolchain
+
+        Returns:
+            Dictionary with categorized agents:
+            {
+                "managed": [...],      # In sync with managed
+                "outdated": [...],     # Older version exists
+                "custom": [...],       # User-created
+                "unused": [...],       # Not needed for this toolchain
+            }
+        """
+        results = {
+            "managed": [],
+            "outdated": [],
+            "custom": [],
+            "unused": [],
+        }
+
+        if not project_agents_dir.exists():
+            self.logger.debug(
+                f"Project agents directory does not exist: {project_agents_dir}"
+            )
+            return results
+
+        # Build lookup map of managed agents by ID
+        managed_by_id = {agent["agent_id"]: agent for agent in managed_agents}
+
+        # Scan project agents
+        for agent_file in project_agents_dir.glob("*.md"):
+            # Skip the unused directory itself
+            if agent_file.name == "unused":
+                continue
+
+            agent_name = agent_file.stem
+
+            # Parse agent to get version and metadata
+            project_agent_info = self._parse_project_agent(agent_file)
+
+            # Check if this is a managed agent
+            if agent_name in managed_by_id:
+                managed_agent = managed_by_id[agent_name]
+
+                # Compare versions
+                project_version = project_agent_info.get("version", "unknown")
+                managed_version = managed_agent.get("version", "unknown")
+
+                if self._is_outdated(project_version, managed_version):
+                    # Outdated version of managed agent
+                    results["outdated"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "current_version": project_version,
+                            "available_version": managed_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+                else:
+                    # Up-to-date managed agent
+                    results["managed"].append(
+                        {
+                            "name": agent_name,
+                            "path": agent_file,
+                            "version": project_version,
+                            "recommended": agent_name in recommended_agent_ids,
+                        }
+                    )
+            else:
+                # Custom user agent (not in managed set)
+                results["custom"].append(
+                    {
+                        "name": agent_name,
+                        "path": agent_file,
+                        "version": project_agent_info.get("version", "unknown"),
+                    }
+                )
+
+        # Identify unused agents (managed or outdated but not recommended)
+        for category in ["managed", "outdated"]:
+            for agent in results[category][:]:  # Copy list to modify during iteration
+                if not agent.get("recommended", False):
+                    # This managed/outdated agent is not recommended for this toolchain
+                    results["unused"].append(agent)
+                    results[category].remove(agent)
+
+        self.logger.info(
+            f"Agent review complete: "
+            f"{len(results['managed'])} managed, "
+            f"{len(results['outdated'])} outdated, "
+            f"{len(results['custom'])} custom, "
+            f"{len(results['unused'])} unused"
+        )
+
+        return results
+
+    def archive_agents(
+        self, agents_to_archive: List[Dict[str, Any]], project_agents_dir: Path
+    ) -> Dict[str, Any]:
+        """Archive agents by moving them to .claude/agents/unused/.
+
+        Args:
+            agents_to_archive: List of agent dicts with 'name' and 'path' keys
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archival results:
+            {
+                "archived": [...],  # Successfully archived
+                "errors": [...],    # Archival errors
+            }
+        """
+        results = {"archived": [], "errors": []}
+
+        if not agents_to_archive:
+            return results
+
+        # Create unused directory
+        unused_dir = project_agents_dir / "unused"
+        unused_dir.mkdir(exist_ok=True)
+
+        for agent in agents_to_archive:
+            agent_path = agent["path"]
+            agent_name = agent["name"]
+
+            try:
+                # Generate timestamped filename to avoid conflicts
+                timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+                archived_name = f"{agent_name}_{timestamp}.md"
+                archived_path = unused_dir / archived_name
+
+                # Move the file
+                shutil.move(str(agent_path), str(archived_path))
+
+                results["archived"].append(
+                    {
+                        "name": agent_name,
+                        "original_path": str(agent_path),
+                        "archived_path": str(archived_path),
+                    }
+                )
+
+                self.logger.debug(f"Archived {agent_name} to {archived_path}")
+
+            except Exception as e:
+                error_msg = f"Failed to archive {agent_name}: {e}"
+                self.logger.error(error_msg)
+                results["errors"].append(error_msg)
+
+        self.logger.info(
+            f"Archived {len(results['archived'])} agents, "
+            f"{len(results['errors'])} errors"
+        )
+
+        return results
+
+    def _parse_project_agent(self, agent_file: Path) -> Dict[str, Any]:
+        """Parse a project agent file to extract metadata.
+
+        Args:
+            agent_file: Path to agent Markdown file
+
+        Returns:
+            Dictionary with agent metadata (version, name, etc.)
+        """
+        try:
+            content = agent_file.read_text(encoding="utf-8")
+
+            # Extract version from YAML frontmatter
+            import re
+
+            version_match = re.search(
+                r'^version:\s*["\']?(.+?)["\']?$', content, re.MULTILINE
+            )
+            version = version_match.group(1) if version_match else "unknown"
+
+            return {
+                "version": version,
+                "name": agent_file.stem,
+            }
+
+        except Exception as e:
+            self.logger.warning(f"Failed to parse agent {agent_file.name}: {e}")
+            return {"version": "unknown", "name": agent_file.stem}
+
+    def _is_outdated(self, current_version: str, available_version: str) -> bool:
+        """Check if current version is outdated compared to available version.
+
+        Args:
+            current_version: Currently deployed version
+            available_version: Available version from managed agents
+
+        Returns:
+            True if current version is outdated
+        """
+        # Handle unknown versions
+        if current_version == "unknown" or available_version == "unknown":
+            return False
+
+        # Simple string comparison for now
+        # TODO: Implement semantic version comparison (1.2.3 vs 1.2.4)
+        return current_version != available_version
+
+    def get_archive_summary(self, project_agents_dir: Path) -> Dict[str, Any]:
+        """Get summary of archived agents.
+
+        Args:
+            project_agents_dir: Base agents directory (.claude/agents/)
+
+        Returns:
+            Dictionary with archive statistics
+        """
+        unused_dir = project_agents_dir / "unused"
+
+        if not unused_dir.exists():
+            return {"count": 0, "agents": []}
+
+        archived_files = list(unused_dir.glob("*.md"))
+
+        return {
+            "count": len(archived_files),
+            "agents": [
+                {
+                    "name": f.stem,
+                    "path": str(f),
+                    "size_bytes": f.stat().st_size,
+                }
+                for f in archived_files
+            ],
+        }

claude_mpm/services/agents/deployment/agent_discovery_service.py

@@ -215,9 +215,8 @@ class AgentDiscoveryService:
             # Extract YAML frontmatter
             frontmatter = self._extract_yaml_frontmatter(template_content)
             if not frontmatter:
-                self.logger.warning(
-                    f"No valid YAML frontmatter in {template_file.name}"
-                )
+                # Silently return None for files without frontmatter
+                # (e.g., PM instruction templates in templates/ directory)
                 return None
 
             # Extract metadata directly from frontmatter (flat structure)

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -676,6 +676,7 @@ Only include memories that are:
 """
             content = content + memory_instructions
 
+        # Combine frontmatter and content
         return frontmatter + content
 
     def build_agent_yaml(

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -16,6 +16,8 @@ import os
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+import yaml
+
 from claude_mpm.core.config import Config
 from claude_mpm.core.logging_config import get_logger
 
@@ -51,6 +53,70 @@ class MultiSourceAgentDeploymentService:
         self.logger = get_logger(__name__)
         self.version_manager = AgentVersionManager()
 
+    def _read_template_version(self, template_path: Path) -> Optional[str]:
+        """Read version from template file (supports both .md and .json formats).
+
+        For .md files: Extract version from YAML frontmatter
+        For .json files: Extract version from JSON structure
+
+        Args:
+            template_path: Path to template file
+
+        Returns:
+            Version string or None if version cannot be extracted
+        """
+        try:
+            if template_path.suffix == ".md":
+                # Parse markdown with YAML frontmatter
+                content = template_path.read_text()
+
+                # Extract YAML frontmatter (between --- markers)
+                if not content.strip().startswith("---"):
+                    return None
+
+                parts = content.split("---", 2)
+                if len(parts) < 3:
+                    return None
+
+                # Parse YAML frontmatter
+                frontmatter = yaml.safe_load(parts[1])
+                if not frontmatter:
+                    return None
+
+                # Extract version from frontmatter
+                version = frontmatter.get("version")
+                return version if version else None
+
+            if template_path.suffix == ".json":
+                # Parse JSON template
+                template_data = json.loads(template_path.read_text())
+                metadata = template_data.get("metadata", {})
+                version = (
+                    template_data.get("agent_version")
+                    or template_data.get("version")
+                    or metadata.get("version")
+                )
+                return version if version else None
+
+            self.logger.warning(
+                f"Unknown template format: {template_path.suffix} for {template_path.name}"
+            )
+            return None
+
+        except yaml.YAMLError as e:
+            self.logger.warning(
+                f"Invalid YAML frontmatter in {template_path.name}: {e}"
+            )
+            return None
+        except json.JSONDecodeError as e:
+            self.logger.warning(f"Invalid JSON in {template_path.name}: {e}")
+            return None
+        except Exception as e:
+            self.logger.warning(
+                f"Error reading template version from {template_path.name}: {e}"
+            )
+            return None
+
     def _build_canonical_id_for_agent(self, agent_info: Dict[str, Any]) -> str:
         """Build or retrieve canonical_id for an agent.
 
@@ -827,17 +893,20 @@ class MultiSourceAgentDeploymentService:
                 comparison_results["needs_update"].append(agent_name)
                 continue
 
-            # Read template version
-            try:
-                template_data = json.loads(template_path.read_text())
-                metadata = template_data.get("metadata", {})
-                template_version = self.version_manager.parse_version(
-                    template_data.get("agent_version")
-                    or template_data.get("version")
-                    or metadata.get("version", "0.0.0")
+            # Read template version using format-aware helper
+            version_string = self._read_template_version(template_path)
+            if not version_string:
+                self.logger.warning(
+                    f"Could not extract version from template for '{agent_name}', skipping"
                 )
+                continue
+
+            try:
+                template_version = self.version_manager.parse_version(version_string)
             except Exception as e:
-                self.logger.warning(f"Error reading template for '{agent_name}': {e}")
+                self.logger.warning(
+                    f"Error parsing version '{version_string}' for '{agent_name}': {e}"
+                )
                 continue
 
             # Read deployed version

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -464,9 +464,22 @@ class RemoteAgentDiscoveryService:
             "AUTO-DEPLOY-INDEX.md",
             "PHASE1_COMPLETE.md",
             "AGENTS.md",
+            # Skill-related files (should not be treated as agents)
+            "SKILL.md",
+            "SKILLS.md",
+            "skill-template.md",
         }
         md_files = [f for f in md_files if f.name not in excluded_files]
 
+        # Filter out files from skills-related directories
+        # Skills are not agents and should not be discovered here
+        excluded_directory_patterns = {"references", "examples", "claude-mpm-skills"}
+        md_files = [
+            f
+            for f in md_files
+            if not any(excluded in f.parts for excluded in excluded_directory_patterns)
+        ]
+
         # In flattened cache mode, also exclude files from git repository subdirectories
         # (files under directories that contain .git folder)
         if scan_dir == self.remote_agents_dir:

claude_mpm/services/agents/git_source_manager.py

@@ -351,6 +351,12 @@ class GitSourceManager:
                 "claude-mpm",
             }
 
+            # Repositories that are NOT agent repositories (should be excluded from agent discovery)
+            # These contain skills, documentation, or other non-agent content
+            EXCLUDED_REPOSITORIES = {
+                "claude-mpm-skills",  # Skills repository, not agents
+            }
+
             for owner_dir in self.cache_root.iterdir():
                 if not owner_dir.is_dir():
                     continue
@@ -367,6 +373,14 @@ class GitSourceManager:
                 for repo_dir in owner_dir.iterdir():
                     if not repo_dir.is_dir():
                         continue
+
+                    # Skip excluded repositories (e.g., skills repos are not agent repos)
+                    if repo_dir.name in EXCLUDED_REPOSITORIES:
+                        logger.debug(
+                            f"[DEBUG] Skipping excluded repository: {repo_dir.name}"
+                        )
+                        continue
+
                     logger.debug(f"[DEBUG] Processing repo_dir: {repo_dir.name}")
 
                     # Bug #5 fix: Don't iterate subdirectories - RemoteAgentDiscoveryService

claude_mpm/services/agents/loading/base_agent_manager.py

@@ -13,9 +13,6 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-# Lazy import for base_agent_loader to reduce initialization overhead
-# base_agent_loader adds ~500ms to import time
-# from claude_mpm.agents.base_agent_loader import clear_base_agent_cache
 from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 from claude_mpm.services.shared import ConfigServiceBase
@@ -23,13 +20,6 @@ from claude_mpm.services.shared import ConfigServiceBase
 logger = get_logger(__name__)
 
 
-def _get_clear_base_agent_cache():
-    """Lazy loader for clear_base_agent_cache function."""
-    from claude_mpm.agents.base_agent_loader import clear_base_agent_cache
-
-    return clear_base_agent_cache
-
-
 class BaseAgentSection(str, Enum):
     """Base agent markdown sections."""
 
@@ -143,9 +133,7 @@ class BaseAgentManager(ConfigServiceBase):
         content = self._structure_to_markdown(current)
         self.base_agent_path.write_text(content, encoding="utf-8")
 
-        # Clear caches (lazy load to avoid import overhead)
-        clear_base_agent_cache = _get_clear_base_agent_cache()
-        clear_base_agent_cache()
+        # Clear cache
         self.cache.invalidate("base_agent:instructions")
 
         logger.info("Base agent updated successfully")