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

claude_mpm/services/command_deployment_service.py

@@ -23,10 +23,14 @@ 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-organize.md",  # Replaced by mpm-ticket-organize.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
+        # Removed - consolidated into /mpm-configure
+        "mpm-agents-list.md",  # Consolidated into /mpm-configure
+        "mpm-agents-detect.md",  # Consolidated into /mpm-configure
+        "mpm-agents-auto-configure.md",  # Consolidated into /mpm-configure
+        "mpm-agents-recommend.md",  # Consolidated into /mpm-configure
     ]
 
     def __init__(self):
@@ -315,10 +319,14 @@ 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-organize.md": "mpm-ticket-organize.md",
+            "mpm-config-view.md": "mpm-config.md",
             "mpm-resume.md": "mpm-session-resume.md",
             "mpm-ticket.md": "mpm-ticket-view.md",
+            # Removed commands - consolidated into /mpm-configure
+            "mpm-agents-list.md": "mpm-configure (use /mpm-configure)",
+            "mpm-agents-detect.md": "mpm-configure (use /mpm-configure)",
+            "mpm-agents-auto-configure.md": "mpm-configure (use /mpm-configure)",
+            "mpm-agents-recommend.md": "mpm-configure (use /mpm-configure)",
         }
 
         for deprecated_cmd in self.DEPRECATED_COMMANDS:
@@ -345,13 +353,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
@@ -359,12 +425,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/delegation_detector.py

