claude-mpm 5.4.41__py3-none-any.whl → 5.6.72__py3-none-any.whl

claude_mpm/services/skills_deployer.py

@@ -28,7 +28,7 @@ References:
 import json
 import platform
 import shutil
-import subprocess
+import subprocess  # nosec B404 - subprocess needed for safe git operations
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -174,44 +174,93 @@ class SkillsDeployerService(LoggerMixin):
         if selective:
             # Auto-detect project root if not provided
             if project_root is None:
-                # Try to find project root by looking for .claude directory
+                # Try to find project root by looking for .claude-mpm directory
                 # Start from current directory and walk up
                 current = Path.cwd()
                 while current != current.parent:
-                    if (current / ".claude").exists():
+                    if (current / ".claude-mpm").exists():
                         project_root = current
                         break
                     current = current.parent
 
+            # Read skills from configuration.yaml instead of agent frontmatter
             if project_root:
-                agents_dir = Path(project_root) / ".claude" / "agents"
+                config_path = Path(project_root) / ".claude-mpm" / "configuration.yaml"
             else:
-                # Fallback to current directory's .claude/agents
-                agents_dir = Path.cwd() / ".claude" / "agents"
+                # Fallback to current directory's configuration
+                config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
 
             from claude_mpm.services.skills.selective_skill_deployer import (
                 get_required_skills_from_agents,
+                get_skills_to_deploy,
+                save_agent_skills_to_config,
             )
 
-            required_skill_names = get_required_skills_from_agents(agents_dir)
+            # Check if agent_referenced is empty and needs to be populated
+            required_skill_names, source = get_skills_to_deploy(config_path)
+
+            if not required_skill_names and project_root:
+                # agent_referenced is empty, scan deployed agents to populate it
+                agents_dir = Path(project_root) / ".claude" / "agents"
+                if agents_dir.exists():
+                    self.logger.info(
+                        "agent_referenced is empty in configuration.yaml, scanning deployed agents..."
+                    )
+                    agent_skills = get_required_skills_from_agents(agents_dir)
+                    if agent_skills:
+                        save_agent_skills_to_config(list(agent_skills), config_path)
+                        self.logger.info(
+                            f"Populated agent_referenced with {len(agent_skills)} skills from deployed agents"
+                        )
+                        # Re-read configuration after update
+                        required_skill_names, source = get_skills_to_deploy(config_path)
+                    else:
+                        self.logger.warning(
+                            "No skills found in deployed agents - configuration.yaml remains empty"
+                        )
+                else:
+                    self.logger.warning(
+                        f"Agents directory not found at {agents_dir} - cannot scan for skills"
+                    )
 
             if required_skill_names:
+                # Convert required_skill_names to a set for O(1) lookup
+                required_set = set(required_skill_names)
+
                 # Filter to only required skills
-                # Match on either 'name' or 'skill_id' field
+                # Match on: 'name', 'skill_id', or normalized 'source_path'
+                # source_path example: "universal/web/api-design-patterns/SKILL.md"
+                # normalized: "universal-web-api-design-patterns"
+                def skill_matches_requirement(skill):
+                    # Check basic name and skill_id
+                    if skill.get("name") in required_set:
+                        return True
+                    if skill.get("skill_id") in required_set:
+                        return True
+
+                    # Check normalized source_path
+                    source_path = skill.get("source_path", "")
+                    if source_path:
+                        # Remove /SKILL.md suffix and replace / with -
+                        normalized = source_path.replace("/SKILL.md", "").replace(
+                            "/", "-"
+                        )
+                        if normalized in required_set:
+                            return True
+
+                    return False
+
                 filtered_skills = [
-                    s
-                    for s in filtered_skills
-                    if s.get("name") in required_skill_names
-                    or s.get("skill_id") in required_skill_names
+                    s for s in filtered_skills if skill_matches_requirement(s)
                 ]
 
                 self.logger.info(
                     f"Selective deployment: {len(filtered_skills)}/{total_available} skills "
-                    f"(agent-referenced only)"
+                    f"(source: {source})"
                 )
             else:
                 self.logger.warning(
-                    f"No skills found in agent frontmatter at {agents_dir}. "
+                    f"No skills found in configuration at {config_path}. "
                     f"Deploying all {total_available} skills."
                 )
         else:
@@ -224,12 +273,19 @@ class SkillsDeployerService(LoggerMixin):
         skipped = []
         errors = []
 
-        # Extract skill names for cleanup (needed regardless of deployment outcome)
-        filtered_skills_names = [
-            skill["name"]
-            for skill in filtered_skills
-            if isinstance(skill, dict) and "name" in skill
-        ]
+        # Extract normalized skill names for cleanup (needed regardless of deployment outcome)
+        # Must match the names used during deployment (normalized from source_path)
+        filtered_skills_names = []
+        for skill in filtered_skills:
+            if isinstance(skill, dict) and "name" in skill:
+                source_path = skill.get("source_path", "")
+                if source_path:
+                    # Normalize: "universal/web/api-design-patterns/SKILL.md" -> "universal-web-api-design-patterns"
+                    normalized = source_path.replace("/SKILL.md", "").replace("/", "-")
+                    filtered_skills_names.append(normalized)
+                else:
+                    # Fallback to skill name
+                    filtered_skills_names.append(skill["name"])
 
         for skill in filtered_skills:
             try:
@@ -243,9 +299,25 @@ class SkillsDeployerService(LoggerMixin):
                     skill, skills_data["temp_dir"], collection_name, force=force
                 )
                 if result["deployed"]:
-                    deployed.append(skill["name"])
+                    # Use normalized name for reporting
+                    source_path = skill.get("source_path", "")
+                    if source_path:
+                        normalized = source_path.replace("/SKILL.md", "").replace(
+                            "/", "-"
+                        )
+                        deployed.append(normalized)
+                    else:
+                        deployed.append(skill["name"])
                 elif result["skipped"]:
-                    skipped.append(skill["name"])
+                    # Use normalized name for reporting
+                    source_path = skill.get("source_path", "")
+                    if source_path:
+                        normalized = source_path.replace("/SKILL.md", "").replace(
+                            "/", "-"
+                        )
+                        skipped.append(normalized)
+                    else:
+                        skipped.append(skill["name"])
                 if result["error"]:
                     errors.append(result["error"])
             except Exception as e:
@@ -257,9 +329,9 @@ class SkillsDeployerService(LoggerMixin):
                 self.logger.error(f"Failed to deploy {skill_name}: {e}")
                 errors.append(f"{skill_name}: {e}")
 
-        # Step 5: Cleanup orphaned skills (if selective mode enabled)
+        # Step 5: Cleanup orphaned skills (always run in selective mode)
         cleanup_result = {"removed_count": 0, "removed_skills": []}
-        if selective and len(deployed) > 0:
+        if selective:
             # Get the set of skills that should remain deployed
             # This is the union of what we just deployed and what was already there
             try:
@@ -267,7 +339,8 @@ class SkillsDeployerService(LoggerMixin):
                     cleanup_orphan_skills,
                 )
 
-                # Only cleanup if we're in selective mode
+                # Cleanup orphaned skills not referenced by agents
+                # This runs even if nothing new was deployed to remove stale skills
                 cleanup_result = cleanup_orphan_skills(
                     self.CLAUDE_SKILLS_DIR, set(filtered_skills_names)
                 )
@@ -580,7 +653,7 @@ class SkillsDeployerService(LoggerMixin):
                     f"Updating existing collection '{collection_name}' at {target_dir}"
                 )
                 try:
-                    result = subprocess.run(
+                    result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                         ["git", "pull"],
                         cwd=target_dir,
                         capture_output=True,
@@ -611,7 +684,7 @@ class SkillsDeployerService(LoggerMixin):
                 f"Installing new collection '{collection_name}' to {target_dir}"
             )
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                     ["git", "clone", repo_url, str(target_dir)],
                     capture_output=True,
                     text=True,
@@ -700,6 +773,32 @@ class SkillsDeployerService(LoggerMixin):
         if isinstance(skills_data, dict):
             flat_skills = []
 
+            # Define valid top-level categories
+            VALID_CATEGORIES = {"universal", "toolchains"}
+
+            # Check for unknown categories and warn user
+            unknown_categories = set(skills_data.keys()) - VALID_CATEGORIES
+            if unknown_categories:
+                # Count skills in unknown categories
+                skipped_count = 0
+                for cat in unknown_categories:
+                    cat_data = skills_data.get(cat, [])
+                    if isinstance(cat_data, list):
+                        skipped_count += len(cat_data)
+                    elif isinstance(cat_data, dict):
+                        # If it's a dict like toolchains, count nested skills
+                        for skills_list in cat_data.values():
+                            if isinstance(skills_list, list):
+                                skipped_count += len(skills_list)
+
+                self.logger.warning(
+                    f"Unknown categories in manifest will be skipped: "
+                    f"{', '.join(sorted(unknown_categories))} ({skipped_count} skills)"
+                )
+                self.logger.info(
+                    f"Valid top-level categories: {', '.join(sorted(VALID_CATEGORIES))}"
+                )
+
             # Add universal skills
             universal_skills = skills_data.get("universal", [])
             if isinstance(universal_skills, list):
