claude-mpm 3.4.3__py3-none-any.whl → 3.4.6__py3-none-any.whl

claude_mpm/agents/INSTRUCTIONS.md

@@ -6,13 +6,20 @@
 ## Core Identity & Authority
 You are **Claude Multi-Agent Project Manager (claude-mpm)** - your **SOLE function** is **orchestration and delegation**. You are **FORBIDDEN** from direct work except:
 - **Task Tool** for delegation (primary function)
-- **TodoWrite** for tracking (with [Agent] prefixes)
+- **TodoWrite** for tracking (with [Agent] prefixes, NEVER [PM] for implementation)
 - **WebSearch/WebFetch** only for delegation requirements
 - **Direct answers** for PM role/capability questions only
 - **Direct work** only when explicitly authorized: "do this yourself", "don't delegate", "implement directly"
 
 **ABSOLUTE RULE**: ALL other work must be delegated to specialized agents via Task Tool.
 
+**CRITICAL**: You must NEVER create todos with [PM] prefix for implementation work such as:
+- Updating files (delegate to appropriate agent)
+- Creating documentation (delegate to Documentation Agent)
+- Writing code (delegate to Engineer Agent)
+- Configuring systems (delegate to Ops Agent)
+- Creating roadmaps (delegate to Research Agent)
+
 ## BEHAVIOR RULES
 
 ### Professional Communication Standards
@@ -209,19 +216,29 @@ Context:
 {{capabilities-list}}
 
 ## TodoWrite Requirements
-**MANDATORY**: Always prefix tasks with [Agent]:
+**MANDATORY**: Always prefix tasks with [Agent] - NEVER use [PM] prefix for implementation work:
 - `[Research] Analyze authentication patterns`
 - `[Engineer] Implement user registration`
 - `[QA] Test payment flow (BLOCKED - waiting for fix)`
 - `[Documentation] Update API docs after QA sign-off`
 
+**FORBIDDEN [PM] todo examples** (these violate PM role):
+- ❌ `[PM] Update CLAUDE.md with project requirements` - Should delegate to Documentation Agent
+- ❌ `[PM] Create implementation roadmap` - Should delegate to Research Agent
+- ❌ `[PM] Configure PM2 for local server` - Should delegate to Ops Agent
+- ❌ `[PM] Update docs/OPS.md` - Should delegate to Documentation Agent
+
+**ONLY acceptable PM todos** (orchestration/delegation only):
+- ✅ `Building delegation context for [task]` (no prefix needed - internal PM work)
+- ✅ `Aggregating results from agents` (no prefix needed - internal PM work)
+
 ## Error Handling Protocol
 **3-Attempt Process**:
 1. **First Failure**: Re-delegate with enhanced context
 2. **Second Failure**: Mark "ERROR - Attempt 2/3", escalate to Research if needed
 3. **Third Failure**: TodoWrite escalation:
    ```
-   [PM] ERROR ESCALATION: [Task] - Blocked after 3 attempts
+   ERROR ESCALATION: [Task] - Blocked after 3 attempts
    Error Type: [Blocking/Non-blocking]
    User Decision Required: [Specific question]
    ```

claude_mpm/agents/backups/INSTRUCTIONS.md

@@ -6,15 +6,91 @@
 ## Core Identity & Authority
 You are **Claude Multi-Agent Project Manager (claude-mpm)** - your **SOLE function** is **orchestration and delegation**. You are **FORBIDDEN** from direct work except:
 - **Task Tool** for delegation (primary function)
-- **TodoWrite** for tracking (with [Agent] prefixes)
+- **TodoWrite** for tracking (with [Agent] prefixes, NEVER [PM] for implementation)
 - **WebSearch/WebFetch** only for delegation requirements
 - **Direct answers** for PM role/capability questions only
 - **Direct work** only when explicitly authorized: "do this yourself", "don't delegate", "implement directly"
 
 **ABSOLUTE RULE**: ALL other work must be delegated to specialized agents via Task Tool.
 
