claude-mpm 4.2.1__py3-none-any.whl → 4.2.3__py3-none-any.whl

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -8,6 +8,7 @@ maintainability and testability.
 """
 
 import json
+import re
 from pathlib import Path
 from typing import Any, Dict, List
 
@@ -166,9 +167,11 @@ class AgentTemplateBuilder:
                 f"Tools must be comma-separated WITHOUT spaces: {tools_str}"
             )
 
-        # Map model names to Claude Code format
+        # Map model names to Claude Code format (as required)
         model_map = {
             "claude-3-5-sonnet-20241022": "sonnet",
+            "claude-3-5-haiku-20241022": "haiku",
+            "claude-3-opus-20240229": "opus",
             "claude-3-5-sonnet": "sonnet",
             "claude-3-sonnet": "sonnet",
             "claude-3-haiku": "haiku",
@@ -180,6 +183,9 @@ class AgentTemplateBuilder:
 
         if model in model_map:
             model = model_map[model]
+        else:
+            # Default to sonnet if model not found in map
+            model = "sonnet"
 
         # Get response format from template or use base agent default
         template_data.get("response", {}).get("format", "structured")
@@ -190,8 +196,6 @@ class AgentTemplateBuilder:
         # CRITICAL: NO underscores allowed - they cause silent failures!
 
         # Validate the name before proceeding
-        import re
-
         if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", claude_code_name):
             self.logger.error(
                 f"Invalid agent name '{claude_code_name}' - must match ^[a-z0-9]+(-[a-z0-9]+)*$"
@@ -201,12 +205,17 @@ class AgentTemplateBuilder:
             )
 
         # Extract description from template with fallback
-        description = (
+        raw_description = (
             template_data.get("description")
             or template_data.get("metadata", {}).get("description")
             or f"{agent_name.title()} agent for specialized tasks"
         )
 
+        # Convert to multiline format with examples for Claude Code compatibility
+        description = self._create_multiline_description(
+            raw_description, agent_name, template_data
+        )
+
         # Extract custom metadata fields
         metadata = template_data.get("metadata", {})
         agent_version = (
@@ -258,39 +267,39 @@ class AgentTemplateBuilder:
         # Include tools field only if agent is clearly restricted (missing core tools or very few tools)
         include_tools_field = not has_core_tools or len(agent_tools) < 6
 
-        # Build YAML frontmatter using Claude Code's minimal format
+        # Build YAML frontmatter using Claude Code's compatible format
         # ONLY include fields that Claude Code recognizes
         #
         # CLAUDE CODE COMPATIBLE FORMAT:
         # - name: kebab-case agent name (required)
-        # - description: when/why to use this agent (required)
-        # - version: agent version for update tracking (recommended)
-        # - tools: comma-separated tool list (optional, only if restricting)
-        # - color, author, tags: metadata fields (optional)
+        # - description: when/why to use this agent with examples (required, multiline)
+        # - model: mapped model name (required)
+        # - color: visual identifier (optional)
+        # - version: agent version for update tracking (optional)
+        # - author: creator information (optional)
+        # NOTE: tags field REMOVED - not supported by Claude Code
         frontmatter_lines = [
             "---",
             f"name: {claude_code_name}",
-            f"description: {description}",
-            f'version: "{agent_version}"',
         ]
 
-        # Add optional metadata if available
+        # Add description as single-line YAML string with \n escapes
+        frontmatter_lines.append(
+            f"description: {self._format_description_for_yaml(description)}"
+        )
+
+        # Add model field (required for Claude Code)
+        frontmatter_lines.append(f"model: {model}")
+
+        # Add optional metadata (excluding tags field completely)
         if metadata.get("color"):
             frontmatter_lines.append(f"color: {metadata['color']}")
+        if (
+            agent_version and agent_version != "1.0.0"
+        ):  # Only include non-default versions
+            frontmatter_lines.append(f'version: "{agent_version}"')
         if metadata.get("author"):
-            frontmatter_lines.append(f"author: {metadata['author']}")
-        if metadata.get("tags"):
-            frontmatter_lines.append("tags:")
-            for tag in metadata["tags"][:10]:  # Limit to 10 tags
-                frontmatter_lines.append(f"  - {tag}")
-        if metadata.get("priority"):
-            frontmatter_lines.append(f"priority: {metadata['priority']}")
-        if metadata.get("category"):
-            frontmatter_lines.append(f"category: {metadata['category']}")
-
-        # Only include tools if restricting to subset
-        if include_tools_field:
-            frontmatter_lines.append(f"tools: {tools_str}")
+            frontmatter_lines.append(f'author: "{metadata["author"]}"')
 
         frontmatter_lines.extend(
             [
@@ -545,3 +554,324 @@ tools:
             formatted_items.append(f"{indent_str}- {item}")
 
         return "\n".join(formatted_items)
+
+    def _create_multiline_description(
+        self, raw_description: str, agent_name: str, template_data: dict
+    ) -> str:
+        """
+        Create a comprehensive multiline description with examples for Claude Code compatibility.
+        Based on Claude's software-engineer.md format: detailed when/why description with examples.
+
+        Args:
+            raw_description: Original single-line description
+            agent_name: Name of the agent
+            template_data: Template data for extracting examples
+
+        Returns:
+            Formatted multiline description with examples in Claude Code format
+        """
+        raw_description = self._format_to_single_line(raw_description)
+
+        # Get agent type for creating targeted descriptions
+        agent_type = template_data.get("agent_type", "general")
+
+        # Create enhanced description based on agent type
+        enhanced_description = self._create_enhanced_description(
+            raw_description, agent_name, agent_type, template_data
+        )
+
+        # Add examples
+        examples = self._extract_examples_from_template(template_data, agent_name)
+        if not examples:
+            examples = self._generate_default_examples(agent_name, template_data)
+
+        # Combine enhanced description with examples
+        if examples:
+            description_parts = [enhanced_description, ""] + examples
+        else:
+            description_parts = [enhanced_description]
+
+        return "\n".join(description_parts)
+
+    def _format_to_single_line(self, description: str) -> str:
+        """
+        Format description to single line by removing line breaks and normalizing whitespace.
+
+        Args:
+            description: Raw description text
+
+        Returns:
+            Single-line formatted description
+        """
+        if not description:
+            return description
+
+        # Remove all line breaks and normalize whitespace
+        single_line = " ".join(description.strip().split())
+
+        # Remove redundant spaces around punctuation
+        single_line = re.sub(r"\s+([,.!?;:])", r"\1", single_line)
+        single_line = re.sub(r"([,.!?;:])\s+", r"\1 ", single_line)
+
+        return single_line
+
+    def _create_enhanced_description(
+        self,
+        raw_description: str,
+        agent_name: str,
+        agent_type: str,
+        template_data: dict,
+    ) -> str:
+        """
+        Create an enhanced description based on agent type that follows Claude's format.
+
+        Args:
+            raw_description: Original description
+            agent_name: Name of the agent
+            agent_type: Type of agent (engineer, qa, research, etc.)
+            template_data: Template data for additional context
+
+        Returns:
+            Enhanced description string
+        """
+        # Type-specific enhanced descriptions following Claude's software-engineer.md pattern
+        enhanced_descriptions = {
+            "engineer": "Use this agent when you need to implement new features, write production-quality code, refactor existing code, or solve complex programming challenges. This agent excels at translating requirements into well-architected, maintainable code solutions across various programming languages and frameworks.",
+            "qa": "Use this agent when you need comprehensive testing, quality assurance validation, or test automation. This agent specializes in creating robust test suites, identifying edge cases, and ensuring code quality through systematic testing approaches across different testing methodologies.",
+            "research": "Use this agent when you need to investigate codebases, analyze system architecture, or gather technical insights. This agent excels at code exploration, pattern identification, and providing comprehensive analysis of existing systems while maintaining strict memory efficiency.",
+            "ops": "Use this agent when you need infrastructure management, deployment automation, or operational excellence. This agent specializes in DevOps practices, cloud operations, monitoring setup, and maintaining reliable production systems.",
+            "security": "Use this agent when you need security analysis, vulnerability assessment, or secure coding practices. This agent excels at identifying security risks, implementing security best practices, and ensuring applications meet security standards.",
+            "documentation": "Use this agent when you need to create, update, or maintain technical documentation. This agent specializes in writing clear, comprehensive documentation including API docs, user guides, and technical specifications.",
+        }
+
+        # Get the enhanced description or fallback to the original with improvements
+        if agent_type in enhanced_descriptions:
+            return enhanced_descriptions[agent_type]
+        # Enhance the raw description if it's a custom type
+        if raw_description and len(raw_description) > 10:
+            return f"Use this agent when you need specialized assistance with {raw_description.lower()}. This agent provides targeted expertise and follows best practices for {agent_name.replace('-', ' ')} related tasks."
+        return f"Use this agent when you need specialized assistance from the {agent_name.replace('-', ' ')} agent. This agent provides targeted expertise and follows established best practices."
+
+    def _extract_examples_from_template(
+        self, template_data: dict, agent_name: str
+    ) -> List[str]:
+        """
+        Extract examples from template data and format with commentary.
+        Creates ONE example with commentary from template data.
+
+        Args:
+            template_data: Template data
+            agent_name: Name of the agent
+
+        Returns:
+            List of example strings (single example with commentary)
+        """
+        examples = []
+
+        # Check for examples in knowledge section
+        knowledge = template_data.get("knowledge", {})
+        template_examples = knowledge.get("examples", [])
+
+        if template_examples:
+            # Take only the first example and add commentary
+            example = template_examples[0]
+            scenario = example.get("scenario", "")
+            approach = example.get("approach", "")
+            commentary = example.get("commentary", "")
+
+            if scenario and approach:
+                examples.extend(
+                    [
+                        "<example>",
+                        f"Context: {scenario}",
+                        f'user: "I need help with {scenario.lower()}"',
+                        f'assistant: "I\'ll use the {agent_name} agent to {approach.lower()}."',
+                        "<commentary>",
+                        (
+                            commentary
+                            if commentary
+                            else f"This agent is well-suited for {scenario.lower()} because it specializes in {approach.lower()} with targeted expertise."
+                        ),
+                        "</commentary>",
+                        "</example>",
+                    ]
+                )
+
+        # Check for triggers that can be converted to examples
+        interactions = template_data.get("interactions", {})
+        triggers = interactions.get("triggers", [])
+
+        if triggers and not examples:
+            # Convert first trigger to example with commentary
+            trigger = triggers[0]
+
+            # Handle both string and dict trigger formats
+            if isinstance(trigger, dict):
+                # New format with pattern and confidence
+                trigger_text = trigger.get("pattern", "")
+            else:
+                # Old format with simple string
+                trigger_text = str(trigger)
+
+            # Skip if we don't have valid trigger text
+            if not trigger_text:
+                return examples
+
+            agent_type = template_data.get("agent_type", "general")
+
+            examples.extend(
+                [
+                    "<example>",
+                    f"Context: When user needs {trigger_text}",
+                    f'user: "{trigger_text}"',
+                    f'assistant: "I\'ll use the {agent_name} agent for {trigger_text}."',
+                    "<commentary>",
+                    f"This {agent_type} agent is appropriate because it has specialized capabilities for {trigger_text.lower()} tasks.",
+                    "</commentary>",
+                    "</example>",
+                ]
+            )
+
+        return examples
+
+    def _generate_default_examples(
+        self, agent_name: str, template_data: dict
+    ) -> List[str]:
+        """
+        Generate default examples when none are available in template.
+        Creates ONE example with commentary for each agent type.
+
+        Args:
+            agent_name: Name of the agent
+            template_data: Template data for context
+
+        Returns:
+            List of example strings (single example with commentary)
+        """
+        agent_type = template_data.get("agent_type", "general")
+
+        # Create type-specific examples with commentary inside
+        type_examples = {
+            "engineer": [
+                "<example>",
+                "Context: When you need to implement new features or write code.",
+                'user: "I need to add authentication to my API"',
+                f'assistant: "I\'ll use the {agent_name} agent to implement a secure authentication system for your API."',
+                "<commentary>",
+                "The engineer agent is ideal for code implementation tasks because it specializes in writing production-quality code, following best practices, and creating well-architected solutions.",
+                "</commentary>",
+                "</example>",
+            ],
+            "ops": [
+                "<example>",
+                "Context: When you need to deploy or manage infrastructure.",
+                'user: "I need to deploy my application to the cloud"',
+                f'assistant: "I\'ll use the {agent_name} agent to set up and deploy your application infrastructure."',
+                "<commentary>",
+                "The ops agent excels at infrastructure management and deployment automation, ensuring reliable and scalable production systems.",
+                "</commentary>",
+                "</example>",
+            ],
+            "qa": [
+                "<example>",
+                "Context: When you need to test or validate functionality.",
+                'user: "I need to write tests for my new feature"',
+                f'assistant: "I\'ll use the {agent_name} agent to create comprehensive tests for your feature."',
+                "<commentary>",
+                "The QA agent specializes in comprehensive testing strategies, quality assurance validation, and creating robust test suites that ensure code reliability.",
+                "</commentary>",
+                "</example>",
+            ],
+            "research": [
+                "<example>",
+                "Context: When you need to investigate or analyze existing codebases.",
+                'user: "I need to understand how the authentication system works in this project"',
+                f'assistant: "I\'ll use the {agent_name} agent to analyze the codebase and explain the authentication implementation."',
+                "<commentary>",
+                "The research agent is perfect for code exploration and analysis tasks, providing thorough investigation of existing systems while maintaining memory efficiency.",
+                "</commentary>",
+                "</example>",
+            ],
+            "security": [
+                "<example>",
+                "Context: When you need to review code for security vulnerabilities.",
+                'user: "I need a security review of my authentication implementation"',
+                f'assistant: "I\'ll use the {agent_name} agent to conduct a thorough security analysis of your authentication code."',
+                "<commentary>",
+                "The security agent specializes in identifying security risks, vulnerability assessment, and ensuring applications meet security standards and best practices.",
+                "</commentary>",
+                "</example>",
+            ],
+            "documentation": [
+                "<example>",
+                "Context: When you need to create or update technical documentation.",
+                'user: "I need to document this new API endpoint"',
+                f'assistant: "I\'ll use the {agent_name} agent to create comprehensive API documentation."',
+                "<commentary>",
+                "The documentation agent excels at creating clear, comprehensive technical documentation including API docs, user guides, and technical specifications.",
+                "</commentary>",
+                "</example>",
+            ],
+        }
+
+        return type_examples.get(
+            agent_type,
+            [
+                "<example>",
+                f"Context: When you need specialized assistance from the {agent_name} agent.",
+                f'user: "I need help with {agent_name.replace("-", " ")} tasks"',
+                f'assistant: "I\'ll use the {agent_name} agent to provide specialized assistance."',
+                "<commentary>",
+                f"This agent provides targeted expertise for {agent_name.replace('-', ' ')} related tasks and follows established best practices.",
+                "</commentary>",
+                "</example>",
+            ],
+        )
+
+    def _indent_multiline_text(self, text: str, spaces: int) -> str:
+        """
+        Indent multiline text with specified number of spaces.
+
+        Args:
+            text: Text to indent
+            spaces: Number of spaces for indentation
+
+        Returns:
+            Indented text
+        """
+        if not text:
+            return ""
+
+        indent = " " * spaces
+        lines = text.split("\n")
+        indented_lines = []
+
+        for line in lines:
+            if line.strip():  # Non-empty lines get indented
+                indented_lines.append(indent + line)
+            else:  # Empty lines stay empty
+                indented_lines.append("")
+
+        return "\n".join(indented_lines)
+
+    def _format_description_for_yaml(self, description: str) -> str:
+        """Format description as a single-line YAML string with escaped newlines.
+
+        Args:
+            description: Multi-line description text
+
+        Returns:
+            Single-line YAML-formatted string with \n escapes
+        """
+        if not description:
+            return '""'
+
+        # The description already contains actual newlines, we need to escape them
+        # Replace actual newlines with \n escape sequence
+        escaped = description.replace("\n", "\\n")
+
+        # Escape any quotes in the description
+        escaped = escaped.replace('"', '\\"')
+
+        # Return as quoted string
+        return f'"{escaped}"'

claude_mpm/services/agents/deployment/agent_validator.py

@@ -331,12 +331,17 @@ class AgentValidator:
         # Extract from YAML frontmatter
         lines = content.split("\n")
         for line in lines:
-            if line.startswith("name:"):
-                agent_info["name"] = line.split(":", 1)[1].strip().strip("\"'")
-            elif line.startswith("description:"):
-                agent_info["description"] = line.split(":", 1)[1].strip().strip("\"'")
-            elif line.startswith("version:"):
-                agent_info["version"] = line.split(":", 1)[1].strip().strip("\"'")
+            stripped_line = line.strip()
+            if stripped_line.startswith("name:"):
+                agent_info["name"] = stripped_line.split(":", 1)[1].strip().strip("\"'")
+            elif stripped_line.startswith("description:"):
+                agent_info["description"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
+            elif stripped_line.startswith("version:"):
+                agent_info["version"] = (
+                    stripped_line.split(":", 1)[1].strip().strip("\"'")
+                )
 
         return agent_info
 

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -469,6 +469,47 @@ class MultiSourceAgentDeploymentService:
 
         return cleanup_results
 
+    def _is_user_created_agent(self, agent_file: Path) -> bool:
+        """Check if an agent is user-created based on metadata.
+
+        User agents are identified by:
+        - Lack of MPM authorship indicators
+        - Missing version or v0.0.0
+        - Certain naming patterns
+
+        Args:
+            agent_file: Path to the agent file to check
+
+        Returns:
+            True if the agent appears to be user-created, False otherwise
+        """
+        try:
+            content = agent_file.read_text()
+
+            # Check for MPM authorship indicators
+            mpm_indicators = [
+                "author: claude-mpm",
+                "author: 'claude-mpm'",
+                'author: "claude-mpm"',
+                "author: Claude MPM",
+                "Claude MPM Team",
+                "Generated by Claude MPM",
+                "claude-mpm-project",
+            ]
+
+            for indicator in mpm_indicators:
+                if indicator.lower() in content.lower():
+                    return False  # This is an MPM agent
+
+            # Check for version 0.0.0 (typical user agent default)
+            if "version: 0.0.0" in content or "version: '0.0.0'" in content:
+                return True
+
+            return True  # Default to user-created if no MPM indicators
+
+        except Exception:
+            return True  # Default to user-created if we can't read it
+
     def _apply_config_filters(
         self, selected_agents: Dict[str, Dict[str, Any]], config: Config
     ) -> Dict[str, Dict[str, Any]]:
@@ -534,7 +575,8 @@ class MultiSourceAgentDeploymentService:
             "needs_update": [],
             "up_to_date": [],
             "new_agents": [],
-            "orphaned_agents": [],  # Agents without templates
+            "orphaned_agents": [],  # System agents without templates
+            "user_agents": [],  # User-created agents (no templates required)
             "version_upgrades": [],
             "version_downgrades": [],
             "source_changes": [],
@@ -655,10 +697,11 @@ class MultiSourceAgentDeploymentService:
                 )
 
         # Check for orphaned agents (deployed but no template)
-        orphaned = self._detect_orphaned_agents_simple(
+        system_orphaned, user_orphaned = self._detect_orphaned_agents_simple(
             deployed_agents_dir, agents_to_deploy
         )
-        comparison_results["orphaned_agents"] = orphaned
+        comparison_results["orphaned_agents"] = system_orphaned
+        comparison_results["user_agents"] = user_orphaned
 
         # Log summary
         summary_parts = [
@@ -668,7 +711,11 @@ class MultiSourceAgentDeploymentService:
         ]
         if comparison_results["orphaned_agents"]:
             summary_parts.append(
-                f"{len(comparison_results['orphaned_agents'])} orphaned"
+                f"{len(comparison_results['orphaned_agents'])} system orphaned"
+            )
+        if comparison_results["user_agents"]:
+            summary_parts.append(
+                f"{len(comparison_results['user_agents'])} user agents"
             )
 
         self.logger.info(f"Version comparison complete: {', '.join(summary_parts)}")
@@ -698,10 +745,10 @@ class MultiSourceAgentDeploymentService:
                     f"{downgrade['template_version']} (keeping deployed version)"
                 )
 
-        # Log orphaned agents if found
+        # Log system orphaned agents if found
         if comparison_results["orphaned_agents"]:
             self.logger.info(
-                f"Found {len(comparison_results['orphaned_agents'])} orphaned agent(s) "
+                f"Found {len(comparison_results['orphaned_agents'])} system orphaned agent(s) "
                 f"(deployed without templates):"
             )
             for orphan in comparison_results["orphaned_agents"]:
@@ -710,6 +757,18 @@ class MultiSourceAgentDeploymentService:
                     f"(consider removing or creating a template)"
                 )
 
+        # Log user agents at debug level if found
+        if comparison_results["user_agents"]:
+            self.logger.debug(
+                f"Found {len(comparison_results['user_agents'])} user-created agent(s) "
+                f"(no templates required):"
+            )
+            for user_agent in comparison_results["user_agents"]:
+                self.logger.debug(
+                    f"  - {user_agent['name']} v{user_agent['version']} "
+                    f"(user-created agent)"
+                )
+
         return comparison_results
 
     def _infer_agent_source_from_context(
@@ -860,7 +919,7 @@ class MultiSourceAgentDeploymentService:
 
     def _detect_orphaned_agents_simple(
         self, deployed_agents_dir: Path, agents_to_deploy: Dict[str, Path]
-    ) -> List[Dict[str, Any]]:
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
         """Simple orphan detection that works with agents_to_deploy structure.
 
         Args:
@@ -868,12 +927,13 @@ class MultiSourceAgentDeploymentService:
             agents_to_deploy: Dictionary mapping file stems to template paths
 
         Returns:
-            List of orphaned agent information
+            Tuple of (system_orphaned_agents, user_orphaned_agents)
         """
-        orphaned = []
+        system_orphaned = []
+        user_orphaned = []
 
         if not deployed_agents_dir.exists():
-            return orphaned
+            return system_orphaned, user_orphaned
 
         # agents_to_deploy already contains file stems as keys
         available_stems = set(agents_to_deploy.keys())
@@ -885,7 +945,7 @@ class MultiSourceAgentDeploymentService:
             if agent_stem in available_stems:
                 continue
 
-            # This is an orphaned agent
+            # This is an orphaned agent - determine if it's user-created or system
             try:
                 deployed_content = deployed_file.read_text()
                 deployed_version, _, _ = (
@@ -899,11 +959,19 @@ class MultiSourceAgentDeploymentService:
             except Exception:
                 version_str = "unknown"
 
-            orphaned.append(
-                {"name": agent_stem, "file": str(deployed_file), "version": version_str}
-            )
+            orphan_info = {
+                "name": agent_stem,
+                "file": str(deployed_file),
+                "version": version_str,
+            }
 
-        return orphaned
+            # Determine if this is a user-created agent
+            if self._is_user_created_agent(deployed_file):
+                user_orphaned.append(orphan_info)
+            else:
+                system_orphaned.append(orphan_info)
+
+        return system_orphaned, user_orphaned
 
     def cleanup_orphaned_agents(
         self, deployed_agents_dir: Path, dry_run: bool = True