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

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))
@@ -991,12 +991,17 @@ class GitSkillSourceManager:
         progress_callback=None,
         skill_filter: Optional[Set[str]] = None,
     ) -> Dict[str, Any]:
-        """Deploy skills from cache to target directory with flat structure.
+        """Deploy skills from cache to target directory with flat structure and automatic cleanup.
 
         Flattens nested Git repository structure into Claude Code compatible
         flat directory structure. Each skill directory is copied with a
         hyphen-separated name derived from its path.
 
+        CRITICAL: When skill_filter is provided (agent-referenced skills), this function:
+        1. Deploys ONLY the filtered skills
+        2. REMOVES orphaned skills (deployed but not in filter)
+        3. Returns removed_count and removed_skills in result
+
         Transformation Example:
             Cache: collaboration/dispatching-parallel-agents/SKILL.md
             Deploy: collaboration-dispatching-parallel-agents/SKILL.md
@@ -1006,8 +1011,8 @@ class GitSkillSourceManager:
             force: Overwrite existing skills
             progress_callback: Optional callback(increment: int) called for each skill deployed
             skill_filter: Optional set of skill names to deploy (selective deployment).
-                         If None, deploys all skills. If provided, only deploys skills
-                         whose name matches an entry in the filter set.
+                         If None, deploys ALL skills WITHOUT cleanup.
+                         If provided, deploys ONLY filtered skills AND removes orphans.
 
         Returns:
             Dict with deployment results:
@@ -1018,7 +1023,9 @@ class GitSkillSourceManager:
                 "deployed_skills": List[str],
                 "skipped_skills": List[str],
                 "errors": List[str],
-                "filtered_count": int  # Number of skills filtered out
+                "filtered_count": int,  # Number of skills filtered out
+                "removed_count": int,   # Number of orphaned skills removed
+                "removed_skills": List[str]  # Names of removed orphaned skills
             }
 
         Example:
@@ -1026,10 +1033,10 @@ class GitSkillSourceManager:
             >>> result = manager.deploy_skills()
             >>> print(f"Deployed {result['deployed_count']} skills")
 
-            # Selective deployment based on agent requirements:
+            # Selective deployment based on agent requirements (with cleanup):
             >>> required = {"typescript-core", "react-patterns"}
             >>> result = manager.deploy_skills(skill_filter=required)
-            >>> print(f"Deployed {result['deployed_count']} of {len(required)} required skills")
+            >>> print(f"Deployed {result['deployed_count']}, removed {result['removed_count']} orphans")
         """
         if target_dir is None:
             target_dir = Path.home() / ".claude" / "skills"
@@ -1040,6 +1047,7 @@ class GitSkillSourceManager:
         skipped = []
         errors = []
         filtered_count = 0
+        removed_skills = []  # Track removed orphaned skills
 
         # Get all skills from all sources
         all_skills = self.get_all_skills()
@@ -1082,11 +1090,16 @@ class GitSkillSourceManager:
             )
 
             # Cleanup: Remove skills from target directory that aren't in the filtered set
-            # This ensures only the skills in the profile are deployed
+            # This ensures only agent-referenced skills remain deployed
             removed_skills = self._cleanup_unfiltered_skills(target_dir, all_skills)
             if removed_skills:
                 self.logger.info(
-                    f"Removed {len(removed_skills)} skills not in profile filter: {removed_skills}"
+                    f"Removed {len(removed_skills)} orphaned skills not referenced by agents: {removed_skills[:10]}"
+                    + (
+                        f" (and {len(removed_skills) - 10} more)"
+                        if len(removed_skills) > 10
+                        else ""
+                    )
                 )
 
         self.logger.info(
@@ -1130,6 +1143,7 @@ class GitSkillSourceManager:
         self.logger.info(
             f"Deployment complete: {len(deployed)} deployed, "
             f"{len(skipped)} skipped, {len(errors)} errors"
+            + (f", {len(removed_skills)} removed" if removed_skills else "")
         )
 
         return {
@@ -1140,6 +1154,8 @@ class GitSkillSourceManager:
             "skipped_skills": skipped,
             "errors": errors,
             "filtered_count": filtered_count,
+            "removed_count": len(removed_skills),
+            "removed_skills": removed_skills,
         }
 
     def _cleanup_unfiltered_skills(
@@ -1147,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)
@@ -1197,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
@@ -1213,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):
@@ -1228,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/selective_skill_deployer.py

@@ -44,13 +44,56 @@ from typing import Any, Dict, List, Set, Tuple
 import yaml
 
 from claude_mpm.core.logging_config import get_logger
-from claude_mpm.services.skills.skill_to_agent_mapper import SkillToAgentMapper
 
 logger = get_logger(__name__)
 
 # Deployment tracking index file
 DEPLOYED_INDEX_FILE = ".mpm-deployed-skills.json"
 
+# Core skills that are universally useful across all projects
+# These are deployed when skill mapping returns too many skills (>60)
+# Target: ~25-30 core skills for balanced functionality
+CORE_SKILLS = {
+    # Universal debugging and verification (4 skills)
+    "universal-debugging-systematic-debugging",
+    "universal-debugging-verification-before-completion",
+    "universal-verification-pre-merge",
+    "universal-verification-screenshot",
+    # Universal testing patterns (2 skills)
+    "universal-testing-test-driven-development",
+    "universal-testing-testing-anti-patterns",
+    # Universal architecture and design (1 skill)
+    "universal-architecture-software-patterns",
+    # Universal infrastructure (3 skills)
+    "universal-infrastructure-env-manager",
+    "universal-infrastructure-docker",
+    "universal-infrastructure-github-actions",
+    # Universal collaboration (1 skill)
+    "universal-collaboration-stacked-prs",
+    # Universal emergency/operations (1 skill)
+    "toolchains-universal-emergency-release",
+    "toolchains-universal-dependency-audit",
+    # Common language toolchains (6 skills)
+    "toolchains-typescript-core",
+    "toolchains-python-core",
+    "toolchains-javascript-tooling-biome",
+    "toolchains-python-tooling-mypy",
+    "toolchains-typescript-testing-vitest",
+    "toolchains-python-frameworks-flask",
+    # Common web frameworks (4 skills)
+    "toolchains-javascript-frameworks-nextjs",
+    "toolchains-nextjs-core",
+    "toolchains-typescript-frameworks-nodejs-backend",
+    "toolchains-javascript-frameworks-react-state-machine",
+    # Common testing tools (2 skills)
+    "toolchains-javascript-testing-playwright",
+    "toolchains-typescript-testing-jest",
+    # Common data/UI tools (3 skills)
+    "universal-data-xlsx",
+    "toolchains-ui-styling-tailwind",
+    "toolchains-ui-components-headlessui",
+}
+
 
 def parse_agent_frontmatter(agent_file: Path) -> Dict[str, Any]:
     """Parse YAML frontmatter from agent markdown file.
@@ -140,22 +183,14 @@ def get_skills_from_agent(frontmatter: Dict[str, Any]) -> Set[str]:
 def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
     """Get skills for agents using SkillToAgentMapper inference.
 
-    Uses SkillToAgentMapper to find all skills associated with given agent IDs.
-    This provides pattern-based skill discovery beyond explicit frontmatter declarations.
-
-    CRITICAL DESIGN DECISION: This function ONLY returns skills for the DEPLOYED agents
-    provided in agent_ids. It does NOT return skills for all agents in the mapping
-    configuration (skill_to_agent_mapping.yaml lists 41 agents, but only 33 may be deployed).
+    DEPRECATED: This function is deprecated as of Phase 3 refactor.
+    Skills are now declared exclusively in agent frontmatter.
 
-    GENERIC AGENT HANDLING: The generic "engineer" agent is mapped to 100+ skills in the
-    configuration because it's designed as a fallback. To prevent over-deployment when
-    specialized agents exist, we skip "engineer" if specialized agents are present.
+    The static skill_to_agent_mapping.yaml is no longer used for skill deployment.
+    Each agent must declare its skills in frontmatter or it gets zero skills.
 
-    WHY THIS MATTERS:
-    - skill_to_agent_mapping.yaml lists ALL possible agents (41 total)
-    - User may only have 33 agents deployed in ~/.claude/agents/
-    - Without filtering, we'd deploy skills for all 41 agents (over-deployment)
-    - Solution: Only query skills for DEPLOYED agents (passed in agent_ids)
+    This function remains for backward compatibility but is NO LONGER CALLED
+    by get_required_skills_from_agents().
 
     Args:
         agent_ids: List of DEPLOYED agent identifiers (e.g., ["python-engineer", "typescript-engineer"])
@@ -163,67 +198,106 @@ def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
 
     Returns:
         Set of unique skill names inferred from mapping configuration for DEPLOYED agents only
+        NOTE: This is now an empty set as the function is deprecated.
 
     Example:
-        >>> # DEPLOYED agents only (from ~/.claude/agents/)
+        >>> # DEPRECATED - use frontmatter instead
         >>> deployed_agent_ids = ["python-engineer", "typescript-engineer", "qa"]
-        >>> skills = get_skills_from_mapping(deployed_agent_ids)
-        >>> print(f"Found {len(skills)} skills for {len(deployed_agent_ids)} deployed agents")
+        >>> skills = get_skills_from_mapping(deployed_agent_ids)  # Returns empty set
     """
-    try:
-        mapper = SkillToAgentMapper()
-        all_skills = set()
-
-        # CRITICAL FIX: Skip generic "engineer" agent if specialized agents exist
-        # The "engineer" agent is mapped to ~107 skills (almost all skills) because
-        # it's a fallback agent. This causes over-deployment when you have specialized
-        # agents like "python-engineer", "typescript-engineer", etc.
-        #
-        # Solution: Filter out "engineer" from agent_ids if specialized agents exist
-        specialized_engineers = [
-            aid for aid in agent_ids if aid.endswith("-engineer") and aid != "engineer"
-        ]
-
-        # If specialized engineers exist, exclude generic "engineer" from skill mapping
-        # This prevents deploying 100+ skills when only a subset is needed
-        agents_to_query = agent_ids
-        if specialized_engineers and "engineer" in agent_ids:
-            agents_to_query = [aid for aid in agent_ids if aid != "engineer"]
-            logger.info(
-                f"Excluding generic 'engineer' agent from skill mapping "
-                f"(found {len(specialized_engineers)} specialized engineers: "
-                f"{', '.join(specialized_engineers[:5])}{'...' if len(specialized_engineers) > 5 else ''})"
-            )
+    # DEPRECATED: Return empty set
+    logger.warning(
+        "get_skills_from_mapping() is DEPRECATED and returns empty set. "
+        "Skills are now declared in agent frontmatter only. "
+        "Update your agents with 'skills:' field in frontmatter."
+    )
+    return set()
 
-        # IMPORTANT: Only query skills for DEPLOYED agents (those in agent_ids)
-        # Do NOT query all agents from skill_to_agent_mapping.yaml (that's 41 agents)
-        for agent_id in agents_to_query:
-            agent_skills = mapper.get_skills_for_agent(agent_id)
-            if agent_skills:
-                all_skills.update(agent_skills)
-                logger.debug(f"Mapped {len(agent_skills)} skills to {agent_id}")
 
-        logger.info(
-            f"Mapped {len(all_skills)} unique skills for {len(agents_to_query)} deployed agents "
-            f"(out of {len(agent_ids)} total deployed, excluding generic 'engineer' if specialized exist)"
-        )
-        return all_skills
+def extract_skills_from_content(agent_file: Path) -> Set[str]:
+    """Extract skill names from [SKILL: skill-name] markers in agent file content.
+
+    This function complements frontmatter skill extraction by finding inline
+    skill references in the agent's markdown content body.
+
+    Supports multiple formats:
+    - Bold marker: **[SKILL: skill-name]**
+    - Plain marker: [SKILL: skill-name]
+    - Backtick list: - `skill-name` - Description
+    - With spaces: [SKILL:  skill-name  ]
 
+    Args:
+        agent_file: Path to agent markdown file
+
+    Returns:
+        Set of skill names found in content body
+
+    Example:
+        >>> skills = extract_skills_from_content(Path("pm.md"))
+        >>> # Finds skills from markers like **[SKILL: mpm-delegation-patterns]**
+        >>> # Also finds from lists like - `mpm-teaching-mode` - Description
+        >>> print(f"Found {len(skills)} skills in content")
+    """
+    try:
+        content = agent_file.read_text(encoding="utf-8")
     except Exception as e:
-        logger.warning(f"Failed to load SkillToAgentMapper: {e}")
-        logger.info("Falling back to frontmatter-only skill discovery")
+        logger.warning(f"Failed to read {agent_file}: {e}")
         return set()
 
