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

claude_mpm/services/skills/selective_skill_deployer.py

@@ -214,18 +214,90 @@ def get_skills_from_mapping(agent_ids: List[str]) -> Set[str]:
     return set()
 
 
+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 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.
 
-    MAJOR CHANGE (Phase 3): Now ONLY uses frontmatter-declared skills.
+    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 in frontmatter or it gets zero skills deployed.
+    declare its skills via frontmatter OR inline markers.
 
     This change:
     - Eliminates dual-source complexity (frontmatter + mapping)
     - Makes skill requirements explicit per agent
-    - Enables per-agent customization via frontmatter
+    - 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/)
@@ -244,37 +316,63 @@ 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}")
 
-    # ONLY use frontmatter skills - no more mapping inference
+    # 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()
+    content_skills = set()
 
     for agent_file in agent_files:
         agent_id = agent_file.stem
 
+        # 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"
             )
-        else:
-            logger.debug(f"Agent {agent_id}: No skills declared in 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"
+            )
+
+        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
+    all_skills = frontmatter_skills | content_skills
 
     logger.info(
-        f"Found {len(frontmatter_skills)} unique skills from agent frontmatter "
-        f"(static mapping no longer used)"
+        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 frontmatter_skills}
+    normalized_skills = {skill.replace("/", "-") for skill in all_skills}
 
-    if normalized_skills != frontmatter_skills:
+    if normalized_skills != all_skills:
         logger.debug(
-            f"Normalized {len(frontmatter_skills)} skills to {len(normalized_skills)} "
+            f"Normalized {len(all_skills)} skills to {len(normalized_skills)} "
             "(converted slashes to dashes)"
         )
 

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

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/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-agent-update-workflow/SKILL.md

@@ -0,0 +1,75 @@
+# PM Skill: Agent Update Workflow
+
+## Trigger Patterns
+- "update agent", "fix agent", "improve agent", "modify agent"
+- "change {agent-name} agent", "edit agent instructions"
+- Any request to modify agent behavior
+
+## FUNDAMENTAL RULE: Official vs Custom Agents
+
+### Official MPM Agents (NEVER edit deployed copies)
+**Source**: `~/.claude-mpm/cache/agents/` (from bobmatnyc/claude-mpm-agents repo)
+**Deployed**: `.claude/agents/` - READ-ONLY for official agents
+
+**Detection**: Check if agent exists in `~/.claude-mpm/cache/agents/`
+- If YES → Official agent → Follow Official Agent Workflow
+- If NO → Custom agent → Can edit `.claude/agents/` directly
+
+### Custom/Localized Agents
+- Created specifically for project
+- Can be edited directly in `.claude/agents/`
+- Not part of official MPM agent set
+
+## Official Agent Update Workflow
+
+### Step 1: Identify Agent Source
+```bash
+ls ~/.claude-mpm/cache/agents/  # Find the source file
+```
+
+### Step 2: Update Source
+Edit the agent source in `~/.claude-mpm/cache/agents/{agent-name}.md`
+(or appropriate path based on agent structure)
+
+### Step 3: Rebuild and Redeploy
+Use MPM deployment tools:
+```bash
+# Redeploy specific agent
+mpm agents deploy {agent-name}
+
+# Or redeploy all agents
+mpm agents deploy --all
+```
+
+### Step 4: Validate (claude-mpm project only)
+When working in the claude-mpm project itself:
+```bash
+# Run deepeval against deployed agent instructions
+deepeval test --agent {agent-name}
+```
+
+## Circuit Breaker
+
+**BLOCK** if attempting to edit `.claude/agents/{official-agent}.md` directly:
+- Official agents in deployed location are BUILD OUTPUTS
+- Must update source → rebuild → redeploy
+- Violation = architectural breach
+
+## Examples
+
+### ❌ WRONG (Editing deployed official agent)
+```
+Edit: .claude/agents/web-qa.md  # VIOLATION - this is a built output
+```
+
+### ✅ CORRECT (Updating source and redeploying)
+```
+1. Edit: ~/.claude-mpm/cache/agents/web-qa.md  # Update source
+2. Run: mpm agents deploy web-qa                # Rebuild/redeploy
+3. Validate: deepeval test --agent web-qa       # (in claude-mpm project)
+```
+
+### ✅ CORRECT (Custom agent - can edit directly)
+```
+Edit: .claude/agents/my-custom-agent.md  # OK - not an official agent
+```