claude-mpm 4.15.6__py3-none-any.whl → 4.21.3__py3-none-any.whl

claude_mpm/services/version_service.py

@@ -9,7 +9,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 """
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from claude_mpm.config.paths import paths
 from claude_mpm.core.base_service import BaseService
@@ -274,3 +274,106 @@ class VersionService(BaseService, VersionServiceInterface):
             "message": "Update checking not implemented",
             "checked_at": None,
         }
+
+    def get_agents_versions(self) -> Dict[str, List[Dict[str, str]]]:
+        """Get all agents grouped by tier with versions.
+
+        Returns:
+            Dict with keys: system, user, project
+            Each value is list of agent dicts with: name, version, id
+        """
+        from claude_mpm.core.unified_agent_registry import get_agent_registry
+
+        agents_by_tier = {"system": [], "user": [], "project": []}
+
+        try:
+            registry = get_agent_registry()
+            all_agents = registry.list_agents()
+
+            for agent in all_agents:
+                agent_info = {
+                    "name": agent.name,
+                    "version": agent.version,
+                    "id": agent.name,  # Use name as ID since agent_id doesn't exist
+                }
+                tier = (
+                    agent.tier.value
+                    if hasattr(agent.tier, "value")
+                    else str(agent.tier)
+                )
+                if tier in agents_by_tier:
+                    agents_by_tier[tier].append(agent_info)
+                else:
+                    agents_by_tier["system"].append(agent_info)
+
+            # Sort each tier alphabetically by name
+            for tier, agents in agents_by_tier.items():
+                agents.sort(key=lambda x: x["name"])
+
+        except Exception as e:
+            self.logger.error(f"Failed to get agent versions: {e}")
+
+        return agents_by_tier
+
+    def get_skills_versions(self) -> Dict[str, List[Dict[str, str]]]:
+        """Get all skills grouped by source with versions.
+
+        Returns:
+            Dict with keys: bundled, user, project
+            Each value is list of skill dicts with: name, version, description
+        """
+        from claude_mpm.skills.registry import get_registry
+
+        skills_by_source = {"bundled": [], "user": [], "project": []}
+
+        try:
+            registry = get_registry()
+
+            for skill in registry.list_skills():
+                skill_info = {
+                    "name": skill.name,
+                    "version": skill.version,
+                    "description": (
+                        skill.description[:60] + "..."
+                        if len(skill.description) > 60
+                        else skill.description
+                    ),
+                }
+                source = skill.source if skill.source in skills_by_source else "bundled"
+                skills_by_source[source].append(skill_info)
+
+            # Sort each source alphabetically by name
+            for source, skills in skills_by_source.items():
+                skills.sort(key=lambda x: x["name"])
+
+        except Exception as e:
+            self.logger.error(f"Failed to get skill versions: {e}")
+
+        return skills_by_source
+
+    def get_version_summary(self) -> Dict:
+        """Get complete version summary.
+
+        Returns:
+            Dict with project_version, build, agents, skills, and counts
+        """
+        agents = self.get_agents_versions()
+        skills = self.get_skills_versions()
+        build = self.get_build_number()
+
+        return {
+            "project_version": self.get_base_version(),
+            "build": build,
+            "agents": agents,
+            "skills": skills,
+            "counts": {
+                "agents_total": sum(len(v) for v in agents.values()),
+                "agents_system": len(agents.get("system", [])),
+                "agents_user": len(agents.get("user", [])),
+                "agents_project": len(agents.get("project", [])),
+                "skills_total": sum(len(v) for v in skills.values()),
+                "skills_bundled": len(skills.get("bundled", [])),
+                "skills_user": len(skills.get("user", [])),
+                "skills_project": len(skills.get("project", [])),
+            },
+        }

claude_mpm/skills/__init__.py

@@ -8,14 +8,35 @@ Skills can be:
 - Bundled with MPM (in skills/bundled/)
 - User-installed (in ~/.claude/skills/)
 - Project-specific (in .claude/skills/)
+
+New Skills Integration System:
+- SkillsService: Core service for skill management
+- AgentSkillsInjector: Dynamic skill injection into agent templates
+- SkillsRegistry: Helper class for registry operations
+
+Legacy System (maintained for compatibility):
+- Skill: Dataclass for skill representation
+- SkillManager: Legacy skill manager
+- get_registry: Legacy registry access
 """
 