+    skills = set()
+
+    # Pattern 1: [SKILL: skill-name] markers (with optional markdown bold)
+    # Handles: **[SKILL: skill-name]** or [SKILL: skill-name]
+    # Pattern breakdown:
+    # - \*{0,2}: Optional bold markdown (0-2 asterisks)
+    # - \[SKILL:\s*: Opening bracket with optional whitespace
+    # - ([a-zA-Z0-9_-]+): Skill name (capture group)
+    # - \s*\]: Closing bracket with optional whitespace
+    # - \*{0,2}: Optional closing bold markdown
+    pattern1 = r"\*{0,2}\[SKILL:\s*([a-zA-Z0-9_-]+)\s*\]\*{0,2}"
+    matches1 = re.findall(pattern1, content, re.IGNORECASE)
+    skills.update(matches1)
+
+    # Pattern 2: Backtick list items with mpm-* or toolchains-* skills
+    # Handles: - `mpm-skill-name` - Description
+    # Pattern breakdown:
+    # - ^-\s+: Start with dash and whitespace (list item)
+    # - `: Opening backtick
+    # - ((?:mpm-|toolchains-|universal-)[a-zA-Z0-9_-]+): Skill name starting with prefix
+    # - `: Closing backtick
+    # - \s+-: Followed by whitespace and dash (description separator)
+    pattern2 = r"^-\s+`((?:mpm-|toolchains-|universal-)[a-zA-Z0-9_-]+)`\s+-"
+    matches2 = re.findall(pattern2, content, re.MULTILINE | re.IGNORECASE)
+    skills.update(matches2)
+
+    if skills:
+        logger.debug(
+            f"Found {len(skills)} skills from content markers in {agent_file.name}"
+        )
+
+    return skills
+
 
 def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
     """Extract all skills referenced by deployed agents.
 
-    Combines skills from two sources:
-    1. Explicit frontmatter declarations (skills: field in agent .md files)
-    2. SkillToAgentMapper inference (pattern-based skill discovery)
+    MAJOR CHANGE (Phase 3): Now uses TWO sources for skill discovery:
+    1. Frontmatter-declared skills (skills: field)
+    2. Content body markers ([SKILL: skill-name])
+
+    The static skill_to_agent_mapping.yaml is DEPRECATED. Each agent must
+    declare its skills via frontmatter OR inline markers.
 
-    This dual-source approach ensures agents get both explicitly declared skills
-    and skills inferred from their domain/toolchain patterns.
+    This change:
+    - Eliminates dual-source complexity (frontmatter + mapping)
+    - Makes skill requirements explicit per agent
+    - Enables per-agent customization via frontmatter or inline markers
+    - Removes dependency on static YAML mapping
+    - Fixes PM skills being removed as orphaned (they use inline markers)
+
+    Special handling for PM_INSTRUCTIONS.md:
+    - Also scans .claude-mpm/PM_INSTRUCTIONS.md for skill markers
+    - PM instructions are not in agents_dir but contain [SKILL: ...] references
 
     Args:
         agents_dir: Path to deployed agents directory (e.g., .claude/agents/)
@@ -242,43 +316,66 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
 
     # Scan all agent markdown files
     agent_files = list(agents_dir.glob("*.md"))
-    logger.debug(f"Scanning {len(agent_files)} agent files in {agents_dir}")
 
-    # Source 1: Extract skills from frontmatter
+    # Special case: Add PM_INSTRUCTIONS.md if it exists
+    # PM instructions live in .claude-mpm/ not .claude/agents/
+    pm_instructions = agents_dir.parent.parent / ".claude-mpm" / "PM_INSTRUCTIONS.md"
+    if pm_instructions.exists():
+        agent_files.append(pm_instructions)
+        logger.debug("Added PM_INSTRUCTIONS.md for skill scanning")
+
+    logger.debug(f"Scanning {len(agent_files)} agent files (including PM instructions)")
+
+    # Use TWO sources: frontmatter AND content markers
     frontmatter_skills = set()
-    agent_ids = []
+    content_skills = set()
 
     for agent_file in agent_files:
         agent_id = agent_file.stem
-        agent_ids.append(agent_id)
 
+        # Source 1: Extract from frontmatter
         frontmatter = parse_agent_frontmatter(agent_file)
-        agent_skills = get_skills_from_agent(frontmatter)
+        agent_fm_skills = get_skills_from_agent(frontmatter)
 
-        if agent_skills:
-            frontmatter_skills.update(agent_skills)
+        if agent_fm_skills:
+            frontmatter_skills.update(agent_fm_skills)
             logger.debug(
-                f"Agent {agent_id}: {len(agent_skills)} skills from frontmatter"
+                f"Agent {agent_id}: {len(agent_fm_skills)} skills from frontmatter"
             )
 
-    logger.info(f"Found {len(frontmatter_skills)} unique skills from frontmatter")
+        # Source 2: Extract from content body [SKILL: ...] markers
+        agent_content_skills = extract_skills_from_content(agent_file)
+
+        if agent_content_skills:
+            content_skills.update(agent_content_skills)
+            logger.debug(
+                f"Agent {agent_id}: {len(agent_content_skills)} skills from content markers"
+            )
 
-    # Source 2: Get skills from SkillToAgentMapper
-    mapped_skills = get_skills_from_mapping(agent_ids)
+        if not agent_fm_skills and not agent_content_skills:
+            logger.debug(
+                f"Agent {agent_id}: No skills declared (checked frontmatter + content)"
+            )
 
     # Combine both sources
-    required_skills = frontmatter_skills | mapped_skills
-
-    # Normalize skill paths: convert slashes to dashes for compatibility with deployment
-    # SkillToAgentMapper returns paths like "toolchains/python/frameworks/django"
-    # but deployment expects "toolchains-python-frameworks-django"
-    normalized_skills = {skill.replace("/", "-") for skill in required_skills}
+    all_skills = frontmatter_skills | content_skills
 
     logger.info(
-        f"Combined {len(frontmatter_skills)} frontmatter + {len(mapped_skills)} mapped "
-        f"= {len(required_skills)} total unique skills (normalized to {len(normalized_skills)})"
+        f"Found {len(all_skills)} unique skills "
+        f"({len(frontmatter_skills)} from frontmatter, "
+        f"{len(content_skills)} from content markers)"
     )
 
+    # Normalize skill paths: convert slashes to dashes for compatibility with deployment
+    # Some skills may use slash format, normalize to dashes
+    normalized_skills = {skill.replace("/", "-") for skill in all_skills}
+
+    if normalized_skills != all_skills:
+        logger.debug(
+            f"Normalized {len(all_skills)} skills to {len(normalized_skills)} "
+            "(converted slashes to dashes)"
+        )
+
     return normalized_skills
 
 

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/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}"