claude-mpm 4.21.0__py3-none-any.whl → 5.0.2__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,47 +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()
-                    and target_file.stat().st_mtime >= source_path.stat().st_mtime
-                ):
-                    # File is up to date based on modification time
-                    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/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: