claude-mpm 5.4.55__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/services/pm_skills_deployer.py

@@ -1,27 +1,30 @@
 """PM Skills Deployer Service - Deploy bundled PM skills to projects.
 
-WHY: PM agents require specific templates and skills for proper operation.
+WHY: PM agents require specific framework management skills for proper operation.
 This service manages deployment of bundled PM skills from the claude-mpm
-package to individual project .claude-mpm directories with version tracking.
+package to the Claude Code skills directory with version tracking.
 
 DESIGN DECISIONS:
-- Deploys from src/claude_mpm/skills/bundled/pm/ to .claude-mpm/skills/pm/
+- Deploys from src/claude_mpm/skills/bundled/pm/ to .claude/skills/
+- Skills named mpm-* (framework management skills)
+- Direct deployment (no intermediate .claude-mpm/skills/pm/ step)
 - Uses package-relative paths (works for both installed and dev mode)
-- Supports two skill formats:
-  1. Directory structure: pm-skill-name/SKILL.md (new format)
-  2. Flat files: skill-name.md (legacy format in .claude-mpm/templates/)
-- Per-project deployment (NOT global like Claude Code skills)
+- Supports directory structure: mpm-skill-name/SKILL.md
+- Per-project deployment to .claude/skills/ (Claude Code location)
 - Version tracking via .claude-mpm/pm_skills_registry.yaml
 - Checksum validation for integrity verification
+- Conflict resolution: mpm-* skills from src WIN (overwrite existing)
+- Non-mpm-* skills in .claude/skills/ are untouched (user/git managed)
 - Non-blocking verification (returns warnings, doesn't halt execution)
 - Force flag to redeploy even if versions match
 
 ARCHITECTURE:
 1. Discovery: Find bundled PM skills in package (skills/bundled/pm/)
-2. Deployment: Copy SKILL.md files to .claude-mpm/skills/pm/{name}.md
-3. Registry: Track deployed versions and checksums
-4. Verification: Check deployment status (non-blocking)
-5. Updates: Compare bundled vs deployed versions
+2. Deployment: Copy SKILL.md files to .claude/skills/{name}/SKILL.md
+3. Conflict Check: Overwrite mpm-* skills, preserve non-mpm-* skills
+4. Registry: Track deployed versions and checksums
+5. Verification: Check deployment status (non-blocking)
+6. Updates: Compare bundled vs deployed versions
 
 PATH RESOLUTION:
 - Installed package: Uses __file__ to find skills/bundled/pm/
@@ -47,6 +50,46 @@ from claude_mpm.core.mixins import LoggerMixin
 # Security constants
 MAX_YAML_SIZE = 10 * 1024 * 1024  # 10MB limit to prevent YAML bombs
 
+# Tier 1: Required PM skills that MUST be deployed for PM agent to function properly
+# These are core framework management skills for basic PM operation
+REQUIRED_PM_SKILLS = [
+    # Core command-based skills (new consolidated CLI)
+    "mpm",
+    "mpm-init",
+    "mpm-status",
+    "mpm-help",
+    "mpm-doctor",
+    # Legacy framework management skills
+    "mpm-git-file-tracking",
+    "mpm-pr-workflow",
+    "mpm-ticketing-integration",
+    "mpm-delegation-patterns",
+    "mpm-verification-protocols",
+    "mpm-bug-reporting",
+    "mpm-teaching-mode",
+    "mpm-agent-update-workflow",
+    "mpm-circuit-breaker-enforcement",
+    "mpm-tool-usage-guide",
+    "mpm-session-management",
+]
+
+# Tier 2: Recommended skills (deployed with standard install)
+# These provide enhanced functionality for common workflows
+RECOMMENDED_PM_SKILLS = [
+    "mpm-config",
+    "mpm-ticket-view",
+    "mpm-session-resume",
+    "mpm-postmortem",
+]
+
+# Tier 3: Optional skills (deployed with full install)
+# These provide additional features for advanced use cases
+OPTIONAL_PM_SKILLS = [
+    "mpm-monitor",
+    "mpm-version",
+    "mpm-organize",
+]
+
 
 @dataclass
 class PMSkillInfo:
@@ -96,15 +139,19 @@ class VerificationResult:
         verified: Whether all skills are properly deployed
         warnings: List of warning messages
         missing_skills: List of missing skill names
+        corrupted_skills: List of corrupted skill names (checksum mismatch)
         outdated_skills: List of outdated skill names
         message: Summary message
+        skill_count: Total number of deployed skills
     """
 
     verified: bool
     warnings: List[str]
     missing_skills: List[str]
