claude-mpm 5.4.96__py3-none-any.whl → 5.6.3__py3-none-any.whl

claude_mpm/services/pm_skills_deployer.py

@@ -50,9 +50,16 @@ from claude_mpm.core.mixins import LoggerMixin
 # Security constants
 MAX_YAML_SIZE = 10 * 1024 * 1024  # 10MB limit to prevent YAML bombs
 
-# Required PM skills that MUST be deployed for PM agent to function properly
-# These are framework management skills that PM uses for orchestration
+# 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",
@@ -66,6 +73,23 @@ REQUIRED_PM_SKILLS = [
     "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:
@@ -383,17 +407,45 @@ class PMSkillsDeployerService(LoggerMixin):
         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/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
@@ -401,16 +453,42 @@ class PMSkillsDeployerService(LoggerMixin):
         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)
+            >>> # 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 = []
@@ -526,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"
         )
 

claude_mpm/services/skills/git_skill_source_manager.py

@@ -682,7 +682,7 @@ class GitSkillSourceManager:
                 try:
                     with open(etag_cache_file, encoding="utf-8") as f:
                         etag_cache = json.load(f)
-                except Exception:
+                except Exception:  # nosec B110 - intentional: proceed without cache on read failure
                     pass
 
             cached_etag = etag_cache.get(str(local_path))