@@ -0,0 +1,175 @@
+"""Delegation Pattern Detector for PM outputs.
+
+WHY this is needed:
+- Detect when PM asks user to do something manually instead of delegating
+- Convert manual instructions into actionable autotodos
+- Enforce delegation principle in PM workflow
+- Help PM recognize delegation opportunities
+
+DESIGN DECISION: Pattern-based detection
+- Simple regex patterns to catch common delegation anti-patterns
+- Extract action items from PM's output
+- Format as autotodos for PM to see and delegate properly
+- Non-invasive - just surfaces patterns for review
+
+Examples of patterns to detect:
+- "Make sure .env.local is in your .gitignore"
+- "You'll need to run npm install"
+- "Please run the tests manually"
+- "Remember to update the README"
+- "Don't forget to commit your changes"
+"""
+
+import re
+from typing import Any, Dict, List, Tuple
+
+from ..core.logger import get_logger
+
+# Delegation anti-patterns with capture groups for action extraction
+# Each pattern is (regex_pattern, todo_template)
+# {match} in template will be replaced with captured text
+USER_DELEGATION_PATTERNS: List[Tuple[str, str]] = [
+    # "Make sure (to) X" → "Verify: X"
+    (r"(?i)make sure (?:to |that |you )?(.+)", "Verify: {match}"),
+    # "You'll/will need to X" → "Task: X"
+    (r"(?i)you(?:'ll| will)? need to (.+)", "Task: {match}"),
+    # "Please run/execute/do X" → "Execute: X"
+    (r"(?i)please (?:run|execute|do) (.+)", "Execute: {match}"),
+    # "Remember to X" → "Task: X"
+    (r"(?i)remember to (.+)", "Task: {match}"),
+    # "Don't forget to X" → "Task: X"
+    (r"(?i)don'?t forget to (.+)", "Task: {match}"),
+    # "You should/can/could X" → "Suggested: X"
+    (r"(?i)you (?:should|can|could) (.+)", "Suggested: {match}"),
+    # "Be sure to X" → "Task: X"
+    (r"(?i)be sure to (.+)", "Task: {match}"),
+    # "Don't forget X" (without 'to') → "Task: X"
+    (r"(?i)don'?t forget (.+)", "Task: {match}"),
+    # "You may want to X" → "Suggested: X"
+    (r"(?i)you may want to (.+)", "Suggested: {match}"),
+    # "It's important to X" → "Task: X"
+    (r"(?i)it'?s important to (.+)", "Task: {match}"),
+]
+
+
+class DelegationDetector:
+    """Detects delegation anti-patterns in PM outputs.
+
+    WHY this design:
+    - Pattern-based detection for common manual instruction phrases
+    - Extract actionable tasks from PM's text
+    - Format as autotodos for PM visibility
+    - Simple and extensible (add new patterns easily)
+    """
+
+    def __init__(self):
+        self.logger = get_logger("delegation_detector")
+
+    def detect_user_delegation(self, text: str) -> List[Dict[str, Any]]:
+        """Detect delegation anti-patterns in text.
+
+        Scans text for patterns where PM is asking user to do something
+        manually instead of delegating to an agent.
+
+        Args:
+            text: PM output text to scan
+
+        Returns:
+            List of detected patterns with:
+                - pattern_type: Type of pattern matched
+                - original_text: Original sentence matched
+                - suggested_todo: Formatted todo text
+                - action: Extracted action text
+        """
+        detections = []
+
+        # Split into sentences for better pattern matching
+        # Split on period followed by space/newline, or just newline
+        # This avoids splitting on periods in filenames like .env.local
+        sentences = re.split(r"(?:\.\s+|\n+)", text)
+
+        for sentence in sentences:
+            sentence = sentence.strip()
+            if not sentence:
+                continue
+
+            # Try each pattern
+            for pattern, todo_template in USER_DELEGATION_PATTERNS:
+                match = re.search(pattern, sentence, re.IGNORECASE)
+                if match:
+                    # Extract the captured action
+                    action = match.group(1).strip()
+
+                    # Skip if action is too short (likely false positive)
+                    if len(action) < 5:
+                        continue
+
+                    # Format todo using template
+                    suggested_todo = todo_template.format(match=action)
+
+                    # Determine pattern type from template prefix
+                    pattern_type = todo_template.split(":")[0]
+
+                    detection = {
+                        "pattern_type": pattern_type,
+                        "original_text": sentence.strip(),
+                        "suggested_todo": suggested_todo,
+                        "action": action,
+                    }
+
+                    detections.append(detection)
+                    self.logger.debug(
+                        f"Detected delegation pattern: {pattern_type} - {action}"
+                    )
+
+                    # Only match first pattern per sentence
+                    break
+
+        return detections
+
+    def format_as_autotodo(self, detection: Dict[str, Any]) -> Dict[str, str]:
+        """Format a detection as an autotodo.
+
+        Args:
+            detection: Detection dict from detect_user_delegation
+
+        Returns:
+            Dictionary with todo fields (content, activeForm, status)
+        """
+        pattern_type = detection["pattern_type"]
+        suggested_todo = detection["suggested_todo"]
+        action = detection["action"]
+
+        # Create todo content
+        content = f"[Delegation] {suggested_todo}"
+
+        # Active form for in-progress display
+        active_form = f"Delegating: {action[:30]}..."
+
+        return {
+            "content": content,
+            "activeForm": active_form,
+            "status": "pending",
+            "metadata": {
+                "pattern_type": pattern_type,
+                "original_text": detection["original_text"],
+                "action": action,
+                "source": "delegation_detector",
+            },
+        }
+
+
+# Global instance
+_delegation_detector: DelegationDetector | None = None
+
+
+def get_delegation_detector() -> DelegationDetector:
+    """Get the global delegation detector instance.
+
+    Returns:
+        DelegationDetector instance
+    """
+    global _delegation_detector
+    if _delegation_detector is None:
+        _delegation_detector = DelegationDetector()
+    return _delegation_detector

claude_mpm/services/diagnostics/checks/agent_check.py

@@ -66,9 +66,9 @@ class AgentCheck(BaseDiagnosticCheck):
 
             if deployed_count == 0:
                 status = ValidationSeverity.ERROR
-                message = f"No agents deployed (0/{available_count} available)"
+                message = f"No agents deployed (0/{available_count} cached)"
                 fix_command = "claude-mpm agents deploy"
-                fix_description = "Deploy all available agents"
+                fix_description = "Deploy all cached agents"
             elif deployed_count < available_count:
                 status = ValidationSeverity.WARNING
                 message = f"{deployed_count}/{available_count} agents deployed"

claude_mpm/services/diagnostics/checks/agent_sources_check.py

@@ -69,6 +69,13 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                     fix_command="claude-mpm agent-source add https://github.com/bobmatnyc/claude-mpm-agents",
                     fix_description="Add default system repository",
                     sub_results=sub_results if self.verbose else [],
