claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

claude_mpm/services/agents/deployment/system_instructions_deployer.py

@@ -5,6 +5,7 @@ Extracted from AgentDeploymentService to reduce complexity and improve maintaina
 """
 
 import logging
+import shutil
 from pathlib import Path
 from typing import Any, Dict
 
@@ -26,33 +27,20 @@ class SystemInstructionsDeployer:
         """
         Deploy system instructions and framework files for PM framework.
 
-        Always deploys to project .claude directory regardless of agent source
-        (system, user, or project). This ensures consistent project-level
-        deployment while maintaining discovery from both user (~/.claude-mpm)
-        and project (.claude-mpm) directories.
+        Deploys to project .claude-mpm directory as merged PM_INSTRUCTIONS_DEPLOYED.md
+        containing PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md.
 
         Args:
-            target_dir: Target directory for deployment (not used - always uses project .claude)
+            target_dir: Target directory for deployment (not used - always uses project .claude-mpm)
             force_rebuild: Force rebuild even if exists
             results: Results dictionary to update
         """
         try:
-            # Always use project's .claude directory
-            # This is the key change - all system instructions go to project .claude
-            claude_dir = self.working_directory / ".claude"
-
-            # Ensure .claude directory exists
-            claude_dir.mkdir(parents=True, exist_ok=True)
-
-            # Framework files to deploy
-            framework_files = [
-                (
-                    "INSTRUCTIONS.md",
-                    "INSTRUCTIONS.md",
-                ),  # Keep INSTRUCTIONS.md as is - NEVER rename to CLAUDE.md
-                ("WORKFLOW.md", "WORKFLOW.md"),
-                ("MEMORY.md", "MEMORY.md"),
-            ]
+            # Deploy to project's .claude-mpm directory (project-local)
+            claude_mpm_dir = self.working_directory / ".claude-mpm"
+
+            # Ensure .claude-mpm directory exists
+            claude_mpm_dir.mkdir(parents=True, exist_ok=True)
 
             # Find the agents directory with framework files
             # Use centralized paths for consistency
@@ -60,44 +48,181 @@ class SystemInstructionsDeployer:
 
             agents_path = paths.agents_dir
 
-            for source_name, target_name in framework_files:
-                source_path = agents_path / source_name
-
-                if not source_path.exists():
-                    self.logger.warning(f"Framework file not found: {source_path}")
-                    continue
+            # Read and merge PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md
+            pm_instructions_path = agents_path / "PM_INSTRUCTIONS.md"
+            workflow_path = agents_path / "WORKFLOW.md"
+            memory_path = agents_path / "MEMORY.md"
 
-                target_file = claude_dir / target_name
+            merged_content = []
+            source_files = []
 
-                # Check if update needed
-                if not force_rebuild and target_file.exists():
-                    # Compare modification times
-                    if target_file.stat().st_mtime >= source_path.stat().st_mtime:
-                        results["skipped"].append(target_name)
-                        self.logger.debug(f"Framework file {target_name} up to date")
-                        continue
+            for path in [pm_instructions_path, workflow_path, memory_path]:
+                if path.exists():
+                    merged_content.append(path.read_text())
+                    source_files.append(str(path))
+                else:
+                    self.logger.warning(f"Framework file not found: {path}")
+
+            if not merged_content:
+                self.logger.error("No framework files found to merge")
+                results["errors"].append("No framework files found to merge")
+                return
+
+            # Determine the most recent modification time of source files
+            latest_mtime = max(
+                path.stat().st_mtime
+                for path in [pm_instructions_path, workflow_path, memory_path]
+                if path.exists()
+            )
+
+            # Write merged content to PM_INSTRUCTIONS_DEPLOYED.md
+            target_file = claude_mpm_dir / "PM_INSTRUCTIONS_DEPLOYED.md"
+
+            # Check if update needed
+            if (
+                not force_rebuild
+                and target_file.exists()
+                and target_file.stat().st_mtime >= latest_mtime
+            ):
+                # File is up to date based on modification time
+                results["skipped"].append("PM_INSTRUCTIONS_DEPLOYED.md")
+                self.logger.debug("PM_INSTRUCTIONS_DEPLOYED.md up to date")
+            else:
+                # Check if file exists before writing (for proper tracking)
+                file_existed = target_file.exists()
 
-                # Read and deploy framework file
-                file_content = source_path.read_text()
-                target_file.write_text(file_content)
+                # Write merged content
+                target_file.write_text("\n\n".join(merged_content))
 
                 # Track deployment
-                file_existed = target_file.exists()
                 deployment_info = {
-                    "name": target_name,
-                    "template": str(source_path),
+                    "name": "PM_INSTRUCTIONS_DEPLOYED.md",
+                    "template": ", ".join(source_files),
                     "target": str(target_file),
                 }
 
                 if file_existed:
                     results["updated"].append(deployment_info)
-                    self.logger.info(f"Updated framework file: {target_name}")
+                    self.logger.info("Updated merged PM_INSTRUCTIONS_DEPLOYED.md")
                 else:
                     results["deployed"].append(deployment_info)
-                    self.logger.info(f"Deployed framework file: {target_name}")
+                    self.logger.info("Deployed merged PM_INSTRUCTIONS_DEPLOYED.md")
 
         except Exception as e:
             error_msg = f"Failed to deploy system instructions: {e}"
             self.logger.error(error_msg)
             results["errors"].append(error_msg)
             # Not raising AgentDeploymentError as this is non-critical
+
+        # Also deploy templates directory
+        self.deploy_templates(claude_mpm_dir, force_rebuild, results)
+
+    def deploy_templates(
+        self,
+        claude_mpm_dir: Path,
+        force_rebuild: bool,
+        results: Dict[str, Any],
+    ) -> None:
+        """
+        Deploy PM instruction template files to project .claude-mpm/templates directory.
+
+        Only deploys PM instruction templates (not agent definition templates).
+        Templates are documentation files referenced in PM_INSTRUCTIONS.md that provide
+        detailed protocols, examples, and matrices.
+
+        Args:
+            claude_mpm_dir: Project .claude-mpm directory
+            force_rebuild: Force rebuild even if exists
+            results: Results dictionary to update
+        """
+        try:
+            # Find templates source directory
+            from claude_mpm.config.paths import paths
+
+            templates_source = paths.agents_dir / "templates"
+
+            if not templates_source.exists():
+                self.logger.warning(
+                    f"Templates source directory not found: {templates_source}"
+                )
+                return
+
+            # Create templates target directory
+            templates_target = claude_mpm_dir / "templates"
+            templates_target.mkdir(parents=True, exist_ok=True)
+
+            # Only deploy PM instruction templates (not agent definitions)
+            pm_templates = [
+                "circuit-breakers.md",
+                "context-management-examples.md",
+                "git-file-tracking.md",
+                "pm-examples.md",
+                "pm-red-flags.md",
+                "pr-workflow-examples.md",
+                "research-gate-examples.md",
+                "response-format.md",
+                "structured-questions-examples.md",
+                "ticketing-examples.md",
+                "validation-templates.md",
+            ]
+
+            # Get template files that exist
+            template_files = [
+                templates_source / name
+                for name in pm_templates
+                if (templates_source / name).exists()
+            ]
+
+            deployed_count = 0
+            skipped_count = 0
+            missing_count = 0
+
+            # Track missing templates
+            for name in pm_templates:
+                if not (templates_source / name).exists():
+                    self.logger.warning(f"PM template not found: {name}")
+                    missing_count += 1
+
+            for template_file in template_files:
+                target_file = templates_target / template_file.name
+
+                # Check if update needed
+                if (
+                    not force_rebuild
+                    and target_file.exists()
+                    and target_file.stat().st_mtime >= template_file.stat().st_mtime
+                ):
+                    skipped_count += 1
+                    continue
+
+                # Copy template file
+                shutil.copy2(template_file, target_file)
+                deployed_count += 1
+
+                self.logger.debug(f"Deployed PM template: {template_file.name}")
+
+            # Track results
+            if deployed_count > 0:
+                template_info = {
+                    "name": "templates/",
+                    "count": deployed_count,
+                    "target": str(templates_target),
+                }
+                results["deployed"].append(template_info)
+                self.logger.info(
+                    f"Deployed {deployed_count} PM template files to {templates_target}"
+                )
+
+            if skipped_count > 0:
+                self.logger.debug(
+                    f"Skipped {skipped_count} up-to-date PM template files"
+                )
+
+            if missing_count > 0:
+                self.logger.warning(f"{missing_count} PM templates not found in source")
+
+        except Exception as e:
+            error_msg = f"Failed to deploy templates: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+            # Not raising exception as template deployment is non-critical

claude_mpm/services/agents/deployment/validation/__init__.py

@@ -5,10 +5,12 @@ including template validation, agent file validation, and
 deployment environment validation.
 """
 
