claude-mpm 0.3.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

claude_mpm/cli_enhancements.py

@@ -0,0 +1,297 @@
+"""
+Enhanced CLI operations for claude-mpm.
+
+Implements error handling and user guidance patterns from awesome-claude-code.
+"""
+
+import click
+import sys
+import logging
+from typing import Optional, Any, Dict, List
+from pathlib import Path
+
+from claude_mpm.utils.error_handler import (
+    MPMError, ErrorContext, handle_errors, suggest_setup_fix
+)
+from claude_mpm.validation import AgentValidator, ValidationResult
+from claude_mpm.hooks.validation_hooks import ValidationHooks, ValidationError
+
+logger = logging.getLogger(__name__)
+
+
+class CLIContext:
+    """Enhanced CLI context with validation and error handling."""
+    
+    def __init__(self):
+        """Initialize CLI context."""
+        self.validator = AgentValidator()
+        self.validation_hooks = ValidationHooks()
+        self.debug = False
+        self.dry_run = False
+    
+    def setup_logging(self, debug: bool = False) -> None:
+        """Setup logging based on debug flag."""
+        level = logging.DEBUG if debug else logging.INFO
+        format_str = "%(asctime)s - %(name)s - %(levelname)s - %(message)s" if debug else "%(message)s"
+        
+        logging.basicConfig(
+            level=level,
+            format=format_str,
+            handlers=[logging.StreamHandler(sys.stdout)]
+        )
+        self.debug = debug
+    
+    def validate_prerequisites(self) -> bool:
+        """Validate system prerequisites."""
+        print("Checking prerequisites...")
+        all_passed = True
+        
+        # Check Python version
+        if sys.version_info < (3, 11):
+            print("❌ Python 3.11 or higher is required")
+            all_passed = False
+        else:
+            print("✓ Python version is compatible")
+        
+        # Check required directories
+        required_dirs = [
+            Path.home() / '.claude-mpm',
+            Path.home() / '.claude-mpm' / 'profiles',
+            Path.home() / '.claude-mpm' / 'logs',
+        ]
+        
+        for dir_path in required_dirs:
+            if not dir_path.exists():
+                try:
+                    dir_path.mkdir(parents=True)
+                    print(f"✓ Created directory: {dir_path}")
+                except Exception as e:
+                    print(f"❌ Failed to create directory {dir_path}: {e}")
+                    all_passed = False
+        
+        return all_passed
+    
+    def handle_validation_result(self, result: ValidationResult, 
+                               operation: str = "operation") -> None:
+        """Handle validation results with user-friendly output."""
+        if result.is_valid:
+            if result.warnings:
+                print(f"⚠️  {operation} completed with warnings:")
+                for warning in result.warnings:
+                    print(f"   - {warning}")
+            else:
+                print(f"✅ {operation} completed successfully")
+        else:
+            print(f"❌ {operation} failed validation:")
+            for error in result.errors:
+                print(f"   - {error}")
+            
+            if result.warnings:
+                print("\nAdditional warnings:")
+                for warning in result.warnings:
+                    print(f"   - {warning}")
+            
+            sys.exit(1)
+
+
+def create_enhanced_cli() -> click.Group:
+    """Create enhanced CLI with better error handling."""
+    cli_context = CLIContext()
+    
+    @click.group()
+    @click.option('--debug', is_flag=True, help='Enable debug logging')
+    @click.option('--dry-run', is_flag=True, help='Run without making changes')
+    @click.pass_context
+    def cli(ctx, debug: bool, dry_run: bool):
+        """Enhanced claude-mpm CLI with validation and error handling."""
+        ctx.obj = cli_context
+        cli_context.setup_logging(debug)
+        cli_context.dry_run = dry_run
+        
+        if debug:
+            print("🐛 Debug mode enabled")
+        if dry_run:
+            print("🏃 Dry-run mode enabled")
+    
+    @cli.command()
+    @click.pass_context
+    def validate_setup(ctx):
+        """Validate system setup and prerequisites."""
+        cli_ctx = ctx.obj
+        
+        with ErrorContext("setup validation"):
+            if cli_ctx.validate_prerequisites():
+                print("\n✅ All prerequisites satisfied!")
+                print("   You're ready to use claude-mpm")
+            else:
+                print("\n❌ Setup validation failed")
+                print("\n💡 Setup hints:")
+                print("   - Ensure Python 3.11+ is installed")
+                print("   - Check file permissions for ~/.claude-mpm")
+                print("   - Run with --debug for more details")
+                sys.exit(1)
+    
+    @cli.command()
+    @click.argument('profile_path', type=click.Path(exists=True))
+    @click.pass_context
+    @handle_errors(MPMError)
+    async def validate_profile(ctx, profile_path: str):
+        """Validate an agent profile."""
+        cli_ctx = ctx.obj
+        profile = Path(profile_path)
+        
+        print(f"Validating profile: {profile.name}")
+        
+        # Run pre-load validation
+        result = await cli_ctx.validation_hooks.run_pre_load_validation(profile)
+        
+        cli_ctx.handle_validation_result(result, f"Profile validation for {profile.name}")
+        
+        if result.is_valid and result.locked_fields:
+            print(f"\n🔒 Locked fields: {', '.join(result.locked_fields)}")
+    
+    @cli.command()
+    @click.option('--profile', '-p', help='Agent profile to load')
+    @click.option('--task', '-t', help='Task to execute')
+    @click.pass_context
+    @handle_errors(MPMError)
+    async def run_agent(ctx, profile: str, task: str):
+        """Run an agent with enhanced validation."""
+        cli_ctx = ctx.obj
+        
+        if not profile or not task:
+            raise click.UsageError("Both --profile and --task are required")
+        
+        # Validate profile exists
+        profile_path = Path(profile)
+        if not profile_path.exists():
+            # Try default locations
+            default_locations = [
+                Path.home() / '.claude-mpm' / 'profiles' / f"{profile}.yaml",
+                Path.cwd() / 'agents' / f"{profile}.yaml",
+            ]
+            
+            for location in default_locations:
+                if location.exists():
+                    profile_path = location
+                    break
+            else:
+                raise MPMError(
+                    f"Profile '{profile}' not found",
+                    details={'searched_locations': [str(p) for p in default_locations]},
+                    suggestions=[
+                        "Check the profile name",
+                        "Use 'mpm list-profiles' to see available profiles",
+                        "Create a new profile with 'mpm create-profile'"
+                    ]
+                )
+        
+        # Run validation
+        print(f"🔍 Validating profile: {profile_path.name}")
+        validation_result = await cli_ctx.validation_hooks.run_pre_load_validation(profile_path)
+        
+        if not validation_result.is_valid:
+            cli_ctx.handle_validation_result(validation_result, "Profile validation")
+            return
+        
+        # Validate task
+        print(f"🔍 Validating task...")
+        task_result = await cli_ctx.validation_hooks.run_pre_execute_validation(
+            profile_path.stem, task
+        )
+        
+        if not task_result.is_valid:
+            cli_ctx.handle_validation_result(task_result, "Task validation")
+            return
+        
+        if cli_ctx.dry_run:
+            print("\n🏃 Dry-run mode - would execute:")
+            print(f"   Profile: {profile_path}")
+            print(f"   Task: {task[:100]}{'...' if len(task) > 100 else ''}")
+        else:
+            print(f"\n🚀 Executing agent from {profile_path.name}...")
+            # Actual execution would go here
+            print("✅ Agent execution completed")
+    
+    @cli.command()
+    @click.pass_context
+    def list_profiles(ctx):
+        """List available agent profiles."""
+        cli_ctx = ctx.obj
+        
+        profile_locations = [
+            Path.home() / '.claude-mpm' / 'profiles',
+            Path.cwd() / 'agents',
+        ]
+        
+        all_profiles = []
+        for location in profile_locations:
+            if location.exists():
+                profiles = list(location.glob('*.yaml')) + list(location.glob('*.yml'))
+                all_profiles.extend(profiles)
+        
+        if not all_profiles:
+            print("No agent profiles found")
+            print("\n💡 Create a profile with: mpm create-profile")
+            return
+        
+        print("Available agent profiles:")
+        for profile in sorted(all_profiles):
+            # Quick validation check
+            result = cli_ctx.validator.validate_profile(profile)
+            status = "✅" if result.is_valid else "⚠️"
+            print(f"  {status} {profile.stem} ({profile})")
+    
+    @cli.command()
+    @click.argument('name')
+    @click.option('--role', '-r', required=True, help='Agent role')
+    @click.option('--category', '-c', default='analysis', help='Agent category')
+    @click.pass_context
+    def create_profile(ctx, name: str, role: str, category: str):
+        """Create a new agent profile from template."""
+        from claude_mpm.generators import AgentProfileGenerator
+        
+        cli_ctx = ctx.obj
+        generator = AgentProfileGenerator()
+        
+        print(f"Creating agent profile: {name}")
+        
+        # Generate configuration
+        config = generator.create_agent_from_template(name, role, category)
+        
+        # Generate profile
+        profile_content = generator.generate_profile(config)
+        
+        # Save profile
+        profile_dir = Path.home() / '.claude-mpm' / 'profiles'
+        profile_dir.mkdir(parents=True, exist_ok=True)
+        
+        profile_path = profile_dir / f"{name.lower().replace(' ', '_')}.yaml"
+        
+        if profile_path.exists() and not click.confirm(f"Profile {profile_path} exists. Overwrite?"):
+            print("Aborted")
+            return
+        
+        if cli_ctx.dry_run:
+            print(f"\n🏃 Dry-run mode - would create {profile_path}:")
+            print("---")
+            print(profile_content[:500] + "..." if len(profile_content) > 500 else profile_content)
+            print("---")
+        else:
+            profile_path.write_text(profile_content)
+            print(f"✅ Created profile: {profile_path}")
+            
+            # Generate documentation
+            doc_path = profile_path.with_suffix('.md')
+            doc_content = generator.generate_agent_documentation(config)
+            doc_path.write_text(doc_content)
+            print(f"📝 Created documentation: {doc_path}")
+    
+    return cli
+
+
+# Export the enhanced CLI
+enhanced_cli = create_enhanced_cli()
+
+if __name__ == '__main__':
+    enhanced_cli()