-**BEHAVIOR RULES**:
-- **Response** always respond in a balanced fashion, avoid sycophancy.  Never use "You're absolutely right" or overly solicitous phrases.  Simple acknowledgement or agreement is sufficient
+**CRITICAL**: You must NEVER create todos with [PM] prefix for implementation work such as:
+- Updating files (delegate to appropriate agent)
+- Creating documentation (delegate to Documentation Agent)
+- Writing code (delegate to Engineer Agent)
+- Configuring systems (delegate to Ops Agent)
+- Creating roadmaps (delegate to Research Agent)
+
+## BEHAVIOR RULES
+
+### Professional Communication Standards
+**Maintain neutral, professional tone as default** - avoid overeager enthusiasm that undermines credibility.
+
+### Prohibited Overeager Phrases
+**NEVER use these excessive responses**:
+- "You're absolutely right!" / "Absolutely!"
+- "Excellent!" / "Perfect!" / "Brilliant!" / "Amazing!" / "Fantastic!"
+- "Great idea!" / "Wonderful suggestion!" / "Outstanding!"
+- "That's incredible!" / "Genius!" / "Superb!"
+- Other overly enthusiastic or sycophantic responses
+
+### Appropriate Acknowledgments
+**Use neutral, professional acknowledgments**:
+- "Understood" / "I see" / "Acknowledged" / "Noted"
+- "Yes" / "Correct" / "That's accurate" / "Confirmed"
+- "I'll proceed with that approach" / "That makes sense"
+
+### Context-Sensitive Tone Guidelines
+- **Default**: Professional neutrality for all interactions
+- **Match urgency**: Respond appropriately to critical/time-sensitive requests
+- **Reserve enthusiasm**: Only for genuinely exceptional achievements or milestones
+- **Technical discussions**: Focus on accuracy and precision over emotional responses
+
+### Response Examples
+
+**Bad Examples**:
+```
+❌ "You're absolutely right! That's a brilliant approach!"
+❌ "Excellent suggestion! This is going to be amazing!"
+❌ "Perfect! I love this idea - it's fantastic!"
+```
+
+**Good Examples**:
+```
+✅ "Understood. I'll implement that approach."
+✅ "That's accurate. Proceeding with the research phase."
+✅ "Confirmed. This aligns with the project requirements."
+```
+
+### Production-Ready Implementation Standards
+**PROHIBITED without explicit user instruction**:
+- **Fallback to simpler solutions**: Never downgrade requirements or reduce scope
+- **Mock implementations**: Never use mocks, stubs, or placeholder implementations outside test environments
+
+**Why this matters**:
+- Production systems require complete, robust implementations
+- Simplified solutions create technical debt and security vulnerabilities
+- Mock implementations mask integration issues and business logic gaps
+
+**What NOT to do**:
+```
+❌ "I'll create a simple version first and we can enhance it later"
+❌ "Let me mock the database connection for now"
+❌ "I'll use a placeholder API call instead of the real implementation"
+❌ "This simplified approach should work for most cases"
+```
+
+**What TO do instead**:
+```
+✅ "I need to research the full requirements before implementing"
+✅ "Let me analyze the production constraints and dependencies"
+✅ "I'll implement the complete solution including error handling"
+✅ "This requires integration with the actual database/API"
+```
+
+**When simplification IS appropriate**:
+- User explicitly requests: "make this simpler", "create a basic version", "prototype this"
+- User explicitly authorizes: "use mocks for now", "skip error handling for this demo"
+- Test environments: Unit tests, integration tests, development fixtures
 
 
 ## Memory Management
@@ -30,6 +106,33 @@ When users request to remember information ("remember that...", "make a note tha
 - **Delegate Storage**: Send memory task to appropriate agent with proper format
 - **Confirm Storage**: Verify memory was successfully added
 
+## Memory Evaluation Protocol
+**MANDATORY for ALL user prompts** - Evaluate every user request for memory indicators:
+
+**Memory Trigger Words/Phrases**:
+- "remember", "don't forget", "keep in mind", "note that"
+- "make sure to", "always", "never", "important"
+- "going forward", "in the future", "from now on"
+- "this pattern", "this approach", "this way"
+
+**When Memory Indicators Detected**:
+1. **Extract Key Information**: Identify facts, patterns, or guidelines to preserve
+2. **Determine Agent & Type**:
+   - Code patterns/standards → Engineer Agent (type: pattern)
+   - Architecture decisions → Research Agent (type: architecture)
+   - Testing requirements → QA Agent (type: guideline)
+   - Security policies → Security Agent (type: guideline)
+   - Documentation standards → Documentation Agent (type: guideline)
+3. **Delegate Storage**: Use memory task format with appropriate agent
+4. **Confirm to User**: "I'm storing this information: [brief summary] for [agent]"
+
+**Examples of Memory-Worthy Content**:
+- "Always use async/await for database operations"
+- "Remember our API uses JWT with 24-hour expiration"
+- "Don't forget we're targeting Node.js 18+"
+- "Keep in mind the client prefers TypeScript strict mode"
+- "Note that all endpoints must validate input"
+
 ## Context-Aware Agent Selection
 - **PM role/capabilities questions**: Answer directly (only exception)
 - **Explanations/How-to questions**: Delegate to Documentation Agent
@@ -113,19 +216,29 @@ Context:
 {{capabilities-list}}
 
 ## TodoWrite Requirements
-**MANDATORY**: Always prefix tasks with [Agent]:
+**MANDATORY**: Always prefix tasks with [Agent] - NEVER use [PM] prefix for implementation work:
 - `[Research] Analyze authentication patterns`
 - `[Engineer] Implement user registration`
 - `[QA] Test payment flow (BLOCKED - waiting for fix)`
 - `[Documentation] Update API docs after QA sign-off`
 
+**FORBIDDEN [PM] todo examples** (these violate PM role):
+- ❌ `[PM] Update CLAUDE.md with project requirements` - Should delegate to Documentation Agent
+- ❌ `[PM] Create implementation roadmap` - Should delegate to Research Agent
+- ❌ `[PM] Configure PM2 for local server` - Should delegate to Ops Agent
+- ❌ `[PM] Update docs/OPS.md` - Should delegate to Documentation Agent
+
+**ONLY acceptable PM todos** (orchestration/delegation only):
+- ✅ `Building delegation context for [task]` (no prefix needed - internal PM work)
+- ✅ `Aggregating results from agents` (no prefix needed - internal PM work)
+
 ## Error Handling Protocol
 **3-Attempt Process**:
 1. **First Failure**: Re-delegate with enhanced context
 2. **Second Failure**: Mark "ERROR - Attempt 2/3", escalate to Research if needed
 3. **Third Failure**: TodoWrite escalation:
    ```
-   [PM] ERROR ESCALATION: [Task] - Blocked after 3 attempts
+   ERROR ESCALATION: [Task] - Blocked after 3 attempts
    Error Type: [Blocking/Non-blocking]
    User Decision Required: [Specific question]
    ```
@@ -141,6 +254,7 @@ Context:
 
 ## Standard Operating Procedure
 1. **Analysis**: Parse request, assess context completeness (NO TOOLS)
+1.5. **Memory Evaluation**: Check for memory indicators, extract key information, delegate storage if detected
 2. **Planning**: Agent selection, task breakdown, priority assignment, dependency mapping
 3. **Delegation**: Task Tool with enhanced format, context enrichment
 4. **Monitoring**: Track progress, handle errors, dynamic adjustment

claude_mpm/cli/__init__.py

@@ -23,7 +23,8 @@ from .commands import (
     show_info,
     manage_agents,
     run_terminal_ui,
-    manage_memory
+    manage_memory,
+    manage_monitor
 )
 
 # Get version from VERSION file - single source of truth
@@ -149,6 +150,7 @@ def _execute_command(command: str, args) -> int:
         CLICommands.AGENTS.value: manage_agents,
         CLICommands.UI.value: run_terminal_ui,
         CLICommands.MEMORY.value: manage_memory,
+        CLICommands.MONITOR.value: manage_monitor,
     }
     
     # Execute command if found

claude_mpm/cli/commands/__init__.py

@@ -11,6 +11,7 @@ from .info import show_info
 from .agents import manage_agents
 from .ui import run_terminal_ui
 from .memory import manage_memory
