claude-mpm 4.1.10__py3-none-any.whl → 4.1.12__py3-none-any.whl

claude_mpm/cli/parsers/mpm_init_parser.py

@@ -0,0 +1,128 @@
+"""
+MPM-Init parser module for claude-mpm CLI.
+
+WHY: This module handles the mpm-init command parser configuration,
+providing a clean interface for initializing projects with optimal
+Claude Code and Claude MPM standards.
+"""
+
+import argparse
+from typing import Any
+
+
+def add_mpm_init_subparser(subparsers: Any) -> None:
+    """
+    Add the mpm-init subparser to the main parser.
+
+    WHY: The mpm-init command sets up projects for optimal use with
+    Claude Code and Claude MPM by delegating to the Agentic Coder Optimizer.
+
+    Args:
+        subparsers: The subparsers object to add the mpm-init command to
+    """
+    mpm_init_parser = subparsers.add_parser(
+        "mpm-init",
+        help="Initialize project for optimal Claude Code and Claude MPM usage",
+        description=(
+            "Initialize a project with comprehensive documentation, single-path workflows, "
+            "and optimized structure for AI agent understanding. Uses the Agentic Coder "
+            "Optimizer agent to establish clear standards and remove ambiguity."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  claude-mpm mpm-init                          # Initialize current directory\n"
+            "  claude-mpm mpm-init --project-type web       # Initialize as web project\n"
+            "  claude-mpm mpm-init --framework react        # Initialize with React framework\n"
+            "  claude-mpm mpm-init /path/to/project --force # Force reinitialize project"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Project configuration options
+    config_group = mpm_init_parser.add_argument_group("project configuration")
+    config_group.add_argument(
+        "--project-type",
+        choices=[
+            "web",
+            "api",
+            "cli",
+            "library",
+            "mobile",
+            "desktop",
+            "fullstack",
+            "data",
+            "ml",
+        ],
+        help="Type of project to initialize (auto-detected if not specified)",
+    )
+    config_group.add_argument(
+        "--framework",
+        type=str,
+        help="Specific framework to configure (e.g., react, vue, django, fastapi, express)",
+    )
+    config_group.add_argument(
+        "--language",
+        choices=["python", "javascript", "typescript", "go", "rust", "java", "cpp"],
+        help="Primary programming language (auto-detected if not specified)",
+    )
+
+    # Initialization options
+    init_group = mpm_init_parser.add_argument_group("initialization options")
+    init_group.add_argument(
+        "--force",
+        action="store_true",
+        help="Force reinitialization even if project is already configured",
+    )
+    init_group.add_argument(
+        "--minimal",
+        action="store_true",
+        help="Create minimal configuration (CLAUDE.md only, no additional setup)",
+    )
+    init_group.add_argument(
+        "--comprehensive",
+        action="store_true",
+        help="Create comprehensive setup including CI/CD, testing, and deployment configs",
+    )
+    init_group.add_argument(
+        "--use-venv",
+        action="store_true",
+        help="Use traditional Python venv instead of mamba/conda environment",
+    )
+
+    # Template options
+    template_group = mpm_init_parser.add_argument_group("template options")
+    template_group.add_argument(
+        "--template",
+        type=str,
+        help="Use a specific template from claude-mpm templates library",
+    )
+    template_group.add_argument(
+        "--list-templates", action="store_true", help="List available project templates"
+    )
+
+    # Output options
+    output_group = mpm_init_parser.add_argument_group("output options")
+    output_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without making changes",
+    )
+    output_group.add_argument(
+        "--json", action="store_true", help="Output results in JSON format"
+    )
+    output_group.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed output during initialization",
+    )
+
+    # Path argument
+    mpm_init_parser.add_argument(
+        "project_path",
+        nargs="?",
+        default=".",
+        help="Path to project directory (default: current directory)",
+    )
+
+    # Set the command handler
+    mpm_init_parser.set_defaults(command="mpm-init")

claude_mpm/constants.py

@@ -43,6 +43,7 @@ class CLICommands(str, Enum):
     CLEANUP = "cleanup-memory"
     MCP = "mcp"
     DOCTOR = "doctor"