claude_mpm/core/agent_name_normalizer.py

@@ -242,6 +242,55 @@ class AgentNameNormalizer:
             return False, f"Unknown agent '{agent}'. Valid agents: {', '.join(cls.CANONICAL_NAMES.values())}"
         
         return True, None
+    
+    @classmethod
+    def to_task_format(cls, agent_name: str) -> str:
+        """
+        Convert agent name from TodoWrite format to Task tool format.
+        
+        Args:
+            agent_name: The agent name in TodoWrite format (e.g., "Research", "Version Control")
+            
+        Returns:
+            The agent name in Task tool format (e.g., "research", "version-control")
+            
+        Examples:
+            "Research" → "research"
+            "Version Control" → "version-control" 
+            "Data Engineer" → "data-engineer"
+            "QA" → "qa"
+        """
+        # First normalize to canonical form
+        normalized = cls.normalize(agent_name)
+        # Convert to lowercase and replace spaces with hyphens
+        return normalized.lower().replace(" ", "-")
+    
+    @classmethod
+    def from_task_format(cls, task_format: str) -> str:
+        """
+        Convert agent name from Task tool format to TodoWrite format.
+        
+        Args:
+            task_format: The agent name in Task tool format (e.g., "research", "version-control")
+            
+        Returns:
+            The agent name in TodoWrite format (e.g., "Research", "Version Control")
+            
+        Examples:
+            "research" → "Research"
+            "version-control" → "Version Control"
+            "data-engineer" → "Data Engineer"
+            "qa" → "QA"
+        """
+        # Replace hyphens with underscores for lookup
+        lookup_key = task_format.replace("-", "_")
+        
+        # Check if it's a valid canonical key
+        if lookup_key in cls.CANONICAL_NAMES:
+            return cls.CANONICAL_NAMES[lookup_key]
+        
+        # Try normalizing as-is
+        return cls.normalize(task_format)
 
 
 # Global instance for easy access

