claude-mpm 3.1.1__py3-none-any.whl → 3.1.3__py3-none-any.whl

claude_mpm/__main__.py

@@ -1,14 +1,38 @@
-"""Main entry point for claude-mpm."""
+"""
+Main entry point for claude-mpm package.
+
+WHY: This module enables running claude-mpm as a Python module via `python -m claude_mpm`.
+It's the standard Python pattern for making packages executable.
+
+DESIGN DECISION: We only import and call the main function from the CLI module,
+keeping this file minimal and focused on its single responsibility.
+"""
 
-import sys
 import os
+import sys
 from pathlib import Path
 
 # Add parent directory to path to ensure proper imports
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-# Import main function from cli
+# Import main function from the new CLI module structure
 from claude_mpm.cli import main
 
+# Restore user's working directory if preserved by bash wrapper
+# WHY: The bash wrapper preserves the user's launch directory in CLAUDE_MPM_USER_PWD
+# to maintain proper file access permissions and security boundaries.
+# Python imports work via PYTHONPATH, so we can safely restore the original directory.
 if __name__ == "__main__":
+    user_pwd = os.environ.get('CLAUDE_MPM_USER_PWD')
+    if user_pwd and os.path.exists(user_pwd):
+        try:
+            os.chdir(user_pwd)
+            # Only log if debug is enabled
+            if os.environ.get('CLAUDE_MPM_DEBUG') == '1':
+                print(f"[INFO] Restored working directory to: {user_pwd}")
+        except Exception as e:
+            # If we can't change to user directory, continue but log warning
+            if os.environ.get('CLAUDE_MPM_DEBUG') == '1':
+                print(f"[WARNING] Could not restore working directory to {user_pwd}: {e}")
+    
     sys.exit(main())

claude_mpm/agents/INSTRUCTIONS.md

@@ -4,15 +4,30 @@
 # Claude Multi-Agent Project Manager Instructions
 
 ## 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:
+You are **Claude Multi-Agent Project Manager (claude-mpm)** - your **SOLE function** is **orchestration and delegation**. 
+
+### Permitted Actions (Exhaustive List)
 - **Task Tool** for delegation (primary function)
 - **TodoWrite** for tracking (with [Agent] prefixes)
 - **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"
+- **Direct work** only when explicitly authorized with phrases like: "do this yourself", "don't delegate", "implement directly"
 
 **ABSOLUTE RULE**: ALL other work must be delegated to specialized agents via Task Tool.
 
+### Professional Standards
+- **Clarity Threshold**: Achieve 90% certainty of success before delegating. Ask clarifying questions when needed.
+- **Agent Standards**: Require the same 90% clarity threshold from your agents before they proceed.
+- **Project Validation**: Verify that requested tasks align with project context and question any incongruities.
+- **Communication Style**: 
+  - Avoid unnecessary affirmation or praise
+  - Never say "You're right!" (or similar) unless correctness was in question and validated by agent authority
+  - Focus on substance over pleasantries
+  - Ask direct questions when clarity is needed
+
+### Your Responsibility
+It is your **JOB** to ensure sufficient clarity before delegation. Set high standards for both yourself and your agents to ensure successful outcomes.
+
 ## Context-Aware Agent Selection
 - **PM role/capabilities questions**: Answer directly (only exception)
 - **Explanations/How-to questions**: Delegate to Documentation Agent

claude_mpm/agents/templates/test-integration-agent.md

@@ -0,0 +1,34 @@
+---
+author: test-script
+model_preference: claude-3-sonnet
+specializations: []
+tags:
+- test
+- integration
+type: custom
+version: 1.0.0
+---
+
+# Test Integration Agent
+
+## 🎯 Primary Role
+test-integration-agent agent
+
+## 🎯 When to Use This Agent
+
+**Select this agent when:**
+
+**Do NOT select for:**
+
+## 🔧 Core Capabilities
+
+## 🔑 Authority & Permissions
+
+### ✅ Exclusive Write Access
+
+### ❌ Forbidden Operations
+
+---
+**Agent Type**: custom
+**Model Preference**: claude-3-sonnet
+**Version**: 1.0.0

claude_mpm/cli/README.md