+from claude_mpm.core.enums import ValidationSeverity
+
 from .agent_validator import AgentValidator
 from .deployment_validator import DeploymentValidator
 from .template_validator import TemplateValidator
-from .validation_result import ValidationResult, ValidationSeverity
+from .validation_result import ValidationResult
 
 __all__ = [
     "AgentValidator",

claude_mpm/services/agents/deployment/validation/deployment_validator.py

@@ -124,8 +124,8 @@ class DeploymentValidator:
             elif not templates_dir.is_dir():
                 result.add_error(f"Templates path is not a directory: {templates_dir}")
             else:
-                # Check for template files
-                template_files = list(templates_dir.glob("*.json"))
+                # Check for template files (templates migrated to .md in v4.26.0+)
+                template_files = list(templates_dir.glob("*.md"))
                 if not template_files:
                     result.add_warning(f"No template files found in: {templates_dir}")
                 else:

claude_mpm/services/agents/deployment/validation/template_validator.py

@@ -31,7 +31,7 @@ class TemplateValidator:
             "agent_type": str,
             "metadata": dict,
             "capabilities": dict,
-            "instructions": dict,
+            "instructions": str,
         }
 
         # Required metadata fields
@@ -45,13 +45,10 @@ class TemplateValidator:
         # Required capabilities fields
         self.required_capabilities_fields = {
             "model": str,
-            "tools": list,
+            "resource_tier": str,
         }
 
