claude-mpm 5.4.96__py3-none-any.whl → 5.6.17__py3-none-any.whl

claude_mpm/scripts/claude-hook-handler.sh

@@ -62,8 +62,13 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Determine the claude-mpm root based on installation type
+# Check if we're in a UV tools installation
+if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+    # UV tools installation - script is at lib/python*/site-packages/claude_mpm/scripts/
+    # The tool root is what we need for Python detection
+    CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages.*||')"
 # Check if we're in a pipx installation
-if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+elif [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
     # pipx installation - script is at lib/python*/site-packages/claude_mpm/scripts/
     # The venv root is what we need for Python detection
     CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages/.*||')"
@@ -89,11 +94,12 @@ fi
 # STRATEGY:
 # This function implements a fallback chain to find Python with claude-mpm dependencies:
 # 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)
+# 2. UV tools installations (~/.local/share/uv/tools/) - uses tool's venv Python
+# 3. pipx installations - uses pipx venv Python
+# 4. Project-specific virtual environments (venv, .venv)
+# 5. Currently active virtual environment ($VIRTUAL_ENV)
+# 6. System python3 (may lack dependencies)
+# 7. System python (last resort)
 #
 # WHY THIS APPROACH:
 # - Claude MPM requires specific packages (socketio, eventlet) not in system Python
@@ -119,12 +125,26 @@ find_python_command() {
     # 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"
+            echo "uv run --directory \"$CLAUDE_MPM_ROOT\" python"
             return
         fi
     fi
 
-    # 2. Check if we're in a pipx installation
+    # 2. Check if we're in a UV tools installation
+    if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+        # UV tools installation - extract the tool root directory
+        CLAUDE_MPM_ROOT="$(echo "$SCRIPT_DIR" | sed 's|/lib/python.*/site-packages.*||')"
+        local uv_python="$CLAUDE_MPM_ROOT/bin/python"
+        if [ -x "$uv_python" ]; then
+            if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+                echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] UV tools Python found: $uv_python" >> /tmp/claude-mpm-hook.log
+            fi
+            echo "$uv_python"
+            return
+        fi
+    fi
+
+    # 3. 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
@@ -133,7 +153,7 @@ find_python_command() {
         fi
     fi
 
-    # 3. Check for project-local virtual environment (common in development)
+    # 4. 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"
@@ -154,7 +174,13 @@ find_python_command() {
 PYTHON_CMD=$(find_python_command)
 
 # Check installation type and set PYTHONPATH accordingly
-if [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
+if [[ "$SCRIPT_DIR" == *"/.local/share/uv/tools/"* ]]; then
+    # UV tools installation - claude_mpm is already in the tool's site-packages
+    # No need to modify PYTHONPATH
+    if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)] UV tools installation detected" >> /tmp/claude-mpm-hook.log
+    fi
+elif [[ "$SCRIPT_DIR" == *"/.local/pipx/venvs/claude-mpm/"* ]]; then
     # pipx installation - claude_mpm is already in the venv's site-packages
     # No need to modify PYTHONPATH
     if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
@@ -193,8 +219,8 @@ log_debug() {
 
 # 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
+if [[ "$PYTHON_CMD" == "uv run"* ]]; then
+    if ! uv run --directory "$CLAUDE_MPM_ROOT" python -c "import claude_mpm" 2>/dev/null; then
         log_debug "claude_mpm module not available, continuing without hook"
         echo '{"action": "continue"}'
         exit 0
@@ -210,10 +236,11 @@ 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
+# Suppress RuntimeWarning to prevent stderr output (which causes hook errors)
+if [[ "$PYTHON_CMD" == "uv run"* ]]; then
+    exec uv run --directory "$CLAUDE_MPM_ROOT" python -W ignore::RuntimeWarning -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
+    exec "$PYTHON_CMD" -W ignore::RuntimeWarning -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
@@ -224,4 +251,4 @@ if [ "${CLAUDE_MPM_HOOK_DEBUG}" = "true" ]; then
 fi
 # Return continue action to prevent blocking Claude Code
 echo '{"action": "continue"}'
-exit 0
+exit 0

claude_mpm/services/agents/agent_recommendation_service.py

@@ -30,16 +30,16 @@ class AgentRecommendationService:
     Can be used by CLI, API, or future auto-configuration features.
     """
 
-    # Core agents always included - matches ToolchainDetector.CORE_AGENTS
+    # Core agents always included - Standard 6 core agents for essential PM workflow
+    # These agents are auto-deployed when no configuration exists
     # Uses exact agent IDs from repository for consistency
     CORE_AGENTS = {
-        "engineer",
-        "qa-agent",
-        "memory-manager-agent",
-        "local-ops-agent",
-        "research-agent",
-        "documentation-agent",
-        "security-agent",
+        "engineer",  # General-purpose implementation
+        "research",  # Codebase exploration and analysis
+        "qa",  # Testing and quality assurance
+        "documentation",  # Documentation generation
+        "ops",  # Basic deployment operations
+        "ticketing",  # Ticket tracking (essential for PM workflow)
     }
 
     # Map detected languages to recommended engineer agents

claude_mpm/services/agents/agent_selection_service.py

@@ -39,10 +39,10 @@ import logging
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set, Tuple
 
-from src.claude_mpm.services.agents.single_tier_deployment_service import (
+from claude_mpm.services.agents.single_tier_deployment_service import (
     SingleTierDeploymentService,
 )
-from src.claude_mpm.services.agents.toolchain_detector import ToolchainDetector
+from claude_mpm.services.agents.toolchain_detector import ToolchainDetector
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/agents/loading/framework_agent_loader.py

@@ -10,10 +10,19 @@ Loading precedence: Project → User → System
 
 This service integrates with the main agent_loader.py to provide
 markdown-based agent profiles alongside JSON-based templates.
+
+Auto-Deployment: When no agents are configured, the standard 6 core agents
+are automatically deployed:
+- engineer: General-purpose implementation
+- research: Codebase exploration and analysis
+- qa: Testing and quality assurance
+- documentation: Documentation generation
+- ops: Basic deployment operations
+- ticketing: Ticket tracking (essential for PM workflow)
 """
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from claude_mpm.agents.agent_loader import AgentTier, list_agents_by_tier
 from claude_mpm.core.logging_utils import get_logger
@@ -21,6 +30,17 @@ from claude_mpm.core.unified_paths import get_path_manager
 
 logger = get_logger(__name__)
 
+# Standard 6 core agents that are auto-deployed when no agents are specified
+# This list is the canonical source - other modules should import from here
+CORE_AGENTS: List[str] = [
+    "engineer",  # General-purpose implementation
+    "research",  # Codebase exploration and analysis
+    "qa",  # Testing and quality assurance
+    "documentation",  # Documentation generation
+    "ops",  # Basic deployment operations
+    "ticketing",  # Ticket tracking (essential for PM workflow)
+]
+
 
 class FrameworkAgentLoader:
     """Loads agent profiles from project, user, and system directories with proper precedence"""
@@ -86,7 +106,7 @@ class FrameworkAgentLoader:
                 data_claude = package_path / "data" / "agents" / "CLAUDE.md"
                 if data_instructions.exists() or data_claude.exists():
                     return package_path / "data"
-        except Exception:
+        except Exception:  # nosec B110 - intentional fallthrough to next location
             pass
 
         current = Path.cwd()
@@ -431,3 +451,56 @@ Please operate according to your profile specifications and maintain quality sta
 """
 
         return instruction.strip()
+
+    def get_core_agents(self) -> List[str]:
+        """
+        Get the standard 6 core agents for auto-deployment.
+
+        These agents are automatically deployed when no agents are specified
+        in the configuration. They provide essential PM workflow functionality.
+
+        Returns:
+            List of core agent IDs
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> core = loader.get_core_agents()
+            >>> 'engineer' in core
+            True
+            >>> len(core)
+            6
+        """
+        return CORE_AGENTS.copy()
+
+    def get_agents_with_fallback(self) -> Dict[str, list]:
+        """
+        Get available agents, falling back to core agents if none found.
+
+        This method implements the auto-deployment logic: when no agents
+        are found in any tier (project, user, system), it returns the
+        standard 6 core agents as a fallback.
+
+        Returns:
+            Dictionary with agent lists by tier. If no agents found in any tier,
+            returns core agents under 'fallback' key.
+
+        Example:
+            >>> loader = FrameworkAgentLoader()
+            >>> loader.initialize()
+            >>> agents = loader.get_agents_with_fallback()
+            >>> if 'fallback' in agents:
+            ...     print("Using core agents as fallback")
+        """
+        available = self.get_available_agents()
+
+        # Check if any agents are found
+        total_agents = sum(len(agents) for agents in available.values())
+
+        if total_agents == 0:
+            logger.info(
+                "No agents found in configuration. "
+                "Auto-deploying standard 6 core agents."
+            )
+            return {"fallback": CORE_AGENTS.copy()}
+
+        return available

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -30,12 +30,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from src.claude_mpm.config.agent_sources import AgentSourceConfiguration
-from src.claude_mpm.models.git_repository import GitRepository
-from src.claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
+from claude_mpm.config.agent_sources import AgentSourceConfiguration
+from claude_mpm.models.git_repository import GitRepository
+from claude_mpm.services.agents.deployment.remote_agent_discovery_service import (
     RemoteAgentDiscoveryService,
 )
-from src.claude_mpm.services.agents.git_source_manager import GitSourceManager
+from claude_mpm.services.agents.git_source_manager import GitSourceManager
 
 logger = logging.getLogger(__name__)
 

claude_mpm/services/event_log.py

@@ -310,8 +310,16 @@ def get_event_log(log_file: Optional[Path] = None) -> EventLog:
 
     Returns:
         EventLog instance
+
+    Note:
+        If log_file is provided and differs from the current instance,
+        a new EventLog is created and replaces the global instance.
+        This allows hooks to use project-specific event logs.
     """
     global _event_log
     if _event_log is None:
         _event_log = EventLog(log_file)
+    elif log_file is not None and _event_log.log_file != log_file:
+        # Create new instance if log file differs from current
+        _event_log = EventLog(log_file)
     return _event_log

claude_mpm/services/pm_skills_deployer.py

@@ -50,9 +50,16 @@ from claude_mpm.core.mixins import LoggerMixin
 # Security constants
 MAX_YAML_SIZE = 10 * 1024 * 1024  # 10MB limit to prevent YAML bombs
 
-# Required PM skills that MUST be deployed for PM agent to function properly
-# These are framework management skills that PM uses for orchestration
+# Tier 1: Required PM skills that MUST be deployed for PM agent to function properly
+# These are core framework management skills for basic PM operation
 REQUIRED_PM_SKILLS = [
+    # Core command-based skills (new consolidated CLI)
+    "mpm",
+    "mpm-init",
+    "mpm-status",
+    "mpm-help",
+    "mpm-doctor",
+    # Legacy framework management skills
     "mpm-git-file-tracking",
     "mpm-pr-workflow",
     "mpm-ticketing-integration",
@@ -66,6 +73,23 @@ REQUIRED_PM_SKILLS = [
     "mpm-session-management",
 ]
 
+# Tier 2: Recommended skills (deployed with standard install)
+# These provide enhanced functionality for common workflows
+RECOMMENDED_PM_SKILLS = [
+    "mpm-config",
+    "mpm-ticket-view",
+    "mpm-session-resume",
+    "mpm-postmortem",
+]
+
+# Tier 3: Optional skills (deployed with full install)
+# These provide additional features for advanced use cases
+OPTIONAL_PM_SKILLS = [
+    "mpm-monitor",
+    "mpm-version",
+    "mpm-organize",
+]
+
 
 @dataclass
 class PMSkillInfo:
@@ -383,17 +407,45 @@ class PMSkillsDeployerService(LoggerMixin):
         self.logger.info(f"Discovered {len(skills)} bundled PM skills")
         return skills
 
+    def _get_skills_for_tier(self, tier: str) -> List[str]:
+        """Get list of skills to deploy based on tier.
+
+        Args:
+            tier: Deployment tier - "minimal", "standard", or "full"
+
+        Returns:
+            List of skill names to deploy
+
+        Raises:
+            ValueError: If tier is invalid
+        """
+        if tier == "minimal":
+            return REQUIRED_PM_SKILLS
+        if tier == "standard":
+            return REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS
+        if tier == "full":
+            return REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS + OPTIONAL_PM_SKILLS
+        raise ValueError(
+            f"Invalid tier '{tier}'. Must be 'minimal', 'standard', or 'full'"
+        )
+
     def deploy_pm_skills(
         self,
         project_dir: Path,
         force: bool = False,
+        tier: str = "standard",
         progress_callback: Optional[Callable[[str, int, int], None]] = None,
     ) -> DeploymentResult:
-        """Deploy bundled PM skills to project directory.
+        """Deploy bundled PM skills to project directory with tier-based selection.
 
         Copies PM skills from bundled templates to .claude/skills/{name}/SKILL.md
         and updates registry with version and checksum information.
 
+        Deployment Tiers:
+        - "minimal": Only REQUIRED_PM_SKILLS (Tier 1 - core functionality)
+        - "standard": REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS (Tier 1+2 - common workflows)
+        - "full": All skills (Tier 1+2+3 - advanced features)
+
         Conflict Resolution:
         - mpm-* skills from src WIN (overwrite existing)
         - Non-mpm-* skills in .claude/skills/ are untouched
@@ -401,16 +453,42 @@ class PMSkillsDeployerService(LoggerMixin):
         Args:
             project_dir: Project root directory
             force: If True, redeploy even if skill already exists
+            tier: Deployment tier - "minimal", "standard" (default), or "full"
             progress_callback: Optional callback(skill_name, current, total) for progress
 
         Returns:
             DeploymentResult with deployment status and details
 
         Example:
-            >>> result = deployer.deploy_pm_skills(Path("/project"), force=True)
+            >>> # Standard deployment (Tier 1 + Tier 2)
+            >>> result = deployer.deploy_pm_skills(Path("/project"))
             >>> print(f"Deployed: {len(result.deployed)} to .claude/skills/")
+            >>>
+            >>> # Minimal deployment (Tier 1 only)
+            >>> result = deployer.deploy_pm_skills(Path("/project"), tier="minimal")
+            >>>
+            >>> # Full deployment (all tiers)
+            >>> result = deployer.deploy_pm_skills(Path("/project"), tier="full")
         """
-        skills = self._discover_bundled_pm_skills()
+        # Get tier-based skill filter
+        try:
+            tier_skills = self._get_skills_for_tier(tier)
+        except ValueError as e:
+            return DeploymentResult(
+                success=False,
+                deployed=[],
+                skipped=[],
+                errors=[{"skill": "all", "error": str(e)}],
+                message=str(e),
+            )
+
+        # Discover all bundled skills, then filter by tier
+        all_skills = self._discover_bundled_pm_skills()
+        skills = [s for s in all_skills if s["name"] in tier_skills]
+
+        self.logger.info(
+            f"Deploying {len(skills)}/{len(all_skills)} skills for tier '{tier}'"
+        )
         deployed = []
         skipped = []
         errors = []
@@ -526,7 +604,7 @@ class PMSkillsDeployerService(LoggerMixin):
 
         success = len(errors) == 0
         message = (
-            f"Deployed {len(deployed)} skills, skipped {len(skipped)}, "
+            f"Deployed {len(deployed)} skills (tier: {tier}), skipped {len(skipped)}, "
             f"{len(errors)} errors"
         )