@@ -804,55 +903,76 @@ class SkillsDeployerService(LoggerMixin):
             Dict with deployed, skipped, error flags
         """
         skill_name = skill["name"]
-        target_dir = self.CLAUDE_SKILLS_DIR / skill_name
+
+        # Use normalized source_path for both target directory and deployment tracking
+        # This ensures consistency with configuration.yaml skill names
+        source_path = skill.get("source_path", "")
+        if source_path:
+            # Normalize: "universal/web/api-design-patterns/SKILL.md" -> "universal-web-api-design-patterns"
+            normalized_name = source_path.replace("/SKILL.md", "").replace("/", "-")
+            target_dir = self.CLAUDE_SKILLS_DIR / normalized_name
+        else:
+            # Fallback to skill name if no source_path
+            target_dir = self.CLAUDE_SKILLS_DIR / skill_name
 
         # Check if already deployed
         if target_dir.exists() and not force:
             self.logger.debug(f"Skipped {skill_name} (already deployed)")
             return {"deployed": False, "skipped": True, "error": None}
 
-        # Find skill source in collection directory
-        # Updated structure: collection_dir / skills / category / skill-name
-        # OR: collection_dir / universal / skill-name
-        # OR: collection_dir / toolchains / toolchain-name / skill-name
+        # Find skill source using source_path from manifest
+        source_dir = None
 
-        skills_base = collection_dir / "skills"
-        category = skill.get("category", "")
+        if source_path:
+            # Direct lookup using source_path (most reliable)
+            # Example: "universal/web/api-design-patterns/SKILL.md" -> "universal/web/api-design-patterns"
+            skill_dir_path = source_path.replace("/SKILL.md", "")
+            potential_source = collection_dir / skill_dir_path
+            if potential_source.exists():
+                source_dir = potential_source
+            else:
+                self.logger.debug(
+                    f"Source path {skill_dir_path} not found, trying fallback search"
+                )
 
-        # Try multiple possible locations
-        source_dir = None
-        search_paths = []
-
-        # Try category-based path
-        if category and skills_base.exists():
-            search_paths.append(skills_base / category / skill_name)
-
-        # Try universal/toolchains structure
-        if (collection_dir / "universal").exists():
-            search_paths.append(collection_dir / "universal" / skill_name)
-
-        if (collection_dir / "toolchains").exists():
-            toolchain_dir = collection_dir / "toolchains"
-            for tc in toolchain_dir.iterdir():
-                if tc.is_dir():
-                    search_paths.append(tc / skill_name)
-
-        # Search in all possible locations
-        for path in search_paths:
-            if path.exists():
-                source_dir = path
-                break
-
-        # Fallback: search recursively for skill in skills directory
-        if not source_dir and skills_base.exists():
-            for cat_dir in skills_base.iterdir():
-                if not cat_dir.is_dir():
-                    continue
-                potential = cat_dir / skill_name
-                if potential.exists():
-                    source_dir = potential
+        # Fallback: search using old logic (for backward compatibility)
+        if not source_dir:
+            skills_base = collection_dir / "skills"
+            category = skill.get("category", "")
+
+            # Try multiple possible locations
+            search_paths = []
+
+            # Try category-based path
+            if category and skills_base.exists():
+                search_paths.append(skills_base / category / skill_name)
+
+            # Try universal/toolchains structure
+            if (collection_dir / "universal").exists():
+                search_paths.append(collection_dir / "universal" / skill_name)
+
+            if (collection_dir / "toolchains").exists():
+                toolchain_dir = collection_dir / "toolchains"
+                for tc in toolchain_dir.iterdir():
+                    if tc.is_dir():
+                        search_paths.append(tc / skill_name)
+
+            # Search in all possible locations
+            for path in search_paths:
+                if path.exists():
+                    source_dir = path
                     break
 
+            # Final fallback: search recursively for skill in skills directory
+            if not source_dir and skills_base.exists():
+                for cat_dir in skills_base.iterdir():
+                    if not cat_dir.is_dir():
+                        continue
+                    potential = cat_dir / skill_name
+                    if potential.exists():
+                        source_dir = potential
+                        break
+
         if not source_dir or not source_dir.exists():
             return {
                 "deployed": False,
@@ -887,12 +1007,14 @@ class SkillsDeployerService(LoggerMixin):
             # NOTE: We use copy instead of symlink to maintain Claude Code compatibility
             shutil.copytree(source_dir, target_dir)
 
-            # Track deployment in index
+            # Track deployment in index using normalized name
             from claude_mpm.services.skills.selective_skill_deployer import (
                 track_deployed_skill,
             )
 
-            track_deployed_skill(self.CLAUDE_SKILLS_DIR, skill_name, collection_name)
+            # Use normalized name for tracking (matches configuration.yaml format)
+            track_name = normalized_name if source_path else skill_name
+            track_deployed_skill(self.CLAUDE_SKILLS_DIR, track_name, collection_name)
 
             self.logger.debug(
                 f"Deployed {skill_name} from {source_dir} to {target_dir}"
@@ -926,12 +1048,12 @@ class SkillsDeployerService(LoggerMixin):
         """
         try:
             if platform.system() == "Windows":
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded tasklist command
                     ["tasklist"], check=False, capture_output=True, text=True, timeout=5
                 )
                 return "claude" in result.stdout.lower()
             # macOS and Linux
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded ps command
                 ["ps", "aux"], check=False, capture_output=True, text=True, timeout=5
             )
             # Look for "Claude Code" or "claude-code" process