-        # Required instructions fields
-        self.required_instructions_fields = {
-            "system_prompt": str,
-        }
+        # Instructions is now a string field, not a dictionary
 
     def validate_template_file(self, template_file: Path) -> ValidationResult:
         """Validate a template file.
@@ -90,9 +87,11 @@ class TemplateValidator:
             if "capabilities" in template_data:
                 self._validate_capabilities(template_data["capabilities"], result)
 
-            # Validate instructions
+            # Validate instructions (now a string field)
             if "instructions" in template_data:
-                self._validate_instructions(template_data["instructions"], result)
+                self._validate_instructions_string(
+                    template_data["instructions"], result
+                )
 
             # Validate agent ID format
             if "agent_id" in template_data:
@@ -191,10 +190,19 @@ class TemplateValidator:
 
         if "tags" in metadata:
             tags = metadata["tags"]
-            if not isinstance(tags, list):
-                result.add_error("Tags should be a list", field_name="metadata.tags")
-            elif len(tags) == 0:
-                result.add_warning("No tags specified", field_name="metadata.tags")
+            if isinstance(tags, str):
+                # Convert comma-separated string to list for validation
+                tag_list = [tag.strip() for tag in tags.split(",") if tag.strip()]
+                if len(tag_list) == 0:
+                    result.add_warning("No tags specified", field_name="metadata.tags")
+            elif isinstance(tags, list):
+                if len(tags) == 0:
+                    result.add_warning("No tags specified", field_name="metadata.tags")
+            else:
+                result.add_error(
+                    "Tags should be a list or comma-separated string",
+                    field_name="metadata.tags",
+                )
 
     def _validate_capabilities(
         self, capabilities: Dict[str, Any], result: ValidationResult
@@ -230,7 +238,7 @@ class TemplateValidator:
                     suggestion=f"Use one of: {', '.join(valid_models)}",
                 )
 
-        # Validate tools
+        # Validate tools (optional field but validate if present)
         if "tools" in capabilities:
             tools = capabilities["tools"]
             if not isinstance(tools, list):
@@ -242,43 +250,55 @@ class TemplateValidator:
                     "No tools specified", field_name="capabilities.tools"
                 )
 
-    def _validate_instructions(
-        self, instructions: Dict[str, Any], result: ValidationResult
+        # Validate resource_tier
+        if "resource_tier" in capabilities:
+            resource_tier = capabilities["resource_tier"]
+            valid_tiers = ["basic", "standard", "intensive", "lightweight", "high"]
+            if resource_tier not in valid_tiers:
+                result.add_warning(
+                    f"Unknown resource tier '{resource_tier}'",
+                    field_name="capabilities.resource_tier",
+                    suggestion=f"Use one of: {', '.join(valid_tiers)}",
+                )
+
+    def _validate_instructions_string(
+        self, instructions: str, result: ValidationResult
     ) -> None:
-        """Validate instructions section.
+        """Validate instructions string.
 
         Args:
-            instructions: Instructions dictionary
+            instructions: Instructions string
             result: ValidationResult to update
         """
