claude-mpm 3.7.8__py3-none-any.whl → 3.9.0__py3-none-any.whl

claude_mpm/validation/frontmatter_validator.py

@@ -0,0 +1,231 @@
+"""
+Claude Code Frontmatter Validator
+
+Validates agent frontmatter against Claude Code Desktop specification.
+Critical for ensuring agents work correctly with Claude Desktop.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+import yaml
+
+
+class FrontmatterValidator:
+    """Validates agent frontmatter against Claude Code specification."""
+    
+    # Claude Code name pattern: lowercase letters, numbers, hyphens only
+    # NO UNDERSCORES, NO UPPERCASE, NO SPECIAL CHARACTERS
+    NAME_PATTERN = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
+    
+    # Valid tool names (from Claude Code spec)
+    VALID_TOOLS = {
+        'Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Grep', 'Glob', 'LS',
+        'WebSearch', 'WebFetch', 'TodoWrite', 'BashOutput', 'KillBash',
+        'NotebookEdit', 'Task', 'ExitPlanMode'
+    }
+    
+    # Valid model tiers
+    VALID_MODELS = {'opus', 'sonnet', 'haiku'}
+    
+    # Required fields in frontmatter
+    REQUIRED_FIELDS = {'name', 'description', 'tools'}
+    
+    @classmethod
+    def validate_name(cls, name: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate agent name field against Claude Code spec.
+        
+        Args:
+            name: Agent name to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if not name:
+            return False, "Name field is required"
+        
+        if not cls.NAME_PATTERN.match(name):
+            return False, (
+                f"Invalid name '{name}'. Must match pattern ^[a-z0-9]+(-[a-z0-9]+)*$ "
+                "(lowercase letters, numbers, and hyphens only - NO underscores!)"
+            )
+        
+        if len(name) > 50:
+            return False, f"Name '{name}' too long (max 50 characters)"
+        
+        return True, None
+    
+    @classmethod
+    def validate_tools(cls, tools: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate tools field format and content.
+        
+        CRITICAL: Tools must be comma-separated WITHOUT spaces!
+        
+        Args:
+            tools: Tools string to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if not tools:
+            return False, "Tools field is required"
+        
+        # Check for spaces after commas (CRITICAL ERROR)
+        if ', ' in tools:
+            return False, (
+                f"CRITICAL: Tools contain spaces after commas! '{tools}' "
+                "Must be comma-separated WITHOUT spaces (e.g., 'Read,Write,Edit')"
+            )
+        
+        # Validate individual tools
+        tool_list = tools.split(',')
+        invalid_tools = [t for t in tool_list if t not in cls.VALID_TOOLS]
+        
+        if invalid_tools:
+            return False, f"Invalid tools: {', '.join(invalid_tools)}. Valid tools: {', '.join(sorted(cls.VALID_TOOLS))}"
+        
+        return True, None
+    
+    @classmethod
+    def validate_model(cls, model: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate model field.
+        
+        Args:
+            model: Model tier to validate
+            
+        Returns:
+            (is_valid, error_message)
+        """
+        if model and model not in cls.VALID_MODELS:
+            return False, f"Invalid model '{model}'. Must be one of: {', '.join(cls.VALID_MODELS)}"
+        
+        return True, None
+    
+    @classmethod
+    def validate_frontmatter(cls, frontmatter: Dict) -> List[str]:
+        """
+        Validate complete frontmatter structure.
+        
+        Args:
+            frontmatter: Parsed frontmatter dictionary
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        # Check required fields
+        missing = cls.REQUIRED_FIELDS - set(frontmatter.keys())
+        if missing:
+            errors.append(f"Missing required fields: {', '.join(missing)}")
+        
+        # Validate name
+        if 'name' in frontmatter:
+            valid, error = cls.validate_name(frontmatter['name'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate tools
+        if 'tools' in frontmatter:
+            valid, error = cls.validate_tools(frontmatter['tools'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate model
+        if 'model' in frontmatter:
+            valid, error = cls.validate_model(frontmatter['model'])
+            if not valid:
+                errors.append(error)
+        
+        # Validate description
+        if 'description' in frontmatter:
+            desc = frontmatter['description']
+            if len(desc) < 10:
+                errors.append(f"Description too short ({len(desc)} chars, min 10)")
+            if len(desc) > 200:
+                errors.append(f"Description too long ({len(desc)} chars, max 200)")
+        
+        return errors
+    
+    @classmethod
+    def validate_agent_file(cls, file_path: Path) -> List[str]:
+        """
+        Validate an agent markdown file.
+        
+        Args:
+            file_path: Path to agent .md file
+            
+        Returns:
+            List of validation errors (empty if valid)
+        """
+        errors = []
+        
+        try:
+            with open(file_path, 'r') as f:
+                content = f.read()
+            
+            # Check for frontmatter markers
+            if not content.startswith('---\n'):
+                errors.append("File must start with '---' frontmatter marker")
+                return errors
+            
+            # Extract frontmatter
+            end_marker = content.find('\n---\n', 4)
+            if end_marker == -1:
+                errors.append("Missing closing '---' frontmatter marker")
+                return errors
+            
+            frontmatter_text = content[4:end_marker]
+            
+            # Parse YAML
+            try:
+                frontmatter = yaml.safe_load(frontmatter_text)
+            except yaml.YAMLError as e:
+                errors.append(f"Invalid YAML in frontmatter: {e}")
+                return errors
+            
+            # Validate frontmatter content
+            validation_errors = cls.validate_frontmatter(frontmatter)
+            errors.extend(validation_errors)
+            
+        except Exception as e:
+            errors.append(f"Error reading file: {e}")
+        
+        return errors
+
+
+def main():
+    """Command-line validation tool."""
+    import sys
+    
+    if len(sys.argv) < 2:
+        print("Usage: python frontmatter_validator.py <agent.md> [agent2.md ...]")
+        sys.exit(1)
+    
+    all_valid = True
+    
+    for file_path in sys.argv[1:]:
+        path = Path(file_path)
+        if not path.exists():
+            print(f"❌ {file_path}: File not found")
+            all_valid = False
+            continue
+        
+        errors = FrontmatterValidator.validate_agent_file(path)
+        
+        if errors:
+            print(f"❌ {file_path}:")
+            for error in errors:
+                print(f"   - {error}")
+            all_valid = False
+        else:
+            print(f"✅ {file_path}: Valid")
+    
+    sys.exit(0 if all_valid else 1)
+
+
+if __name__ == "__main__":
+    main()

{claude_mpm-3.7.8.dist-info → claude_mpm-3.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.7.8
+Version: 3.9.0
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team
@@ -32,7 +32,7 @@ Requires-Dist: watchdog>=3.0.0
 Requires-Dist: tree-sitter>=0.21.0
 Requires-Dist: python-socketio>=5.11.0
 Requires-Dist: aiohttp>=3.9.0
-Requires-Dist: aiohttp-cors>=0.8.0
+Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0
 Requires-Dist: python-engineio>=4.8.0
 Requires-Dist: python-frontmatter>=1.0.0
 Requires-Dist: mistune>=3.0.0
@@ -44,6 +44,10 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
+Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
 Provides-Extra: monitor
 Provides-Extra: agents
 Requires-Dist: bandit>=1.7.5; extra == "agents"
@@ -109,168 +113,74 @@ A powerful orchestration framework for Claude Code that enables multi-agent work
 - 🔍 **Git Integration**: View diffs and track changes across projects
 - 🎯 **Smart Task Orchestration**: PM agent intelligently routes work to specialists
 
-## Installation
+## Quick Installation
 
 ```bash
-# Basic installation - pure Python, no compilation required
 pip install claude-mpm
-
-# Install with development dependencies
-pip install "claude-mpm[dev]"
-
-# Install with agent dependencies - pure Python tools
-pip install "claude-mpm[agents]"
-
-# Install with all optional dependencies
-pip install "claude-mpm[agents,dev]"
 ```
 
-All dependencies are pure Python - no Rust or compilation required. The `agents` dependency group includes tools for testing, code analysis, documentation, and development workflows.
+**That's it!** See [QUICKSTART.md](QUICKSTART.md) for immediate usage or [docs/user/installation.md](docs/user/installation.md) for advanced options.
 
-## Basic Usage
+## Quick Usage
 
 ```bash
-# Interactive mode (recommended)
+# Start interactive mode (recommended)
 claude-mpm
 
-# Non-interactive with task
-claude-mpm run -i "analyze this codebase" --non-interactive
-
-# With monitoring dashboard
+# Start with monitoring dashboard
 claude-mpm run --monitor
-
-# Resume last session
-claude-mpm run --resume
 ```
 
-### Agent Management
-
-```bash
-# View agent hierarchy and precedence
-claude-mpm agents list --by-tier
-
-# Inspect specific agent configuration
-claude-mpm agents view engineer
-
-# Fix agent configuration issues
-claude-mpm agents fix --all --dry-run
-```
-
-For detailed usage, see [QUICKSTART.md](QUICKSTART.md)
-
-### Agent Dependencies
-
-Claude MPM automatically manages Python dependencies required by agents. All dependencies are pure Python packages that don't require compilation. Agents can declare their dependencies in their configuration files, and the system aggregates them for easy installation.
-
-```bash
-# Install all agent dependencies (pure Python)
-pip install "claude-mpm[agents]"
-
-# View current agent dependencies
-python scripts/aggregate_agent_dependencies.py --dry-run
-
-# Update pyproject.toml with latest agent dependencies
-python scripts/aggregate_agent_dependencies.py
-```
+See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
-**Agent developers** can declare dependencies in their agent configurations:
 
-```json
-{
-  "agent_id": "my_agent",
-  "dependencies": {
-    "python": ["pandas>=2.0.0", "numpy>=1.24.0"],
-    "system": ["ripgrep", "git"]
-  }
-}
-```
+## Architecture
 
-Dependencies are automatically aggregated from all agent sources (PROJECT > USER > SYSTEM) during the build process, with intelligent version conflict resolution taking the highest compatible version.
+Claude MPM v3.8.2+ features a **modern service-oriented architecture** with interface-based design, dependency injection, and intelligent caching for 50-80% performance improvements.
 
-For comprehensive documentation, see [docs/AGENT_DEPENDENCIES.md](docs/AGENT_DEPENDENCIES.md).
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture information.
 
 ## Key Capabilities
 
 ### Multi-Agent Orchestration
-The PM agent automatically delegates work to specialized agents:
-- **Research**: Codebase analysis and investigation
-- **Engineer**: Implementation and coding
-- **QA**: Testing and validation
-- **Documentation**: Docs and guides
-- **Security**: Security analysis
-- **Ops**: Deployment and infrastructure
-- **Data Engineer**: Data pipelines and AI integrations
-- **Test Integration**: E2E testing and cross-system validation
-- **Version Control**: Git workflows and release management
-
-**Three-Tier Agent System**: PROJECT > USER > SYSTEM precedence allows project-specific agent customization while maintaining fallbacks. Use `claude-mpm agents list --by-tier` to see the active agent hierarchy.
-
-### Session Management
-- All work is tracked in persistent sessions
-- Resume any session with `--resume`
-- Switch between projects with per-session directories
-- View session history and activity
+The PM agent automatically delegates work to specialized agents including Research, Engineer, QA, Documentation, Security, Ops, Data Engineer, Test Integration, and Version Control.
 
 ### Agent Memory System
-Agents learn and improve over time with persistent memory:
-- **Project-Specific Knowledge**: Automatically analyzes your codebase to understand patterns
-- **Continuous Learning**: Agents remember insights across sessions
-- **Memory Management**: Initialize, optimize, and manage agent memories
-- **Quick Initialization**: Use `/mpm memory init` to scan project and create memories
-
-```bash
-# Initialize project-specific memories
-claude-mpm memory init
-
-# View memory status
-claude-mpm memory status
-
-# Add specific learning
-claude-mpm memory add engineer pattern "Always use async/await for I/O"
-
-# Start with monitoring dashboard
-claude-mpm run --monitor
-```
-
-See [docs/MEMORY.md](docs/MEMORY.md) for comprehensive memory system documentation.
+Agents learn project-specific patterns and remember insights across sessions. Initialize with `claude-mpm memory init`.
 
 ### Real-Time Monitoring
-The `--monitor` flag opens a web dashboard showing:
-- Live agent activity and delegations
-- File operations with git diff viewer
-- Tool usage and results
-- Session management UI
+The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 
-See [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for full monitoring guide.
+See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
 ## Documentation
 
+### User Documentation
 - **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
-- **[Agent Memory System](docs/MEMORY.md)** - Comprehensive memory documentation
-- **[Monitoring Dashboard](docs/developer/11-dashboard/README.md)** - Real-time monitoring features
-- **[Project Structure](docs/STRUCTURE.md)** - Codebase organization
-- **[Deployment Guide](docs/DEPLOY.md)** - Publishing and versioning
+- **[Installation Guide](docs/user/installation.md)** - Complete installation options
 - **[User Guide](docs/user/)** - Detailed usage documentation
-- **[Developer Guide](docs/developer/)** - Architecture and API reference
+- **[Memory System](docs/MEMORY.md)** - Agent memory documentation
+- **[Troubleshooting](docs/user/troubleshooting.md)** - Common issues and solutions
+
+### Developer Documentation
+- **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
+- **[API Reference](docs/api/)** - Complete API documentation with Sphinx
+- **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
+- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
+- **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
+- **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
+- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from previous versions
+- **[Developer Guide](docs/developer/)** - Comprehensive development documentation
 
-## Recent Updates (v3.4.27)
+### API Documentation
+Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
 
-### Core System Enhancements
-- **Project Structure Reorganization**: Centralized path management with ClaudeMPMPaths enum
-- **Agent Services Hierarchy**: Reorganized agent and memory services into hierarchical structures  
-- **Response Logging Improvements**: Flat structure logging without session_ prefix
-- **Memory System Expansion**: Added data_engineer and test_integration agents with specialized keywords
-- **Path Management System**: Implemented centralized configuration path handling
+## Recent Updates (v3.8.2)
 
-### Project Cleanup & Organization
-- **Test File Migration**: Moved 66 test files from scripts/ to tests/ directory
-- **Documentation Archives**: Archived 35+ QA reports to docs/archive/
-- **Obsolete Directory Removal**: Cleaned up orchestration, docker, security, and terminal_wrapper directories
-- **Agent Registry Caching**: Enhanced performance with intelligent caching mechanisms
-- **Improved TodoWrite Integration**: Enhanced agent prefix guidelines across all agent templates
+**Major Architecture Refactoring (TSK-0053)**: Complete service-oriented redesign with 50-80% performance improvements, enhanced security, and interface-based design.
 
-See [CHANGELOG.md](CHANGELOG.md) for full history.
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
 
 ## Development