+    DASHBOARD = "dashboard"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -99,6 +100,15 @@ class MonitorCommands(str, Enum):
     PORT = "port"
 
 
+class DashboardCommands(str, Enum):
+    """Dashboard subcommand constants."""
+
+    START = "start"
+    STOP = "stop"
+    STATUS = "status"
+    OPEN = "open"
+
+
 class ConfigCommands(str, Enum):
     """Config subcommand constants."""
 

claude_mpm/core/config.py

@@ -533,6 +533,24 @@ class Config:
                 "exclude_dependencies": False,  # Whether to exclude agent dependencies too
                 "case_sensitive": False,  # Whether agent name matching is case-sensitive
             },
+            # Instruction reinforcement system configuration
+            "instruction_reinforcement": {
+                "enabled": True,
+                "test_mode": True,
+                "injection_interval": 5,
+                "test_messages": [
+                    "[TEST-REMINDER] This is an injected instruction reminder",
+                    "[PM-INSTRUCTION] Remember to delegate all work to agents",
+                    "[PM-INSTRUCTION] Do not use Edit, Write, or Bash tools directly",
+                    "[PM-INSTRUCTION] Your role is orchestration and coordination",
+                ],
+                "production_messages": [
+                    "[PM-REMINDER] Delegate implementation tasks to specialized agents",
+                    "[PM-REMINDER] Use Task tool for all work delegation",
+                    "[PM-REMINDER] Focus on orchestration, not implementation",
+                    "[PM-REMINDER] Your role is coordination and management",
+                ],
+            },
         }
 
         # Apply defaults for missing keys

claude_mpm/core/instruction_reinforcement_hook.py

