claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__py3-none-any.whl

claude_mpm/skills/agent_skills_injector.py

@@ -87,13 +87,13 @@ class AgentSkillsInjector(LoggerMixin):
             >>> assert 'required' in template['skills']
         """
         try:
-            with open(template_path, encoding='utf-8') as f:
+            with open(template_path, encoding="utf-8") as f:
                 template = json.load(f)
         except (OSError, json.JSONDecodeError) as e:
             self.logger.error(f"Failed to load template {template_path}: {e}")
             raise ValueError(f"Cannot load template {template_path}") from e
 
-        agent_id = template.get('agent_id')
+        agent_id = template.get("agent_id")
         if not agent_id:
             self.logger.error(f"Template missing agent_id: {template_path}")
             return template
@@ -106,10 +106,10 @@ class AgentSkillsInjector(LoggerMixin):
             required = skills[:2] if len(skills) > 2 else skills
             optional = skills[2:] if len(skills) > 2 else []
 
-            template['skills'] = {
-                'required': required,
-                'optional': optional,
-                'auto_load': True
+            template["skills"] = {
+                "required": required,
+                "optional": optional,
+                "auto_load": True,
             }
 
             self.logger.info(f"Enhanced {agent_id} with {len(skills)} skills")
@@ -151,37 +151,30 @@ class AgentSkillsInjector(LoggerMixin):
         """
         # Build frontmatter dict
         frontmatter = {
-            'name': agent_config.get('agent_id'),
-            'description': agent_config.get('metadata', {}).get('description'),
-            'version': agent_config.get('version'),
-            'tools': agent_config.get('capabilities', {}).get('tools', [])
+            "name": agent_config.get("agent_id"),
+            "description": agent_config.get("metadata", {}).get("description"),
+            "version": agent_config.get("version"),
+            "tools": agent_config.get("capabilities", {}).get("tools", []),
         }
 
         # Add skills if present
-        if 'skills' in agent_config:
-            skills_config = agent_config['skills']
-            required = skills_config.get('required', [])
-            optional = skills_config.get('optional', [])
+        if "skills" in agent_config:
+            skills_config = agent_config["skills"]
+            required = skills_config.get("required", [])
+            optional = skills_config.get("optional", [])
             all_skills = required + optional
 
             if all_skills:
-                frontmatter['skills'] = all_skills
+                frontmatter["skills"] = all_skills
 
         # Convert to YAML with clean formatting
         yaml_str = yaml.dump(
-            frontmatter,
-            default_flow_style=False,
-            sort_keys=False,
-            allow_unicode=True
+            frontmatter, default_flow_style=False, sort_keys=False, allow_unicode=True
         )
 
         return f"---\n{yaml_str}---\n"
 
-    def inject_skills_documentation(
-        self,
-        agent_content: str,
-        skills: List[str]
-    ) -> str:
+    def inject_skills_documentation(self, agent_content: str, skills: List[str]) -> str:
         """Inject skills documentation reference into agent instructions.
 
         Adds a "## Available Skills" section after the YAML frontmatter that
@@ -222,8 +215,8 @@ class AgentSkillsInjector(LoggerMixin):
         skills_section += "\nClaude will automatically read these skills when your task matches their descriptions.\n"
 
         # Insert after frontmatter
-        if '---' in agent_content:
-            parts = agent_content.split('---', 2)
+        if "---" in agent_content:
+            parts = agent_content.split("---", 2)
             if len(parts) >= 3:
                 # Reconstruct: frontmatter + skills section + rest
                 return f"{parts[0]}---{parts[1]}---{skills_section}{parts[2]}"
@@ -232,9 +225,7 @@ class AgentSkillsInjector(LoggerMixin):
         return agent_content + skills_section
 
     def enhance_agent_with_skills(
-        self,
-        agent_id: str,
-        template_content: str
+        self, agent_id: str, template_content: str
     ) -> Dict[str, Any]:
         """Convenience method to fully enhance an agent with skills.
 