+    corrupted_skills: List[str]
     outdated_skills: List[str]
     message: str
+    skill_count: int = 0
 
 
 @dataclass
@@ -128,8 +175,9 @@ class PMSkillsDeployerService(LoggerMixin):
     """Deploy and manage PM skills from bundled sources to projects.
 
     This service provides:
-    - Discovery of bundled PM skills (templates)
-    - Deployment to .claude-mpm/skills/pm/
+    - Discovery of bundled PM skills (mpm-* framework management skills)
+    - Deployment to .claude/skills/ (Claude Code location)
+    - Conflict resolution (mpm-* skills from src WIN)
     - Version tracking via pm_skills_registry.yaml
     - Checksum validation for integrity
     - Non-blocking verification (warnings only)
@@ -138,7 +186,7 @@ class PMSkillsDeployerService(LoggerMixin):
     Example:
         >>> deployer = PMSkillsDeployerService()
         >>> result = deployer.deploy_pm_skills(Path("/project/root"))
-        >>> print(f"Deployed {len(result.deployed)} skills")
+        >>> print(f"Deployed {len(result.deployed)} skills to .claude/skills/")
         >>>
         >>> verify_result = deployer.verify_pm_skills(Path("/project/root"))
         >>> if not verify_result.verified:
@@ -244,9 +292,9 @@ class PMSkillsDeployerService(LoggerMixin):
             project_dir: Project root directory
 
         Returns:
-            Path to .claude-mpm/skills/pm/
+            Path to .claude/skills/
         """
-        return project_dir / ".claude-mpm" / "skills" / "pm"
+        return project_dir / ".claude" / "skills"
 
     def _load_registry(self, project_dir: Path) -> Dict[str, Any]:
         """Load PM skills registry with security checks.
@@ -320,14 +368,12 @@ class PMSkillsDeployerService(LoggerMixin):
     def _discover_bundled_pm_skills(self) -> List[Dict[str, Any]]:
         """Discover all PM skills in bundled templates directory.
 
-        PM skills can be in two formats:
-        1. Directory structure: pm-skill-name/SKILL.md (new format)
-        2. Flat files: skill-name.md (legacy format for .claude-mpm/templates/)
+        PM skills follow mpm-skill-name/SKILL.md structure.
 
         Returns:
             List of skill dictionaries containing:
-            - name: Skill name (directory/filename without extension)
-            - path: Full path to skill file (SKILL.md or .md file)
+            - name: Skill name (directory name, e.g., mpm-git-file-tracking)
+            - path: Full path to skill file (SKILL.md)
             - type: File type (always 'md')
         """
         skills = []
@@ -338,11 +384,16 @@ class PMSkillsDeployerService(LoggerMixin):
             )
             return skills
 
-        # Scan for skill directories containing SKILL.md (new format)
+        # Scan for skill directories containing SKILL.md
         for skill_dir in self.bundled_pm_skills_path.iterdir():
             if not skill_dir.is_dir() or skill_dir.name.startswith("."):
                 continue
 
+            # Only process mpm-* skills (framework management)
+            if not skill_dir.name.startswith("mpm-"):
+                self.logger.debug(f"Skipping non-mpm skill: {skill_dir.name}")
+                continue
+
             skill_file = skill_dir / "SKILL.md"
             if skill_file.exists():
                 skills.append(
@@ -353,46 +404,91 @@ class PMSkillsDeployerService(LoggerMixin):
                     }
                 )
 
-        # Fallback: Scan for .md files directly (legacy format)
-        for skill_file in self.bundled_pm_skills_path.glob("*.md"):
-            if skill_file.name.startswith("."):
-                continue
-
-            skills.append(
-                {
-                    "name": skill_file.stem,
-                    "path": skill_file,
-                    "type": "md",
-                }
-            )
-
         self.logger.info(f"Discovered {len(skills)} bundled PM skills")
         return skills
 
+    def _get_skills_for_tier(self, tier: str) -> List[str]:
+        """Get list of skills to deploy based on tier.
+
+        Args:
+            tier: Deployment tier - "minimal", "standard", or "full"
+
+        Returns:
+            List of skill names to deploy
+
+        Raises:
+            ValueError: If tier is invalid
+        """
+        if tier == "minimal":
+            return REQUIRED_PM_SKILLS
+        if tier == "standard":
+            return REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS
+        if tier == "full":
+            return REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS + OPTIONAL_PM_SKILLS
+        raise ValueError(
+            f"Invalid tier '{tier}'. Must be 'minimal', 'standard', or 'full'"
+        )
+
     def deploy_pm_skills(
         self,
         project_dir: Path,
         force: bool = False,
+        tier: str = "standard",
         progress_callback: Optional[Callable[[str, int, int], None]] = None,
     ) -> DeploymentResult:
-        """Deploy bundled PM skills to project directory.
+        """Deploy bundled PM skills to project directory with tier-based selection.
 
-        Copies PM skills from bundled templates to .claude-mpm/skills/pm/
+        Copies PM skills from bundled templates to .claude/skills/{name}/SKILL.md
         and updates registry with version and checksum information.
 
+        Deployment Tiers:
+        - "minimal": Only REQUIRED_PM_SKILLS (Tier 1 - core functionality)
+        - "standard": REQUIRED_PM_SKILLS + RECOMMENDED_PM_SKILLS (Tier 1+2 - common workflows)
+        - "full": All skills (Tier 1+2+3 - advanced features)
+
+        Conflict Resolution:
+        - mpm-* skills from src WIN (overwrite existing)
+        - Non-mpm-* skills in .claude/skills/ are untouched
+
         Args:
             project_dir: Project root directory
             force: If True, redeploy even if skill already exists
+            tier: Deployment tier - "minimal", "standard" (default), or "full"
             progress_callback: Optional callback(skill_name, current, total) for progress
 
         Returns:
             DeploymentResult with deployment status and details
 
         Example:
-            >>> result = deployer.deploy_pm_skills(Path("/project"), force=True)
-            >>> print(f"Deployed: {len(result.deployed)}")
+            >>> # Standard deployment (Tier 1 + Tier 2)
+            >>> result = deployer.deploy_pm_skills(Path("/project"))
+            >>> print(f"Deployed: {len(result.deployed)} to .claude/skills/")
+            >>>
+            >>> # Minimal deployment (Tier 1 only)
+            >>> result = deployer.deploy_pm_skills(Path("/project"), tier="minimal")
+            >>>
+            >>> # Full deployment (all tiers)
+            >>> result = deployer.deploy_pm_skills(Path("/project"), tier="full")
         """
-        skills = self._discover_bundled_pm_skills()
+        # Get tier-based skill filter
+        try:
+            tier_skills = self._get_skills_for_tier(tier)
+        except ValueError as e:
+            return DeploymentResult(
+                success=False,
+                deployed=[],
+                skipped=[],
+                errors=[{"skill": "all", "error": str(e)}],
+                message=str(e),
+            )
+
+        # Discover all bundled skills, then filter by tier
+        all_skills = self._discover_bundled_pm_skills()
+        skills = [s for s in all_skills if s["name"] in tier_skills]
+
+        self.logger.info(
+            f"Deploying {len(skills)}/{len(all_skills)} skills for tier '{tier}'"
+        )
         deployed = []
         skipped = []
         errors = []
@@ -445,8 +541,12 @@ class PMSkillsDeployerService(LoggerMixin):
                 if progress_callback:
                     progress_callback(skill_name, idx + 1, total_skills)
 
-                # Use skill name for target file (e.g., pm-delegation-patterns.md)
-                target_path = deployment_dir / f"{skill_name}.md"
+                # Create skill directory: .claude/skills/{skill_name}/
+                skill_dir = deployment_dir / skill_name
+                skill_dir.mkdir(parents=True, exist_ok=True)
+
+                # Target path: .claude/skills/{skill_name}/SKILL.md
+                target_path = skill_dir / "SKILL.md"
 
                 # SECURITY: Validate target path
                 if not self._validate_safe_path(deployment_dir, target_path):
@@ -466,7 +566,7 @@ class PMSkillsDeployerService(LoggerMixin):
                         )
                         continue
 
-                # Deploy skill
+                # Deploy skill (overwrites if exists - mpm-* skills WIN)
                 shutil.copy2(source_path, target_path)
 
                 # Add to deployed list
@@ -504,7 +604,7 @@ class PMSkillsDeployerService(LoggerMixin):
 
         success = len(errors) == 0
         message = (
-            f"Deployed {len(deployed)} skills, skipped {len(skipped)}, "
+            f"Deployed {len(deployed)} skills (tier: {tier}), skipped {len(skipped)}, "
             f"{len(errors)} errors"
         )
 