@@ -1163,6 +1163,10 @@ class GitSkillSourceManager:
     ) -> List[str]:
         """Remove skills from target directory that aren't in the filtered skill list.
 
+        CRITICAL: Only removes MPM-managed skills (those in our cache). Custom user skills
+        are preserved. This prevents accidental deletion of user-created skills that were
+        never part of MPM's skill repository.
+
         Uses fuzzy matching to handle both exact deployment names and short skill names.
         For example:
         - "toolchains-python-frameworks-flask" (deployed dir) matches "flask" (filter)
@@ -1213,6 +1217,40 @@ class GitSkillSourceManager:
 
             return False
 
+        def is_mpm_managed_skill(skill_dir_name: str) -> bool:
+            """Check if skill is managed by MPM (exists in our cache).
+
+            Custom user skills (not in cache) are NEVER deleted, even if not in filter.
+            Only MPM-managed skills (in cache but not in filter) are candidates for removal.
+
+            Args:
+                skill_dir_name: Name of deployed skill directory
+
+            Returns:
+                True if skill exists in MPM cache (MPM-managed), False if custom user skill
+            """
+            # Check all configured skill sources for this skill
+            for source in self.config.get_enabled_sources():
+                cache_path = self._get_source_cache_path(source)
+                if not cache_path.exists():
+                    continue
+
+                # Check if this skill directory exists anywhere in the cache
+                # Use glob to find matching directories recursively
+                matches = list(cache_path.rglob(f"*{skill_dir_name}*"))
+                if matches:
+                    # Found in cache - this is MPM-managed
+                    self.logger.debug(
+                        f"Skill '{skill_dir_name}' found in cache at {matches[0]} - MPM-managed"
+                    )
+                    return True
+
+            # Not found in any cache - this is a custom user skill
+            self.logger.debug(
+                f"Skill '{skill_dir_name}' not found in cache - custom user skill, preserving"
+            )
+            return False
+
         # Check each directory in target_dir
         if not target_dir.exists():
             return removed_skills
@@ -1229,6 +1267,15 @@ class GitSkillSourceManager:
 
                 # Check if this skill directory should be kept (fuzzy matching)
                 if not should_keep_skill(item.name):
+                    # CRITICAL: Check if this is an MPM-managed skill before deletion
+                    if not is_mpm_managed_skill(item.name):
+                        # This is a custom user skill - NEVER delete
+                        self.logger.debug(
+                            f"Preserving custom user skill (not in MPM cache): {item.name}"
+                        )
+                        continue
+
+                    # It's MPM-managed but not in filter - safe to remove
                     try:
                         # Security: Validate path is within target_dir
                         if not self._validate_safe_path(target_dir, item):
@@ -1244,7 +1291,9 @@ class GitSkillSourceManager:
                             shutil.rmtree(item)
 
                         removed_skills.append(item.name)
-                        self.logger.info(f"Removed orphaned skill: {item.name}")
+                        self.logger.info(
+                            f"Removed orphaned MPM-managed skill: {item.name}"
+                        )
 
                     except Exception as e:
                         self.logger.warning(

claude_mpm/services/skills/skill_discovery_service.py

@@ -163,10 +163,22 @@ class SkillDiscoveryService:
         skill_md_files = list(self.skills_dir.rglob("SKILL.md"))
 
         # Also find legacy *.md files in top-level directory for backward compatibility
+        # Exclude common non-skill documentation files
+        excluded_filenames = {
+            "skill.md",  # Case variations of SKILL.md
+            "readme.md",
+            "claude.md",
+            "contributing.md",
+            "changelog.md",
+            "license.md",
+            "authors.md",
+            "code_of_conduct.md",
+        }
+
         legacy_md_files = [
             f
             for f in self.skills_dir.glob("*.md")
-            if f.name != "SKILL.md" and f.name.lower() != "readme.md"
+            if f.name.lower() not in excluded_filenames
         ]
 
         all_skill_files = skill_md_files + legacy_md_files
@@ -255,7 +267,35 @@ class SkillDiscoveryService:
         try:
             frontmatter, body = self._extract_frontmatter(content)
         except Exception as e:
-            self.logger.warning(f"No valid frontmatter in {skill_file.name}: {e}")
+            # Only log as debug for documentation files to reduce noise
+            # Common documentation files (CLAUDE.md, README.md) are expected to lack skill frontmatter
+            relative_path = (
+                skill_file.relative_to(self.skills_dir)
+                if skill_file.is_relative_to(self.skills_dir)
+                else skill_file
+            )
+
+            # Check if this looks like a documentation file
+            is_documentation = any(
+                doc_pattern in skill_file.name.lower()
+                for doc_pattern in [
+                    "readme",
+                    "claude",
+                    "contributing",
+                    "changelog",
+                    "license",
+                ]
+            )
+
+            if is_documentation:
+                self.logger.debug(
+                    f"Skipping documentation file {relative_path} (no skill frontmatter): {e}"
+                )
+            else:
+                # For actual skill files with invalid YAML, use warning level
+                self.logger.warning(
+                    f"Failed to parse skill frontmatter in {relative_path}: {e}"
+                )
             return None
 
         # Validate required fields
@@ -354,10 +394,24 @@ class SkillDiscoveryService:
         frontmatter_text = match.group(1)
         body = match.group(2)
 
-        # Parse YAML
+        # Parse YAML with improved error handling
         try:
             frontmatter = yaml.safe_load(frontmatter_text)
         except yaml.YAMLError as e:
+            # Provide more specific error message with context
+            error_line = getattr(e, "problem_mark", None)
+            if error_line:
+                line_num = error_line.line + 1
+                col_num = error_line.column + 1
+                # Extract problematic line for context
+                lines = frontmatter_text.split("\n")
+                problem_line = (
+                    lines[error_line.line] if error_line.line < len(lines) else ""
+                )
+                raise ValueError(
+                    f"Invalid YAML in frontmatter at line {line_num}, column {col_num}: {e.problem}\n"
+                    f"  Problematic line: {problem_line.strip()}"
+                ) from e
             raise ValueError(f"Invalid YAML in frontmatter: {e}") from e
 
         if not isinstance(frontmatter, dict):

claude_mpm/skills/bundled/pm/mpm/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mpm
+description: Access Claude MPM functionality and manage multi-agent orchestration
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required]
+---
+
+# /mpm
+
+Access Claude MPM functionality and manage your multi-agent orchestration.
+
+## Available MPM Commands
+
+- `/mpm-agents` - Show available agents and versions
+- `/mpm-doctor` - Run diagnostic checks
+- `/mpm-help` - Show command help
+- `/mpm-status` - Show MPM status
+- `/mpm-ticket` - Ticketing workflow management (organize, proceed, status, update, project)
+- `/mpm-config` - Manage configuration
+- `/mpm-resume` - Create session resume files
+- `/mpm-version` - Display version information for project, agents, and skills
+
+## What is Claude MPM?
+
+Claude MPM extends Claude Code with:
+- **Multi-agent orchestration** - Delegate work to specialized agents
+- **Project-specific PM instructions** - Tailored guidance for your project
+- **Agent memory management** - Context-aware agent interactions
+- **WebSocket monitoring** - Real-time system monitoring
+- **Hook system for automation** - Automate workflows and tasks
+
+## Quick Start
+
+Use `/mpm-help` to explore commands or `/mpm-status` to check system health.
+
+For more information, use `/mpm-help [command]` for specific command details.

claude_mpm/skills/bundled/pm/mpm-config/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mpm-config
+description: Manage Claude MPM configuration
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, config, pm-recommended]
+---
+
+# /mpm-config
+
+Unified configuration management with auto-detection.
+
+## Usage
+```
+/mpm-config [auto|view|validate|status] [options]
+```
+
+**Modes:**
+- `auto` (default): Auto-detect toolchain and configure agents/skills
+- `view`: Display current configuration
+- `validate`: Check configuration validity
+- `status`: Show configuration health
+
+**Key Options:**
+- `--yes`: Auto-deploy without confirmation
+- `--preview`: Show recommendations only
+
+See docs/commands/config.md for full options.

claude_mpm/skills/bundled/pm/mpm-doctor/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: mpm-doctor
+description: Run diagnostic checks on Claude MPM installation
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required, diagnostics, troubleshooting]
+---
+
+# /mpm-doctor
+
+Run comprehensive diagnostics on Claude MPM installation.
+
+## Usage
+
+```
+/mpm-doctor [--verbose] [--fix]
+```
+
+## Options
+
+- `--verbose`: Show detailed diagnostic output
+- `--fix`: Attempt to automatically fix detected issues
+
+## What It Checks
+
+- **Installation**: MPM package installation and version
+- **Configuration**: Config file validity and required settings
+- **WebSocket**: WebSocket server connectivity and health
+- **Agents**: Agent availability and configuration
+- **Memory**: Memory system health and accessibility
+- **Hooks**: Hook system setup and functionality
+
+## When to Use
+
+- After initial MPM installation (verify setup)
+- When experiencing issues with commands or delegation
+- Before reporting bugs (gather diagnostic information)
+- After configuration changes (verify correctness)
+- When WebSocket monitoring isn't working
+
+## Example Output
+
+```
+✅ MPM Installation: OK (v5.4.105)
+✅ Configuration: Valid
+⚠️  WebSocket Server: Not running (start with /mpm-monitor start)
+✅ Agents: 15 available
+✅ Memory System: Healthy
+✅ Hooks: Configured
+```
+
+See docs/commands/doctor.md for details.

claude_mpm/skills/bundled/pm/mpm-help/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: mpm-help
+description: Display help for Claude MPM commands
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required, documentation]
+---
+
+# /mpm-help
+
+Show help for MPM commands. Delegates to PM agent.
+
+## Usage
+
+```
+/mpm-help [command]
+```
+
+## Examples
+
+```
+/mpm-help              # Show all available commands
+/mpm-help mpm-init     # Show detailed help for mpm-init
+/mpm-help mpm-ticket   # Show ticketing workflow help
+```
+
+## What It Provides
+
+- **Command listing**: All available MPM commands
+- **Command details**: Syntax, options, and usage examples
+- **Delegation patterns**: Which agent handles which command
+- **Workflow guidance**: Common command sequences and workflows
+
+See docs/commands/help.md for full command reference.

claude_mpm/skills/bundled/pm/mpm-init/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: mpm-init
+description: Initialize or update project for Claude Code and MPM
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-required, setup]
+---
+
+# /mpm-init
+
+Initialize or intelligently update project for Claude Code and Claude MPM.
+
+## Usage
+
+```
+/mpm-init [update|context|resume|catchup] [options]
+```
+
+## Core Modes
+
+### Project Setup
+
+```
+/mpm-init                      # Auto-detect: offer update or create
+/mpm-init update               # Quick update (30-day git activity)
+/mpm-init --update             # Full documentation refresh
+/mpm-init --force              # Force recreate from scratch
+```
+
+**Delegates to Agentic Coder Optimizer agent** for:
+- CLAUDE.md creation/update (with priority rankings 🔴🟡🟢⚪)
+- AST analysis and code structure docs
+- Single-path workflows (ONE way to do ANYTHING)
+- Tool configuration, memory system, gitignore management
+
+**Smart Update Mode:** Auto-detects existing CLAUDE.md and offers update vs recreate.
+
+### Context Analysis
+
+```
+/mpm-init context [--days N]   # Intelligent git history analysis (default: 7 days)
+/mpm-init catchup              # Quick commit history (last 25 commits, no analysis)
+```
+
+**context:** Delegates to Research agent for deep analysis of:
+- Active work streams (from commit patterns)
+- Intent and motivation (from messages)
+- Risks and blockers
+- Recommended next actions
+
+**catchup:** Direct CLI execution, instant output.
+
+### Resume from Logs
+
+```
+/mpm-init resume [--list] [--session-id ID]
+```
+
+Reads stop event logs from `.claude-mpm/resume-logs/` and `.claude-mpm/responses/` showing:
+- What was being worked on
+- Tasks completed, files modified
+- Next steps, stop reason, token usage
+- Git context (branch, status)
+
+## Key Options
+
+**Configuration:**
+- `--project-type TYPE`: web, api, cli, library
+- `--framework NAME`: react, django, fastapi, etc.
+- `--ast-analysis` / `--no-ast-analysis`: Enable/disable code analysis
+- `--comprehensive` / `--minimal`: Full setup vs CLAUDE.md only
+
+**Organization:**
+- `--organize`: Organize misplaced files
+- `--preserve-custom`: Keep custom sections (default)
+- `--review`: Review without changes
+
+## What Gets Created
+
+**New Projects:**
+- ✅ CLAUDE.md (priority-ranked instructions)
+- ✅ Single-path workflows (make build/test/deploy)
+- ✅ Tool configs (linting, formatting, testing)
+- ✅ Memory system (.claude-mpm/memories/)
+- ✅ DEVELOPER.md, CODE_STRUCTURE.md (with AST)
+- ✅ .gitignore updates (auto-adds .claude-mpm/)
+
+**Updates:**
+- ✅ Smart merging (preserves custom sections)
+- ✅ Automatic archival (docs/_archive/)
+- ✅ Change tracking
+
+## Examples
+
+```bash
+# Quick start
+/mpm-init                      # Auto-detect mode
+
+# Quick update (lightweight)
+/mpm-init update               # 30-day activity report
+
+# Resume work
+/mpm-init context --days 14    # Analyze last 2 weeks
+/mpm-init resume               # Show latest session from logs
+/mpm-init catchup              # Quick commit history
+
+# Full configuration
+/mpm-init --project-type web --framework react --comprehensive
+```
+
+## Implementation Notes
+
+**Delegation patterns:**
+- **Project init/update:** → Agentic Coder Optimizer agent
+- **context:** → PM → Research agent (structured analysis)
+- **catchup:** → Direct CLI (git log wrapper)
+- **resume:** → PM (reads logs, no delegation)
+
+**Token budgets:**
+- context analysis: 10-30s processing time
+- resume display: ~10-20k tokens
+- catchup: instant, minimal tokens
+
+See docs/commands/init.md for comprehensive documentation.

claude_mpm/skills/bundled/pm/mpm-monitor/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mpm-monitor
+description: Control monitoring server and dashboard
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, system, pm-optional]
+---
+
+# /mpm-monitor
+
+Manage Socket.IO monitoring server for real-time dashboard.
+
+## Usage
+```
+/mpm-monitor [start|stop|restart|status|port] [options]
+```
+
+**Subcommands:**
+- `start`: Start server (auto-selects port 8765-8785)
+- `stop`: Stop running server
+- `status`: Show server status
+- `port <PORT>`: Start on specific port
+
+**Key Options:**
+- `--port PORT`: Specific port
+- `--force`: Force kill to reclaim port
+- `--foreground`: Run in foreground (default: background)
+
+Dashboard: http://localhost:8766
+
+See docs/commands/monitor.md for details.