claude-mpm 3.5.4__py3-none-any.whl → 3.5.6__py3-none-any.whl

claude_mpm/.claude-mpm/logs/hooks_20250728.log

@@ -0,0 +1,10 @@
+2025-07-28 09:57:00,914 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: 9a641bea)
+2025-07-28 09:57:00,914 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:254 - PostToolUse: Bash (exit code: N/A)
+2025-07-28 09:57:09,289 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: 9a641bea)
+2025-07-28 09:57:09,290 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:247 - PreToolUse: Bash
+2025-07-28 09:57:21,601 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: 9a641bea)
+2025-07-28 09:57:21,601 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:247 - PreToolUse: LS
+2025-07-28 09:57:25,939 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:231 - Claude Code hook event: PostToolUse (session: 9a641bea)
+2025-07-28 09:57:25,939 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:254 - PostToolUse: LS (exit code: N/A)
+2025-07-28 09:57:35,668 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:231 - Claude Code hook event: PreToolUse (session: 9a641bea)
+2025-07-28 09:57:35,668 - claude_mpm_hooks_claude_mpm - INFO - hook_handler.py:247 - PreToolUse: Bash

claude_mpm/VERSION

@@ -1 +1 @@
-3.5.4
+3.5.6

claude_mpm/agents/INSTRUCTIONS.md

@@ -249,14 +249,15 @@ See TODOWRITE.md for complete TodoWrite guidelines.
 ## Critical Operating Principles
 
 1. **🔴 ALWAYS DELEGATE BY DEFAULT** - You MUST delegate ALL work unless user EXPLICITLY says otherwise
-2. **You are an orchestrator and delegator ONLY** - Your value is in coordination, not implementation
-3. **Power through delegation** - Leverage specialized agents' expertise
-4. **Memory awareness** - Check EVERY prompt for memory indicators
-5. **Workflow discipline** - Follow the sequence unless explicitly overridden
-6. **TodoWrite compliance** - ALWAYS use [Agent] prefixes for delegated work
-7. **No direct implementation** - Delegate ALL technical work to specialists (NO EXCEPTIONS without explicit override)
-8. **PM questions only** - Only answer directly about PM role and capabilities
-9. **Context preservation** - Pass complete context to each agent
-10. **Error escalation** - Follow 3-attempt protocol before blocking
-11. **Professional communication** - Maintain neutral, clear tone
-12. **DEFAULT = DELEGATE** - When in doubt, ALWAYS delegate. Direct action requires EXPLICIT user permission
+2. **🔴 NEVER ASSUME - ALWAYS VERIFY** - NEVER assume anything about code, files, or implementations. ALWAYS verify by checking actual files, reading configs, and confirming dependencies exist
+3. **You are an orchestrator and delegator ONLY** - Your value is in coordination, not implementation
+4. **Power through delegation** - Leverage specialized agents' expertise
+5. **Memory awareness** - Check EVERY prompt for memory indicators
+6. **Workflow discipline** - Follow the sequence unless explicitly overridden
+7. **TodoWrite compliance** - ALWAYS use [Agent] prefixes for delegated work
+8. **No direct implementation** - Delegate ALL technical work to specialists (NO EXCEPTIONS without explicit override)
+9. **PM questions only** - Only answer directly about PM role and capabilities
+10. **Context preservation** - Pass complete context to each agent
+11. **Error escalation** - Follow 3-attempt protocol before blocking
+12. **Professional communication** - Maintain neutral, clear tone
+13. **DEFAULT = DELEGATE** - When in doubt, ALWAYS delegate. Direct action requires EXPLICIT user permission

claude_mpm/agents/agent-template.yaml

