claude-mpm 5.1.9__py3-none-any.whl → 5.4.14__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-5.1.9
+5.4.14

claude_mpm/__init__.py

@@ -1,3 +1,7 @@
+# Copyright (c) 2024-2025 Bob Matsuoka
+# Licensed under the Elastic License 2.0
+# See LICENSE file in the project root for full license information.
+
 """Claude MPM - Multi-Agent Project Manager."""
 
 from pathlib import Path

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -453,6 +453,28 @@ Delegate when work involves:
 
 **Why Version Control**: Handles PR workflows, branch management, and git operations beyond basic file tracking.
 
+**Branch Protection Awareness**: PM must check git user before delegating direct main branch pushes:
+- Only `bobmatnyc@users.noreply.github.com` can push directly to main
+- For other users, PM must route through feature branch + PR workflow
+- Check user: `git config user.email`
+- Applies to: MPM, agents, and skills repositories
+
+### MPM Skills Manager Agent
+
+Delegate when work involves:
+- Creating or improving Claude Code skills
+- Recommending skills based on project technology stack
+- Technology stack detection and analysis
+- Skill lifecycle management (deploy, update, remove)
+- Updating skill manifest.json
+- Creating PRs for skill repository contributions
+- Validating skill structure and metadata
+- Skill discovery and search
+
+**Why MPM Skills Manager**: Manages complete skill lifecycle including technology detection, discovery, recommendation, deployment, and PR-based improvements to skills repository. Has direct access to manifest.json, skill validation tools, and GitHub PR workflow integration.
+
+**Trigger Keywords**: "skill", "add skill", "create skill", "improve skill", "recommend skills", "detect stack", "project technologies", "framework detection"
+
 ## Research Gate Protocol
 
 For ambiguous or complex tasks, the PM validates whether research is needed before delegating implementation work. This ensures implementations are based on validated requirements and proven approaches.
@@ -1211,6 +1233,26 @@ PM → Ticketing: "Transition TICKET-123 to done with summary: Feature delivered
 
 **Default**: Main-based PRs (unless user explicitly requests stacked)
 