@@ -267,19 +258,19 @@ class AgentSkillsInjector(LoggerMixin):
 
         if not skills:
             return {
-                'agent_id': agent_id,
-                'skills': [],
-                'frontmatter': '',
-                'content': template_content
+                "agent_id": agent_id,
+                "skills": [],
+                "frontmatter": "",
+                "content": template_content,
             }
 
         # Create config dict for frontmatter generation
         agent_config = {
-            'agent_id': agent_id,
-            'skills': {
-                'required': skills[:2] if len(skills) > 2 else skills,
-                'optional': skills[2:] if len(skills) > 2 else []
-            }
+            "agent_id": agent_id,
+            "skills": {
+                "required": skills[:2] if len(skills) > 2 else skills,
+                "optional": skills[2:] if len(skills) > 2 else [],
+            },
         }
 
         # Generate frontmatter
@@ -289,10 +280,10 @@ class AgentSkillsInjector(LoggerMixin):
         enhanced_content = self.inject_skills_documentation(template_content, skills)
 
         return {
-            'agent_id': agent_id,
-            'skills': skills,
-            'frontmatter': frontmatter,
-            'content': enhanced_content
+            "agent_id": agent_id,
+            "skills": skills,
+            "frontmatter": frontmatter,
+            "content": enhanced_content,
         }
 
     def get_skills_references_for_agent(self, agent_id: str) -> List[Dict[str, str]]:
@@ -320,12 +311,14 @@ class AgentSkillsInjector(LoggerMixin):
 
         skill_refs = []
         for skill_name in skills:
-            metadata = registry.get('skills_metadata', {}).get(skill_name, {})
-
-            skill_refs.append({
-                'name': skill_name,
-                'category': metadata.get('category', 'unknown'),
-                'description': metadata.get('description', '')
-            })
+            metadata = registry.get("skills_metadata", {}).get(skill_name, {})
+
+            skill_refs.append(
+                {
+                    "name": skill_name,
+                    "category": metadata.get("category", "unknown"),
+                    "description": metadata.get("description", ""),
+                }
+            )
 
         return skill_refs

claude_mpm/skills/bundled/.gitkeep

@@ -0,0 +1,2 @@
+# This directory will contain bundled Claude Code skills
+# Skills will be organized by category subdirectories

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

@@ -3,6 +3,10 @@ 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

claude_mpm/skills/bundled/collaboration/dispatching-parallel-agents/SKILL.md

@@ -2,9 +2,17 @@
 name: Dispatching Parallel Agents
 description: Use multiple Claude agents to investigate and fix independent problems concurrently
 when_to_use: when facing 3+ independent failures that can be investigated without shared state or dependencies
-version: 1.1.0
-languages: all
-context: AI-assisted development (Claude Code or similar)
+version: 2.0.0
+progressive_disclosure:
+  entry_point:
+    summary: "Dispatch one agent per independent problem domain to solve multiple unrelated failures concurrently"
+    when_to_use: "When you have 3+ independent failures in different test files/subsystems with no shared state or dependencies"
+    quick_start: "1. Identify independent domains 2. Create focused agent tasks 3. Dispatch in parallel 4. Review summaries 5. Verify no conflicts and integrate"
+  references:
+    - coordination-patterns.md
+    - agent-prompts.md
+    - examples.md
+    - troubleshooting.md
 ---
 
 # Dispatching Parallel Agents
@@ -15,45 +23,52 @@ When you have multiple unrelated failures (different test files, different subsy
 
 **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
 
-## When to Use
-
-```dot
-digraph when_to_use {
-    "Multiple failures?" [shape=diamond];
-    "Are they independent?" [shape=diamond];
-    "Single agent investigates all" [shape=box];
-    "One agent per problem domain" [shape=box];
-    "Can they work in parallel?" [shape=diamond];
-    "Sequential agents" [shape=box];
-    "Parallel dispatch" [shape=box];
-
-    "Multiple failures?" -> "Are they independent?" [label="yes"];
-    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
-    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
-    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
-    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
-}
-```
+## When to Use This Skill
 
-**Use when:**
-- 3+ test files failing with different root causes
-- Multiple subsystems broken independently
-- Each problem can be understood without context from others
-- No shared state between investigations
+Activate this skill when you're facing:
+- **3+ test files failing** with different root causes
+- **Multiple subsystems broken** independently
+- **Each problem is self-contained** - can be understood without context from others
+- **No shared state** between investigations
+- **Clear domain boundaries** - fixing one won't affect others
 
 **Don't use when:**
 - Failures are related (fix one might fix others)
-- Need to understand full system state
-- Agents would interfere with each other
+- Need to understand full system state first
+- Agents would interfere with each other (editing same files)
+- Exploratory debugging (don't know what's broken yet)
+
+## The Iron Law
+
+```
+One agent, one problem domain, one clear outcome.
+Never overlap scopes. Never share state. Always integrate consciously.
+```
+
+## Core Principles
+
+### Independence is Key
+Problems must be truly independent - no shared files, no related root causes, no dependencies between fixes.
+
+### Focus Over Breadth
+Each agent gets narrow scope: one test file, one subsystem, one clear goal. Broad tasks lead to confusion.
+
+### Clear Output Required
+Every agent must return a summary: what was found, what was fixed, what changed. No silent fixes.
 
-## The Pattern
+### Conscious Integration
+Don't blindly merge agent work. Review summaries, check conflicts, run full suite, verify compatibility.
+
+## Quick Start
 
 ### 1. Identify Independent Domains
 
 Group failures by what's broken:
-- File A tests: Tool approval flow
-- File B tests: Batch completion behavior
-- File C tests: Abort functionality
+```
+File A tests: Tool approval flow
+File B tests: Batch completion behavior
+File C tests: Abort functionality
+```
 
 Each domain is independent - fixing tool approval doesn't affect abort tests.
 
@@ -65,6 +80,8 @@ Each agent gets:
 - **Constraints:** Don't change other code
 - **Expected output:** Summary of what you found and fixed
 
+**→** [agent-prompts.md](references/agent-prompts.md) for prompt templates and examples
+
 ### 3. Dispatch in Parallel
 
 ```typescript
@@ -75,110 +92,87 @@ Task("Fix tool-approval-race-conditions.test.ts failures")
 // All three run concurrently
 ```
 
+**→** [coordination-patterns.md](references/coordination-patterns.md) for dispatch strategies
+
 ### 4. Review and Integrate
 
 When agents return:
-- Read each summary
-- Verify fixes don't conflict
-- Run full test suite
-- Integrate all changes
-
-## Agent Prompt Structure
-
-Good agent prompts are:
-1. **Focused** - One clear problem domain
-2. **Self-contained** - All context needed to understand the problem
-3. **Specific about output** - What should the agent return?
-
-```markdown
-Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
-
-1. "should abort tool with partial output capture" - expects 'interrupted at' in message
-2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
-3. "should properly track pendingToolCount" - expects 3 results but gets 0
+- Read each summary - understand what changed
+- Verify fixes don't conflict - check for same file edits
+- Run full test suite - ensure compatibility
+- Spot check changes - agents can make systematic errors
 
-These are timing/race condition issues. Your task:
+**→** [troubleshooting.md](references/troubleshooting.md) for conflict resolution
 
-1. Read the test file and understand what each test verifies
-2. Identify root cause - timing issues or actual bugs?
-3. Fix by:
-   - Replacing arbitrary timeouts with event-based waiting
-   - Fixing bugs in abort implementation if found
-   - Adjusting test expectations if testing changed behavior
+## Decision Tree
 
-Do NOT just increase timeouts - find the real issue.
-
-Return: Summary of what you found and what you fixed.
+```
+Multiple failures?
+  └→ Are they independent?
+      ├→ NO (related) → Single agent investigates all
+      └→ YES → Can they work in parallel?
+          ├→ NO (shared state) → Sequential agents
+          └→ YES → Parallel dispatch ✓
 ```
 
-## Common Mistakes
-
-**❌ Too broad:** "Fix all the tests" - agent gets lost
-**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
-
-**❌ No context:** "Fix the race condition" - agent doesn't know where
-**✅ Context:** Paste the error messages and test names
-
-**❌ No constraints:** Agent might refactor everything
-**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
-
-**❌ Vague output:** "Fix it" - you don't know what changed
-**✅ Specific:** "Return summary of root cause and changes"
+## Key Benefits
 
-## When NOT to Use
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - N problems solved in time of 1
 
-**Related failures:** Fixing one might fix others - investigate together first
-**Need full context:** Understanding requires seeing entire system
-**Exploratory debugging:** You don't know what's broken yet
-**Shared state:** Agents would interfere (editing same files, using same resources)
+## Navigation
 
-## Real Example from Session
+### Pattern Reference
+- **[Coordination Patterns](references/coordination-patterns.md)** - Dispatch strategies, domain identification, integration workflows
 
-**Scenario:** 6 test failures across 3 files after major refactoring
+### Agent Management
+- **[Agent Prompts](references/agent-prompts.md)** - Prompt structure, templates, common mistakes, constraints
 
-**Failures:**
-- agent-tool-abort.test.ts: 3 failures (timing issues)
-- batch-completion-behavior.test.ts: 2 failures (tools not executing)
-- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+### Learning Resources
+- **[Examples](references/examples.md)** - Real-world scenarios, case studies, time savings analysis
 
-**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+### Problem Solving
+- **[Troubleshooting](references/troubleshooting.md)** - Conflict resolution, verification strategies, common pitfalls
 
-**Dispatch:**
-```
-Agent 1 → Fix agent-tool-abort.test.ts
-Agent 2 → Fix batch-completion-behavior.test.ts
-Agent 3 → Fix tool-approval-race-conditions.test.ts
-```
+### Related Skills
+- **[pm-workflow](../pm-workflow/)** - PM coordination and task management
+- **[test-driven-development](../../testing/test-driven-development/)** - TDD patterns that benefit from parallel fixing
+- **[verification-before-completion](../../productivity/verification-before-completion/)** - Integration verification
 
-**Results:**
-- Agent 1: Replaced timeouts with event-based waiting
-- Agent 2: Fixed event structure bug (threadId in wrong place)
-- Agent 3: Added wait for async tool execution to complete
+## Key Reminders
 
-**Integration:** All fixes independent, no conflicts, full suite green
+1. **Independence is mandatory** - Related failures need single-agent investigation
+2. **Focus beats breadth** - Narrow scope per agent prevents confusion
+3. **Always verify integration** - Don't blindly merge agent work
+4. **Clear outputs required** - Every agent returns summary of changes
+5. **Parallelization has overhead** - Only worth it for 3+ independent problems
 
-**Time saved:** 3 problems solved in parallel vs sequentially
+## Red Flags - STOP
 
-## Key Benefits
+**STOP immediately if:**
+- Agents are editing the same files (scope overlap)
+- Fixes from one agent break another's work (hidden dependencies)
+- You can't clearly separate problem domains (not independent)
+- Agents return no summary (can't verify changes)
+- Integration requires major refactoring (conflicts)
 
-1. **Parallelization** - Multiple investigations happen simultaneously
-2. **Focus** - Each agent has narrow scope, less context to track
-3. **Independence** - Agents don't interfere with each other
-4. **Speed** - 3 problems solved in time of 1
+**When in doubt:** Start with one agent, understand the landscape, then dispatch if truly independent.
 
-## Verification
+## Integration with Other Skills
 
-After agents return:
-1. **Review each summary** - Understand what changed
-2. **Check for conflicts** - Did agents edit same code?
-3. **Run full suite** - Verify all fixes work together
-4. **Spot check** - Agents can make systematic errors
+**Prerequisite:** Basic understanding of problem domains and test structure
+**Complementary:** [pm-workflow](../pm-workflow/) for coordinating multiple agents
+**Domain-specific:** Testing skills for understanding test failures
 
 ## Real-World Impact
 
 From debugging session (2025-10-03):
-- 6 failures across 3 files
-- 3 agents dispatched in parallel
-- All investigations completed concurrently
-- All fixes integrated successfully
-- Zero conflicts between agent changes
+- **6 failures** across 3 test files
+- **3 agents** dispatched in parallel
+- **All investigations** completed concurrently
+- **Zero conflicts** between agent changes
+- **Time saved:** 3 problems solved in parallel vs sequentially
+
+**→** [examples.md](references/examples.md) for detailed case study