+# New Skills Integration System
+from .agent_skills_injector import AgentSkillsInjector
+
+# Legacy System (maintained for compatibility)
 from .registry import Skill, SkillsRegistry, get_registry
 from .skill_manager import SkillManager
+from .skills_registry import SkillsRegistry as SkillsRegistryHelper
+from .skills_service import SkillsService
 
 __all__ = [
+    "AgentSkillsInjector",
+    # Legacy System
     "Skill",
     "SkillManager",
     "SkillsRegistry",
+    "SkillsRegistryHelper",
+    # New Skills Integration System
+    "SkillsService",
     "get_registry",
 ]

claude_mpm/skills/agent_skills_injector.py

@@ -0,0 +1,324 @@
+"""Agent Skills Injector - Dynamically inject skills into agent templates.
+
+This module implements dynamic skill injection into agent templates and frontmatter.
+It reads skill assignments from the registry and enhances agent definitions at runtime
+without modifying template files on disk.
+
+Design Principles:
+- Dynamic injection (no template file modifications)
+- Registry is source of truth (not templates)
+- Return enhanced templates as dicts
+- Generate clean YAML frontmatter
+- Inject skills docs after frontmatter
+
+References:
+- Design: docs/design/claude-mpm-skills-integration-design.md (lines 632-711)
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+import yaml
+
+from claude_mpm.core.mixins import LoggerMixin
+
+from .skills_service import SkillsService
+
+
+class AgentSkillsInjector(LoggerMixin):
+    """Injects skill references into agent templates and frontmatter.
+
+    This class provides methods to:
+    - Enhance agent JSON templates with skills field
+    - Generate YAML frontmatter with skills included
+    - Inject skills documentation into agent markdown content
+
+    The injector reads from the skills registry (not template files) to determine
+    which skills should be assigned to each agent, then dynamically injects this
+    information when agents are loaded.
+
+    Example:
+        >>> service = SkillsService()
+        >>> injector = AgentSkillsInjector(service)
+        >>>
+        >>> # Enhance template
+        >>> template = injector.enhance_agent_template(Path('engineer.json'))
+        >>> print(template['skills'])  # {'required': [...], 'optional': [...]}
+        >>>
+        >>> # Generate frontmatter
+        >>> frontmatter = injector.generate_frontmatter_with_skills(template)
+        >>> print(frontmatter)  # ---\nname: engineer\nskills:\n  - ...\n---
+    """
+
+    def __init__(self, skills_service: SkillsService) -> None:
+        """Initialize Agent Skills Injector.
+
+        Args:
+            skills_service: SkillsService instance for accessing registry
+        """
+        super().__init__()
+        self.skills_service: SkillsService = skills_service
+
+    def enhance_agent_template(self, template_path: Path) -> Dict[str, Any]:
+        """Add skills field to agent template JSON.
+
+        Reads an agent JSON template, determines which skills should be assigned
+        from the registry, and adds a 'skills' field to the template dict.
+
+        The skills field structure:
+        {
+            "required": [skill1, skill2],  # First 2 skills
+            "optional": [skill3, skill4],  # Remaining skills
+            "auto_load": true
+        }
+
+        Args:
+            template_path: Path to agent JSON template file
+
+        Returns:
+            Enhanced template dict with 'skills' field added
+
+        Example:
+            >>> template = injector.enhance_agent_template(
+            ...     Path('src/claude_mpm/agents/templates/engineer.json')
+            ... )
+            >>> assert 'skills' in template
+            >>> assert 'required' in template['skills']
+        """
+        try:
+            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")
+        if not agent_id:
+            self.logger.error(f"Template missing agent_id: {template_path}")
+            return template
+
+        # Get skills for this agent from registry
+        skills = self.skills_service.get_skills_for_agent(agent_id)
+
+        if skills:
+            # Split into required (first 2) and optional (rest)
+            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,
+            }
+
+            self.logger.info(f"Enhanced {agent_id} with {len(skills)} skills")
+        else:
+            self.logger.debug(f"No skills assigned to {agent_id}")
+
+        return template
+
+    def generate_frontmatter_with_skills(self, agent_config: Dict[str, Any]) -> str:
+        """Generate YAML frontmatter including skills field.
+
+        Creates clean YAML frontmatter for agent markdown files, including:
+        - name: Agent ID
+        - description: Agent description
+        - version: Agent version
+        - tools: List of tools
+        - skills: List of all skills (required + optional)
+
+        Args:
+            agent_config: Agent configuration dict (from JSON template)
+
+        Returns:
+            YAML frontmatter string with delimiters (---\n...yaml...\n---)
+
+        Example:
+            >>> config = {
+            ...     'agent_id': 'engineer',
+            ...     'metadata': {'description': 'Software development'},
+            ...     'version': '2.1.0',
+            ...     'capabilities': {'tools': ['Read', 'Write']},
+            ...     'skills': {
+            ...         'required': ['test-driven-development'],
+            ...         'optional': ['code-review']
+            ...     }
+            ... }
+            >>> frontmatter = injector.generate_frontmatter_with_skills(config)
+            >>> assert 'skills:' in frontmatter
+            >>> assert 'test-driven-development' in frontmatter
+        """
+        # 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", []),
+        }
+
+        # Add skills if present
+        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
+
+        # Convert to YAML with clean formatting
+        yaml_str = yaml.dump(
+            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:
+        """Inject skills documentation reference into agent instructions.
+
+        Adds a "## Available Skills" section after the YAML frontmatter that
+        lists all skills available to this agent. This section informs the agent
+        about its skills and explains that Claude will auto-load them when relevant.
+
+        Args:
+            agent_content: Original agent markdown content (with frontmatter)
+            skills: List of skill names to document
+
+        Returns:
+            Agent content with skills section injected after frontmatter
+
+        Example:
+            >>> content = '''---
+            ... name: engineer
+            ... ---
+            ...
+            ... # Software Engineer Agent
+            ...
+            ... You are a software development specialist...
+            ... '''
+            >>> skills = ['test-driven-development', 'systematic-debugging']
+            >>> enhanced = injector.inject_skills_documentation(content, skills)
+            >>> assert '## Available Skills' in enhanced
+            >>> assert 'test-driven-development' in enhanced
+        """
+        if not skills:
+            return agent_content
+
+        # Build skills section
+        skills_section = "\n\n## Available Skills\n\n"
+        skills_section += "You have access to the following skills that will be loaded when relevant:\n\n"
+
+        for skill in skills:
+            skills_section += f"- **{skill}**: Automatically activated when needed\n"
+
+        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 len(parts) >= 3:
+                # Reconstruct: frontmatter + skills section + rest
+                return f"{parts[0]}---{parts[1]}---{skills_section}{parts[2]}"
+
+        # If no frontmatter, append at end
+        return agent_content + skills_section
+
+    def enhance_agent_with_skills(
+        self, agent_id: str, template_content: str
+    ) -> Dict[str, Any]:
+        """Convenience method to fully enhance an agent with skills.
+
+        Combines all enhancement steps:
+        1. Gets skills from registry
+        2. Generates enhanced frontmatter
+        3. Injects skills documentation
+
+        Args:
+            agent_id: Agent identifier
+            template_content: Original agent template markdown content
+
+        Returns:
+            Dict containing:
+            - agent_id: Agent identifier
+            - skills: List of skill names
+            - frontmatter: YAML frontmatter with skills
+            - content: Full enhanced markdown content
+
+        Example:
+            >>> result = injector.enhance_agent_with_skills(
+            ...     'engineer',
+            ...     '---\nname: engineer\n---\n\n# Engineer\n...'
+            ... )
+            >>> print(result['skills'])  # ['test-driven-development', ...]
+            >>> print(result['content'])  # Enhanced markdown with skills section
+        """
+        # Get skills for agent
+        skills = self.skills_service.get_skills_for_agent(agent_id)
+
+        if not skills:
+            return {
+                "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 [],
+            },
+        }
+
+        # Generate frontmatter
+        frontmatter = self.generate_frontmatter_with_skills(agent_config)
+
+        # Inject skills documentation
+        enhanced_content = self.inject_skills_documentation(template_content, skills)
+
+        return {
+            "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]]:
+        """Get skill references with metadata for an agent.
+
+        Returns detailed information about each skill assigned to an agent,
+        including name, category, and description from the registry.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            List of dicts containing skill reference information:
+            - name: Skill name
+            - category: Skill category (from metadata)
+            - description: Brief description
+
+        Example:
+            >>> refs = injector.get_skills_references_for_agent('engineer')
+            >>> for ref in refs:
+            ...     print(f"{ref['name']}: {ref['description']}")
+        """
+        skills = self.skills_service.get_skills_for_agent(agent_id)
+        registry = self.skills_service.registry
+
+        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", ""),
+                }
+            )
+
+        return skill_refs

claude_mpm/skills/bundled/LICENSE_ATTRIBUTIONS.md

@@ -0,0 +1,79 @@
+# License Attributions for Bundled Skills
+
+This document provides license information and attributions for all skills bundled with Claude MPM.
+
+---
+
+## Summary
+
+- **Total Skills**: 15
+- **Unique Licenses**: 3
+
+  - **UNKNOWN**: 8 skill(s)
+  - **Complete terms in LICENSE.txt**: 5 skill(s)
+  - **MIT**: 2 skill(s)
+
+---
+
+## Complete terms in LICENSE.txt Licensed Skills
+
+| Skill Name | Author | Category | Description | Source |
+|------------|--------|----------|-------------|--------|
+| artifacts-builder | Unknown | main | Suite of tools for creating elaborate, multi-component claud... | N/A |
+| internal-comms | Unknown | main | A set of resources to help me write all kinds of internal co... | N/A |
+| mcp-builder | Unknown | main | Guide for creating high-quality MCP (Model Context Protocol)... | N/A |
+| skill-creator | Unknown | main | Guide for creating effective skills. This skill should be us... | N/A |
+| webapp-testing | Unknown | testing | Toolkit for interacting with and testing local web applicati... | N/A |
+
+---
+
+## MIT Licensed Skills
+
+| Skill Name | Author | Category | Description | Source |
+|------------|--------|----------|-------------|--------|
+| systematic-debugging | Jesse Vincent | debugging | Methodical debugging instead of random changes | [Link](https://github.com/obra/superpowers-skills/tree/main/skills/debugging/systematic-debugging) |
+| test-driven-development | Jesse Vincent | testing | Write the test first, watch it fail, write minimal code to p... | [Link](https://github.com/obra/superpowers-skills/tree/main/skills/testing/test-driven-development) |
+
+---
+
+## UNKNOWN Licensed Skills
+
+| Skill Name | Author | Category | Description | Source |
+|------------|--------|----------|-------------|--------|
+| Brainstorming Ideas Into Designs | Unknown | collaboration | Interactive idea refinement using Socratic method to develop... | N/A |
+| Condition-Based Waiting | Unknown | testing | Replace arbitrary timeouts with condition polling for reliab... | N/A |
+| Dispatching Parallel Agents | Unknown | collaboration | Use multiple Claude agents to investigate and fix independen... | N/A |
+| Requesting Code Review | Unknown | collaboration | Dispatch code-reviewer subagent to review implementation aga... | N/A |
+| Root Cause Tracing | Unknown | debugging | Systematically trace bugs backward through call stack to fin... | N/A |
+| Testing Anti-Patterns | Unknown | testing | Never test mock behavior. Never add test-only methods to pro... | N/A |
+| Verification Before Completion | Unknown | debugging | Run verification commands and confirm output before claiming... | N/A |
+| Writing Plans | Unknown | collaboration | Create detailed implementation plans with bite-sized tasks f... | N/A |
+
+---
+
+## ⚠️ Missing License Information
+
+The following skills do not have license information in their SKILL.md:
+
+- Brainstorming Ideas Into Designs
+- Condition-Based Waiting
+- Dispatching Parallel Agents
+- Requesting Code Review
+- Root Cause Tracing
+- Testing Anti-Patterns
+- Verification Before Completion
+- Writing Plans
+
+---
+
+## How to Update
+
+To update this file, run:
+
+```bash
+python scripts/generate_license_attributions.py
+```
+
+---
+
+*Generated automatically by Claude MPM*