claude-mpm 5.4.41__py3-none-any.whl → 5.6.23__py3-none-any.whl

claude_mpm/commander/workflow/notifier.py

@@ -0,0 +1,146 @@
+"""Basic notification delivery for events.
+
+This module provides Notifier which sends notifications for events.
+Currently supports logging, with extensibility for future channels
+(Slack, email, webhooks).
+"""
+
+import logging
+from dataclasses import dataclass
+
+from ..models.events import Event
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NotifierConfig:
+    """Configuration for notifier.
+
+    Attributes:
+        log_level: Logging level for notifications (default: INFO)
+
+    Future attributes:
+        slack_webhook: URL for Slack webhook notifications
+        email_config: SMTP configuration for email notifications
+        webhook_urls: List of webhook URLs for custom integrations
+    """
+
+    log_level: str = "INFO"
+    # Future: slack_webhook, email_config, webhook_urls
+
+
+class Notifier:
+    """Sends notifications for events.
+
+    Currently implements logging-based notifications with configurable
+    log levels. Designed for extensibility to support future notification
+    channels like Slack, email, and webhooks.
+
+    Attributes:
+        config: Notifier configuration
+
+    Example:
+        >>> config = NotifierConfig(log_level="INFO")
+        >>> notifier = Notifier(config)
+        >>> await notifier.notify(event)
+        >>> await notifier.notify_resolution(event, "User responded")
+    """
+
+    def __init__(self, config: NotifierConfig | None = None) -> None:
+        """Initialize notifier.
+
+        Args:
+            config: Optional NotifierConfig (uses defaults if not provided)
+        """
+        self.config = config or NotifierConfig()
+
+        # Map log level string to logging level
+        level_map = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        self._log_level = level_map.get(self.config.log_level.upper(), logging.INFO)
+
+        logger.debug("Notifier initialized with log level: %s", self.config.log_level)
+
+    async def notify(self, event: Event) -> None:
+        """Send notification for an event.
+
+        Currently logs the event at the configured log level. Future versions
+        will support additional notification channels.
+
+        Args:
+            event: Event to notify about
+
+        Example:
+            >>> await notifier.notify(event)
+            # Logs: [HIGH] Event evt_123: Choose deployment target
+        """
+        # Format notification message
+        message = self._format_event(event)
+
+        # Log notification
+        logger.log(
+            self._log_level,
+            "Event notification: %s",
+            message,
+        )
+
+        # Future: Send to Slack, email, webhooks
+        # if self.config.slack_webhook:
+        #     await self._send_slack(event)
+        # if self.config.email_config:
+        #     await self._send_email(event)
+
+    async def notify_resolution(self, event: Event, response: str) -> None:
+        """Notify that an event was resolved.
+
+        Logs the resolution with the user's response. Future versions will
+        send resolution notifications to configured channels.
+
+        Args:
+            event: Event that was resolved
+            response: User's response to the event
+
+        Example:
+            >>> await notifier.notify_resolution(event, "Deploy to staging")
+            # Logs: Event evt_123 resolved: Deploy to staging
+        """
+        message = f"Event {event.id} resolved: {response[:100]}"
+
+        logger.log(
+            self._log_level,
+            "Event resolution: %s",
+            message,
+        )
+
+        # Future: Send resolution notifications to channels
+
+    def _format_event(self, event: Event) -> str:
+        """Format event for notification display.
+
+        Args:
+            event: Event to format
+
+        Returns:
+            Formatted notification string
+
+        Example:
+            >>> msg = notifier._format_event(event)
+            '[HIGH] evt_123 (proj_456): Choose deployment target'
+        """
+        parts = [
+            f"[{event.priority.value.upper()}]",
+            f"{event.id}",
+            f"({event.project_id})",
+            f"{event.title}",
+        ]
+
+        if event.options:
+            parts.append(f"Options: {', '.join(event.options)}")
+
+        return " ".join(parts)

claude_mpm/commands/mpm-config.md

@@ -5,7 +5,15 @@ aliases: [mpm-config]
 migration_target: /mpm/config
 category: config
 description: Manage Claude MPM configuration
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-config"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-config` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-config` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-config
 
 Unified configuration management with auto-detection.

claude_mpm/commands/mpm-doctor.md

@@ -5,7 +5,15 @@ aliases: [mpm-doctor]
 migration_target: /mpm/system:doctor
 category: system
 description: Run diagnostic checks on Claude MPM installation
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-doctor"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-doctor` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-doctor` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-doctor
 
 Run comprehensive diagnostics on Claude MPM installation.

claude_mpm/commands/mpm-help.md

@@ -5,7 +5,15 @@ aliases: [mpm-help]
 migration_target: /mpm/system:help
 category: system
 description: Display help for Claude MPM commands
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-help"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-help` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-help` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-help
 
 Show help for MPM commands. Delegates to PM agent.

