claude-mpm 5.4.96__py3-none-any.whl → 5.6.17__py3-none-any.whl

claude_mpm/skills/registry.py

@@ -14,35 +14,144 @@ logger = get_logger(__name__)
 
 @dataclass
 class Skill:
-    """Represents a skill that can be used by agents."""
-
+    """Represents a skill that can be used by agents.
+
+    Supports agentskills.io specification with backward compatibility for legacy claude-mpm format.
+
+    Spec fields (agentskills.io):
+    - name: Required, 1-64 chars, lowercase alphanumeric + hyphens
+    - description: Required, 1-1024 chars
+    - license: Optional, license name or reference
+    - compatibility: Optional, max 500 chars, environment requirements
+    - metadata: Optional, key-value mapping for arbitrary data
+    - allowed_tools: Optional, list of pre-approved tools
+
+    Internal fields:
+    - path: Path to skill file
+    - content: Skill content (markdown)
+    - source: Origin of skill ('bundled', 'user', 'project', 'pm')
+    - version: Skill version (from metadata.version or top-level)
+    - skill_id: Internal ID (defaults to name)
+    - agent_types: Which agent types can use this skill
+    - updated_at: Last update timestamp (from metadata.updated)
+    - tags: Tags for discovery (from metadata.tags or top-level)
+
+    Claude-mpm extensions (preserved for backward compat):
+    - category: Skill category for organization
+    - toolchain: Associated toolchain (python, javascript, etc.)
+    - progressive_disclosure: Progressive disclosure configuration
+    - user_invocable: Whether skill can be manually invoked
+    """
+
+    # Core spec fields (agentskills.io)
     name: str
-    path: Path
-    content: str
-    source: str  # 'bundled', 'user', or 'project'
-
-    # Version tracking fields
-    version: str = "0.1.0"
-    skill_id: str = ""  # defaults to name if not provided
-
-    # Existing fields
-    description: str = ""
+    description: str
+    license: Optional[str] = None
+    compatibility: Optional[str] = None
+    metadata: Dict[str, Any] = None
+    allowed_tools: List[str] = None
+
+    # Internal fields (not in frontmatter spec)
+    path: Path = None
+    content: str = ""
+    source: str = "bundled"  # 'bundled', 'user', 'project', 'pm'
+
+    # Derived fields (from metadata or fallback)
+    version: str = "0.1.0"  # From metadata.version or top-level
+    skill_id: str = ""  # Internal ID (defaults to name)
     agent_types: List[str] = None  # Which agent types can use this skill
+    updated_at: Optional[str] = None  # From metadata.updated
+    tags: List[str] = None  # From metadata.tags or top-level
 
-    # Optional metadata
-    updated_at: Optional[str] = None
-    tags: List[str] = None
+    # Claude-mpm extensions (preserved for backward compat)
+    category: Optional[str] = None
+    toolchain: Optional[str] = None
+    progressive_disclosure: Optional[Dict[str, Any]] = None
+    user_invocable: bool = False
 
     def __post_init__(self):
         """Initialize default values if not provided."""
+        if self.metadata is None:
+            self.metadata = {}
         if self.agent_types is None:
             self.agent_types = []
         if self.tags is None:
             self.tags = []
+        if self.allowed_tools is None:
+            self.allowed_tools = []
         if not self.skill_id:
             self.skill_id = self.name
 
 
