claude-mpm 4.0.34__py3-none-any.whl → 4.1.0__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.0.34
+4.1.0

claude_mpm/agents/INSTRUCTIONS.md

@@ -1,9 +1,9 @@
 <!-- FRAMEWORK_VERSION: 0010 -->
 <!-- LAST_MODIFIED: 2025-08-10T00:00:00Z -->
 
-# Claude Multi-Agent Project Manager Instructions
+# Claude Multi-Agent (Claude-MPM) Project Manager Instructions
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
+## 🔴 YOUR PRIME DIRECTIVE - MANDATORY DELEGATION 🔴
 
 **YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
 
@@ -97,6 +97,74 @@ You are a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized
 
 ## MCP Vector Search Integration
 
+## 🎫 MANDATORY TICKET TRACKING PROTOCOL 🎫
+
+**CRITICAL REQUIREMENT**: You MUST track ALL work using the integrated ticketing system. This is NOT optional.
+
+### Session Work Tracking Rules
+
+**At Session Start**:
+1. **ALWAYS create or update an ISS (Issue) ticket** for the current user request
+2. **Attach the ISS to an appropriate Epic (EP-)** or create new Epic if needed
+3. **Set ISS status to "in-progress"** when beginning work
+4. **Use ticket ID in all agent delegations** for traceability
+
+**During Work**:
+1. **Include ticket context in ALL delegations** to agents
+2. **Agents will create TSK (Task) tickets** for their implementation work
+3. **Update ISS ticket after each phase completion** with progress
+4. **Add comments to ticket for significant decisions or blockers**
+
+**At Work Completion**:
+1. **Update ISS ticket status to "done"** when all delegations complete
+2. **Add final summary comment** with outcomes and deliverables
+3. **Close the ticket** if no follow-up work is needed
+4. **Reference ticket ID in final response** to user
+
+### Ticket Creation Commands
+
+**When MCP Gateway is available**:
+```
+Use mcp__claude-mpm-gateway__ticket tool with operation: "create"
+```
+
+**When using delegation**:
+```
+Delegate to Ticketing Agent with clear instructions:
+- Create ISS for: [user request]
+- Parent Epic: [EP-XXXX or create new]
+- Priority: [based on urgency]
+- Description: [detailed context]
+```
+
+### Work Resumption via Tickets
+
+**Instead of session resume, use tickets for continuity**:
+1. Search for open ISS tickets: `operation: "list", status: "in-progress"`
+2. View ticket details: `operation: "view", ticket_id: "ISS-XXXX"`
+3. Resume work based on ticket history and status
+4. Continue updating the same ticket throughout the work
+
+### Ticket Hierarchy Enforcement
+
+```
+Epic (EP-XXXX) - Major initiative or multi-session work
+└── Issue (ISS-XXXX) - PM tracks user request here ← YOU CREATE THIS
+    ├── Task (TSK-XXXX) - Research Agent's work
+    ├── Task (TSK-XXXX) - Engineer Agent's work
+    ├── Task (TSK-XXXX) - QA Agent's work
+    └── Task (TSK-XXXX) - Documentation Agent's work
+```
+
+**REMEMBER**:
+- ✅ ALWAYS create ISS tickets for user requests
+- ✅ ALWAYS attach ISS to an Epic
+- ✅ ALWAYS update ticket status as work progresses
+- ✅ ALWAYS close tickets when work completes
+- ❌ NEVER work without an active ISS ticket
+- ❌ NEVER create TSK tickets (agents do this)
+- ❌ NEVER leave tickets in "in-progress" after completion
+
 ## Agent Response Format
 
 When completing tasks, all agents should structure their responses with:

claude_mpm/agents/OUTPUT_STYLE.md

@@ -5,17 +5,6 @@ description: Multi-Agent Project Manager orchestration mode for delegation and c
 
 You are Claude Multi-Agent PM, a PROJECT MANAGER whose SOLE PURPOSE is to delegate work to specialized agents.
 
-## 🔴 PRIMARY DIRECTIVE - MANDATORY DELEGATION 🔴
-
-**YOU ARE STRICTLY FORBIDDEN FROM DOING ANY WORK DIRECTLY.**
-
-Direct implementation is ABSOLUTELY PROHIBITED unless the user EXPLICITLY overrides with phrases like:
-- "do this yourself"
-- "don't delegate"
-- "implement directly"
-- "you do it"
-- "no delegation"
-
 ## Core Operating Rules
 
 **DEFAULT BEHAVIOR - ALWAYS DELEGATE**:

claude_mpm/agents/WORKFLOW.md

@@ -372,7 +372,11 @@ Delegate to Research when:
 - Architecture decisions needed
 - Domain knowledge required
 
-### Ticketing Agent Integration
+### 🔴 MANDATORY Ticketing Agent Integration 🔴
+
+**THIS IS NOT OPTIONAL - ALL WORK MUST BE TRACKED IN TICKETS**
+
+The PM MUST create and maintain tickets for ALL user requests. Failure to track work in tickets is a CRITICAL VIOLATION of PM protocols.
 
 **ALWAYS delegate to Ticketing Agent when user mentions:**
 - "ticket", "tickets", "ticketing"
@@ -437,4 +441,12 @@ The Ticketing Agent specializes in:
 - Generating structured project documentation
 - Breaking down work into manageable pieces
 - Tracking project progress and dependencies
-- Maintaining clear audit trail of all work performed
+- Maintaining clear audit trail of all work performed
+
+### Ticket-Based Work Resumption
+
+**Tickets replace session resume for work continuation**:
+- When starting any session, first check for open ISS tickets
+- Resume work on existing tickets rather than starting new ones
+- Use ticket history to understand context and progress
+- This ensures continuity across sessions and PMs

claude_mpm/cli/__init__.py

@@ -83,15 +83,26 @@ def main(argv: Optional[list] = None):
     # Initialize or update project registry
     _initialize_project_registry()
 
-    # Verify MCP Gateway configuration on startup (non-blocking)
-    _verify_mcp_gateway_startup()
-
-    # Create parser with version
+    # Parse args early to check if we should skip auto-configuration
+    # (for commands like --version, --help, etc.)
     parser = create_parser(version=__version__)
-
-    # Preprocess and parse arguments
     processed_argv = preprocess_args(argv)
     args = parser.parse_args(processed_argv)
+    
+    # Skip auto-configuration for certain commands
+    skip_auto_config_commands = ["--version", "-v", "--help", "-h"]
+    # sys is already imported at module level (line 16), use it directly
+    should_skip_auto_config = (
+        any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_auto_config_commands)
+        or (hasattr(args, 'command') and args.command in ["info", "doctor", "config", "mcp"])  # Info, diagnostic, and MCP commands
+    )
+    
+    if not should_skip_auto_config:
+        # Check for MCP auto-configuration (pipx installations)
+        _check_mcp_auto_configuration()
+
+    # Verify MCP Gateway configuration on startup (non-blocking)
+    _verify_mcp_gateway_startup()
 
     # Set up logging
     # Special case: For MCP start command, we need minimal logging to avoid stdout interference
@@ -101,7 +112,7 @@ def main(argv: Optional[list] = None):
     ):
         # For MCP server, configure minimal stderr-only logging
         import logging
-        import sys
+        # sys is already imported at module level
 
         # Only log errors to stderr for MCP server
         if not getattr(args, "test", False) and not getattr(
@@ -176,6 +187,36 @@ def _initialize_project_registry():
         # Continue execution - registry failure shouldn't block startup
 
 
+def _check_mcp_auto_configuration():
+    """
+    Check and potentially auto-configure MCP for pipx installations.
+    
+    WHY: Users installing via pipx should have MCP work out-of-the-box with
+    minimal friction. This function offers one-time auto-configuration with
+    user consent.
+    
+    DESIGN DECISION: This is blocking but quick - it only runs once and has
+    a 10-second timeout. We want to catch users on first run for the best
+    experience.
+    """
+    try:
+        from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
+        
+        # This function handles all the logic:
+        # - Checks if already configured
+        # - Checks if pipx installation
+        # - Checks if already asked before
+        # - Prompts user if needed
+        # - Configures if user agrees
+        check_and_configure_mcp()
+        
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+        logger = get_logger("cli")
+        logger.debug(f"MCP auto-configuration check failed: {e}")
+
+
 def _verify_mcp_gateway_startup():
     """
     Verify MCP Gateway configuration on startup and pre-warm MCP services.

claude_mpm/cli/commands/agents.py

@@ -71,6 +71,7 @@ class AgentsCommand(AgentCommand):
                 "deps-install": self._install_agent_dependencies,
                 "deps-list": self._list_agent_dependencies,
                 "deps-fix": self._fix_agent_dependencies,
+                "cleanup-orphaned": self._cleanup_orphaned_agents,
             }
 
             if args.agents_command in command_map:
@@ -469,6 +470,87 @@ class AgentsCommand(AgentCommand):
         except Exception as e:
             self.logger.error(f"Error fixing dependencies: {e}", exc_info=True)
             return CommandResult.error_result(f"Error fixing dependencies: {e}")
+    
+    def _cleanup_orphaned_agents(self, args) -> CommandResult:
+        """Clean up orphaned agents that don't have templates."""
+        try:
+            from ...services.agents.deployment.multi_source_deployment_service import (
+                MultiSourceAgentDeploymentService
+            )
+            
+            # Determine agents directory
+            if hasattr(args, 'agents_dir') and args.agents_dir:
+                agents_dir = args.agents_dir
+            else:
+                # Check for project-level .claude/agents first
+                project_agents_dir = Path.cwd() / ".claude" / "agents"
+                if project_agents_dir.exists():
+                    agents_dir = project_agents_dir
+                else:
+                    # Fall back to user home directory
+                    agents_dir = Path.home() / ".claude" / "agents"
+            
+            if not agents_dir.exists():
+                return CommandResult.success_result(f"Agents directory not found: {agents_dir}")
+            
+            # Initialize service
+            service = MultiSourceAgentDeploymentService()
+            
+            # Determine if we're doing a dry run
+            dry_run = getattr(args, 'dry_run', True)
+            if hasattr(args, 'force') and args.force:
+                dry_run = False
+            
+            # Perform cleanup
+            results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+            
+            output_format = getattr(args, 'format', 'text')
+            quiet = getattr(args, 'quiet', False)
+            
+            if output_format in ['json', 'yaml']:
+                return CommandResult.success_result(
+                    f"Found {len(results.get('orphaned', []))} orphaned agents",
+                    data=results
+                )
+            else:
+                # Text output
+                if not results.get("orphaned"):
+                    print("✅ No orphaned agents found")
+                    return CommandResult.success_result("No orphaned agents found")
+                
+                if not quiet:
+                    print(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+                    for orphan in results["orphaned"]:
+                        print(f"  - {orphan['name']} v{orphan['version']}")
+                
+                if dry_run:
+                    print(
+                        f"\n📝 This was a dry run. Use --force to actually remove "
+                        f"{len(results['orphaned'])} orphaned agent(s)"
+                    )
+                else:
+                    if results.get("removed"):
+                        print(
+                            f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                        )
+                    
+                    if results.get("errors"):
+                        print(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                        for error in results["errors"]:
+                            print(f"  - {error}")
+                        return CommandResult.error_result(
+                            f"Cleanup completed with {len(results['errors'])} errors",
+                            data=results
+                        )
+                
+                return CommandResult.success_result(
+                    f"Cleanup {'preview' if dry_run else 'completed'}",
+                    data=results
+                )
+                
+        except Exception as e:
+            self.logger.error(f"Error during cleanup: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error during cleanup: {e}")
 
 
 def manage_agents(args):

claude_mpm/cli/commands/cleanup_orphaned_agents.py

@@ -0,0 +1,150 @@
+"""CLI command to clean up orphaned agents without templates.
+
+This command helps manage deployed agents that no longer have corresponding
+templates, which can happen when agents are removed from the system or when
+switching between different agent sources.
+"""
+
+import argparse
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_config import get_logger
+from claude_mpm.services.agents.deployment.multi_source_deployment_service import (
+    MultiSourceAgentDeploymentService
+)
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    """Add the cleanup-orphaned-agents command parser.
+    
+    Args:
+        subparsers: The subparsers object from argparse
+    """
+    parser = subparsers.add_parser(
+        "cleanup-orphaned-agents",
+        help="Clean up orphaned agents that don't have templates",
+        description=(
+            "Detect and optionally remove deployed agents that no longer have "
+            "corresponding templates. This can happen when agents are removed "
+            "from the system or when switching between agent sources."
+        ),
+    )
+    
+    parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        help="Directory containing deployed agents (default: .claude/agents/)",
+    )
+    
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        help="Only show what would be removed without actually removing (default)",
+    )
+    
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Actually remove orphaned agents (disables dry-run)",
+    )
+    
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only show summary, not individual agents",
+    )
+    
+    parser.set_defaults(func=cleanup_orphaned_agents)
+
+
+def cleanup_orphaned_agents(args: argparse.Namespace) -> int:
+    """Clean up orphaned agents.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    logger = get_logger(__name__)
+    
+    # Determine agents directory
+    if args.agents_dir:
+        agents_dir = args.agents_dir
+    else:
+        # Check for project-level .claude/agents first
+        project_agents_dir = Path.cwd() / ".claude" / "agents"
+        if project_agents_dir.exists():
+            agents_dir = project_agents_dir
+        else:
+            # Fall back to user home directory
+            agents_dir = Path.home() / ".claude" / "agents"
+    
+    if not agents_dir.exists():
+        logger.info(f"Agents directory not found: {agents_dir}")
+        return 0
+    
+    logger.info(f"Checking for orphaned agents in: {agents_dir}")
+    
+    # Initialize service
+    service = MultiSourceAgentDeploymentService()
+    
+    # Determine if we're doing a dry run
+    dry_run = args.dry_run and not args.force
+    
+    try:
+        # Perform cleanup
+        results = service.cleanup_orphaned_agents(agents_dir, dry_run=dry_run)
+        
+        # Handle results
+        if not results["orphaned"]:
+            logger.info("✅ No orphaned agents found")
+            return 0
+        
+        if not args.quiet:
+            logger.info(f"\nFound {len(results['orphaned'])} orphaned agent(s):")
+            for orphan in results["orphaned"]:
+                logger.info(f"  - {orphan['name']} v{orphan['version']}")
+        
+        if dry_run:
+            logger.info(
+                f"\n📝 This was a dry run. Use --force to actually remove "
+                f"{len(results['orphaned'])} orphaned agent(s)"
+            )
+        else:
+            if results["removed"]:
+                logger.info(
+                    f"\n✅ Successfully removed {len(results['removed'])} orphaned agent(s)"
+                )
+            
+            if results["errors"]:
+                logger.error(f"\n❌ Encountered {len(results['errors'])} error(s):")
+                for error in results["errors"]:
+                    logger.error(f"  - {error}")
+                return 1
+        
+        return 0
+        
+    except Exception as e:
+        logger.error(f"Error during cleanup: {e}")
+        return 1
+
+
+# For backward compatibility
+def main(args: Optional[argparse.Namespace] = None) -> int:
+    """Main entry point for the command.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code
+    """
+    if args is None:
+        parser = argparse.ArgumentParser()
+        add_parser(parser.add_subparsers())
+        args = parser.parse_args()
+    
+    return cleanup_orphaned_agents(args)

claude_mpm/cli/commands/mcp_pipx_config.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+MCP configuration command for pipx installations.
+
+This module provides a CLI command to configure MCP for users who installed
+claude-mpm via pipx.
+"""
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from claude_mpm.core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def find_claude_config_path() -> Path:
+    """Find the Claude Code configuration file path."""
+    system = platform.system()
+    
+    if system == "Darwin":  # macOS
+        config_path = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif system == "Windows":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            config_path = Path(appdata) / "Claude" / "claude_desktop_config.json"
+        else:
+            config_path = Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    else:  # Linux and others
+        config_path = Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+    
+    return config_path
+
+
+def check_pipx_installation() -> bool:
+    """Check if claude-mpm is installed via pipx."""
+    try:
+        # Check if running from pipx
+        if "pipx" in sys.executable.lower():
+            return True
+        
+        # Check pipx list
+        result = subprocess.run(
+            ["pipx", "list", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        if result.returncode == 0:
+            pipx_data = json.loads(result.stdout)
+            return "claude-mpm" in pipx_data.get("venvs", {})
+    except Exception:
+        pass
+    
+    return False
+
+
+def create_mcp_config() -> Dict[str, Any]:
+    """Create MCP configuration for pipx installation."""
+    return {
+        "mcpServers": {
+            "claude-mpm-gateway": {
+                "command": "claude-mpm-mcp"
+            }
+        }
+    }
+
+
+def configure_mcp_for_pipx(args) -> int:
+    """
+    Configure MCP for pipx installation.
+    
+    Args:
+        args: Command line arguments
+        
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    print("Claude MPM - MCP Configuration for pipx")
+    print("=" * 40)
+    
+    # Check if this is a pipx installation
+    if not check_pipx_installation():
+        print("\n⚠️  This doesn't appear to be a pipx installation")
+        print("This command is specifically for pipx users.")
+        print("\nFor other installation methods, see:")
+        print("  docs/MCP_SETUP.md")
+        
+        if not args.force:
+            return 1
+        print("\n--force flag detected, continuing anyway...")
+    
+    # Find Claude config
+    config_path = find_claude_config_path()
+    print(f"\n📁 Claude config path: {config_path}")
+    
+    # Load existing config
+    existing_config = {}
+    if config_path.exists():
+        try:
+            with open(config_path, 'r') as f:
+                existing_config = json.load(f)
+            print("✅ Existing config loaded")
+        except json.JSONDecodeError:
+            print("⚠️  Config exists but is invalid JSON")
+            if not args.force:
+                print("Use --force to overwrite")
+                return 1
+    else:
+        print("📝 Config will be created")
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Check for existing MCP config
+    if "mcpServers" in existing_config and "claude-mpm-gateway" in existing_config["mcpServers"]:
+        print("\n⚠️  claude-mpm-gateway is already configured")
+        if not args.force:
+            print("Use --force to overwrite")
+            return 0
+        print("Overwriting existing configuration...")
+    
+    # Create and merge config
+    mcp_config = create_mcp_config()
+    existing_config.update(mcp_config)
+    
+    # Show what will be written
+    if not args.quiet:
+        print("\n📝 Configuration to write:")
+        print(json.dumps(mcp_config, indent=2))
+    
+    # Write config
+    if not args.dry_run:
+        try:
+            with open(config_path, 'w') as f:
+                json.dump(existing_config, f, indent=2)
+            print(f"\n✅ Configuration written to: {config_path}")
+        except Exception as e:
+            print(f"\n❌ Failed to write config: {e}")
+            return 1
+    else:
+        print("\n--dry-run: Configuration not written")
+    
+    # Test the command
+    print("\n🧪 Testing claude-mpm-mcp command...")
+    try:
+        result = subprocess.run(
+            ["which", "claude-mpm-mcp"],
+            capture_output=True,
+            text=True,
+            timeout=2
+        )
+        if result.returncode == 0:
+            print(f"✅ Command found: {result.stdout.strip()}")
+        else:
+            print("⚠️  Command not found in PATH")
+            print("   Ensure pipx bin directory is in your PATH")
+    except Exception as e:
+        print(f"⚠️  Could not test command: {e}")
+    
+    print("\n✨ Next steps:")
+    print("1. Restart Claude Code")
+    print("2. Look for the MCP icon in the interface")
+    print("3. Try using @claude-mpm-gateway in a conversation")
+    print("\nFor more help, see: docs/MCP_PIPX_SETUP.md")
+    
+    return 0
+
+
+def add_parser(subparsers):
+    """Add the mcp-pipx-config command parser."""
+    parser = subparsers.add_parser(
+        'mcp-pipx-config',
+        help='Configure MCP for pipx installation',
+        description='Configure MCP Gateway for Claude Code when installed via pipx'
+    )
+    
+    parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Force configuration even if not pipx or already configured'
+    )
+    
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Show what would be done without making changes'
+    )
+    
+    parser.add_argument(
+        '--quiet',
+        action='store_true',
+        help='Suppress non-essential output'
+    )
+    
+    parser.set_defaults(func=configure_mcp_for_pipx)

claude_mpm/cli/parsers/agents_parser.py

@@ -132,5 +132,32 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         default=3,
         help="Maximum retry attempts per package (default: 3)",
     )
+    
+    # Cleanup orphaned agents
+    cleanup_orphaned_parser = agents_subparsers.add_parser(
+        "cleanup-orphaned",
+        help="Clean up orphaned agents that don't have templates"
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--agents-dir",
+        type=Path,
+        help="Directory containing deployed agents (default: .claude/agents/)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=True,
+        help="Only show what would be removed without actually removing (default)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Actually remove orphaned agents (disables dry-run)",
+    )
+    cleanup_orphaned_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Only show summary, not individual agents",
+    )
 
     return agents_parser