claude_mpm/commands/mpm-init.md

@@ -5,7 +5,15 @@ aliases: [mpm-init]
 migration_target: /mpm/system:init
 category: system
 description: Initialize or update project for Claude Code and MPM
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-init"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-init` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-init` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-init
 
 Initialize or intelligently update project for Claude Code and Claude MPM.

claude_mpm/commands/mpm-monitor.md

@@ -5,7 +5,15 @@ aliases: [mpm-monitor]
 migration_target: /mpm/system:monitor
 category: system
 description: Control monitoring server and dashboard
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-monitor"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-monitor` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-monitor` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-monitor
 
 Manage Socket.IO monitoring server for real-time dashboard.

claude_mpm/commands/mpm-organize.md

@@ -5,7 +5,15 @@ aliases: [mpm-organize]
 migration_target: /mpm/system:organize
 category: system
 description: Organize project files with intelligent consolidation
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-organize"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-organize` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-organize` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-organize
 
 Organize ALL project files with intelligent detection, consolidation, and pruning.

claude_mpm/commands/mpm-postmortem.md

@@ -5,7 +5,15 @@ aliases: [mpm-postmortem]
 migration_target: /mpm/analysis:postmortem
 category: analysis
 description: Analyze session errors and suggest improvements
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-postmortem"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-postmortem` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-postmortem` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-postmortem
 
 Analyze session errors and generate improvement suggestions.

claude_mpm/commands/mpm-session-resume.md

@@ -5,7 +5,15 @@ aliases: [mpm-session-resume]
 migration_target: /mpm/session:resume
 category: session
 description: Load context from paused session
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-session-resume"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-session-resume` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-session-resume` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-session-resume
 
 Load and display context from most recent paused session.
@@ -21,7 +29,7 @@ Load and display context from most recent paused session.
 - Git context and recent commits
 - Next recommended actions
 
-**Session location:** `.claude-mpm/sessions/session-*.json`
+**Session location:** `.claude-mpm/sessions/session-*.md`
 
 **Token usage:** ~20-40k tokens (10-20% of context budget)
 

claude_mpm/commands/mpm-status.md

@@ -5,7 +5,15 @@ aliases: [mpm-status]
 migration_target: /mpm/system:status
 category: system
 description: Display Claude MPM system status
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-status"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-status` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-status` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-status
 
 Show MPM system status. Delegates to PM agent.

claude_mpm/commands/mpm-ticket-view.md

@@ -5,7 +5,15 @@ aliases: [mpm-ticket-view]
 migration_target: /mpm/ticket:view
 category: tickets
 description: Orchestrate ticketing agent for project management workflows
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-ticket-view"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-ticket-view` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-ticket-view` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-ticket
 
 High-level ticketing workflows delegating to ticketing agent.

claude_mpm/commands/mpm-version.md

@@ -5,7 +5,15 @@ aliases: [mpm-version]
 migration_target: /mpm/system:version
 category: system
 description: Show version information
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm-version"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm-version` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm-version` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # /mpm-version
 
 Display version information for MPM, agents, and skills.

claude_mpm/commands/mpm.md

@@ -6,7 +6,15 @@ migration_target: /mpm
 category: system
 deprecated_aliases: []
 description: Access Claude MPM functionality and manage multi-agent orchestration
+deprecated: true
+deprecated_in: "5.5.0"
+replacement: "skill:mpm"
 ---
+
+> **Deprecated:** This command file is deprecated in favor of the `mpm` skill.
+> For Claude Code 2.1.3+, use the skill-based `/mpm` command instead.
+> This file is kept for backward compatibility with Claude Code < 2.1.3.
+
 # Claude MPM - Multi-Agent Project Manager
 
 Access Claude MPM functionality and manage your multi-agent orchestration.

claude_mpm/config/agent_presets.py

@@ -25,12 +25,17 @@ from typing import Any, Callable, Dict, List, Union
 PresetResolver = Union[List[str], Callable[[], List[str]]]
 
 # Core agents included in ALL presets (MIN and MAX)