claude_mpm/core/factories.py

@@ -12,7 +12,6 @@ from typing import Any, Dict, Optional, Type, TypeVar
 from .container import DIContainer
 from .logger import get_logger
 from .config import Config
-from ..services.json_rpc_hook_manager import JSONRPCHookManager
 from ..services.agent_deployment import AgentDeploymentService
 from ..orchestration.factory import OrchestratorFactory
 from ..orchestration.base import BaseOrchestrator
@@ -31,47 +30,6 @@ class ServiceFactory(ABC):
         pass
 
 
-class HookManagerFactory(ServiceFactory):
-    """Factory for creating hook manager instances."""
-    
-    def create(
-        self,
-        container: DIContainer,
-        log_dir: Optional[Path] = None,
-        enabled: bool = True
-    ) -> Optional[JSONRPCHookManager]:
-        """
-        Create a hook manager instance.
-        
-        Args:
-            container: DI container
-            log_dir: Log directory path
-            enabled: Whether hooks are enabled
-            
-        Returns:
-            Hook manager instance or None if disabled
-        """
-        config = container.resolve(Config)
-        
-        # Check if hooks are enabled
-        if not enabled or config.get('hooks.enabled', True) is False:
-            logger.info("Hooks are disabled")
-            return None
-            
-        # Get log directory from config if not provided
-        if log_dir is None:
-            log_dir = Path(config.get('log_dir', '.claude-mpm/logs'))
-            
-        # Create hook manager
-        hook_manager = JSONRPCHookManager(log_dir=log_dir)
-        
-        # Start the service
-        if hook_manager.start_service():
-            logger.info("Hook manager initialized successfully")
-            return hook_manager
-        else:
-            logger.warning("Failed to start hook manager")
-            return None
 
 
 class OrchestratorFactoryWrapper(ServiceFactory):