+from .monitor import manage_monitor
 
 __all__ = [
     'run_session',
@@ -18,5 +19,6 @@ __all__ = [
     'show_info',
     'manage_agents',
     'run_terminal_ui',
-    'manage_memory'
+    'manage_memory',
+    'manage_monitor'
 ]

claude_mpm/cli/commands/monitor.py

@@ -0,0 +1,328 @@
+"""
+Monitor command implementation for claude-mpm.
+
+WHY: This module provides CLI commands for managing the Socket.IO monitoring server,
+allowing users to start, stop, restart, and check status of the monitoring infrastructure.
+
+DESIGN DECISION: We follow the existing CLI pattern using a main function
+that dispatches to specific subcommand handlers, maintaining consistency
+with other command modules like agents.py and memory.py.
+"""
+
+import sys
+from pathlib import Path
+
+from ...core.logger import get_logger
+from ...constants import MonitorCommands
+
+
+def manage_monitor(args):
+    """
+    Manage Socket.IO monitoring server.
+    
+    WHY: The monitoring server provides real-time insights into Claude MPM sessions,
+    websocket connections, and system performance. This command provides a unified
+    interface for all monitor-related operations.
+    
+    DESIGN DECISION: When no subcommand is provided, we show the server status
+    as the default action, giving users a quick overview of the monitoring system.
+    
+    Args:
+        args: Parsed command line arguments with monitor_command attribute
+    """
+    logger = get_logger("cli")
+    
+    try:
+        # Import ServerManager from socketio_server_manager.py
+        from ...scripts.socketio_server_manager import ServerManager
+        server_manager = ServerManager()
+        
+        if not args.monitor_command:
+            # No subcommand - show help
+            # WHY: Since we removed status, show help instead when no subcommand is provided
+            print("Available monitor commands:")
+            print("  start    - Start the Socket.IO monitoring server")
+            print("  stop     - Stop the Socket.IO monitoring server")
+            print("  restart  - Restart the Socket.IO monitoring server")
+            print("  port <N> - Start/restart on specific port")
+            print()
+            print("Use 'claude-mpm monitor <command> --help' for more information")
+            return 0
+        
+        if args.monitor_command == MonitorCommands.START.value:
+            success = _start_server(args, server_manager)
+            return 0 if success else 1
+        
+        elif args.monitor_command == MonitorCommands.STOP.value:
+            success = _stop_server(args, server_manager)
+            return 0 if success else 1
+        
+        elif args.monitor_command == MonitorCommands.RESTART.value:
+            success = _restart_server(args, server_manager)
+            return 0 if success else 1
+        
+        elif args.monitor_command == MonitorCommands.PORT.value:
+            success = _port_server(args, server_manager)
+            return 0 if success else 1
+        
+        else:
+            logger.error(f"Unknown monitor command: {args.monitor_command}")
+            print(f"Unknown monitor command: {args.monitor_command}")
+            print("Available commands: start, stop, restart, port")
+            return 1
+        
+    except ImportError as e:
+        logger.error(f"Server manager not available: {e}")
+        print("Error: Socket.IO server manager not available")
+        print("This may indicate a missing dependency or installation issue.")
+        return 1
+    except Exception as e:
+        logger.error(f"Error managing monitor: {e}")
+        print(f"Error: {e}")
+        return 1
+    
+    return 0
+
+
+def _port_server(args, server_manager):
+    """
+    Start or restart the Socket.IO monitoring server on a specific port.
+    
+    WHY: Users need to be able to start/restart the monitoring server on a specific
+    port, either if no server is running (start) or if a server is already running
+    on a different port (restart).
+    
+    Args:
+        args: Command arguments with required port and optional host
+        server_manager: ServerManager instance
+        
+    Returns:
+        bool: True if server started/restarted successfully, False otherwise
+    """
+    port = args.port
+    host = getattr(args, 'host', 'localhost')
+    
+    print(f"Managing Socket.IO monitoring server on port {port}...")
+    print(f"Target: {host}:{port}")
+    print()
+    
+    try:
+        # Check if there are any running servers
+        running_servers = server_manager.list_running_servers()
+        
+        # Check if server is already running on this port
+        server_on_port = any(server.get('port') == port for server in running_servers)
+        
+        if server_on_port:
+            print(f"Server already running on port {port}. Restarting...")
+            success = server_manager.restart_server(port=port)
+            action = "restarted"
+        else:
+            # Check if servers are running on other ports
+            if running_servers:
+                print("Servers running on other ports:")
+                for server in running_servers:
+                    server_port = server.get('port')
+                    server_id = server.get('server_id', 'unknown')
+                    print(f"  • Server '{server_id}' on port {server_port}")
+                print()
+                print(f"Starting new server on port {port}...")
+            else:
+                print("No servers currently running. Starting new server...")
+            
+            success = server_manager.start_server(port=port, host=host, server_id="monitor-server")
+            action = "started"
+        
+        if success:
+            print()
+            print(f"Monitor server {action} successfully on port {port}")
+            print()
+            print("Server management commands:")
+            print(f"  Status:  ps aux | grep socketio")
+            print(f"  Stop:    claude-mpm monitor stop --port {port}")
+            print(f"  Restart: claude-mpm monitor restart --port {port}")
+            print()
+            print(f"WebSocket URL: ws://{host}:{port}")
+        else:
+            print(f"Failed to {action.replace('ed', '')} server on port {port}")
+            print()
+            print("Troubleshooting:")
+            print(f"  • Check if port {port} is available: lsof -i :{port}")
+            print(f"  • Try a different port: claude-mpm monitor port {port + 1}")
+            print("  • Check system resources: free -h && df -h")
+        
+        return success
+        
+    except Exception as e:
+        print(f"Error managing server on port {port}: {e}")
+        print()
+        print("Troubleshooting:")
+        print(f"  • Verify port {port} is valid and available")
+        print("  • Check system resources and permissions")
+        print("  • Try manual start/stop operations")
+        return False
+
+
+def _start_server(args, server_manager):
+    """
+    Start the Socket.IO monitoring server.
+    
+    WHY: Users need to start the monitoring server to enable real-time monitoring
+    of Claude MPM sessions and websocket connections.
+    
+    Args:
+        args: Command arguments with optional port and host
+        server_manager: ServerManager instance
+        
+    Returns:
+        bool: True if server started successfully, False otherwise
+    """
+    port = getattr(args, 'port', 8765)
+    host = getattr(args, 'host', 'localhost')
+    
+    print(f"Starting Socket.IO monitoring server...")
+    print(f"Target: {host}:{port}")
+    print()
+    
+    try:
+        success = server_manager.start_server(port=port, host=host, server_id="monitor-server")
+        
+        if success:
+            print()
+            print("Monitor server management commands:")
+            print(f"  Status: claude-mpm monitor status")
+            print(f"  Stop:   claude-mpm monitor stop")
+            print(f"  Restart: claude-mpm monitor restart")
+            print()
+            print(f"WebSocket URL: ws://{host}:{port}")
+            
+        return success
+        
+    except Exception as e:
+        print(f"Failed to start monitoring server: {e}")
+        print()
+        print("Troubleshooting:")
+        print(f"  • Check if port {port} is available: lsof -i :{port}")
+        print(f"  • Try a different port: claude-mpm monitor start --port {port + 1}")
+        print("  • Check system resources: free -h && df -h")
+        return False
+
+
+def _stop_server(args, server_manager):
+    """
+    Stop the Socket.IO monitoring server.
+    
+    WHY: Users need to stop the monitoring server when it's no longer needed
+    or when troubleshooting connection issues.
+    
+    Args:
+        args: Command arguments with optional port
+        server_manager: ServerManager instance
+        
+    Returns:
+        bool: True if server stopped successfully, False otherwise
+    """
+    port = getattr(args, 'port', None)
+    
+    print("Stopping Socket.IO monitoring server...")
+    
+    try:
+        # If no port specified, try to find running servers and stop them
+        if port is None:
+            running_servers = server_manager.list_running_servers()
+            if not running_servers:
+                print("No running servers found to stop")
+                return True
+            
+            # Stop the first server (or all if multiple)
+            success = True
+            for server in running_servers:
+                server_port = server.get('port')
+                server_id = server.get('server_id', 'unknown')
+                print(f"Stopping server '{server_id}' on port {server_port}...")
+                
+                if not server_manager.stop_server(port=server_port):
+                    print(f"Failed to stop server on port {server_port}")
+                    success = False
+            
+            return success
+        else:
+            # Stop specific server on given port
+            success = server_manager.stop_server(port=port)
+            
+            if success:
+                print(f"Monitor server stopped on port {port}")
+            else:
+                print(f"Failed to stop server on port {port}")
+                print()
+                print("Troubleshooting:")
+                print(f"  • Check if server is running: claude-mpm monitor status")
+                print(f"  • Try force kill: kill $(lsof -ti :{port})")
+            
+            return success
+        
+    except Exception as e:
+        print(f"Error stopping server: {e}")
+        return False
+
+
+def _restart_server(args, server_manager):
+    """
+    Restart the Socket.IO monitoring server.
+    
+    WHY: Users need to restart the monitoring server to apply configuration
+    changes or recover from error states.
+    
+    Args:
+        args: Command arguments with optional port
+        server_manager: ServerManager instance
+        
+    Returns:
+        bool: True if server restarted successfully, False otherwise
+    """
+    port = getattr(args, 'port', None)
+    
+    print("Restarting Socket.IO monitoring server...")
+    
+    try:
+        # If no port specified, find running servers to restart
+        if port is None:
+            running_servers = server_manager.list_running_servers()
+            if not running_servers:
+                print("No running servers found. Starting new server on default port...")
+                return _start_server(args, server_manager)
+            
+            # Restart the first server found
+            server = running_servers[0]
+            port = server.get('port', 8765)
+            
+        print(f"Using port {port} for restart...")
+        
+        # Use ServerManager's restart method
+        success = server_manager.restart_server(port=port)
+        
+        if success:
+            print(f"Monitor server restarted successfully on port {port}")
+            print()
+            print("Server management commands:")
+            print(f"  Status: claude-mpm monitor status")
+            print(f"  Stop:   claude-mpm monitor stop --port {port}")
+            print(f"  Start:  claude-mpm monitor start --port {port}")
+        else:
+            print(f"Failed to restart server on port {port}")
+            print()
+            print("Troubleshooting:")
+            print("  • Try stopping and starting manually:")
+            print(f"    claude-mpm monitor stop --port {port}")
+            print(f"    claude-mpm monitor start --port {port}")
+            print("  • Check server logs for errors")
+        
+        return success
+        
+    except Exception as e:
+        print(f"Error restarting server: {e}")
+        print()
+        print("Fallback options:")
+        print("  • Manual restart: stop then start")
+        print("  • Check system resources and try again")
+        return False

claude_mpm/cli/commands/run.py

@@ -585,24 +585,16 @@ def _start_standalone_socketio_server(port, logger):
             
             logger.debug(f"Checking server readiness (attempt {attempt + 1}/{max_attempts}, waiting {delay}s)")
             
-            # Check if thread is alive first
-            if hasattr(server, 'thread') and server.thread and server.thread.is_alive():
-                logger.debug("Server thread is alive, checking connectivity...")
-                
-                # Give it time for socket binding (progressive delay)
-                time.sleep(delay)
-                
-                # Verify it's actually accepting connections
-                if _check_socketio_server_running(port, logger):
-                    logger.info(f"✅ Standalone Socket.IO server started successfully on port {port}")
-                    logger.info(f"🕐 Server ready after {attempt + 1} attempts ({(attempt + 1) * delay:.1f}s)")
-                    return True
-                else:
-                    logger.debug(f"Server not yet accepting connections on attempt {attempt + 1}")
+            # Give the daemon process time to initialize and bind to the socket
+            time.sleep(delay)
+            
+            # Check if the daemon server is accepting connections
+            if _check_socketio_server_running(port, logger):
+                logger.info(f"✅ Standalone Socket.IO server started successfully on port {port}")
+                logger.info(f"🕐 Server ready after {attempt + 1} attempts ({(attempt + 1) * delay:.1f}s)")
+                return True
             else:
-                logger.warning(f"Server thread not alive or not created on attempt {attempt + 1}")
-                # Give thread more time to start
-                time.sleep(delay)
+                logger.debug(f"Server not yet accepting connections on attempt {attempt + 1}")
         
         logger.error(f"❌ Socket.IO server failed to start properly on port {port} after {max_attempts} attempts")
         logger.error(f"💡 This may indicate a port conflict or dependency issue")