+# Standard 9 core agents for essential PM workflow functionality
 CORE_AGENTS = [
     "claude-mpm/mpm-agent-manager",  # Agent lifecycle management
     "claude-mpm/mpm-skills-manager",  # Skills management
-    "universal/research",  # Codebase investigation
+    "engineer/core/engineer",  # General-purpose implementation
+    "universal/research",  # Codebase exploration and analysis
+    "qa/qa",  # Testing and quality assurance
+    "qa/web-qa",  # Browser-based testing specialist
     "documentation/documentation",  # Documentation generation
-    "engineer/core/engineer",  # General-purpose engineering
+    "ops/core/ops",  # Basic deployment operations
+    "documentation/ticketing",  # Ticket tracking (essential for PM workflow)
 ]
 
 PRESETS: Dict[str, Dict[str, Any]] = {
@@ -39,11 +44,7 @@ PRESETS: Dict[str, Dict[str, Any]] = {
     # ========================================
     "minimal": {
         "description": "Core agents only - universal starter kit",
-        "agents": CORE_AGENTS
-        + [
-            "qa/qa",
-            "ops/core/ops",
-        ],
+        "agents": CORE_AGENTS,  # All 8 core agents (no additional needed)
         "use_cases": ["Any project type", "Quick start", "Learning"],
     },
     # ========================================

claude_mpm/config/skill_sources.py

@@ -54,6 +54,7 @@ class SkillSource:
         branch: Git branch to use (default: "main")
         priority: Priority for skill resolution (lower = higher precedence)
         enabled: Whether this source should be synced
+        token: Optional GitHub token or env var reference (e.g., "$MY_TOKEN")
 
     Priority System:
         - 0: Reserved for system repository (highest precedence)
@@ -61,6 +62,12 @@ class SkillSource:
         - 100-999: Normal priority custom sources
         - 1000+: Low priority custom sources
 
+    Token Authentication:
+        - Direct token: "ghp_xxxxx" (stored in config, not recommended)
+        - Env var reference: "$PRIVATE_REPO_TOKEN" (resolved at runtime)
+        - If None, falls back to GITHUB_TOKEN or GH_TOKEN env vars
+        - Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
     Example:
         >>> source = SkillSource(
         ...     id="system",
@@ -70,6 +77,12 @@ class SkillSource:
         ... )
         >>> source.validate()
         []
+        >>> private_source = SkillSource(
+        ...     id="private",
+        ...     type="git",
+        ...     url="https://github.com/myorg/private-skills",
+        ...     token="$PRIVATE_REPO_TOKEN"
+        ... )
     """
 
     id: str
@@ -78,6 +91,7 @@ class SkillSource:
     branch: str = "main"
     priority: int = 100
     enabled: bool = True
+    token: Optional[str] = None
 
     def __post_init__(self):
         """Validate skill source configuration after initialization.
@@ -262,6 +276,7 @@ class SkillSourceConfiguration:
                         branch=source_data.get("branch", "main"),
                         priority=source_data.get("priority", 100),
                         enabled=source_data.get("enabled", True),
+                        token=source_data.get("token"),
                     )
                     sources.append(source)
                 except (KeyError, ValueError) as e:
@@ -326,6 +341,7 @@ class SkillSourceConfiguration:
                     "branch": source.branch,
                     "priority": source.priority,
                     "enabled": source.enabled,
+                    **({"token": source.token} if source.token else {}),
                 }
                 for source in sources
             ]

claude_mpm/constants.py

@@ -169,6 +169,7 @@ class SkillsCommands(str, Enum):
     INFO = "info"
     CONFIG = "config"
     CONFIGURE = "configure"  # Interactive skills selection (like agents configure)
+    SELECT = "select"  # Interactive topic-grouped skill selector
     # GitHub deployment commands
     DEPLOY_FROM_GITHUB = "deploy-github"
     LIST_AVAILABLE = "list-available"

claude_mpm/core/claude_runner.py

@@ -1,5 +1,7 @@
 """Claude runner with both exec and subprocess launch methods."""
 
+import hashlib
+import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -211,9 +213,146 @@ class ClaudeRunner:
                 }
             )
 
