claude-mpm 5.6.12__py3-none-any.whl → 5.6.14__py3-none-any.whl

claude_mpm/commander/work/executor.py

@@ -51,16 +51,19 @@ class WorkExecutor:
 
         logger.debug(f"Initialized WorkExecutor for project {queue.project_id}")
 
-    async def execute_next(self) -> bool:
+    async def execute_next(self, pane_target: Optional[str] = None) -> bool:
         """Execute next available work item.
 
         Gets next work from queue, starts it, and executes via RuntimeExecutor.
 
+        Args:
+            pane_target: Optional tmux pane target for execution
+
         Returns:
             True if work was executed, False if queue empty/blocked
 
         Example:
-            >>> executed = await executor.execute_next()
+            >>> executed = await executor.execute_next("%5")
             >>> if not executed:
             ...     print("No work available")
         """
@@ -71,10 +74,12 @@ class WorkExecutor:
             return False
 
         # Execute the work item
-        await self.execute(work_item)
+        await self.execute(work_item, pane_target)
         return True
 
-    async def execute(self, work_item: WorkItem) -> None:
+    async def execute(
+        self, work_item: WorkItem, pane_target: Optional[str] = None
+    ) -> None:
         """Execute a specific work item.
 
         Marks work as IN_PROGRESS and sends to RuntimeExecutor.
@@ -83,12 +88,13 @@ class WorkExecutor:
 
         Args:
             work_item: WorkItem to execute
+            pane_target: Optional tmux pane target for execution
 
         Raises:
             RuntimeError: If execution fails
 
         Example:
-            >>> await executor.execute(work_item)
+            >>> await executor.execute(work_item, "%5")
         """
         # Mark as in progress
         if not self.queue.start(work_item.id):
@@ -103,17 +109,21 @@ class WorkExecutor:
         )
 
         try:
-            # Send work content to runtime
-            # Note: In actual implementation, this would integrate with
-            # ProjectSession which manages the pane_target
-            # For now, we assume runtime has active session
-            # This will be properly integrated when wiring with ProjectSession
+            # Send work content to runtime if pane target provided
+            if pane_target:
+                await self.runtime.send_message(pane_target, work_item.content)
+                logger.info(
+                    f"Work item {work_item.id} sent to pane {pane_target} for execution"
+                )
+            else:
+                logger.warning(
+                    f"No pane target provided for work item {work_item.id}, "
+                    f"work marked as in-progress but not sent to runtime"
+                )
 
             # Store work item ID in metadata for callback tracking
             work_item.metadata["execution_started"] = True
 
-            logger.info(f"Work item {work_item.id} sent to runtime for execution")
-
         except Exception as e:
             logger.error(f"Failed to execute work item {work_item.id}: {e}")
             await self.handle_failure(work_item.id, str(e))

claude_mpm/core/output_style_manager.py

@@ -297,6 +297,9 @@ class OutputStyleManager:
             target_path = style_config["target"]
             style_name = style_config["name"]
 
+            # Check if this is a fresh install (file doesn't exist yet)
+            is_fresh_install = not target_path.exists()
+
             # If content not provided, read from source
             if content is None:
                 content = self.extract_output_style_content(style=style)
@@ -310,7 +313,9 @@ class OutputStyleManager:
 
             # Activate the style if requested
             if activate:
-                self._activate_output_style(style_name)
+                self._activate_output_style(
+                    style_name, is_fresh_install=is_fresh_install
+                )
 
             return True
 
@@ -318,12 +323,21 @@ class OutputStyleManager:
             self.logger.error(f"Failed to deploy {style} style: {e}")
             return False
 
-    def _activate_output_style(self, style_name: str = "Claude MPM") -> bool:
+    def _activate_output_style(
+        self, style_name: str = "Claude MPM", is_fresh_install: bool = False
+    ) -> bool:
         """
         Update Claude Code settings to activate a specific output style.
 
+        Only activates the style if:
+        1. No active style is currently set (first deployment), OR
+        2. This is a fresh install (style file didn't exist before deployment)
+
+        This preserves user preferences if they've manually changed their active style.
+
         Args:
             style_name: Name of the style to activate (e.g., "Claude MPM", "Claude MPM Teacher")
+            is_fresh_install: Whether this is a fresh install (style file didn't exist before)
 
         Returns:
             True if activated successfully, False otherwise
@@ -342,8 +356,12 @@ class OutputStyleManager:
             # Check current active style
             current_style = settings.get("activeOutputStyle")
 
-            # Update active output style if different
-            if current_style != style_name:
+            # Only set activeOutputStyle if:
+            # 1. No active style is set (first deployment), OR
+            # 2. This is a fresh install (file didn't exist before deployment)
+            should_activate = current_style is None or is_fresh_install
+
+            if should_activate and current_style != style_name:
                 settings["activeOutputStyle"] = style_name
 
                 # Ensure settings directory exists
@@ -358,7 +376,10 @@ class OutputStyleManager:
                     f"✅ Activated {style_name} output style (was: {current_style or 'none'})"
                 )
             else:
-                self.logger.debug(f"{style_name} output style already active")
+                self.logger.debug(
+                    f"Preserving user preference: {current_style or 'none'} "
+                    f"(skipping activation of {style_name})"
+                )
 
             return True
 
@@ -452,6 +473,10 @@ class OutputStyleManager:
         """
         results: Dict[str, bool] = {}
 
+        # Check if professional style exists BEFORE deployment
+        # This determines if this is a fresh install
+        professional_style_existed = self.styles["professional"]["target"].exists()
+
         for style_type_key in self.styles:
             # Deploy without activation
             # Cast is safe because we know self.styles keys are OutputStyleType
@@ -459,9 +484,11 @@ class OutputStyleManager:
             success = self.deploy_output_style(style=style_type, activate=False)
             results[style_type] = success
 
-        # Activate the default style if requested
+        # Activate the default style if requested AND this is first deployment
         if activate_default and results.get("professional", False):
-            self._activate_output_style("Claude MPM")
+            self._activate_output_style(
+                "Claude MPM", is_fresh_install=not professional_style_existed
+            )
 
         return results
 

claude_mpm/skills/__init__.py

@@ -24,7 +24,7 @@ Legacy System (maintained for compatibility):
 from .agent_skills_injector import AgentSkillsInjector
 
 # Legacy System (maintained for compatibility)
-from .registry import Skill, SkillsRegistry, get_registry
+from .registry import Skill, SkillsRegistry, get_registry, validate_agentskills_spec
 from .skill_manager import SkillManager
 from .skills_registry import SkillsRegistry as SkillsRegistryHelper
 from .skills_service import SkillsService
@@ -39,4 +39,5 @@ __all__ = [
     # New Skills Integration System
     "SkillsService",
     "get_registry",
+    "validate_agentskills_spec",
 ]

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}")