@@ -0,0 +1,83 @@
+# Agent Profile Template Configuration
+# Inspired by awesome-claude-code's template system
+
+profile:
+  name: "{{AGENT_NAME}}"
+  version: "{{VERSION}}"
+  description: "{{DESCRIPTION}}"
+  author: "{{AUTHOR}}"
+  created: "{{CREATED_DATE}}"
+  
+  # Categories for organizing agents
+  categories:
+    - id: analysis
+      title: "Code Analysis Agents"
+      description: |
+        > Agents specialized in analyzing codebases, identifying patterns, and providing insights
+      icon: "🔍"
+    
+    - id: implementation
+      title: "Implementation Agents"
+      description: |
+        > Agents focused on writing and modifying code
+      icon: "🛠️"
+    
+    - id: testing
+      title: "Testing & QA Agents"
+      description: |
+        > Agents dedicated to testing, quality assurance, and validation
+      icon: "🧪"
+    
+    - id: security
+      title: "Security Agents"
+      description: |
+        > Agents specialized in security analysis and vulnerability detection
+      icon: "🔒"
+
+agents:
+  - name: "{{AGENT_ID}}"
+    category: "{{CATEGORY}}"
+    role: "{{ROLE}}"
+    description: "{{AGENT_DESCRIPTION}}"
+    
+    capabilities:
+      - "{{CAPABILITY_1}}"
+      - "{{CAPABILITY_2}}"
+      - "{{CAPABILITY_3}}"
+    
+    constraints:
+      - "{{CONSTRAINT_1}}"
+      - "{{CONSTRAINT_2}}"
+    
+    tools:
+      - name: "{{TOOL_NAME}}"
+        description: "{{TOOL_DESCRIPTION}}"
+        required: true
+    
+    prompt_template: |
+      You are a {{ROLE}} agent specializing in {{SPECIALIZATION}}.
+      
+      ## Your Capabilities:
+      {{CAPABILITIES_LIST}}
+      
+      ## Your Constraints:
+      {{CONSTRAINTS_LIST}}
+      
+      ## Context:
+      {context}
+      
+      ## Task:
+      {task}
+      
+      ## Additional Instructions:
+      {{ADDITIONAL_INSTRUCTIONS}}
+    
+    examples:
+      - scenario: "{{EXAMPLE_SCENARIO}}"
+        input: "{{EXAMPLE_INPUT}}"
+        expected_output: "{{EXAMPLE_OUTPUT}}"
+    
+    best_practices:
+      - "{{BEST_PRACTICE_1}}"
+      - "{{BEST_PRACTICE_2}}"
+      - "{{BEST_PRACTICE_3}}"

claude_mpm/cli/README.md

@@ -0,0 +1,108 @@
+# 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
+└── 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/commands/agents.py

@@ -34,7 +34,16 @@ def manage_agents(args):
     
     try:
         from ...services import AgentDeploymentService
-        deployment_service = AgentDeploymentService()
+        import os
+        from pathlib import Path
+        
+        # Determine the user's working directory from environment
+        # This ensures agents are deployed to the correct directory
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        
+        deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         
         if not args.agents_command:
             # No subcommand - show agent versions
@@ -153,7 +162,15 @@ def _deploy_agents(args, deployment_service, force=False):
     
     # Also deploy project agents if they exist
     from pathlib import Path
-    project_agents_dir = Path.cwd() / '.claude-mpm' / 'agents'
+    import os
+    
+    # Use the user's working directory if available
+    if 'CLAUDE_MPM_USER_PWD' in os.environ:
+        project_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+    else:
+        project_dir = Path.cwd()
+    
+    project_agents_dir = project_dir / '.claude-mpm' / 'agents'
     if project_agents_dir.exists():
         json_files = list(project_agents_dir.glob('*.json'))
         if json_files:
@@ -161,7 +178,8 @@ def _deploy_agents(args, deployment_service, force=False):
             from claude_mpm.services.agents.deployment.agent_deployment import AgentDeploymentService
             project_service = AgentDeploymentService(
                 templates_dir=project_agents_dir,
-                base_agent_path=project_agents_dir / 'base_agent.json' if (project_agents_dir / 'base_agent.json').exists() else None
+                base_agent_path=project_agents_dir / 'base_agent.json' if (project_agents_dir / 'base_agent.json').exists() else None,
+                working_directory=project_dir  # Pass the project directory
             )
             project_results = project_service.deploy_agents(
                 target_dir=args.target if args.target else Path.cwd() / '.claude' / 'agents',

claude_mpm/cli/commands/run.py

@@ -281,17 +281,10 @@ def run_session(args):
         websocket_port=websocket_port
     )
     
-    # Ensure project agents are available if we're in a project directory
-    # This deploys system agents to .claude-mpm/agents/ for local customization
-    if not hasattr(args, 'no_native_agents') or not args.no_native_agents:
-        # Check if we're in a project directory (has .git or other markers)
-        project_markers = ['.git', 'pyproject.toml', 'package.json', 'requirements.txt']
-        cwd = Path.cwd()
-        is_project = any((cwd / marker).exists() for marker in project_markers)
-        
-        if is_project:
-            logger.debug("Detected project directory, ensuring agents are available locally")
-            runner.ensure_project_agents()
+    # Agent deployment is handled by ClaudeRunner.setup_agents() and 
+    # ClaudeRunner.deploy_project_agents_to_claude() which are called
+    # in both run_interactive() and run_oneshot() methods.
+    # No need for redundant deployment here.
     
     # Set browser opening flag for monitor mode
     if monitor_mode:

claude_mpm/cli/utils.py

@@ -61,7 +61,15 @@ def get_agent_versions_display() -> Optional[str]:
     """
     try:
         from ..services import AgentDeploymentService
-        deployment_service = AgentDeploymentService()
+        import os
+        from pathlib import Path
+        
+        # Determine the user's working directory from environment
+        user_working_dir = None
+        if 'CLAUDE_MPM_USER_PWD' in os.environ:
+            user_working_dir = Path(os.environ['CLAUDE_MPM_USER_PWD'])
+        
+        deployment_service = AgentDeploymentService(working_directory=user_working_dir)
         
         # Get deployed agents
         verification = deployment_service.verify_deployment()

claude_mpm/cli_module/refactoring_guide.md

@@ -0,0 +1,253 @@
+# CLI Refactoring Guide
+
+This guide shows how to refactor the main() function in `/src/claude_mpm/cli.py` to reduce complexity from 16 to under 10.
+
+## Current Issues
+
+1. **High Cyclomatic Complexity (16)**
+   - Multiple nested conditionals
+   - Duplicate argument definitions
+   - Mixed concerns in one function
+
+2. **Code Duplication**
+   - Arguments defined twice (global level + run subcommand)
+   - Similar patterns repeated for each command
+
+3. **Poor Maintainability**
+   - Adding new commands requires multiple changes
+   - Hard to test individual components
+
+## Refactoring Steps
+
+### Step 1: Update imports in cli.py
+
+```python
+# Add to imports
+from .cli import ArgumentRegistry, CommandRegistry, register_standard_commands
+```
+
+### Step 2: Replace main() function
+
+Replace the entire `main()` function with:
+
+```python
+def main(argv: Optional[list] = None):
+    """Main CLI entry point with reduced complexity."""
+    # Initialize registries
+    arg_registry = ArgumentRegistry()
+    cmd_registry = CommandRegistry(arg_registry)
+    
+    # Register standard commands
+    register_standard_commands(cmd_registry)
+    
+    # Create parser
+    parser = argparse.ArgumentParser(
+        prog="claude-mpm",
+        description=f"Claude Multi-Agent Project Manager v{__version__}",
+        epilog="By default, runs an orchestrated Claude session."
+    )
+    
+    # Store version for ArgumentRegistry
+    parser._version = f"claude-mpm {__version__}"
+    
+    # Apply global arguments
+    arg_registry.apply_arguments(parser, groups=['global'])
+    
+    # Apply run arguments at top level (for default behavior)
+    arg_registry.apply_arguments(parser, groups=['run'], exclude=['no_hooks'])
+    
+    # Set up subcommands
+    cmd_registry.setup_subcommands(parser)
+    
+    # Parse arguments
+    args = parser.parse_args(argv)
+    
+    # Set up logging
+    _setup_logging(args)
+    
+    # Initialize hook service
+    hook_manager = _initialize_hook_service(args)
+    
+    try:
+        # Execute command
+        result = cmd_registry.execute_command(args, hook_manager=hook_manager)
+        if result is None and not args.command:
+            parser.print_help()
+            return 1
+        return result or 0
+        
+    except KeyboardInterrupt:
+        get_logger("cli").info("Session interrupted by user")
+        return 0
+    except Exception as e:
+        logger = get_logger("cli")
+        logger.error(f"Error: {e}")
+        if args.debug:
+            import traceback
+            traceback.print_exc()
+        return 1
+    finally:
+        if hook_manager:
+            hook_manager.stop_service()
+```
+
+### Step 3: Extract helper functions
+
+Add these helper functions after main():
+
+```python
+def _setup_logging(args):
+    """Set up logging based on arguments."""
+    if args.debug and args.logging == "OFF":
+        args.logging = "DEBUG"
+    
+    if args.logging != "OFF":
+        setup_logging(level=args.logging, log_dir=args.log_dir)
+    else:
+        import logging
+        logger = logging.getLogger("cli")
+        logger.setLevel(logging.WARNING)
+
+
+def _initialize_hook_service(args):
+    """Initialize hook service if enabled."""
+    if getattr(args, 'no_hooks', False):
+        return None
+        
+    try:
+        from .config.hook_config import HookConfig
+        
+        if not HookConfig.is_hooks_enabled():
+            get_logger("cli").info("Hooks disabled via configuration")
+            return None
+            
+        hook_manager = HookServiceManager(log_dir=args.log_dir)
+        if hook_manager.start_service():
+            logger = get_logger("cli")
+            logger.info(f"Hook service started on port {hook_manager.port}")
+            print(f"Hook service started on port {hook_manager.port}")
+            return hook_manager
+        else:
+            logger = get_logger("cli")
+            logger.warning("Failed to start hook service")
+            print("Failed to start hook service, continuing without hooks")
+            return None
+            
+    except Exception as e:
+        get_logger("cli").warning(f"Hook service init failed: {e}")
+        return None
+```
+
+### Step 4: Update command handler signatures
+
+Ensure all command handlers accept `**kwargs`:
+
+```python
+def run_session(args, hook_manager=None, **kwargs):
+    """Run an orchestrated Claude session."""
+    # ... existing implementation
+
+def list_tickets(args, **kwargs):
+    """List recent tickets."""
+    # ... existing implementation
+
+def show_info(args, hook_manager=None, **kwargs):
+    """Show framework and configuration information."""
+    # ... existing implementation
+```
+
+## Benefits Achieved
+
+### Complexity Reduction
+- **Before**: Cyclomatic complexity of 16
+- **After**: Cyclomatic complexity of ~8
+
+### Code Organization
+- Centralized argument definitions
+- No duplicate argument definitions
+- Clear separation of concerns
+- Easier to add new commands
+
+### Maintainability
+- New commands can be added with a single `register()` call
+- Arguments are defined once and reused
+- Helper functions are testable in isolation
+- Registry pattern allows for extension
+
+## Adding New Commands
+
+With the registry system, adding a new command is simple:
+
+```python
+# In your code or plugin
+def my_command(args, **kwargs):
+    """Implementation of your command."""
+    print(f"Running my command with args: {args}")
+    return 0
+
+# Register it
+cmd_registry.register(
+    name='mycommand',
+    help_text='Description of my command',
+    handler=my_command,
+    argument_groups=['framework'],  # Reuse existing argument groups
+    extra_args={
+        'custom_arg': {
+            'flags': ['--custom'],
+            'type': str,
+            'help': 'A custom argument for this command'
+        }
+    }
+)
+```
+
+## Testing
+
+The refactored code is easier to test:
+
+```python
+# Test argument registry
+def test_argument_registry():
+    registry = ArgumentRegistry()
+    parser = argparse.ArgumentParser()
+    registry.apply_arguments(parser, groups=['logging'])
+    
+    # Verify logging arguments were added
+    args = parser.parse_args(['--logging', 'DEBUG'])
+    assert args.logging == 'DEBUG'
+
+# Test command registry
+def test_command_registry():
+    arg_reg = ArgumentRegistry()
+    cmd_reg = CommandRegistry(arg_reg)
+    
+    called = False
+    def test_handler(args, **kwargs):
+        nonlocal called
+        called = True
+        return 0
+    
+    cmd_reg.register('test', 'Test command', test_handler)
+    
+    parser = argparse.ArgumentParser()
+    cmd_reg.setup_subcommands(parser)
+    
+    args = parser.parse_args(['test'])
+    result = cmd_reg.execute_command(args)
+    
+    assert called
+    assert result == 0
+```
+
+## Migration Checklist
+
+- [ ] Create `/src/claude_mpm/cli/` directory
+- [ ] Create `args.py` with ArgumentRegistry
+- [ ] Create `commands.py` with CommandRegistry
+- [ ] Create `__init__.py` to export classes
+- [ ] Update imports in `cli.py`
+- [ ] Replace main() function
+- [ ] Add helper functions
+- [ ] Update command handler signatures
+- [ ] Test the refactored CLI
+- [ ] Verify complexity is reduced to ≤10