+    def _get_deployment_state_path(self) -> Path:
+        """Get path to deployment state file.
+
+        CRITICAL: Must match path used by startup.py::_save_deployment_state_after_reconciliation()
+        Located at: .claude-mpm/cache/deployment_state.json
+        """
+        return Path.cwd() / ".claude-mpm" / "cache" / "deployment_state.json"
+
+    def _calculate_deployment_hash(self, agents_dir: Path) -> str:
+        """Calculate hash of all agent files for change detection.
+
+        Args:
+            agents_dir: Directory containing agent .md files
+
+        Returns:
+            SHA256 hash of agent file contents
+        """
+        if not agents_dir.exists():
+            return ""
+
+        # Get all .md files sorted for consistent hashing
+        agent_files = sorted(agents_dir.glob("*.md"))
+
+        hash_obj = hashlib.sha256()
+        for agent_file in agent_files:
+            # Include filename and content in hash
+            hash_obj.update(agent_file.name.encode())
+            try:
+                hash_obj.update(agent_file.read_bytes())
+            except Exception as e:
+                self.logger.debug(f"Error reading {agent_file} for hash: {e}")
+
+        return hash_obj.hexdigest()
+
+    def _check_deployment_state(self) -> bool:
+        """Check if agents are already deployed and up-to-date.
+
+        Returns:
+            True if agents are already deployed and match current version, False otherwise
+        """
+        state_file = self._get_deployment_state_path()
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        # If state file doesn't exist, need to deploy
+        if not state_file.exists():
+            return False
+
+        # If agents directory doesn't exist, need to deploy
+        if not agents_dir.exists():
+            return False
+
+        try:
+            # Load deployment state
+            state_data = json.loads(state_file.read_text())
+
+            # Get current version from package
+            from claude_mpm import __version__
+
+            # Check if version matches
+            if state_data.get("version") != __version__:
+                self.logger.debug(
+                    f"Version mismatch: {state_data.get('version')} != {__version__}"
+                )
+                return False
+
+            # Check if agent count and hash match
+            current_hash = self._calculate_deployment_hash(agents_dir)
+            stored_hash = state_data.get("deployment_hash", "")
+
+            if current_hash != stored_hash:
+                self.logger.debug("Agent deployment hash mismatch")
+                return False
+
+            # All checks passed - agents are already deployed
+            agent_count = state_data.get("agent_count", 0)
+            self.logger.debug(
+                f"Agents already deployed: {agent_count} agents (v{__version__})"
+            )
+            return True
+
+        except Exception as e:
+            self.logger.debug(f"Error checking deployment state: {e}")
+            return False
+
+    def _save_deployment_state(self, agent_count: int) -> None:
+        """Save current deployment state.
+
+        Args:
+            agent_count: Number of agents deployed
+        """
+        state_file = self._get_deployment_state_path()
+        agents_dir = Path.cwd() / ".claude" / "agents"
+
+        try:
+            import time
+
+            from claude_mpm import __version__
+
+            # Calculate deployment hash
+            deployment_hash = self._calculate_deployment_hash(agents_dir)
+
+            # Create state data
+            state_data = {
+                "version": __version__,
+                "agent_count": agent_count,
+                "deployment_hash": deployment_hash,
+                "deployed_at": time.time(),
+            }
+
+            # Ensure directory exists
+            state_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write state file
+            state_file.write_text(json.dumps(state_data, indent=2))
+            self.logger.debug(f"Saved deployment state: {agent_count} agents")
+
+        except Exception as e:
+            self.logger.debug(f"Error saving deployment state: {e}")
+
     def setup_agents(self) -> bool:
         """Deploy native agents to .claude/agents/."""
         try:
+            # SIMPLE CHECK: If agents already exist from reconciliation, skip deployment
+            # This ensures reconciliation's user-configured agents are never overwritten
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            if agents_dir.exists():
+                existing_agents = list(agents_dir.glob("*.md"))
+                if len(existing_agents) > 0:
+                    # Reconciliation already deployed agents - skip
+                    self.logger.debug(
+                        f"Skipping setup_agents: {len(existing_agents)} agents already deployed by reconciliation"
+                    )
+                    if self.project_logger:
+                        self.project_logger.log_system(
+                            f"Agents already deployed via reconciliation: {len(existing_agents)} agents",
+                            level="DEBUG",
+                            component="deployment",
+                        )
+                    return True
+
             if self.project_logger:
                 self.project_logger.log_system(
                     "Starting agent deployment", level="INFO", component="deployment"
@@ -239,6 +378,12 @@ class ClaudeRunner:
 
                 # Set Claude environment
                 self.deployment_service.set_claude_environment()
+
+                # Save deployment state for future runs
+                agents_dir = Path.cwd() / ".claude" / "agents"
+                total_agents = len(list(agents_dir.glob("*.md")))
+                self._save_deployment_state(total_agents)
+
                 return True
             self.logger.info("All agents already up to date")
             if self.project_logger:
@@ -247,6 +392,13 @@ class ClaudeRunner:
                     level="INFO",
                     component="deployment",
                 )
+
+            # Save deployment state even if no changes
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            if agents_dir.exists():
+                total_agents = len(list(agents_dir.glob("*.md")))
+                self._save_deployment_state(total_agents)
+
             return True
 
         except PermissionError as e:
@@ -730,7 +882,7 @@ Use these agents to delegate specialized work via the Task tool.
                     import json
 
                     settings = json.loads(settings_file.read_text())
-                    if settings.get("activeOutputStyle") == "claude-mpm":
+                    if settings.get("activeOutputStyle") == "Claude MPM":
                         # Already active, check if file exists
                         output_style_file = (
                             Path.home() / ".claude" / "output-styles" / "claude-mpm.md"
@@ -740,7 +892,7 @@ Use these agents to delegate specialized work via the Task tool.
                                 "Output style 'Claude MPM' already deployed and active"
                             )
                             return
-                except Exception:
+                except Exception:  # nosec B110
                     pass  # Continue with deployment if we can't read settings
 
             # Read the OUTPUT_STYLE.md content if it exists