@@ -0,0 +1,266 @@
+"""Instruction Reinforcement Hook for PM instruction drift prevention.
+
+This module implements a hook that intercepts TodoWrite calls and injects
+reminder messages at configurable intervals to combat PM instruction drift
+during long conversations.
+
+WHY this is needed:
+- PM agents can drift from their original instructions during long sessions
+- Direct tool usage (Edit, Write, Bash) is a common drift pattern
+- Reminder injection via TodoWrite is a non-intrusive way to reinforce instructions
+- Configurable intervals and message rotation provide flexibility
+
+The hook works by:
+1. Tracking TodoWrite call count
+2. Injecting reminders at configured intervals (default: every 5 calls)
+3. Rotating through multiple reminder messages
+4. Providing metrics for monitoring effectiveness
+"""
+
+import threading
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from ..core.logger import get_logger
+
+
+class InstructionReinforcementHook:
+    """Hook for injecting instruction reminders into TodoWrite calls.
+
+    This class intercepts TodoWrite operations and periodically injects
+    reminder messages to help prevent PM instruction drift.
+
+    Key features:
+    - Configurable injection intervals
+    - Message rotation for variety
+    - Thread-safe operation
+    - Metrics tracking
+    - Test mode support
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        """Initialize the instruction reinforcement hook.
+
+        Args:
+            config: Configuration dictionary with optional keys:
+                - enabled: Whether the hook is enabled (default: True)
+                - test_mode: Whether to use test messages (default: True)
+                - injection_interval: Calls between injections (default: 5)
+                - test_messages: List of test messages to rotate through
+        """
+        self.logger = get_logger("instruction_reinforcement_hook")
+
+        # Initialize configuration
+        config = config or {}
+        self.enabled = config.get("enabled", True)
+        self.test_mode = config.get("test_mode", True)
+        self.injection_interval = config.get("injection_interval", 5)
+
+        # Thread-safe counters
+        self._lock = threading.Lock()
+        self.call_count = 0
+        self.injection_count = 0
+        self.message_index = 0
+
+        # Default test messages (will be used in test_mode)
+        self.test_messages = config.get(
+            "test_messages",
+            [
+                "[TEST-REMINDER] This is an injected instruction reminder",
+                "[PM-INSTRUCTION] Remember to delegate all work to agents",
+                "[PM-INSTRUCTION] Do not use Edit, Write, or Bash tools directly",
+                "[PM-INSTRUCTION] Your role is orchestration and coordination",
+            ],
+        )
+
+        # Production messages (used when test_mode=False)
+        self.production_messages = [
+            "[STOP] Are you about to use Edit/Write/Bash? Delegate to Engineer instead!",
+            "[DELEGATE] Your job is coordination, not implementation - pass this to an agent",
+            "[REMINDER] PM = Project Manager, not Project Implementer - delegate this work",
+            "[CHECK] If you're reading code files, stop and delegate to Research Agent",
+            "[WARNING] Direct implementation detected - use 'do this yourself' to override",
+        ]
+
+        self.logger.info(
+            f"InstructionReinforcementHook initialized: "
+            f"enabled={self.enabled}, test_mode={self.test_mode}, "
+            f"interval={self.injection_interval}"
+        )
+
+    def intercept_todowrite(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Intercept TodoWrite parameters and potentially inject reminders.
+
+        Args:
+            params: TodoWrite parameters dictionary containing 'todos' list
+
+        Returns:
+            Modified parameters with potentially injected reminders
+        """
+        if not self.enabled:
+            return params
+
+        try:
+            # Extract todos safely
+            todos = params.get("todos", [])
+            if not isinstance(todos, list):
+                self.logger.warning("Invalid todos format - skipping injection")
+                return params
+
+            with self._lock:
+                self.call_count += 1
+
+                # Check if we should inject
+                if self.should_inject():
+                    modified_todos = self.inject_reminders(todos)
+                    params = params.copy()  # Don't modify original
+                    params["todos"] = modified_todos
+                    self.injection_count += 1
+
+                    self.logger.info(
+                        f"Injected reminder #{self.injection_count} at call #{self.call_count}"
+                    )
+
+            return params
+
+        except Exception as e:
+            self.logger.error(f"Error in TodoWrite interception: {e}")
+            # Return original params on error to avoid breaking functionality
+            return params
+
+    def should_inject(self) -> bool:
+        """Determine if a reminder should be injected.
+
+        Returns:
+            True if injection should occur
+        """
+        if not self.enabled:
+            return False
+
+        return self.call_count % self.injection_interval == 0
+
+    def inject_reminders(self, todos: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Inject reminder message into todos list.
+
+        Args:
+            todos: Original todos list
+
+        Returns:
+            Modified todos list with reminder injected at the beginning
+        """
+        # Choose message set based on mode
+        messages = self.test_messages if self.test_mode else self.production_messages
+
+        # Get next message (rotate through available messages)
+        message = messages[self.message_index % len(messages)]
+        self.message_index += 1
+
+        # Create reminder todo
+        reminder_todo = {
+            "content": message,
+            "status": "pending",
+            "activeForm": "Processing instruction reminder",
+        }
+
+        # Insert at beginning of todos list
+        modified_todos = todos.copy()
+        modified_todos.insert(0, reminder_todo)
+
+        self.logger.debug(f"Injected reminder: {message}")
+
+        return modified_todos
+
+    def get_metrics(self) -> Dict[str, Any]:
+        """Get current hook metrics.
+
+        Returns:
+            Dictionary containing metrics:
+            - call_count: Total TodoWrite calls processed
+            - injection_count: Total reminders injected
+            - injection_rate: Ratio of injections to calls
+            - next_injection_in: Calls until next injection
+            - enabled: Whether hook is enabled
+            - test_mode: Whether using test messages
+        """
+        with self._lock:
+            next_injection = self.injection_interval - (
+                self.call_count % self.injection_interval
+            )
+            if next_injection == self.injection_interval:
+                next_injection = 0  # Next call will trigger injection
+
+            return {
+                "call_count": self.call_count,
+                "injection_count": self.injection_count,
+                "injection_rate": self.injection_count / max(self.call_count, 1),
+                "next_injection_in": next_injection,
+                "enabled": self.enabled,
+                "test_mode": self.test_mode,
+                "injection_interval": self.injection_interval,
+                "timestamp": datetime.utcnow().isoformat(),
+            }
+
+    def reset_counters(self):
+        """Reset all counters to zero.
+
+        Useful for testing or starting fresh tracking.
+        """
+        with self._lock:
+            self.call_count = 0
+            self.injection_count = 0
+            self.message_index = 0
+
+        self.logger.info("Reset instruction reinforcement counters")
+
+    def update_config(self, config: Dict[str, Any]):
+        """Update hook configuration.
+
+        Args:
+            config: New configuration values
+        """
+        if "enabled" in config:
+            self.enabled = config["enabled"]
+        if "test_mode" in config:
+            self.test_mode = config["test_mode"]
+        if "injection_interval" in config:
+            self.injection_interval = max(1, config["injection_interval"])  # Minimum 1
+        if "test_messages" in config:
+            self.test_messages = config["test_messages"]
+
+        self.logger.info(f"Updated configuration: {config}")
+
+
+# Global instance for singleton pattern
+_instruction_reinforcement_hook: Optional[InstructionReinforcementHook] = None
+_hook_lock = threading.Lock()
+
+
+def get_instruction_reinforcement_hook(
+    config: Optional[Dict[str, Any]] = None,
+) -> InstructionReinforcementHook:
+    """Get the global instruction reinforcement hook instance.
+
+    Args:
+        config: Configuration for first-time initialization
+
+    Returns:
+        InstructionReinforcementHook instance
+    """
+    global _instruction_reinforcement_hook
+
+    with _hook_lock:
+        if _instruction_reinforcement_hook is None:
+            _instruction_reinforcement_hook = InstructionReinforcementHook(config)
+
+    return _instruction_reinforcement_hook
+
+
+def reset_instruction_reinforcement_hook():
+    """Reset the global hook instance.
+
+    Primarily used for testing to ensure clean state.
+    """
+    global _instruction_reinforcement_hook
+
+    with _hook_lock:
+        _instruction_reinforcement_hook = None

claude_mpm/core/pm_hook_interceptor.py

@@ -19,6 +19,7 @@ from typing import Any, Dict, List, Optional
 
 from ..core.hook_manager import get_hook_manager
 from ..core.logger import get_logger
+from .instruction_reinforcement_hook import get_instruction_reinforcement_hook
 
 
 class PMHookInterceptor:
@@ -31,11 +32,16 @@ class PMHookInterceptor:
     - Provides real-time event streaming for PM operations
     """
 
-    def __init__(self):
+    def __init__(self, instruction_reinforcement_config=None):
         self.logger = get_logger("pm_hook_interceptor")
         self.hook_manager = get_hook_manager()
         self._in_intercept = threading.local()  # Prevent recursion
 
+        # Initialize instruction reinforcement hook
+        self.instruction_reinforcement_hook = get_instruction_reinforcement_hook(
+            instruction_reinforcement_config
+        )
+
     def intercept_todowrite(self, original_function):
         """Decorator to intercept TodoWrite calls and trigger hooks.
 
@@ -58,12 +64,29 @@ class PMHookInterceptor:
                 # Extract todos from arguments
                 todos = self._extract_todos_from_args(args, kwargs)
 
+                # Apply instruction reinforcement hook (modify parameters if needed)
+                params = {"todos": todos}
+                modified_params = (
+                    self.instruction_reinforcement_hook.intercept_todowrite(params)
+                )
+                modified_todos = modified_params.get("todos", todos)
+
+                # Update args/kwargs with potentially modified todos
+                if modified_todos != todos:
+                    args, kwargs = self._update_args_with_todos(
+                        args, kwargs, modified_todos
+                    )
+                    self.logger.debug(
+                        f"Applied instruction reinforcement: {len(modified_todos)} todos"
+                    )
+
                 # Trigger pre-tool hook
                 self.hook_manager.trigger_pre_tool_hook(
-                    "TodoWrite", {"todos": todos, "source": "PM", "intercepted": True}
+                    "TodoWrite",
+                    {"todos": modified_todos, "source": "PM", "intercepted": True},
                 )
 
-                # Call the original function
+                # Call the original function with potentially modified arguments
                 result = original_function(*args, **kwargs)
 
                 # Trigger post-tool hook
@@ -71,14 +94,18 @@ class PMHookInterceptor:
                     "TodoWrite",
                     0,
                     {
-                        "todos_count": len(todos) if todos else 0,
+                        "todos_count": len(modified_todos) if modified_todos else 0,
+                        "original_todos_count": len(todos) if todos else 0,
                         "source": "PM",
                         "success": True,
+                        "instruction_reinforcement_applied": len(modified_todos)
+                        != len(todos),
                     },
                 )
 
                 self.logger.debug(
-                    f"Successfully intercepted TodoWrite with {len(todos) if todos else 0} todos"
+                    f"Successfully intercepted TodoWrite with {len(modified_todos) if modified_todos else 0} todos "
+                    f"(original: {len(todos) if todos else 0})"
                 )
 
                 return result
@@ -119,6 +146,39 @@ class PMHookInterceptor:
 
         return []
 
+    def _update_args_with_todos(
+        self, args, kwargs, modified_todos: List[Dict[str, Any]]
+    ):
+        """Update function arguments with modified todos list.
+
+        Args:
+            args: Original positional arguments
+            kwargs: Original keyword arguments
+            modified_todos: Modified todos list to inject
+
+        Returns:
+            Tuple of (updated_args, updated_kwargs)
+        """
+        # Update kwargs if todos was passed as keyword argument
+        if "todos" in kwargs:
+            kwargs = kwargs.copy()
+            kwargs["todos"] = modified_todos
+            return args, kwargs
+
+        # Update positional args if todos was passed positionally
+        args_list = list(args)
+        for i, arg in enumerate(args_list):
+            if isinstance(arg, list) and arg and isinstance(arg[0], dict):
+                # Check if this looks like a todos list
+                if "content" in arg[0] or "id" in arg[0]:
+                    args_list[i] = modified_todos
+                    return tuple(args_list), kwargs
+
+        # If we can't find where todos was passed, add as keyword argument
+        kwargs = kwargs.copy()
+        kwargs["todos"] = modified_todos
+        return args, kwargs
+
     def trigger_manual_todowrite_hooks(self, todos: List[Dict[str, Any]]):
         """Manually trigger TodoWrite hooks for given todos.
 
@@ -169,16 +229,37 @@ class PMHookInterceptor:
             self.logger.error(f"Error manually triggering TodoWrite hooks: {e}")
             return False
 
+    def get_instruction_reinforcement_metrics(self) -> Dict[str, Any]:
+        """Get metrics from the instruction reinforcement hook.
+
+        Returns:
+            Dictionary containing reinforcement metrics
+        """
+        return self.instruction_reinforcement_hook.get_metrics()
+
+    def reset_instruction_reinforcement_counters(self):
+        """Reset instruction reinforcement counters."""
+        self.instruction_reinforcement_hook.reset_counters()
+        self.logger.info("Reset instruction reinforcement counters via PM interceptor")
+
 
 # Global instance
 _pm_hook_interceptor: Optional[PMHookInterceptor] = None
 
 
-def get_pm_hook_interceptor() -> PMHookInterceptor:
-    """Get the global PM hook interceptor instance."""
+def get_pm_hook_interceptor(instruction_reinforcement_config=None) -> PMHookInterceptor:
+    """Get the global PM hook interceptor instance.
+
+    Args:
+        instruction_reinforcement_config: Configuration for instruction reinforcement hook
+                                        (only used on first initialization)
+
+    Returns:
+        PMHookInterceptor instance
+    """
     global _pm_hook_interceptor
     if _pm_hook_interceptor is None:
-        _pm_hook_interceptor = PMHookInterceptor()
+        _pm_hook_interceptor = PMHookInterceptor(instruction_reinforcement_config)
     return _pm_hook_interceptor
 
 
@@ -215,3 +296,19 @@ def simulate_pm_todowrite_operation(todos: List[Dict[str, Any]]):
 
     # Log completion
     logger.info("PM TodoWrite simulation completed")
+
+
+def get_instruction_reinforcement_metrics() -> Dict[str, Any]:
+    """Get instruction reinforcement metrics from the global PM hook interceptor.
+
+    Returns:
+        Dictionary containing reinforcement metrics
+    """
+    interceptor = get_pm_hook_interceptor()
+    return interceptor.get_instruction_reinforcement_metrics()
+
+
+def reset_instruction_reinforcement_counters():
+    """Reset instruction reinforcement counters in the global PM hook interceptor."""
+    interceptor = get_pm_hook_interceptor()
+    interceptor.reset_instruction_reinforcement_counters()