+def validate_agentskills_spec(skill: Skill) -> tuple[bool, List[str]]:
+    """Validate skill against agentskills.io specification.
+
+    Args:
+        skill: Skill object to validate
+
+    Returns:
+        Tuple of (is_valid, list_of_warnings)
+        - is_valid: True if skill meets spec requirements
+        - warnings: List of warning messages for spec violations
+    """
+    warnings = []
+
+    # Validate name (required field)
+    if not skill.name:
+        warnings.append("Missing required field: name")
+        return False, warnings
+
+    # Validate name format: lowercase alphanumeric + hyphens, no leading/trailing hyphens
+    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", skill.name):
+        warnings.append(
+            f"Invalid name format: '{skill.name}' (must be lowercase alphanumeric with hyphens, "
+            "no leading/trailing hyphens, no consecutive hyphens)"
+        )
+
+    # Validate name length (max 64 chars)
+    if len(skill.name) > 64:
+        warnings.append(
+            f"Name too long: {len(skill.name)} chars (max 64 per agentskills.io spec)"
+        )
+
+    # Validate description (required field)
+    if not skill.description:
+        warnings.append("Missing required field: description")
+        return False, warnings
+
+    # Validate description length (1-1024 chars)
+    desc_len = len(skill.description)
+    if desc_len < 1 or desc_len > 1024:
+        warnings.append(
+            f"Description length {desc_len} chars is outside spec range (1-1024 chars)"
+        )
+
+    # Validate compatibility length (max 500 chars)
+    if skill.compatibility and len(skill.compatibility) > 500:
+        warnings.append(
+            f"Compatibility field too long: {len(skill.compatibility)} chars (max 500)"
+        )
+
+    # Validate metadata is dict
+    if skill.metadata is not None and not isinstance(skill.metadata, dict):
+        warnings.append("Metadata must be a key-value mapping (dict)")
+
+    # Check for spec-compliant metadata structure
+    spec_metadata_fields = ["version", "author", "updated", "tags"]
+    for field in spec_metadata_fields:
+        if hasattr(skill, field):
+            field_value = getattr(skill, field)
+            if field_value and field not in skill.metadata:
+                warnings.append(
+                    f"Field '{field}' should be in metadata block per agentskills.io spec "
+                    f"(found as top-level field)"
+                )
+
+    # Valid if no errors (only warnings allowed)
+    is_valid = len(warnings) == 0 or all("should be in metadata" in w for w in warnings)
+    return is_valid, warnings
+
+
 class SkillsRegistry:
     """Registry for managing skills across all tiers."""
 
@@ -54,7 +163,10 @@ class SkillsRegistry:
         self._load_project_skills()
 
     def _parse_skill_frontmatter(self, content: str) -> Dict[str, Any]:
-        """Parse YAML frontmatter from skill markdown file.
+        """Parse YAML frontmatter from skill markdown file with spec validation.
+
+        Supports both agentskills.io spec format and legacy claude-mpm format
+        with automatic migration.
 
         Returns:
             Dict with frontmatter fields or empty dict if no frontmatter
@@ -70,11 +182,150 @@ class SkillsRegistry:
 
         try:
             frontmatter = yaml.safe_load(match.group(1))
-            return frontmatter or {}
+            if not frontmatter:
+                return {}
+
+            # Apply backward compatibility migration
+            return self._apply_backward_compatibility(frontmatter)
         except yaml.YAMLError as e:
             logger.warning(f"Failed to parse skill frontmatter: {e}")
             return {}
 