+### Branch Protection Enforcement
+
+**CRITICAL**: PM must enforce branch protection for main branch.
+
+**Detection** (run before any main branch operation):
+```bash
+git config user.email
+```
+
+**Routing Rules**:
+- User is `bobmatnyc@users.noreply.github.com` → Can push directly to main (if explicitly requested)
+- Any other user → MUST use feature branch + PR workflow
+
+**User Request Translation**:
+- User says "commit to main" (non-bobmatnyc) → PM: "Creating feature branch workflow instead"
+- User says "push to main" (non-bobmatnyc) → PM: "Branch protection requires PR workflow"
+- User says "merge to main" (non-bobmatnyc) → PM: "Creating PR for review"
+
+**Error Prevention**: PM proactively guides non-privileged users to correct workflow (don't wait for git errors).
+
 ### When User Requests PRs
 
 - Single ticket → One PR (no question needed)
@@ -1301,6 +1343,45 @@ PM: "I notice this is a FastAPI project. Would you like me to run auto-configura
 - User choice: Always respect if user prefers manual configuration
 - Preview first: Recommend --preview flag for first-time users
 
+## Proactive Architecture Improvement Suggestions
+
+**When agents report opportunities, PM suggests improvements to user.**
+
+### Trigger Conditions
+- Research/Code Analyzer reports code smells, anti-patterns, or structural issues
+- Engineer reports implementation difficulty due to architecture
+- Repeated similar issues suggest systemic problems
+
+### Suggestion Format
+```
+💡 Architecture Suggestion
+
+[Agent] identified [specific issue].
+
+Consider: [improvement] — [one-line benefit]
+Effort: [small/medium/large]
+
+Want me to implement this?
+```
+
+### Example
+```
+💡 Architecture Suggestion
+
+Research found database queries scattered across 12 files.
+
+Consider: Repository pattern — centralized queries, easier testing
+Effort: Medium
+
+Want me to implement this?
+```
+
+### Rules
+- Max 1-2 suggestions per session
+- Don't repeat declined suggestions
+- If accepted: delegate to Research → Code Analyzer → Engineer (standard workflow)
+- Be specific, not vague ("Repository pattern" not "better architecture")
+
 ## PM Examples: Correct Delegation Patterns
 
 ### Example 1: Bug Fixing Workflow
@@ -1418,6 +1499,10 @@ When the user mentions ticket IDs or says "ticket", "issue", "create ticket", de
 
 When the user requests "stacked PRs" or "dependent PRs", delegate to version-control agent with stacked PR parameters.
 
+When the user says "commit to main" or "push to main", check git user email first. If not bobmatnyc@users.noreply.github.com, route to feature branch + PR workflow instead.
+
+When the user mentions "skill", "add skill", "create skill", "improve skill", "recommend skills", or asks about "project stack", "technologies", "frameworks", delegate to mpm-skills-manager agent for all skill operations and technology analysis.
+
 ## Session Resume Capability
 
 Git history provides session continuity. PM can resume work by inspecting git history.

claude_mpm/agents/agent_loader.py

@@ -45,30 +45,13 @@ from claude_mpm.core.logging_utils import get_logger
 
 # Import modular components
 from claude_mpm.core.unified_agent_registry import AgentTier, get_agent_registry
-from claude_mpm.core.unified_paths import get_path_manager
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 
 from ..core.agent_name_normalizer import AgentNameNormalizer
 
-# Lazy import for base_agent_loader to reduce initialization overhead
-# base_agent_loader adds ~500ms to import time and is only needed when
-# actually loading agent prompts, not during module import
-# from .base_agent_loader import prepend_base_instructions
-
 logger = get_logger(__name__)
 
 
-def _get_prepend_base_instructions():
-    """Lazy loader for prepend_base_instructions function.
-
-    This defers the import of base_agent_loader until it's actually needed,
-    reducing hook handler initialization time by ~500ms.
-    """
-    from .base_agent_loader import prepend_base_instructions
-
-    return prepend_base_instructions
-
-
 class ModelType(str, Enum):
     """Claude model types for agent configuration."""
 
@@ -102,33 +85,27 @@ def _get_agent_templates_dirs() -> Dict[AgentTier, Optional[Path]]:
     """
     Get directories containing agent JSON files across all tiers.
 
-    Returns a dictionary mapping tiers to their agent directories:
-    - PROJECT: .claude-mpm/agents in the current working directory
-    - USER: ~/.claude-mpm/agents
-    - SYSTEM: Built-in agents relative to this module
+    SIMPLIFIED ARCHITECTURE:
+    - SOURCE: ~/.claude-mpm/cache/remote-agents/ (git cache from GitHub)
+    - DEPLOYMENT: .claude/agents/ (project-level Claude Code discovery)
 
-    WHY: We support multiple tiers to allow project-specific customization
-    while maintaining backward compatibility with system agents.
+    This function is kept for backward compatibility but the tier-based
+    system is being phased out in favor of the simplified architecture.
 
     Returns:
         Dict mapping AgentTier to Path (or None if not available)
     """
     dirs = {}
 
-    # PROJECT tier - ALWAYS check current working directory dynamically
-    # This ensures we pick up project agents even if CWD changes
-    project_dir = Path.cwd() / get_path_manager().CONFIG_DIR / "agents"
+    # PROJECT tier - Deprecated in simplified architecture
+    # Agents are now deployed to .claude/agents/ directly
+    project_dir = Path.cwd() / ".claude" / "agents"
     if project_dir.exists():
         dirs[AgentTier.PROJECT] = project_dir
         logger.debug(f"Found PROJECT agents at: {project_dir}")
 
-    # USER tier - check user home directory
-    user_config_dir = get_path_manager().get_user_config_dir()
-    if user_config_dir:
-        user_agents_dir = user_config_dir / "agents"
-        if user_agents_dir.exists():
-            dirs[AgentTier.USER] = user_agents_dir
-            logger.debug(f"Found USER agents at: {user_agents_dir}")
+    # USER tier - Deprecated in simplified architecture
+    # (Kept for backward compatibility but not actively used)
 
     # SYSTEM tier - built-in agents
     system_dir = Path(__file__).parent / "templates"
@@ -255,9 +232,7 @@ class AgentLoader:
             logger.warning(f"Agent '{agent_id}' has no instructions")
             return None
 
-        # Prepend base instructions (lazy load to avoid import overhead)
-        prepend_base_instructions = _get_prepend_base_instructions()
-        return prepend_base_instructions(instructions)
+        return instructions
 
     def get_agent_metadata(self, agent_id: str) -> Optional[Dict[str, Any]]:
         """
@@ -803,16 +778,10 @@ def get_agent_prompt(
         model_metadata = f"\n<!-- Model Selection: {selected_model} (Complexity: {model_config.get('complexity_level', 'UNKNOWN')}) -->\n"
         prompt = model_metadata + prompt
 
-    # Prepend base instructions with dynamic template based on complexity
-    # The base instructions provide common guidelines all agents should follow
-    complexity_score = model_config.get("complexity_score", 50) if model_config else 50
-    prepend_base_instructions = _get_prepend_base_instructions()
-    final_prompt = prepend_base_instructions(prompt, complexity_score=complexity_score)
-
     # Return format based on caller's needs
     if return_model_info:
-        return final_prompt, selected_model, model_config
-    return final_prompt
+        return prompt, selected_model, model_config
+    return prompt
 
 
 # Legacy hardcoded agent functions removed - use get_agent_prompt(agent_id) instead

claude_mpm/agents/templates/circuit-breakers.md

@@ -1154,6 +1154,139 @@ Before delegating implementation, PM MUST verify:
 
 ---
 
+## Circuit Breaker #8: Skills Management Violation
+
+**Purpose**: Prevent PM from performing skill operations directly instead of delegating to mpm-skills-manager
+
+### Trigger Conditions
+
+**IF PM attempts ANY of the following:**
+
+#### Direct Skill Operations
+- PM creates SKILL.md files directly (using Write/Edit tools)
+- PM modifies manifest.json for skills
+- PM attempts to deploy skills without mpm-skills-manager
+- PM creates PRs to skills repository directly
+- PM recommends skills without technology detection
+- PM attempts skill validation or structure checks
+
+#### Missing Delegation Signals
+- User request contains skill keywords but PM doesn't delegate
+- PM attempts to handle "create skill", "add skill", "improve skill" requests directly
+- PM tries to analyze technology stack without mpm-skills-manager
+- PM bypasses skill workflow for skill-related operations
+
+### Violation Response
+
+**→ STOP IMMEDIATELY**
+
+**→ ERROR**: `"PM VIOLATION - Must delegate skill operations to mpm-skills-manager"`
+
+**→ REQUIRED ACTION**: Delegate ALL skill operations to mpm-skills-manager agent
+
+**→ VIOLATIONS TRACKED AND REPORTED**
+
+### Correct Delegation Pattern
+
+PM delegates ALL skill operations to mpm-skills-manager:
+- "I'll have mpm-skills-manager create the [technology] skill"
+- "I'll delegate skill recommendation to mpm-skills-manager"
+- "mpm-skills-manager will handle the PR for this skill improvement"
+- "I'll have mpm-skills-manager detect the project technology stack"
+
+### Why This Matters
+
+**mpm-skills-manager provides critical functionality:**
+- Technology stack detection from project files
+- Skill validation and structure enforcement
+- manifest.json integrity management
+- GitHub PR workflow integration for skill contributions
+- Skill versioning and lifecycle management
+
+**PM lacks skill management expertise:**
+- No access to skill validation tools
+- No knowledge of manifest.json structure requirements
+- No PR workflow integration for skills repository
+- Risk of creating malformed skills without validation
+
+### Examples
+
+#### ❌ VIOLATION Examples
+
+```
+# Violation: PM creating skill file directly
+User: "Create a FastAPI skill"
+PM: Write(file_path="skills/fastapi/SKILL.md", ...)  # ❌ VIOLATION
+
+# Violation: PM modifying manifest directly
+PM: Edit(file_path="manifest.json", ...)  # ❌ VIOLATION
+
+# Violation: PM creating PR to skills repository
+PM: Task(agent="version-control", task="Create PR to claude-code-skills")  # ❌ VIOLATION
+
+# Violation: PM recommending skills without detection
+User: "What skills do I need?"
+PM: "You need React and FastAPI skills"  # ❌ VIOLATION - no technology detection
+```
+
+#### ✅ CORRECT Examples
+
+```
+# Correct: Skill creation delegation
+User: "Create a FastAPI skill"
+PM: Task(agent="mpm-skills-manager", task="Create comprehensive skill for FastAPI framework")
+
+# Correct: Skill recommendation delegation
+User: "What skills do I need for this project?"
+PM: Task(agent="mpm-skills-manager", task="Detect project technology stack and recommend relevant skills")
+
+# Correct: Skill improvement delegation
+User: "The React skill is missing hooks patterns"
+PM: Task(agent="mpm-skills-manager", task="Improve React skill by adding hooks patterns section")
+
+# Correct: Technology detection delegation
+User: "What frameworks are we using?"
+PM: Task(agent="mpm-skills-manager", task="Analyze project files and identify all frameworks and technologies")
+```
+
+### Enforcement Levels
+
+| Violation Count | Response | Action |
+|----------------|----------|--------|
+| **Violation #1** | ⚠️ WARNING | PM reminded to delegate skill operations to mpm-skills-manager |
+| **Violation #2** | 🚨 ESCALATION | PM must STOP and delegate to mpm-skills-manager immediately |
+| **Violation #3+** | ❌ FAILURE | Session marked as non-compliant, skill operations blocked |
+
+### Skill-Related Trigger Keywords
+
+**PM should detect these keywords and delegate to mpm-skills-manager:**
+
+**Skill Operations**:
+- "skill", "add skill", "create skill", "new skill"
+- "improve skill", "update skill", "skill is missing"
+- "deploy skill", "install skill", "remove skill"
+
+**Technology Detection**:
+- "detect stack", "analyze technologies", "what frameworks"
+- "project stack", "identify dependencies"
+- "what are we using", "technology analysis"
+
+**Skill Discovery**:
+- "recommend skills", "suggest skills", "what skills"
+- "skills for [framework]", "need skills for"
+
+### Integration with PM Workflow
+
+**When PM sees skill keywords → IMMEDIATELY delegate to mpm-skills-manager**
+
+**No exceptions for:**
+- "Simple" skill operations (all require validation)
+- "Quick" manifest updates (integrity critical)
+- "Minor" skill improvements (still need PR workflow)
+- Technology stack "guesses" (detection required)
+
+---
+
 ## Violation Tracking Format
 
 When PM attempts forbidden action, use this format:
@@ -1173,6 +1306,7 @@ When PM attempts forbidden action, use this format:
 | **FILE TRACKING** | PM didn't track new files | `PM ended session without tracking 2 new files` |
 | **TICKETING** | PM used ticketing tools directly | `PM used mcp-ticketer tool - Must delegate to ticketing` |
 | **RESEARCH GATE** | PM skipped Research for ambiguous task | `PM delegated to Engineer without Research - Must delegate to Research first` |
+| **SKILLS** | PM attempted skill operations directly | `PM created SKILL.md directly - Must delegate to mpm-skills-manager` |
 
 ---
 
@@ -1207,6 +1341,8 @@ Violations are tracked and escalated based on severity:
 - "Is this task ambiguous? Should I delegate to Research BEFORE Engineer?"
 - "Did Research validate the approach before implementation?"
 - "Does my delegation include Research context?"
+- "Is this a skill-related request? Should I delegate to mpm-skills-manager?"
+- "Am I about to create/modify skill files directly instead of delegating?"
 - "Did any agent create a new file during this session?"
 - "Have I run `git status` to check for untracked files?"
 - "Are all trackable files staged in git?"
@@ -1232,6 +1368,7 @@ Violations are tracked and escalated based on severity:
 - [ ] No ticketing tool misuse (Circuit Breaker #6)
 - [ ] **Research delegated for all ambiguous tasks** ← Circuit Breaker #7
 - [ ] **Implementation references Research findings** ← Circuit Breaker #7
+- [ ] **All skill operations delegated to mpm-skills-manager** ← Circuit Breaker #8
 - [ ] Unresolved issues documented
 - [ ] Violation report provided (if violations occurred)
 
@@ -1241,7 +1378,7 @@ Violations are tracked and escalated based on severity:
 
 ## The PM Mantra
 
-**"I don't investigate. I don't implement. I don't assert. I research-first for ambiguous tasks. I delegate, verify, and track files."**
+**"I don't investigate. I don't implement. I don't assert. I research-first for ambiguous tasks. I delegate skills to mpm-skills-manager. I delegate, verify, and track files."**
 
 ---
 

claude_mpm/cli/__main__.py

@@ -1,3 +1,7 @@
+# Copyright (c) 2024-2025 Bob Matsuoka
+# Licensed under the Elastic License 2.0
+# See LICENSE file in the project root for full license information.
+
 """
 Entry point for executing the CLI module with python -m claude_mpm.cli.
 

claude_mpm/cli/commands/agent_state_manager.py

@@ -152,7 +152,7 @@ class SimpleAgentManager:
 
                     # Get metadata for display info
                     metadata = template_data.get("metadata", {})
-                    metadata.get("name", agent_id)
+                    display_name = metadata.get("name", agent_id)
                     description = metadata.get(
                         "description", "No description available"
                     )
@@ -182,9 +182,10 @@ class SimpleAgentManager:
                         dependencies=display_tools,
                     )
 