@@ -0,0 +1,109 @@
+# Claude MPM CLI Architecture
+
+This document describes the refactored CLI architecture for claude-mpm.
+
+## Overview
+
+The CLI has been refactored from a single monolithic `cli.py` file into a modular structure that improves maintainability and code organization.
+
+## Directory Structure
+
+```
+cli/
+├── __init__.py       # Main entry point - orchestrates the CLI flow
+├── parser.py         # Argument parsing logic - single source of truth for CLI arguments
+├── utils.py          # Shared utility functions
+├── commands/         # Individual command implementations
+│   ├── __init__.py
+│   ├── run.py        # Default command - runs Claude sessions
+│   ├── tickets.py    # Lists tickets
+│   ├── info.py       # Shows system information
+│   ├── agents.py     # Manages agent deployments
+│   └── ui.py         # Terminal UI launcher
+└── README.md         # This file
+```
+
+## Key Design Decisions
+
+### 1. Modular Command Structure
+Each command is implemented in its own module under `commands/`. This makes it easy to:
+- Add new commands without touching existing code
+- Test commands in isolation
+- Understand what each command does
+
+### 2. Centralized Argument Parsing
+All argument definitions are in `parser.py`. This provides:
+- Single source of truth for CLI arguments
+- Reusable argument groups (common arguments, run arguments)
+- Clear separation of parsing from execution
+
+### 3. Shared Utilities
+Common functions are in `utils.py`:
+- `get_user_input()` - Handles input from files, stdin, or command line
+- `get_agent_versions_display()` - Formats agent version information
+- `setup_logging()` - Configures logging based on arguments
+- `ensure_directories()` - Creates required directories on first run
+
+### 4. Backward Compatibility
+The refactoring maintains full backward compatibility:
+- `__main__.py` still imports from `claude_mpm.cli`
+- The main `cli/__init__.py` exports the same `main()` function
+- All existing commands and arguments work exactly as before
+
+## Entry Points
+
+1. **Package execution**: `python -m claude_mpm`
+   - Uses `__main__.py` which imports from `cli/__init__.py`
+
+2. **Direct import**: `from claude_mpm.cli import main`
+   - Imports the main function from `cli/__init__.py`
+
+3. **Shell script**: `claude-mpm` command
+   - Calls `python -m claude_mpm` with proper environment setup
+
+## Adding New Commands
+
+To add a new command:
+
+1. Create a new module in `commands/`:
+```python
+# commands/mycommand.py
+def my_command(args):
+    """Execute my command."""
+    # Implementation here
+```
+
+2. Add the command to `commands/__init__.py`:
+```python
+from .mycommand import my_command
+```
+
+3. Add parser configuration in `parser.py`:
+```python
+# In create_parser()
+mycommand_parser = subparsers.add_parser(
+    "mycommand",
+    help="Description of my command"
+)
+# Add command-specific arguments
+```
+
+4. Add the command mapping in `cli/__init__.py`:
+```python
+# In _execute_command()
+command_map = {
+    # ... existing commands ...
+    "mycommand": my_command,
+}
+```
+
+## Removed Files
+
+- `cli_main.py` - Redundant entry point, functionality moved to `__main__.py`
+- Original `cli.py` - Split into the modular structure described above
+
+## Preserved Files
+
+- `cli_enhancements.py` - Experimental Click-based CLI with enhanced features
+  - Kept for reference and future enhancement ideas
+  - Not currently used in production

claude_mpm/cli/__init__.py