-        for field, expected_type in self.required_instructions_fields.items():
-            if field not in instructions:
-                result.add_error(
-                    f"Missing required instructions field: {field}",
-                    field_name=f"instructions.{field}",
-                )
-            else:
-                value = instructions[field]
-                if not isinstance(value, expected_type):
-                    result.add_error(
-                        f"Instructions field '{field}' should be {expected_type.__name__}, got {type(value).__name__}",
-                        field_name=f"instructions.{field}",
-                    )
+        # Check if instructions is actually a string
+        if not isinstance(instructions, str):
+            result.add_error(
+                f"Instructions should be a string, got {type(instructions).__name__}",
+                field_name="instructions",
+            )
+            return
 
-        # Validate system prompt
-        if "system_prompt" in instructions:
-            system_prompt = instructions["system_prompt"]
-            if not system_prompt or not system_prompt.strip():
-                result.add_error(
-                    "System prompt cannot be empty",
-                    field_name="instructions.system_prompt",
-                )
-            elif len(system_prompt) < 20:
-                result.add_warning(
-                    "System prompt is very short",
-                    field_name="instructions.system_prompt",
-                    suggestion="Provide more detailed instructions",
-                )
+        # Check if instructions is not empty
+        if not instructions or not instructions.strip():
+            result.add_error(
+                "Instructions cannot be empty",
+                field_name="instructions",
+            )
+        elif len(instructions) < 20:
+            result.add_warning(
+                "Instructions are very short",
+                field_name="instructions",
+                suggestion="Provide more detailed instructions",
+            )
+
+        # Check for file references that might be invalid
+        if instructions.startswith("file:"):
+            file_ref = instructions[5:]  # Remove "file:" prefix
+            result.add_warning(
+                f"Instructions reference external file: {file_ref}",
+                field_name="instructions",
+                suggestion="Consider embedding instructions directly or ensure the referenced file exists",
+            )
 
     def _validate_agent_id(self, agent_id: str, result: ValidationResult) -> None:
         """Validate agent ID format.

claude_mpm/services/agents/deployment/validation/validation_result.py

@@ -1,17 +1,9 @@
 """Validation result classes for deployment validation."""
 
 from dataclasses import dataclass, field
-from enum import Enum
 from typing import Any, Dict, List, Optional
 
-
-class ValidationSeverity(Enum):
-    """Severity levels for validation issues."""
-
-    INFO = "info"
-    WARNING = "warning"
-    ERROR = "error"
-    CRITICAL = "critical"
+from claude_mpm.core.enums import ValidationSeverity
 
 
 @dataclass