+    def _apply_backward_compatibility(
+        self, frontmatter: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Apply backward compatibility transformations to legacy frontmatter.
+
+        Auto-migrates legacy claude-mpm fields to agentskills.io spec format:
+        - version → metadata.version
+        - author → metadata.author
+        - updated → metadata.updated
+        - tags → metadata.tags (if not already present)
+
+        Args:
+            frontmatter: Parsed frontmatter dict
+
+        Returns:
+            Transformed frontmatter with spec-compliant structure
+        """
+        # Initialize metadata if not present
+        if "metadata" not in frontmatter:
+            frontmatter["metadata"] = {}
+
+        metadata = frontmatter["metadata"]
+
+        # Auto-migrate version (top-level → metadata.version)
+        if "version" in frontmatter and "version" not in metadata:
+            metadata["version"] = frontmatter["version"]
+            logger.debug(
+                f"Auto-migrated 'version' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate author (top-level → metadata.author)
+        if "author" in frontmatter and "author" not in metadata:
+            metadata["author"] = frontmatter["author"]
+            logger.debug(
+                f"Auto-migrated 'author' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate updated (top-level → metadata.updated)
+        if "updated" in frontmatter and "updated" not in metadata:
+            metadata["updated"] = frontmatter["updated"]
+            logger.debug(
+                f"Auto-migrated 'updated' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate tags (top-level → metadata.tags)
+        if "tags" in frontmatter and "tags" not in metadata:
+            metadata["tags"] = frontmatter["tags"]
+            logger.debug(
+                f"Auto-migrated 'tags' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Parse allowed-tools from space-delimited string to list
+        if "allowed-tools" in frontmatter:
+            allowed_tools = frontmatter["allowed-tools"]
+            if isinstance(allowed_tools, str):
+                frontmatter["allowed-tools"] = allowed_tools.split()
+
+        # Set default compatibility for claude-code if not present
+        if "compatibility" not in frontmatter:
+            frontmatter["compatibility"] = "claude-code"
+
+        return frontmatter
+
+    def _create_skill_from_frontmatter(
+        self, frontmatter: Dict[str, Any], path: Path, content: str, source: str
+    ) -> Optional[Skill]:
+        """Create Skill object from frontmatter with spec compliance.
+
+        Args:
+            frontmatter: Parsed and migrated frontmatter dict
+            path: Path to skill file
+            content: Full skill content
+            source: Source type ('bundled', 'user', 'project', 'pm')
+
+        Returns:
+            Skill object or None if required fields missing
+        """
+        # Extract spec fields (required)
+        name = frontmatter.get("name")
+        description = frontmatter.get("description", "")
+
+        # If name not in frontmatter, use filename stem
+        if not name:
+            name = path.stem
+
+        # If description not in frontmatter, extract from content
+        if not description:
+            description = self._extract_description(content)
+
+        # Validate required fields
+        if not name or not description:
+            logger.warning(
+                f"Skipping skill at {path}: missing required field (name or description)"
+            )
+            return None
+
+        # Extract spec fields (optional)
+        license_field = frontmatter.get("license")
+        compatibility = frontmatter.get("compatibility", "claude-code")
+        metadata = frontmatter.get("metadata", {})
+        allowed_tools = frontmatter.get("allowed-tools", [])
+
+        # Extract derived fields from metadata or top-level
+        version = frontmatter.get("version") or metadata.get("version", "0.1.0")
+        skill_id = frontmatter.get("skill_id", name)
+        updated_at = frontmatter.get("updated_at") or metadata.get("updated")
+        tags = frontmatter.get("tags", []) or metadata.get("tags", [])
+
+        # Extract claude-mpm extensions
+        category = frontmatter.get("category")
+        toolchain = frontmatter.get("toolchain")
+        progressive_disclosure = frontmatter.get("progressive_disclosure")
+        user_invocable = frontmatter.get("user-invocable", False)
+
+        # Create skill object
+        return Skill(
+            name=name,
+            description=description,
+            license=license_field,
+            compatibility=compatibility,
+            metadata=metadata,
+            allowed_tools=allowed_tools,
+            path=path,
+            content=content,
+            source=source,
+            version=version,
+            skill_id=skill_id,
+            updated_at=updated_at,
+            tags=tags,
+            category=category,
+            toolchain=toolchain,
+            progressive_disclosure=progressive_disclosure,
+            user_invocable=user_invocable,
+        )
+
     def _load_bundled_skills(self):
         """Load skills bundled with MPM."""
         bundled_dir = Path(__file__).parent / "bundled"
@@ -88,32 +339,16 @@ class SkillsRegistry:
                 skill_name = skill_file.stem
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="bundled",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "bundled"
                 )
-                skill_count += 1
+                if skill:
+                    self.skills[skill_name] = skill
+                    skill_count += 1
             except Exception as e:
                 logger.error(f"Error loading bundled skill {skill_file}: {e}")
 
@@ -130,36 +365,20 @@ class SkillsRegistry:
         for skill_file in user_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # User skills override bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="user",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "user"
                 )
-                skill_count += 1
-                logger.debug(f"User skill '{skill_name}' overrides bundled version")
+                if skill:
+                    # User skills override bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(f"User skill '{skill_name}' overrides bundled version")
             except Exception as e:
                 logger.error(f"Error loading user skill {skill_file}: {e}")
 
@@ -177,36 +396,22 @@ class SkillsRegistry:
         for skill_file in project_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # Project skills override both user and bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="project",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "project"
                 )
-                skill_count += 1
-                logger.debug(f"Project skill '{skill_name}' overrides other versions")
+                if skill:
+                    # Project skills override both user and bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(
+                        f"Project skill '{skill_name}' overrides other versions"
+                    )
             except Exception as e:
                 logger.error(f"Error loading project skill {skill_file}: {e}")
 

{claude_mpm-5.4.96.dist-info → claude_mpm-5.6.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 5.4.96
+Version: 5.6.17
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -23,7 +23,7 @@ License-File: LICENSE
 License-File: LICENSE-FAQ.md
 Requires-Dist: ai-trackdown-pytools>=1.4.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: pexpect>=4.8.0
 Requires-Dist: psutil>=5.9.0
@@ -49,6 +49,8 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: pyee>=13.0.0
 Requires-Dist: pathspec>=0.11.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-vector-search>=0.1.0; extra == "mcp"
@@ -108,7 +110,7 @@ Dynamic: license-file
 
 A powerful orchestration framework for **Claude Code (CLI)** that enables multi-agent workflows, session management, and real-time monitoring through a streamlined Rich-based interface.
 
-> **⚠️ Important**: Claude MPM **requires Claude Code CLI** (v2.0.30+), not Claude Desktop (app). All MCP integrations work with Claude Code's CLI interface only.
+> **⚠️ Important**: Claude MPM **requires Claude Code CLI** (v2.1.3+), not Claude Desktop (app). All MCP integrations work with Claude Code's CLI interface only.
 >
 > **Don't have Claude Code?** Install from: https://docs.anthropic.com/en/docs/claude-code
 >
@@ -118,7 +120,7 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 
 ## Who Should Use Claude MPM?
 
-- 👥 **[Non-Technical Users (Founders/PMs)](docs/usecases/non-technical-users.md)** - Understand and oversee your technical projects without coding experience
+- 👥 **[Non-Technical Users (Founders/PMs)](docs/usecases/non-technical-users.md)** - Research and understand codebases using Research Mode - no coding experience required
 - 💻 **[Developers](docs/usecases/developers.md)** - Multi-agent development workflows with semantic code search and advanced features
 - 🏢 **[Teams](docs/usecases/teams.md)** - Collaboration patterns, session management, and coordinated workflows
 
@@ -141,8 +143,10 @@ Claude MPM transforms Claude Code into a **multi-agent orchestration platform**
 
 ### Prerequisites
 
-1. **Python 3.10+** (3.11+ recommended)
-2. **Claude Code CLI v2.0.30+** (required!)
+1. **Python 3.11+** (required - older versions will install outdated claude-mpm)
+2. **Claude Code CLI v2.1.3+** (required!)
+
+> ⚠️ **Python Version Note**: Claude MPM requires Python 3.11 or higher. If you have Python 3.9 or 3.10, you'll get an old version (4.x) that lacks current features. Check with `python3 --version` before installing.
 
 ```bash
 # Verify Claude Code is installed
@@ -195,6 +199,8 @@ ls ~/.claude/agents/    # Should show 47+ agents
 
 **💡 Recommended Partners**: Install [kuzu-memory](https://github.com/bobmatnyc/kuzu-memory) (persistent context) and [mcp-vector-search](https://github.com/bobmatnyc/mcp-vector-search) (semantic search) for enhanced capabilities.
 
+**💡 Tool Version Management**: Use [ASDF version manager](docs/guides/asdf-tool-versions.md) to avoid Python/uv version conflicts across projects.
+
 ---
 
 ## Key Features
@@ -231,6 +237,16 @@ ls ~/.claude/agents/    # Should show 47+ agents
 
 [→ Learn more: Developer Use Cases](docs/usecases/developers.md#semantic-code-search)
 
+### 🧪 MPM Commander (ALPHA)
+- **Multi-Project Orchestration** with autonomous AI coordination across codebases
+- **Tmux Integration** for isolated project environments and session management
+- **Event-Driven Architecture** with inbox system for cross-project communication
+- **LLM-Powered Decisions** via OpenRouter for autonomous work queue processing
+- **Real-Time Monitoring** with state tracking (IDLE, WORKING, BLOCKED, PAUSED, ERROR)
+- ⚠️ **Experimental** - API and CLI interface subject to change
+
+[→ Commander Documentation](docs/commander/usage-guide.md)
+
 ### 🔌 Advanced Integration
 - **MCP Integration** with full Model Context Protocol support
 - **Real-Time Monitoring** via `--monitor` flag and web dashboard