+                    explanation=(
+                        "Agent sources define where Claude MPM discovers specialized agents. "
+                        "Without configured sources, no agents can be deployed or delegated to. "
+                        "This is a critical component for multi-agent workflows."
+                    ),
+                    severity="critical",
+                    doc_link="https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md",
                 )
 
             # Check 2: Configuration is valid YAML
@@ -141,16 +148,30 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 r for r in sub_results if r.status == ValidationSeverity.WARNING
             ]
 
+            # Determine status and enhanced troubleshooting info (issue #125)
             if error_results:
                 status = ValidationSeverity.ERROR
                 message = f"Agent sources have {len(error_results)} critical issue(s)"
                 fix_command = None
                 fix_description = None
+                severity = "critical"
+                explanation = (
+                    "Agent sources are the foundation of Claude MPM's delegation system. "
+                    "Critical errors prevent agent discovery and deployment, blocking "
+                    "multi-agent workflows entirely."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             elif warning_results:
                 status = ValidationSeverity.WARNING
                 message = f"Agent sources have {len(warning_results)} minor issue(s)"
                 fix_command = "claude-mpm agent-source update"
                 fix_description = "Update all sources to refresh cache"
+                severity = "medium"
+                explanation = (
+                    "Some agent sources have issues but the system can still function. "
+                    "You may have limited agent availability or outdated cache."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/guides/agent-sources.md"
             else:
                 status = OperationResult.SUCCESS
                 enabled_count = details["enabled_sources"]
@@ -158,6 +179,12 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 message = f"All checks passed ({enabled_count} source(s), {agents_count} agent(s))"
                 fix_command = None
                 fix_description = None
+                severity = "info"
+                explanation = (
+                    "Agent sources are properly configured and agents are discoverable. "
+                    "You can delegate tasks to specialized agents."
+                )
+                doc_link = ""
 
             return DiagnosticResult(
                 category=self.category,
@@ -167,6 +194,9 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
                 fix_command=fix_command,
                 fix_description=fix_description,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:
@@ -432,7 +462,7 @@ class AgentSourcesCheck(BaseDiagnosticCheck):
 
     def _check_cache_directory(self) -> DiagnosticResult:
         """Check cache directory health."""
-        cache_dir = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+        cache_dir = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         if not cache_dir.exists():
             return DiagnosticResult(

claude_mpm/services/diagnostics/checks/configuration_check.py

@@ -63,12 +63,36 @@ class ConfigurationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Configuration is valid"
 
+            # Add enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Configuration files control how Claude MPM behaves. Critical errors "
+                    "in configuration may prevent features from working correctly or cause "
+                    "unexpected behavior."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "Configuration has minor issues that may affect optional features. "
+                    "Core functionality should still work."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/configuration.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/installation_check.py

@@ -65,12 +65,34 @@ class InstallationCheck(BaseDiagnosticCheck):
                 status = OperationResult.SUCCESS
                 message = "Installation is healthy"
 
+            # Determine severity and explanation based on status (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "Claude MPM installation verification failed. Critical components are missing "
+                    "or misconfigured, which will prevent the system from functioning properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/installation.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "medium"
+                explanation = (
+                    "Installation is functional but has minor issues. These may affect "
+                    "performance or features but won't prevent basic operation."
+                )
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/checks/mcp_services_check.py

@@ -216,12 +216,35 @@ class MCPServicesCheck(BaseDiagnosticCheck):
                 status = ValidationSeverity.WARNING
                 message = f"All {total_services} MCP services installed but connections not tested"
 
+            # Enhanced troubleshooting info (issue #125)
+            severity = "medium"
+            explanation = ""
+            doc_link = ""
+
+            if status == ValidationSeverity.ERROR:
+                severity = "high"
+                explanation = (
+                    "MCP services provide enhanced capabilities like vector search, browser automation, "
+                    "and ticket management. Critical errors prevent these services from functioning."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+            elif status == ValidationSeverity.WARNING:
+                severity = "low"
+                explanation = (
+                    "MCP services are optional but provide powerful features. "
+                    "Some services may not be installed or configured properly."
+                )
+                doc_link = "https://github.com/bobmatnyc/claude-mpm/blob/main/docs/mcp-services.md"
+
             return DiagnosticResult(
                 category=self.category,
                 status=status,
                 message=message,
                 details=details,
                 sub_results=sub_results if self.verbose else [],
+                explanation=explanation,
+                severity=severity,
+                doc_link=doc_link,
             )
 
         except Exception as e:

claude_mpm/services/diagnostics/doctor_reporter.py

@@ -28,6 +28,15 @@ class DoctorReporter:
         OperationResult.SKIPPED: "⏭️ ",
     }
 
+    # Severity level emojis (issue #125)
+    SEVERITY_SYMBOLS = {
+        "critical": "🔴",
+        "high": "🟠",
+        "medium": "🟡",
+        "low": "🟢",
+        "info": "🔵",
+    }
+
     # ANSI color codes
     COLORS = {
         "reset": "\033[0m",
@@ -93,8 +102,15 @@ class DoctorReporter:
         symbol = self.STATUS_SYMBOLS.get(result.status, "?")
         color = self._get_status_color(result.status)
 
+        # Add severity indicator if present (issue #125)
+        severity_prefix = ""
+        if result.severity and result.severity != "medium":
+            severity_symbol = self.SEVERITY_SYMBOLS.get(result.severity, "")
+            if severity_symbol:
+                severity_prefix = f"{severity_symbol} {result.severity.upper()}: "
+
         # Main result line
-        line = f"{indent_str}{symbol} {result.category}: "
+        line = f"{indent_str}{severity_prefix}{symbol} {result.category}: "
 
         if result.status == OperationResult.SUCCESS:
             line += self._color("OK", color)
@@ -111,6 +127,15 @@ class DoctorReporter:
         message_indent = "   " + indent_str
         print(f"{message_indent}{result.message}")
 
+        # Explanation (issue #125)
+        if result.explanation:
+            # Format multi-line explanations with proper indentation
+            explanation_lines = result.explanation.split("\n")
+            for explanation_line in explanation_lines:
+                print(
+                    f"{message_indent}{self._color(explanation_line.strip(), 'gray')}"
+                )
+
         # Details (in verbose mode)
         if self.verbose and result.details:
             for key, value in result.details.items():
@@ -126,6 +151,11 @@ class DoctorReporter:
             if result.fix_description:
                 print(f"{fix_indent}  {self._color(result.fix_description, 'gray')}")
 
+        # Documentation link (issue #125)
+        if result.doc_link:
+            doc_indent = "   " + indent_str
+            print(f"{doc_indent}{self._color('📖 Docs:', 'blue')} {result.doc_link}")
+
         # Sub-results (in verbose mode)
         if self.verbose and result.sub_results:
             for sub_result in result.sub_results:

claude_mpm/services/diagnostics/models.py

@@ -51,9 +51,14 @@ class DiagnosticResult:
     fix_description: Optional[str] = None
     sub_results: List["DiagnosticResult"] = field(default_factory=list)
 
+    # Enhanced troubleshooting fields (issue #125)
+    explanation: str = ""  # What this check means and why it matters
+    severity: str = "medium"  # critical, high, medium, low, info
+    doc_link: str = ""  # Link to relevant documentation
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
-        return {
+        result = {
             "category": self.category,
             "status": self.status.value,
             "message": self.message,
@@ -62,6 +67,14 @@ class DiagnosticResult:
             "fix_description": self.fix_description,
             "sub_results": [r.to_dict() for r in self.sub_results],
         }
+        # Include enhanced fields if present
+        if self.explanation:
+            result["explanation"] = self.explanation
+        if self.severity != "medium":
+            result["severity"] = self.severity
+        if self.doc_link:
+            result["doc_link"] = self.doc_link
+        return result
 
     @property
     def has_issues(self) -> bool:

claude_mpm/services/event_bus/config.py

@@ -52,9 +52,11 @@ class EventBusConfig:
     )
 
     # Relay configuration
+    # DirectSocketIORelay disabled by default - events already emit via direct sio.emit()
+    # Enable with CLAUDE_MPM_RELAY_ENABLED=true if needed for external consumers
     relay_enabled: bool = field(
         default_factory=lambda: os.environ.get(
-            "CLAUDE_MPM_RELAY_ENABLED", "true"
+            "CLAUDE_MPM_RELAY_ENABLED", "false"
         ).lower()
         == "true"
     )