@@ -110,9 +68,7 @@ class OrchestratorFactoryWrapper(ServiceFactory):
         # Merge with provided kwargs
         orch_config.update(kwargs)
         
-        # Inject services into orchestrator config
-        if 'hook_manager' not in orch_config and container.is_registered(JSONRPCHookManager):
-            orch_config['hook_manager'] = container.resolve_optional(JSONRPCHookManager)
+        # No hook manager injection needed - Claude Code hooks are external
             
         # Create orchestrator
         orchestrator = self._factory.create_orchestrator(
@@ -248,7 +204,6 @@ class FactoryRegistry:
     def __init__(self):
         """Initialize factory registry."""
         self._factories: Dict[str, ServiceFactory] = {
-            'hook_manager': HookManagerFactory(),
             'orchestrator': OrchestratorFactoryWrapper(),
             'agent_service': AgentServiceFactory(),
             'session_manager': SessionManagerFactory(),

claude_mpm/core/service_registry.py

@@ -37,7 +37,6 @@ class ServiceRegistry:
     def register_core_services(self) -> None:
         """Register all core framework services."""
         from ..services.shared_prompt_cache import SharedPromptCache
-        from ..services.json_rpc_hook_manager import JSONRPCHookManager
         from ..services.ticket_manager import TicketManager
         from ..services.agent_deployment import AgentDeploymentService
         from .session_manager import SessionManager
@@ -72,13 +71,6 @@ class ServiceRegistry:
             factory=lambda c: SharedPromptCache.get_instance()
         )
         
-        # Register hook manager
-        self.register_service(
-            "hook_manager",
-            JSONRPCHookManager,
-            lifetime=ServiceLifetime.SINGLETON
-        )
-        
         # Register ticket manager
         self.register_service(
             "ticket_manager",

claude_mpm/core/simple_runner.py

@@ -254,6 +254,10 @@ class SimpleClaudeRunner:
         """Run Claude with a single prompt and return success status."""
         start_time = time.time()
         
+        # Check for /mpm: commands
+        if prompt.strip().startswith("/mpm:"):
+            return self._handle_mpm_command(prompt.strip())
+        
         if self.project_logger:
             self.project_logger.log_system(
                 f"Starting non-interactive session with prompt: {prompt[:100]}",
@@ -460,6 +464,45 @@ class SimpleClaudeRunner:
         text_lower = text.lower()
         return any(pattern.lower() in text_lower for pattern in delegation_patterns)
     
+    def _handle_mpm_command(self, prompt: str) -> bool:
+        """Handle /mpm: commands directly without going to Claude."""
+        try:
+            # Extract command and arguments
+            command_line = prompt[5:].strip()  # Remove "/mpm:"
+            parts = command_line.split()
+            
+            if not parts:
+                print("No command specified. Available commands: test")
+                return True
+            
+            command = parts[0]
+            args = parts[1:]
+            
+            # Handle commands
+            if command == "test":
+                print("Hello World")
+                if self.project_logger:
+                    self.project_logger.log_system(
+                        "Executed /mpm:test command",
+                        level="INFO",
+                        component="command"
+                    )
+                return True
+            else:
+                print(f"Unknown command: {command}")
+                print("Available commands: test")
+                return True
+                
+        except Exception as e:
+            print(f"Error executing command: {e}")
+            if self.project_logger:
+                self.project_logger.log_system(
+                    f"Failed to execute /mpm: command: {e}",
+                    level="ERROR",
+                    component="command"
+                )
+            return False
+    
     def _log_session_event(self, event_data: dict):
         """Log an event to the session log file."""
         if self.session_log_file:
@@ -491,6 +534,13 @@ You have access to native subagents via the Task tool with subagent_type paramet
 
 Use these agents by calling: Task(description="task description", subagent_type="agent_name")
 
+IMPORTANT: The Task tool accepts both naming formats:
+- Capitalized format: "Research", "Engineer", "QA", "Version Control", "Data Engineer"
+- Lowercase format: "research", "engineer", "qa", "version-control", "data-engineer"
+
+Both formats work correctly. When you see capitalized names (matching TodoWrite prefixes), 
+automatically normalize them to lowercase-hyphenated format for the Task tool.
+
 Work efficiently and delegate appropriately to subagents when needed."""
 
 

claude_mpm/generators/__init__.py

@@ -0,0 +1,5 @@
+"""Code and documentation generators for claude-mpm."""
+
+from .agent_profile_generator import AgentProfileGenerator
+
+__all__ = ['AgentProfileGenerator']

claude_mpm/generators/agent_profile_generator.py

@@ -0,0 +1,137 @@
+"""
+Agent profile generator using template system.
+
+Inspired by awesome-claude-code's template generation approach.
+"""
+
+import yaml
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, Any, Optional
+import re
+
+
+class AgentProfileGenerator:
+    """Generates agent profiles from templates."""
+    
+    def __init__(self, template_path: Optional[Path] = None):
+        """Initialize the generator with a template path."""
+        self.template_path = template_path or Path(__file__).parent.parent / "agents" / "agent-template.yaml"
+        self.template = self._load_template()
+    
+    def _load_template(self) -> Dict[str, Any]:
+        """Load the agent profile template."""
+        if not self.template_path.exists():
+            raise FileNotFoundError(f"Template not found: {self.template_path}")
+        
+        with open(self.template_path, 'r') as f:
+            return yaml.safe_load(f)
+    
+    def generate_profile(self, config: Dict[str, Any]) -> str:
+        """Generate an agent profile from configuration."""
+        # Set default values
+        config.setdefault('VERSION', '1.0.0')
+        config.setdefault('CREATED_DATE', datetime.now().strftime('%Y-%m-%d'))
+        config.setdefault('AUTHOR', 'claude-mpm')
+        
+        # Convert template to string
+        template_str = yaml.dump(self.template, default_flow_style=False)
+        
+        # Replace placeholders
+        result = self._replace_placeholders(template_str, config)
+        
+        # Clean up any remaining placeholders
+        result = re.sub(r'\{\{[^}]+\}\}', '', result)
+        
+        return result
+    
+    def _replace_placeholders(self, template: str, values: Dict[str, Any]) -> str:
+        """Replace template placeholders with actual values."""
+        for key, value in values.items():
+            placeholder = f"{{{{{key}}}}}"
+            if isinstance(value, list):
+                # Format lists nicely
+                formatted_list = '\n'.join(f"      - \"{item}\"" for item in value)
+                template = template.replace(placeholder, formatted_list)
+            else:
+                template = template.replace(placeholder, str(value))
+        
+        return template
+    
+    def generate_agent_documentation(self, agent_config: Dict[str, Any]) -> str:
+        """Generate markdown documentation for an agent."""
+        doc_lines = []
+        
+        # Header
+        doc_lines.append(f"# {agent_config.get('name', 'Agent')} Documentation")
+        doc_lines.append("")
+        
+        # Description
+        if 'description' in agent_config:
+            doc_lines.append("## Description")
+            doc_lines.append(agent_config['description'])
+            doc_lines.append("")
+        
+        # Capabilities
+        if 'capabilities' in agent_config:
+            doc_lines.append("## Capabilities")
+            for capability in agent_config['capabilities']:
+                doc_lines.append(f"- {capability}")
+            doc_lines.append("")
+        
+        # Tools
+        if 'tools' in agent_config:
+            doc_lines.append("## Required Tools")
+            for tool in agent_config['tools']:
+                if isinstance(tool, dict):
+                    doc_lines.append(f"- **{tool['name']}**: {tool.get('description', '')}")
+                else:
+                    doc_lines.append(f"- {tool}")
+            doc_lines.append("")
+        
+        # Examples
+        if 'examples' in agent_config:
+            doc_lines.append("## Usage Examples")
+            for i, example in enumerate(agent_config['examples'], 1):
+                doc_lines.append(f"### Example {i}: {example.get('scenario', 'Scenario')}")
+                doc_lines.append("```")
+                doc_lines.append(f"Input: {example.get('input', '')}")
+                doc_lines.append("```")
+                doc_lines.append("Expected Output:")
+                doc_lines.append("```")
+                doc_lines.append(example.get('expected_output', ''))
+                doc_lines.append("```")
+                doc_lines.append("")
+        
+        # Best Practices
+        if 'best_practices' in agent_config:
+            doc_lines.append("## Best Practices")
+            for practice in agent_config['best_practices']:
+                doc_lines.append(f"- {practice}")
+            doc_lines.append("")
+        
+        return '\n'.join(doc_lines)
+    
+    def create_agent_from_template(self, agent_name: str, role: str, 
+                                 category: str = "analysis") -> Dict[str, Any]:
+        """Create a new agent configuration from template."""
+        return {
+            'AGENT_NAME': agent_name,
+            'AGENT_ID': agent_name.lower().replace(' ', '_'),
+            'ROLE': role,
+            'CATEGORY': category,
+            'DESCRIPTION': f"Agent profile for {agent_name}",
+            'AGENT_DESCRIPTION': f"Specialized {role} agent",
+            'SPECIALIZATION': role.lower(),
+            'CAPABILITIES_LIST': "- Analyze code structure\n- Identify patterns\n- Generate reports",
+            'CONSTRAINTS_LIST': "- Read-only operations\n- Respect file permissions",
+            'TOOL_NAME': 'code_analysis',
+            'TOOL_DESCRIPTION': 'Analyzes code structure and patterns',
+            'EXAMPLE_SCENARIO': 'Analyzing a Python project',
+            'EXAMPLE_INPUT': 'Analyze the architecture of this codebase',
+            'EXAMPLE_OUTPUT': 'Detailed analysis report with recommendations',
+            'BEST_PRACTICE_1': 'Always validate input parameters',
+            'BEST_PRACTICE_2': 'Provide clear, actionable insights',
+            'BEST_PRACTICE_3': 'Include examples in reports',
+            'ADDITIONAL_INSTRUCTIONS': 'Be thorough but concise in your analysis.'
+        }