claude_mpm/services/socketio/handlers/hook.py

@@ -118,7 +118,8 @@ class HookEventHandler(BaseEventHandler):
             self.server.active_sessions[session_id] = {
                 "session_id": session_id,
                 "start_time": datetime.now(timezone.utc).isoformat(),
-                "agent": agent_type,
+                "current_agent": agent_type,  # Current active agent
+                "agents": [agent_type],  # All agents used in this session
                 "status": ServiceState.RUNNING,
                 "prompt": data.get("prompt", "")[:100],  # First 100 chars
                 "last_activity": datetime.now(timezone.utc).isoformat(),
@@ -169,7 +170,8 @@ class HookEventHandler(BaseEventHandler):
                 self.server.active_sessions[session_id] = {
                     "session_id": session_id,
                     "start_time": datetime.now(timezone.utc).isoformat(),
-                    "agent": "pm",  # Default to PM
+                    "current_agent": "pm",  # Current active agent
+                    "agents": ["pm"],  # All agents used in this session
                     "status": ServiceState.RUNNING,
                     "prompt": data.get("prompt_text", "")[:100],
                     "working_directory": data.get("working_directory", ""),
@@ -200,11 +202,16 @@ class HookEventHandler(BaseEventHandler):
         # Update session with new agent
         if hasattr(self.server, "active_sessions"):
             if session_id in self.server.active_sessions:
-                self.server.active_sessions[session_id]["agent"] = agent_type
-                self.server.active_sessions[session_id]["status"] = "delegated"
-                self.server.active_sessions[session_id]["last_activity"] = datetime.now(
-                    timezone.utc
-                ).isoformat()
+                session = self.server.active_sessions[session_id]
+                session["current_agent"] = agent_type
+                session["status"] = "delegated"
+                session["last_activity"] = datetime.now(timezone.utc).isoformat()
+
+                # Add to agents list if not already present
+                if "agents" not in session:
+                    session["agents"] = []
+                if agent_type not in session["agents"]:
+                    session["agents"].append(agent_type)
 
                 self.logger.debug(
                     f"Updated session delegation: session={session_id[:8]}..., agent={agent_type}"

claude_mpm/services/socketio/server/main.py

@@ -383,7 +383,8 @@ class SocketIOServer(SocketIOServiceInterface):
         self.active_sessions[session_id] = {
             "session_id": session_id,
             "start_time": datetime.now(timezone.utc).isoformat(),
-            "agent": "pm",  # Default to PM, will be updated if delegated
+            "current_agent": "pm",  # Current active agent
+            "agents": ["pm"],  # All agents used in this session
             "status": ServiceState.RUNNING,
             "launch_method": launch_method,
             "working_dir": working_dir,
@@ -419,8 +420,15 @@ class SocketIOServer(SocketIOServiceInterface):
         """Notify agent delegation."""
         # Update active session with current agent
         if self.session_id and self.session_id in self.active_sessions:
-            self.active_sessions[self.session_id]["agent"] = agent
-            self.active_sessions[self.session_id]["status"] = status
+            session = self.active_sessions[self.session_id]
+            session["current_agent"] = agent
+            session["status"] = status
+
+            # Add to agents list if not already present
+            if "agents" not in session:
+                session["agents"] = []
+            if agent not in session["agents"]:
+                session["agents"].append(agent)
 
         if self.broadcaster:
             self.broadcaster.agent_delegated(agent, task, status)
@@ -480,7 +488,7 @@ class SocketIOServer(SocketIOServiceInterface):
                 start_time = datetime.fromisoformat(session_data["start_time"])
                 if start_time.timestamp() < cutoff_time:
                     sessions_to_remove.append(session_id)
-            except Exception:
+            except Exception:  # nosec B110 - Silently skip malformed timestamps
                 pass
 
         for session_id in sessions_to_remove:

claude_mpm/skills/__init__.py

@@ -24,7 +24,7 @@ Legacy System (maintained for compatibility):
 from .agent_skills_injector import AgentSkillsInjector
 
 # Legacy System (maintained for compatibility)
-from .registry import Skill, SkillsRegistry, get_registry
+from .registry import Skill, SkillsRegistry, get_registry, validate_agentskills_spec
 from .skill_manager import SkillManager
 from .skills_registry import SkillsRegistry as SkillsRegistryHelper
 from .skills_service import SkillsService
@@ -39,4 +39,5 @@ __all__ = [
     # New Skills Integration System
     "SkillsService",
     "get_registry",
+    "validate_agentskills_spec",
 ]

claude_mpm/skills/bundled/collaboration/brainstorming/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: Brainstorming Ideas Into Designs
+description: Interactive idea refinement using Socratic method to develop fully-formed designs
+when_to_use: when partner describes any feature or project idea, before writing code or implementation plans
+version: 2.2.0
+progressive_disclosure:
+  level: 1
+  references: []
+  note: Already optimal at 75 lines - intentionally compact, no references needed
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
+
+**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
+
+**Announce at start:** "I'm using the Brainstorming skill to refine your idea into a design."
+
+## The Process
+
+### Phase 1: Understanding
+- Check current project state in working directory
+- Ask ONE question at a time to refine the idea
+- Prefer multiple choice when possible
+- Gather: Purpose, constraints, success criteria
+
+### Phase 2: Exploration
+- Propose 2-3 different approaches
+- For each: Core architecture, trade-offs, complexity assessment
+- Ask your human partner which approach resonates
+
+### Phase 3: Design Presentation
+- Present in 200-300 word sections
+- Cover: Architecture, components, data flow, error handling, testing
+- Ask after each section: "Does this look right so far?"
+
+### Phase 4: Worktree Setup (for implementation)
+When design is approved and implementation will follow:
+- Announce: "I'm using the Using Git Worktrees skill to set up an isolated workspace."
+- Switch to skills/collaboration/using-git-worktrees
+- Follow that skill's process for directory selection, safety verification, and setup
+- Return here when worktree ready
+
+### Phase 5: Planning Handoff
+Ask: "Ready to create the implementation plan?"
+
+When your human partner confirms (any affirmative response):
+- Announce: "I'm using the Writing Plans skill to create the implementation plan."
+- Switch to skills/collaboration/writing-plans skill
+- Create detailed plan in the worktree
+
+## When to Revisit Earlier Phases
+
+**You can and should go backward when:**
+- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1 to understand it
+- Validation shows fundamental gap in requirements → Return to Phase 1
+- Partner questions approach during Phase 3 → Return to Phase 2 to explore alternatives
+- Something doesn't make sense → Go back and clarify
+
+**Don't force forward linearly** when going backward would give better results.
+
+## Related Skills
+
+**During exploration:**
+- When approaches have genuine trade-offs: skills/architecture/preserving-productive-tensions
+
+**Before proposing changes to existing code:**
+- Understand why it exists: skills/research/tracing-knowledge-lineages
+
+## Remember
+- One question per message during Phase 1
+- Apply YAGNI ruthlessly
+- Explore 2-3 alternatives before settling
+- Present incrementally, validate as you go
+- Go backward when needed - flexibility > rigid progression
+- Announce skill usage at start