claude-mpm 5.4.65__py3-none-any.whl → 5.6.10__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
 
@@ -653,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,
@@ -684,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,
@@ -773,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):
@@ -1022,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/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
+```

claude_mpm/skills/bundled/pm/mpm-bug-reporting/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: pm-bug-reporting
+version: "1.0.0"
+description: Bug reporting protocol for PM and agents to file GitHub issues
+when_to_use: Framework bugs, agent errors, skill content errors detected
+category: pm-workflow
+tags: [bug-reporting, github, issues, pm-required]
+---
+
+# PM Bug Reporting Protocol
+
+## When to Report Bugs
+
+Report bugs when you encounter:
+- **PM instruction errors** or missing guidance
+- **Agent malfunction** or incorrect behavior
+- **Skill content errors** or outdated information
+- **Framework crashes** or unexpected behavior
+- **Missing or incorrect documentation**
+- **Configuration errors** or invalid defaults
+
+## GitHub Repositories
+
+Route bugs to the correct repository:
+
+| Bug Type | Repository | Owner/Repo |
+|----------|------------|------------|
+| Core MPM (CLI, startup, config, orchestration) | claude-mpm | bobmatnyc/claude-mpm |
+| Agent bugs (wrong behavior, errors, missing capabilities) | claude-mpm-agents | bobmatnyc/claude-mpm-agents |
+| Skill bugs (wrong info, outdated, missing content) | claude-mpm-skills | bobmatnyc/claude-mpm-skills |
+
+## Bug Report Template
+
+When creating an issue, include:
+
+### Title
+Brief, descriptive title (50 chars max)
+- ✅ "PM delegates to non-existent agent"
+- ✅ "Research skill missing web search examples"
+- ❌ "Bug in system"
+- ❌ "Fix this"
+
+### Labels
+Always include:
+- `bug` (required)
+- `agent-reported` (required)
+- Additional context labels:
+  - `high-priority` - Critical functionality broken
+  - `documentation` - Documentation error
+  - `agent-error` - Agent-specific issue
+  - `skill-error` - Skill content issue
+
+### Body Structure
+```markdown
+## What Happened
+[Clear description of the bug]
+
+## Expected Behavior
+[What should have happened]
+
+## Steps to Reproduce
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+## Context
+- Agent: [agent name if applicable]
+- Skill: [skill name if applicable]
+- Error Message: [full error if available]
+- Version: [MPM version if known]
+
+## Impact
+[How this affects users/workflow]
+```
+
+## Using gh CLI
+
+### Prerequisites Check
+```bash
+gh auth status
+```
+
+If not authenticated:
+```bash
+gh auth login
+```
+
+### Creating Issues
+
+**Delegate to ticketing agent** with:
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for [bug type]
+  context: |
+    Repository: bobmatnyc/claude-mpm[-agents|-skills]
+    Title: [brief title]
+    Labels: bug, agent-reported
+    Body: |
+      ## What Happened
+      [description]
+
+      ## Expected Behavior
+      [expected]
+
+      ## Steps to Reproduce
+      1. [step 1]
+      2. [step 2]
+
+      ## Context
+      - Agent: [agent name]
+      - Error: [error message]
+
+      ## Impact
+      [impact description]
+```
+
+## Examples
+
+### Core MPM Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for core MPM bug
+  context: |
+    Repository: bobmatnyc/claude-mpm
+    Title: PM fails to load configuration on startup
+    Labels: bug, agent-reported, high-priority
+    Body: |
+      ## What Happened
+      PM fails to initialize when configuration.yaml contains invalid syntax.
+      No clear error message shown to user.
+
+      ## Expected Behavior
+      PM should display clear YAML syntax error with line number and fix suggestion.
+
+      ## Steps to Reproduce
+      1. Add invalid YAML to .claude-mpm/configuration.yaml
+      2. Run `mpm`
+      3. Observe generic error without details
+
+      ## Context
+      - Component: Configuration loader
+      - Error: "Failed to load configuration"
+      - Version: 5.4.x
+
+      ## Impact
+      Users cannot diagnose configuration errors, requiring manual YAML validation.
+```
+
+### Agent Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for agent bug
+  context: |
+    Repository: bobmatnyc/claude-mpm-agents
+    Title: Research agent fails to search with special characters
+    Labels: bug, agent-reported, agent-error
+    Body: |
+      ## What Happened
+      Research agent throws error when search query contains quotes or special chars.
+
+      ## Expected Behavior
+      Search queries should be properly escaped and executed.
+
+      ## Steps to Reproduce
+      1. Delegate to research: "Search for 'React hooks'"
+      2. Research agent attempts search
+      3. Error: "Invalid search query"
+
+      ## Context
+      - Agent: research
+      - Error: grep command fails with unescaped quotes
+
+      ## Impact
+      Cannot search for quoted phrases or technical terms with special characters.
+```
+
+### Skill Bug
+```
+Task:
+  agent: ticketing
+  task: Create GitHub issue for skill content error
+  context: |
+    Repository: bobmatnyc/claude-mpm-skills
+    Title: Git workflow skill contains outdated branch strategy
+    Labels: bug, agent-reported, documentation, skill-error
+    Body: |
+      ## What Happened
+      Skill recommends `git flow` branching model, which project no longer uses.
+      Current standard is trunk-based development.
+
+      ## Expected Behavior
+      Skill should document current trunk-based workflow.
+
+      ## Context
+      - Skill: git-workflow.md
+      - Section: "Branching Strategy"
+      - Line: 45-60
+
+      ## Impact
+      Agents follow outdated branching model, creating workflow friction.
+```
+
+## Escalation Path
+
+When ticketing agent is unavailable or gh CLI fails:
+
+1. **Log locally** for manual reporting:
+   ```
+   echo "[BUG] $(date): [description]" >> .claude-mpm/logs/bugs.log
+   ```
+
+2. **Report to PM** for alternative action:
+   ```
+   PM should create ticket in primary ticketing system (Linear/JIRA)
+   with note to create GitHub issue once available
+   ```
+
+3. **User notification**:
+   ```
+   "Bug detected: [description]. Logged for manual GitHub issue creation."
+   ```
+
+## Success Criteria
+
+Bug reporting successful when:
+- ✅ Issue created in correct repository
+- ✅ All required labels applied (`bug`, `agent-reported`)
+- ✅ Body follows template structure
+- ✅ Title is clear and concise
+- ✅ Context includes agent/skill name if applicable
+- ✅ Issue URL returned for tracking
+
+## PM Enforcement
+
+PM MUST:
+- Detect bugs during agent interactions
+- Delegate bug reporting to ticketing agent
+- NOT attempt to create GitHub issues directly
+- Follow escalation path if ticketing unavailable
+- Log all bug reports for audit trail
+
+## Related Skills
+- [pm-ticketing-integration.md](pm-ticketing-integration.md) - Ticket delegation patterns
+- [pm-delegation-patterns.md](pm-delegation-patterns.md) - General delegation guidance
+- [ticketing-examples.md](ticketing-examples.md) - Ticketing delegation examples