@@ -518,75 +618,107 @@ class PMSkillsDeployerService(LoggerMixin):
             message=message,
         )
 
-    def verify_pm_skills(self, project_dir: Path) -> VerificationResult:
-        """Verify PM skills are properly deployed (non-blocking).
+    def verify_pm_skills(
+        self, project_dir: Path, auto_repair: bool = True
+    ) -> VerificationResult:
+        """Verify PM skills are properly deployed with enhanced validation.
 
-        Checks deployment status and returns warnings without halting execution.
-        This allows graceful degradation if PM skills are missing.
+        Checks ALL required PM skills for:
+        - Existence in deployment directory
+        - File integrity (non-empty, valid checksums)
+        - Version currency (compared to bundled source)
+
+        Auto-repair logic:
+        - If auto_repair=True (default), automatically deploys missing/corrupted skills
+        - Reports what was fixed in the result
 
         Args:
             project_dir: Project root directory
+            auto_repair: If True, auto-deploy missing/corrupted skills (default: True)
 
         Returns:
-            VerificationResult with verification status and warnings
+            VerificationResult with detailed verification status:
+            - verified: True if all required skills are deployed and valid
+            - missing_skills: List of required skills not deployed
+            - corrupted_skills: List of skills with checksum mismatches
+            - warnings: List of warning messages
+            - skill_count: Total number of deployed skills
 
         Example:
             >>> result = deployer.verify_pm_skills(Path("/project"))
             >>> if not result.verified:
-            ...     for warning in result.warnings:
-            ...         print(f"WARNING: {warning}")
+            ...     print(f"Missing: {result.missing_skills}")
+            ...     print(f"Corrupted: {result.corrupted_skills}")
         """
         warnings = []
         missing_skills = []
+        corrupted_skills = []
         outdated_skills = []
 
         # Check if registry exists
         registry = self._load_registry(project_dir)
-        if not registry:
-            warnings.append("PM skills registry not found or invalid")
-            missing_skills.append("all")
-            return VerificationResult(
-                verified=False,
-                warnings=warnings,
-                missing_skills=missing_skills,
-                outdated_skills=outdated_skills,
-                message="PM skills not deployed. Run 'claude-mpm init' to deploy.",
-            )
-
-        # Check each registered skill exists
         deployment_dir = self._get_deployment_dir(project_dir)
-        deployed_skills = registry.get("skills", [])
+        deployed_skills_data = registry.get("skills", []) if registry else []
 
-        for skill in deployed_skills:
-            skill_name = skill["name"]
-            skill_file = deployment_dir / f"{skill_name}.md"
+        # Build lookup for deployed skills
+        deployed_lookup = {skill["name"]: skill for skill in deployed_skills_data}
 
+        # Check ALL required PM skills
+        for required_skill in REQUIRED_PM_SKILLS:
+            # Check if skill is in registry
+            if required_skill not in deployed_lookup:
+                warnings.append(f"Required PM skill missing: {required_skill}")
+                missing_skills.append(required_skill)
+                continue
+
+            # Check if skill file exists
+            skill_file = deployment_dir / required_skill / "SKILL.md"
             if not skill_file.exists():
-                warnings.append(f"Deployed skill file missing: {skill_name}")
-                missing_skills.append(skill_name)
+                warnings.append(
+                    f"Required PM skill file missing: {required_skill}/SKILL.md"
+                )
+                missing_skills.append(required_skill)
+                continue
+
+            # Check if skill file is empty/corrupted
+            try:
+                file_size = skill_file.stat().st_size
+                if file_size == 0:
+                    warnings.append(
+                        f"Required PM skill file is empty: {required_skill}/SKILL.md"
+                    )
+                    corrupted_skills.append(required_skill)
+                    continue
+            except OSError as e:
+                warnings.append(
+                    f"Cannot read required PM skill file: {required_skill}/SKILL.md - {e}"
+                )
+                corrupted_skills.append(required_skill)
                 continue
 
             # Verify checksum
+            deployed_skill = deployed_lookup[required_skill]
             current_checksum = self._compute_checksum(skill_file)
-            expected_checksum = skill.get("checksum", "")
+            expected_checksum = deployed_skill.get("checksum", "")
 
             if current_checksum != expected_checksum:
                 warnings.append(
-                    f"Skill checksum mismatch: {skill_name} (file may be corrupted)"
+                    f"Required PM skill checksum mismatch: {required_skill} (file may be corrupted)"
                 )
-                outdated_skills.append(skill_name)
+                corrupted_skills.append(required_skill)
 
-        # Check for available updates
+        # Check for available updates (bundled skills newer than deployed)
         bundled_skills = {s["name"]: s for s in self._discover_bundled_pm_skills()}
         for skill_name, bundled_skill in bundled_skills.items():
+            # Skip non-required skills
+            if skill_name not in REQUIRED_PM_SKILLS:
+                continue
+
             # Find corresponding deployed skill
-            deployed_skill = next(
-                (s for s in deployed_skills if s["name"] == skill_name), None
-            )
+            deployed_skill = deployed_lookup.get(skill_name)
 
             if not deployed_skill:
-                warnings.append(f"New PM skill available: {skill_name}")
-                missing_skills.append(skill_name)
+                # Already tracked as missing
                 continue
 
             # Check if checksums differ
@@ -594,22 +726,66 @@ class PMSkillsDeployerService(LoggerMixin):
             deployed_checksum = deployed_skill.get("checksum", "")
 
             if bundled_checksum != deployed_checksum:
-                warnings.append(f"PM skill update available: {skill_name}")
-                outdated_skills.append(skill_name)
+                # Don't add to outdated_skills if already in corrupted_skills
+                if skill_name not in corrupted_skills:
+                    warnings.append(f"PM skill update available: {skill_name}")
+                    outdated_skills.append(skill_name)
+
+        # Auto-repair if enabled and issues found
+        repaired_skills = []
+        if auto_repair and (missing_skills or corrupted_skills):
+            self.logger.info(
+                f"Auto-repairing PM skills: {len(missing_skills)} missing, "
+                f"{len(corrupted_skills)} corrupted"
+            )
+
+            # Deploy missing and corrupted skills
+            repair_result = self.deploy_pm_skills(project_dir, force=True)
+
+            if repair_result.success:
+                repaired_skills = repair_result.deployed
+                self.logger.info(f"Auto-repaired {len(repaired_skills)} PM skills")
+
+                # Remove repaired skills from missing/corrupted lists
+                missing_skills = [s for s in missing_skills if s not in repaired_skills]
+                corrupted_skills = [
+                    s for s in corrupted_skills if s not in repaired_skills
+                ]
+
+                # Update warnings
+                if repaired_skills:
+                    warnings.append(
+                        f"Auto-repaired {len(repaired_skills)} PM skills: {', '.join(repaired_skills)}"
+                    )
+            else:
+                warnings.append(
+                    f"Auto-repair failed: {len(repair_result.errors)} errors"
+                )
+                self.logger.error(
+                    f"Auto-repair failed with errors: {repair_result.errors}"
+                )
 
-        verified = len(warnings) == 0
+        # Determine verification status
+        verified = len(missing_skills) == 0 and len(corrupted_skills) == 0
 
+        # Build message
         if verified:
-            message = "All PM skills verified and up-to-date"
+            if repaired_skills:
+                message = f"All PM skills verified (auto-repaired {len(repaired_skills)} skills)"
+            else:
+                message = "All PM skills verified and up-to-date"
         else:
-            message = f"{len(warnings)} verification warnings found"
+            issue_count = len(missing_skills) + len(corrupted_skills)
+            message = f"{issue_count} PM skill issues found"
 
         return VerificationResult(
             verified=verified,
             warnings=warnings,
             missing_skills=missing_skills,
+            corrupted_skills=corrupted_skills,
             outdated_skills=outdated_skills,
             message=message,
+            skill_count=len(deployed_skills_data),
         )
 
     def get_deployed_skills(self, project_dir: Path) -> List[PMSkillInfo]:
@@ -632,10 +808,10 @@ class PMSkillsDeployerService(LoggerMixin):
         skills = []
         for skill_data in registry.get("skills", []):
             skill_name = skill_data["name"]
-            deployed_path = deployment_dir / f"{skill_name}.md"
+            deployed_path = deployment_dir / skill_name / "SKILL.md"
 
             # Find source path (may not exist if bundled skills changed)
-            source_path = self.bundled_pm_skills_path / f"{skill_name}.md"
+            source_path = self.bundled_pm_skills_path / skill_name / "SKILL.md"
 
             skills.append(
                 PMSkillInfo(