@@ -0,0 +1,172 @@
+"""
+Claude MPM Command-Line Interface.
+
+WHY: This module serves as the main entry point for the CLI, coordinating
+argument parsing and command execution. It replaces the monolithic cli.py
+with a more modular structure.
+
+DESIGN DECISION: We maintain backward compatibility by keeping the same
+interface while organizing code into logical modules. The main() function
+remains the primary entry point for both direct execution and package imports.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.utils.imports import safe_import
+
+# Import constants and utilities using safe_import pattern
+CLICommands, LogLevel = safe_import('claude_mpm.constants', None, ['CLICommands', 'LogLevel'])
+create_parser, preprocess_args = safe_import('claude_mpm.cli.parser', None, ['create_parser', 'preprocess_args'])
+ensure_directories, setup_logging = safe_import('claude_mpm.cli.utils', None, ['ensure_directories', 'setup_logging'])
+
+# Import commands
+run_session = safe_import('claude_mpm.cli.commands', None, ['run_session'])
+list_tickets = safe_import('claude_mpm.cli.commands', None, ['list_tickets'])
+show_info = safe_import('claude_mpm.cli.commands', None, ['show_info'])
+manage_agents = safe_import('claude_mpm.cli.commands', None, ['manage_agents'])
+run_terminal_ui = safe_import('claude_mpm.cli.commands', None, ['run_terminal_ui'])
+
+# Get version from VERSION file - single source of truth
+version_file = Path(__file__).parent.parent.parent / "VERSION"
+if version_file.exists():
+    __version__ = version_file.read_text().strip()
+else:
+    # Try to import from package as fallback using safe_import
+    version_module = safe_import('claude_mpm', None)
+    if version_module and hasattr(version_module, '__version__'):
+        __version__ = version_module.__version__
+    else:
+        # Default version if all else fails
+        __version__ = "0.0.0"
+
+
+def main(argv: Optional[list] = None):
+    """
+    Main CLI entry point.
+    
+    WHY: This function orchestrates the entire CLI flow:
+    1. Ensures directories exist
+    2. Preprocesses arguments (handling --mpm: prefix)
+    3. Parses arguments
+    4. Sets up logging
+    5. Executes the appropriate command
+    
+    DESIGN DECISION: We keep error handling at this level to provide consistent
+    error messages and exit codes across all commands.
+    
+    Args:
+        argv: Optional list of command line arguments for testing
+        
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    # Ensure directories are initialized on first run
+    ensure_directories()
+    
+    # Create parser with version
+    parser = create_parser(version=__version__)
+    
+    # Preprocess and parse arguments
+    processed_argv = preprocess_args(argv)
+    args = parser.parse_args(processed_argv)
+    
+    # Set up logging
+    logger = setup_logging(args)
+    
+    # Debug output if requested
+    if hasattr(args, 'debug') and args.debug:
+        logger.debug(f"Command: {args.command}")
+        logger.debug(f"Arguments: {args}")
+        # Log working directory context
+        logger.debug(f"Working directory: {os.getcwd()}")
+        logger.debug(f"User PWD (from env): {os.environ.get('CLAUDE_MPM_USER_PWD', 'Not set')}")
+        logger.debug(f"Framework path: {os.environ.get('CLAUDE_MPM_FRAMEWORK_PATH', 'Not set')}")
+    
+    # Hook system note: Claude Code hooks are handled externally via the
+    # hook_handler.py script installed in ~/.claude/settings.json
+    # The --no-hooks flag is kept for backward compatibility but doesn't affect
+    # Claude Code hooks which are configured separately.
+    
+    # Default to run command if no command specified
+    if not args.command:
+        args.command = CLICommands.RUN.value
+        # Ensure run-specific attributes exist when defaulting to run
+        _ensure_run_attributes(args)
+    
+    # Execute command
+    try:
+        exit_code = _execute_command(args.command, args)
+        return exit_code
+    except KeyboardInterrupt:
+        logger.info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+def _ensure_run_attributes(args):
+    """
+    Ensure run command attributes exist when defaulting to run.
+    
+    WHY: When no command is specified, we default to 'run' but the args object
+    won't have run-specific attributes from the subparser. This function ensures
+    they exist with sensible defaults.
+    
+    Args:
+        args: Parsed arguments object to update
+    """
+    # Set defaults for run command attributes
+    args.no_tickets = getattr(args, 'no_tickets', False)
+    args.no_hooks = getattr(args, 'no_hooks', False)
+    args.intercept_commands = getattr(args, 'intercept_commands', False)
+    args.input = getattr(args, 'input', None)
+    args.non_interactive = getattr(args, 'non_interactive', False)
+    args.no_native_agents = getattr(args, 'no_native_agents', False)
+    args.claude_args = getattr(args, 'claude_args', [])
+
+
+def _execute_command(command: str, args) -> int:
+    """
+    Execute the specified command.
+    
+    WHY: This function maps command names to their implementations, providing
+    a single place to manage command routing.
+    
+    Args:
+        command: The command name to execute
+        args: Parsed command line arguments
+        
+    Returns:
+        Exit code from the command
+    """
+    # Map commands to their implementations
+    command_map = {
+        CLICommands.RUN.value: run_session,
+        CLICommands.TICKETS.value: list_tickets,
+        CLICommands.INFO.value: show_info,
+        CLICommands.AGENTS.value: manage_agents,
+        CLICommands.UI.value: run_terminal_ui,
+    }
+    
+    # Execute command if found
+    if command in command_map:
+        result = command_map[command](args)
+        # Commands may return None (success) or an exit code
+        return result if result is not None else 0
+    else:
+        # Unknown command - this shouldn't happen with argparse
+        # but we handle it for completeness
+        print(f"Unknown command: {command}")
+        return 1
+
+
+# For backward compatibility - export main
+if __name__ == "__main__":
+    sys.exit(main())

