claude-mpm 5.4.85__py3-none-any.whl → 5.6.1__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/core/config.py

@@ -605,6 +605,11 @@ class Config:
                 "sync_interval": "startup",  # Options: "startup", "hourly", "daily", "manual"
                 "cache_dir": str(Path.home() / ".claude-mpm" / "cache" / "agents"),
             },
+            # Autotodos configuration
+            "autotodos": {
+                "auto_inject_on_startup": True,  # Auto-inject pending todos on PM session start
+                "max_todos_per_session": 10,  # Max todos to inject per session
+            },
         }
 
         # Apply defaults for missing keys

claude_mpm/core/hook_manager.py

@@ -16,13 +16,15 @@ import contextlib
 import json
 import os
 import queue
-import subprocess
+import subprocess  # nosec B404
 import threading
 import uuid
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
 from ..core.logger import get_logger
+from ..services.event_bus.event_bus import EventBus
+from ..services.event_log import get_event_log
 from .hook_error_memory import get_hook_error_memory
 from .hook_performance_config import get_hook_performance_config
 from .unified_paths import get_package_root
@@ -46,6 +48,10 @@ class HookManager:
         # Initialize error memory for tracking and preventing repeated errors
         self.error_memory = get_hook_error_memory()
 
+        # Initialize event log and event bus for event-driven architecture
+        self.event_log = get_event_log()
+        self.event_bus = EventBus.get_instance()
+
         # Initialize background hook processing for async execution
         self.performance_config = get_hook_performance_config()
         queue_config = self.performance_config.get_queue_config()
@@ -100,6 +106,45 @@ class HookManager:
         self.background_thread.start()
         self.logger.debug("Started background hook processor thread")
 
+    def _publish_error_event(
+        self, hook_type: str, error_info: Dict[str, str], suggestion: str
+    ):
+        """Publish hook error event to event log and event bus.
+
+        WHY publish events:
+        - Decouple error detection from error handling
+        - Enable autotodos CLI to read from persistent event log
+        - Support real-time notifications via event bus
+        - Maintain audit trail of all hook errors
+
+        Args:
+            hook_type: Type of hook that failed
+            error_info: Error information from error detection
+            suggestion: Fix suggestion from error memory
+        """
+        try:
+            # Prepare event payload
+            payload = {
+                "error_type": error_info["type"],
+                "hook_type": hook_type,
+                "details": error_info.get("details", ""),
+                "full_message": error_info.get("match", ""),
+                "suggested_fix": suggestion,
+                "source": "hook_manager",
+            }
+
+            # Publish to event log (persistent storage)
+            self.event_log.append_event(
+                event_type="autotodo.error", payload=payload, status="pending"
+            )
+
+            # Publish to event bus (real-time listeners)
+            self.event_bus.publish("autotodo.error", payload)
+
+        except Exception as e:
+            # Don't let event publishing break hook processing
+            self.logger.debug(f"Failed to publish error event: {e}")
+
     def _execute_hook_sync(self, hook_data: Dict[str, Any]):
         """Execute a single hook synchronously in the background thread with error detection.
 
@@ -141,7 +186,7 @@ class HookManager:
             env["CLAUDE_MPM_HOOK_DEBUG"] = "true"
 
             # Execute with timeout in background thread
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607
                 ["python", str(self.hook_handler_path)],
                 input=event_json,
                 text=True,
@@ -157,7 +202,7 @@ class HookManager:
             )
 
             if error_info:
-                # Record the error
+                # Record the error in memory (for skipping repeated failures)
                 self.error_memory.record_error(error_info, hook_type)
 
                 # Get fix suggestion
@@ -165,6 +210,9 @@ class HookManager:
 
                 # Log error with suggestion
                 self.logger.warning(f"Hook {hook_type} error detected:\n{suggestion}")
+
+                # Publish event to event log for autotodos processing
+                self._publish_error_event(hook_type, error_info, suggestion)
             elif result.returncode != 0:
                 # Non-zero return without detected pattern
                 self.logger.debug(f"Hook {hook_type} returned code {result.returncode}")

claude_mpm/core/logger.py

@@ -214,19 +214,22 @@ def setup_logging(
 
     # Console handler
     if console_output:
+        # MUST use stderr to avoid corrupting hook JSON output
+        # WHY stderr: Hook handlers output JSON to stdout. Logging to stdout
+        # corrupts this JSON and causes "hook error" messages from Claude Code.
         if use_streaming:
             # Use streaming handler for single-line INFO messages
-            console_handler = StreamingHandler(sys.stdout)
+            console_handler = StreamingHandler(sys.stderr)
             console_handler.setFormatter(simple_formatter)
         elif use_rich and not json_format:
             # Rich support has been removed, use standard handler
-            console_handler = logging.StreamHandler(sys.stdout)
+            console_handler = logging.StreamHandler(sys.stderr)
             console_handler.setFormatter(simple_formatter)
         else:
-            console_handler = logging.StreamHandler(sys.stdout)
+            console_handler = logging.StreamHandler(sys.stderr)
             console_handler.setFormatter(formatter if json_format else simple_formatter)
 
-        console_handler.setLevel(logging.INFO)
+        console_handler.setLevel(log_level)  # Respect the requested log level
         logger.addHandler(console_handler)
 
     # File handler
@@ -263,7 +266,7 @@ def setup_logging(
                 if deleted_count > 0:
                     # Log to the new file handler that we're about to add
                     pass  # Deletion count will be logged when logger is ready
-            except Exception:
+            except Exception:  # nosec B110 - intentional: logging should not break app
                 pass  # Ignore cleanup errors
 
             # Also create a symlink to latest log (with thread safety)
@@ -305,7 +308,7 @@ def setup_logging(
                     # Fallback: try to create a regular file with reference to actual log
                     try:
                         latest_link.write_text(f"Latest log: {log_file.name}\n")
-                    except Exception:
+                    except Exception:  # nosec B110 - intentional: logging should not break app
                         pass  # Silently fail - logging should not break the application
                 except Exception as e:
                     # Catch any other unexpected errors to ensure logging doesn't break
@@ -381,7 +384,7 @@ def cleanup_old_mpm_logs(
             try:
                 log_file.unlink()
                 deleted_count += 1
-            except Exception:
+            except Exception:  # nosec B110 - intentional: log cleanup is best-effort
                 pass  # Ignore deletion errors
 
         return deleted_count

claude_mpm/core/logging_utils.py

@@ -108,8 +108,10 @@ class LoggerFactory:
         # Remove existing handlers
         root_logger.handlers = []
 
-        # Console handler
-        console_handler = logging.StreamHandler(sys.stdout)
+        # Console handler - MUST use stderr to avoid corrupting hook JSON output
+        # WHY stderr: Hook handlers output JSON to stdout. Logging to stdout
+        # corrupts this JSON and causes "hook error" messages from Claude Code.
+        console_handler = logging.StreamHandler(sys.stderr)
         console_handler.setLevel(LoggingConfig.LEVELS.get(cls._log_level, logging.INFO))
         console_formatter = logging.Formatter(
             log_format or LoggingConfig.DEFAULT_FORMAT,

claude_mpm/core/output_style_manager.py

@@ -27,7 +27,9 @@ _CACHED_CLAUDE_VERSION: Optional[str] = None
 _VERSION_DETECTED: bool = False
 
 # Output style types
-OutputStyleType = Literal["professional", "teaching", "founders"]
+OutputStyleType = Literal[
+    "professional", "teaching", "research", "founders"
+]  # "founders" is deprecated, use "research"
 
 
 class StyleConfig(TypedDict):
@@ -44,7 +46,7 @@ class OutputStyleManager:
     Supports three output styles:
     - professional: Default Claude MPM style (claude-mpm.md)
     - teaching: Adaptive teaching mode (claude-mpm-teacher.md)
-    - founders: Non-technical mode for startup founders (claude-mpm-founders.md)
+    - research: Codebase research mode for founders, PMs, and developers (claude-mpm-research.md)
     """
 
     def __init__(self) -> None:
@@ -72,12 +74,20 @@ class OutputStyleManager:
                 target=self.output_style_dir / "claude-mpm-teacher.md",
                 name="Claude MPM Teacher",
             ),
+            "research": StyleConfig(
+                source=Path(__file__).parent.parent
+                / "agents"
+                / "CLAUDE_MPM_RESEARCH_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-research.md",
+                name="Claude MPM Research",
+            ),
+            # Backward compatibility alias (deprecated)
             "founders": StyleConfig(
                 source=Path(__file__).parent.parent
                 / "agents"
-                / "CLAUDE_MPM_FOUNDERS_OUTPUT_STYLE.md",
-                target=self.output_style_dir / "claude-mpm-founders.md",
-                name="Claude MPM Founders",
+                / "CLAUDE_MPM_RESEARCH_OUTPUT_STYLE.md",
+                target=self.output_style_dir / "claude-mpm-research.md",
+                name="Claude MPM Research",
             ),
         }
 

claude_mpm/core/unified_config.py

@@ -73,15 +73,19 @@ class AgentConfig(BaseModel):
     )
 
     # Required agents that are always deployed
+    # Standard 7 core agents for essential PM workflow functionality
+    # These are auto-deployed when no agents are specified in configuration
     required: List[str] = Field(
         default_factory=lambda: [
-            "research",
-            "mpm-skills-manager",
-            "mpm-agent-manager",
-            "memory-manager",
-            "ticketing",
+            "engineer",  # General-purpose implementation
+            "research",  # Codebase exploration and analysis
+            "qa",  # Testing and quality assurance
+            "web-qa",  # Browser-based testing specialist
+            "documentation",  # Documentation generation
+            "ops",  # Basic deployment operations
+            "ticketing",  # Ticket tracking (essential for PM workflow)
         ],
-        description="Agents that are always deployed (core system agents)",
+        description="Agents that are always deployed (standard 7 core agents)",
     )
 
     include_universal: bool = Field(