-                    # Set deployment status
+                    # Set deployment status and display name
                     agent_config.is_deployed = is_deployed
                     agent_config.source_type = "local"
+                    agent_config.display_name = display_name
 
                     agents.append(agent_config)
 
@@ -235,7 +236,7 @@ class SimpleAgentManager:
                 # Create AgentConfig with source information
                 # Store full agent_dict for later use in deployment
                 agent_config = AgentConfig(
-                    name=agent_id,  # Use agent_id as name for uniqueness
+                    name=name,  # Use display name for UI
                     description=(
                         f"[{category}] {description[:60]}..."
                         if len(description) > 60
@@ -248,6 +249,7 @@ class SimpleAgentManager:
                 agent_config.source_type = "remote"
                 agent_config.is_deployed = is_deployed
                 agent_config.display_name = name
+                agent_config.agent_id = agent_id  # Store technical ID for reference
                 agent_config.full_agent_id = agent_id
                 agent_config.source_dict = agent_dict  # Store full dict for deployment
 
@@ -272,9 +274,9 @@ class SimpleAgentManager:
             True if agent is deployed, False otherwise
         """
         # Check virtual deployment state (primary method)
+        # Only checking project-level deployment in simplified architecture
         deployment_state_paths = [
             Path.cwd() / ".claude" / "agents" / ".mpm_deployment_state",
-            Path.home() / ".claude" / "agents" / ".mpm_deployment_state",
         ]
 
         for state_path in deployment_state_paths:
@@ -319,8 +321,8 @@ class SimpleAgentManager:
             leaf_name = agent_id.split("/")[-1]
             agent_file_names.append(f"{leaf_name}.md")
 
-        # Check .claude-mpm/agents/ directory (project level)
-        project_agents_dir = Path.cwd() / ".claude-mpm" / "agents"
+        # Check .claude/agents/ directory (project deployment)
+        project_agents_dir = Path.cwd() / ".claude" / "agents"
         if project_agents_dir.exists():
             for agent_file_name in agent_file_names:
                 agent_file = project_agents_dir / agent_file_name
@@ -330,15 +332,4 @@ class SimpleAgentManager:
                     )
                     return True
 
-        # Check ~/.claude/agents/ directory (user level)
-        user_agents_dir = Path.home() / ".claude" / "agents"
-        if user_agents_dir.exists():
-            for agent_file_name in agent_file_names:
-                agent_file = user_agents_dir / agent_file_name
-                if agent_file.exists():
-                    self.logger.debug(
-                        f"Agent {agent_id} found as physical file: {agent_file}"
-                    )
-                    return True
-
         return False