claude_mpm/cli/commands/__init__.py

@@ -0,0 +1,20 @@
+"""
+CLI commands for claude-mpm.
+
+WHY: This package contains individual command implementations, organized into
+separate modules for better maintainability and code organization.
+"""
+
+from .run import run_session
+from .tickets import list_tickets
+from .info import show_info
+from .agents import manage_agents
+from .ui import run_terminal_ui
+
+__all__ = [
+    'run_session',
+    'list_tickets',
+    'show_info',
+    'manage_agents',
+    'run_terminal_ui'
+]

claude_mpm/cli/commands/agents.py

@@ -0,0 +1,202 @@
+"""
+Agents command implementation for claude-mpm.
+
+WHY: This module manages Claude Code native agents, including listing, deploying,
+and cleaning agent deployments.
+"""
+
+from pathlib import Path
+
+from claude_mpm.utils.imports import safe_import
+
+# Import dependencies using safe_import pattern
+get_logger = safe_import('claude_mpm.core.logger', None, ['get_logger'])
+AgentCommands = safe_import('claude_mpm.constants', None, ['AgentCommands'])
+get_agent_versions_display = safe_import('claude_mpm.cli.utils', None, ['get_agent_versions_display'])
+
+
+def manage_agents(args):
+    """
+    Manage Claude Code native agents.
+    
+    WHY: Claude Code agents need to be deployed and managed. This command provides
+    a unified interface for all agent-related operations.
+    
+    DESIGN DECISION: When no subcommand is provided, we show the current agent
+    versions as a quick status check. This matches the behavior users see at startup.
+    
+    Args:
+        args: Parsed command line arguments with agents_command attribute
+    """
+    logger = get_logger("cli")
+    
+    # Import AgentDeploymentService using safe_import pattern
+    AgentDeploymentService = safe_import(
+        'claude_mpm.services.agent_deployment',
+        None,
+        ['AgentDeploymentService']
+    )
+    
+    if not AgentDeploymentService:
+        logger.error("Agent deployment service not available")
+        print("Error: Agent deployment service not available")
+        return
+    
+    try:
+        deployment_service = AgentDeploymentService()
+        
+        if not args.agents_command:
+            # No subcommand - show agent versions
+            # WHY: This provides a quick way for users to check deployed agent versions
+            # without needing to specify additional subcommands
+            agent_versions = get_agent_versions_display()
+            if agent_versions:
+                print(agent_versions)
+            else:
+                print("No deployed agents found")
+                print("\nTo deploy agents, run: claude-mpm --mpm:agents deploy")
+            return
+        
+        if args.agents_command == AgentCommands.LIST.value:
+            _list_agents(args, deployment_service)
+        
+        elif args.agents_command == AgentCommands.DEPLOY.value:
+            _deploy_agents(args, deployment_service, force=False)
+        
+        elif args.agents_command == AgentCommands.FORCE_DEPLOY.value:
+            _deploy_agents(args, deployment_service, force=True)
+        
+        elif args.agents_command == AgentCommands.CLEAN.value:
+            _clean_agents(args, deployment_service)
+        
+    except Exception as e:
+        logger.error(f"Error managing agents: {e}")
+        print(f"Error: {e}")
+
+
+def _list_agents(args, deployment_service):
+    """
+    List available or deployed agents.
+    
+    WHY: Users need to see what agents are available in the system and what's
+    currently deployed. This helps them understand the agent ecosystem.
+    
+    Args:
+        args: Command arguments with 'system' and 'deployed' flags
+        deployment_service: Agent deployment service instance
+    """
+    if args.system:
+        # List available agent templates
+        print("Available Agent Templates:")
+        print("-" * 80)
+        agents = deployment_service.list_available_agents()
+        if not agents:
+            print("No agent templates found")
+        else:
+            for agent in agents:
+                print(f"📄 {agent['file']}")
+                if 'name' in agent:
+                    print(f"   Name: {agent['name']}")
+                if 'description' in agent:
+                    print(f"   Description: {agent['description']}")
+                if 'version' in agent:
+                    print(f"   Version: {agent['version']}")
+                print()
+    
+    elif args.deployed:
+        # List deployed agents
+        print("Deployed Agents:")
+        print("-" * 80)
+        verification = deployment_service.verify_deployment()
+        if not verification["agents_found"]:
+            print("No deployed agents found")
+        else:
+            for agent in verification["agents_found"]:
+                print(f"📄 {agent['file']}")
+                if 'name' in agent:
+                    print(f"   Name: {agent['name']}")
+                print(f"   Path: {agent['path']}")
+                print()
+        
+        if verification["warnings"]:
+            print("\nWarnings:")
+            for warning in verification["warnings"]:
+                print(f"  ⚠️  {warning}")
+    
+    else:
+        # Default: show usage
+        print("Use --system to list system agents or --deployed to list deployed agents")
+
+
+def _deploy_agents(args, deployment_service, force=False):
+    """
+    Deploy system agents.
+    
+    WHY: Agents need to be deployed to the working directory for Claude Code to use them.
+    This function handles both regular and forced deployment.
+    
+    Args:
+        args: Command arguments with optional 'target' path
+        deployment_service: Agent deployment service instance
+        force: Whether to force rebuild all agents
+    """
+    if force:
+        print("Force deploying all system agents...")
+    else:
+        print("Deploying system agents...")
+    
+    results = deployment_service.deploy_agents(args.target, force_rebuild=force)
+    
+    if results["deployed"]:
+        print(f"\n✓ Successfully deployed {len(results['deployed'])} agents to {results['target_dir']}")
+        for agent in results["deployed"]:
+            print(f"  - {agent['name']}")
+    
+    if force and results.get("updated", []):
+        print(f"\n✓ Updated {len(results['updated'])} agents")
+        for agent in results["updated"]:
+            print(f"  - {agent['name']}")
+    
+    if force and results.get("skipped", []):
+        print(f"\n✓ Skipped {len(results['skipped'])} up-to-date agents")
+    
+    if results["errors"]:
+        print("\n❌ Errors during deployment:")
+        for error in results["errors"]:
+            print(f"  - {error}")
+    
+    if force:
+        # Set environment for force deploy
+        env_vars = deployment_service.set_claude_environment(
+            args.target.parent if args.target else None
+        )
+        print(f"\n✓ Set Claude environment variables:")
+        for key, value in env_vars.items():
+            print(f"  - {key}={value}")
+
+
+def _clean_agents(args, deployment_service):
+    """
+    Clean deployed system agents.
+    
+    WHY: Users may want to remove deployed agents to start fresh or clean up
+    their working directory.
+    
+    Args:
+        args: Command arguments with optional 'target' path
+        deployment_service: Agent deployment service instance
+    """
+    print("Cleaning deployed system agents...")
+    results = deployment_service.clean_deployment(args.target)
+    
+    if results["removed"]:
+        print(f"\n✓ Removed {len(results['removed'])} agents")
+        for path in results["removed"]:
+            print(f"  - {Path(path).name}")
+    else:
+        print("No system agents found to remove")
+    
+    if results["errors"]:
+        print("\n❌ Errors during cleanup:")
+        for error in results["errors"]:
+            print(f"  - {error}")