minion-code 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

minion_code/skills/__init__.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Skills system for MinionCode
+
+Skills are folders of instructions, scripts, and resources that are loaded
+dynamically to improve performance on specialized tasks. Each skill has a
+SKILL.md file with YAML frontmatter containing name and description.
+
+Skill search paths (in order):
+- .claude/skills (project-level)
+- ~/.claude/skills (user-level)
+- .minion/skills (project-level)
+- ~/.minion/skills (user-level)
+"""
+
+from .skill import Skill
+from .skill_registry import SkillRegistry
+from .skill_loader import SkillLoader
+
+__all__ = [
+    "Skill",
+    "SkillRegistry",
+    "SkillLoader",
+]

minion_code/skills/skill.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Skill data class representing a loaded skill.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import yaml
+
+
+@dataclass
+class Skill:
+    """Represents a loaded skill with its metadata and content."""
+
+    name: str
+    description: str
+    content: str  # The markdown body (instructions)
+    path: Path  # Path to the skill directory
+
+    # Optional metadata from frontmatter
+    license: Optional[str] = None
+    allowed_tools: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    # Source location type
+    location: str = "project"  # project, user, managed
+
+    @classmethod
+    def from_skill_md(
+        cls, skill_md_path: Path, location: str = "project"
+    ) -> Optional["Skill"]:
+        """
+        Parse a SKILL.md file and create a Skill instance.
+
+        Args:
+            skill_md_path: Path to the SKILL.md file
+            location: Where the skill was found (project, user, managed)
+
+        Returns:
+            Skill instance or None if parsing fails
+        """
+        if not skill_md_path.exists():
+            return None
+
+        content = skill_md_path.read_text(encoding="utf-8")
+        frontmatter, body = cls._parse_frontmatter(content)
+
+        if not frontmatter:
+            return None
+
+        name = frontmatter.get("name")
+        description = frontmatter.get("description")
+
+        if not name or not description:
+            return None
+
+        return cls(
+            name=name,
+            description=description,
+            content=body.strip(),
+            path=skill_md_path.parent,
+            license=frontmatter.get("license"),
+            allowed_tools=frontmatter.get("allowed-tools", []) or [],
+            metadata=frontmatter.get("metadata", {}) or {},
+            location=location,
+        )
+
+    @staticmethod
+    def _parse_frontmatter(content: str) -> tuple[Dict[str, Any], str]:
+        """
+        Parse YAML frontmatter from markdown content.
+
+        Args:
+            content: Raw markdown content with potential YAML frontmatter
+
+        Returns:
+            Tuple of (frontmatter dict, body content)
+        """
+        # Match YAML frontmatter pattern: starts with ---, ends with ---
+        pattern = r"^---\s*\n(.*?)\n---\s*\n(.*)$"
+        match = re.match(pattern, content, re.DOTALL)
+
+        if not match:
+            return {}, content
+
+        yaml_content = match.group(1)
+        body = match.group(2)
+
+        try:
+            frontmatter = yaml.safe_load(yaml_content) or {}
+        except yaml.YAMLError:
+            return {}, content
+
+        return frontmatter, body
+
+    def get_prompt(self) -> str:
+        """
+        Get the full prompt content for this skill.
+        Includes the skill location header for resolving relative paths
+        to bundled resources (references/, scripts/, assets/).
+
+        Returns:
+            Full prompt string with base directory header
+        """
+        header = f"""Loading: {self.name}
+Base directory: {self.path}
+
+"""
+        return header + self.content
+
+    def to_xml(self) -> str:
+        """
+        Format skill as XML for inclusion in prompts.
+
+        Returns:
+            XML formatted skill entry
+        """
+        return f"""<skill>
+<name>{self.name}</name>
+<description>{self.description}</description>
+<location>{self.location}</location>
+</skill>"""
+
+    def __repr__(self) -> str:
+        return f"Skill(name={self.name!r}, location={self.location!r})"

minion_code/skills/skill_loader.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Skill Loader - discovers and loads skills from standard directories.
+"""
+
+import os
+from pathlib import Path
+from typing import List, Optional
+import logging
+
+from .skill import Skill
+from .skill_registry import SkillRegistry, get_skill_registry
+
+logger = logging.getLogger(__name__)
+
+
+class SkillLoader:
+    """
+    Discovers and loads skills from standard directories.
+
+    Search paths (in priority order):
+    1. .claude/skills (project-level)
+    2. .minion/skills (project-level)
+    3. ~/.claude/skills (user-level)
+    4. ~/.minion/skills (user-level)
+
+    Project-level skills override user-level skills with the same name.
+    """
+
+    # Default skill directory names
+    SKILL_DIRS = [
+        ".claude/skills",
+        ".minion/skills",
+    ]
+
+    SKILL_FILE = "SKILL.md"
+
+    def __init__(self, project_root: Optional[Path] = None):
+        """
+        Initialize the skill loader.
+
+        Args:
+            project_root: Root directory of the project. Defaults to current directory.
+        """
+        self.project_root = Path(project_root) if project_root else Path.cwd()
+        self.home_dir = Path.home()
+
+    def get_search_paths(self) -> List[tuple[Path, str]]:
+        """
+        Get all skill search paths with their location type.
+
+        Returns:
+            List of (path, location_type) tuples
+        """
+        paths = []
+
+        # Project-level paths (higher priority)
+        for skill_dir in self.SKILL_DIRS:
+            project_path = self.project_root / skill_dir
+            paths.append((project_path, "project"))
+
+        # User-level paths (lower priority)
+        for skill_dir in self.SKILL_DIRS:
+            user_path = self.home_dir / skill_dir
+            paths.append((user_path, "user"))
+
+        return paths
+
+    def discover_skills(self, skills_dir: Path) -> List[Path]:
+        """
+        Discover all skill directories within a skills directory.
+
+        A skill directory must contain a SKILL.md file.
+
+        Args:
+            skills_dir: Directory containing skill subdirectories
+
+        Returns:
+            List of paths to SKILL.md files
+        """
+        if not skills_dir.exists() or not skills_dir.is_dir():
+            return []
+
+        skill_files = []
+
+        for item in skills_dir.iterdir():
+            if item.is_dir():
+                skill_md = item / self.SKILL_FILE
+                if skill_md.exists():
+                    skill_files.append(skill_md)
+                else:
+                    # Check for nested skill directories (e.g., document-skills/pdf)
+                    for nested_item in item.iterdir():
+                        if nested_item.is_dir():
+                            nested_skill_md = nested_item / self.SKILL_FILE
+                            if nested_skill_md.exists():
+                                skill_files.append(nested_skill_md)
+
+        return skill_files
+
+    def load_skill(self, skill_md_path: Path, location: str) -> Optional[Skill]:
+        """
+        Load a single skill from its SKILL.md file.
+
+        Args:
+            skill_md_path: Path to the SKILL.md file
+            location: Location type (project, user, managed)
+
+        Returns:
+            Skill instance or None if loading fails
+        """
+        try:
+            skill = Skill.from_skill_md(skill_md_path, location)
+            if skill:
+                logger.debug(f"Loaded skill: {skill.name} from {skill_md_path}")
+            else:
+                logger.warning(f"Failed to parse skill: {skill_md_path}")
+            return skill
+        except Exception as e:
+            logger.error(f"Error loading skill from {skill_md_path}: {e}")
+            return None
+
+    def load_all(self, registry: Optional[SkillRegistry] = None) -> SkillRegistry:
+        """
+        Load all skills from all search paths into the registry.
+
+        Args:
+            registry: Optional registry to load into. Creates new if not provided.
+
+        Returns:
+            SkillRegistry containing all loaded skills
+        """
+        if registry is None:
+            registry = get_skill_registry()
+
+        for search_path, location in self.get_search_paths():
+            skill_files = self.discover_skills(search_path)
+
+            for skill_md_path in skill_files:
+                skill = self.load_skill(skill_md_path, location)
+                if skill:
+                    registered = registry.register(skill)
+                    if registered:
+                        logger.info(f"Registered skill: {skill.name} ({location})")
+                    else:
+                        logger.debug(
+                            f"Skipped skill {skill.name} - already registered from higher priority location"
+                        )
+
+        return registry
+
+    def reload(self, registry: Optional[SkillRegistry] = None) -> SkillRegistry:
+        """
+        Reload all skills, clearing the existing registry first.
+
+        Args:
+            registry: Optional registry to reload. Uses global if not provided.
+
+        Returns:
+            SkillRegistry containing all reloaded skills
+        """
+        if registry is None:
+            registry = get_skill_registry()
+
+        registry.clear()
+        return self.load_all(registry)
+
+
+def load_skills(project_root: Optional[Path] = None) -> SkillRegistry:
+    """
+    Convenience function to load all skills.
+
+    Args:
+        project_root: Root directory of the project
+
+    Returns:
+        SkillRegistry containing all loaded skills
+    """
+    loader = SkillLoader(project_root)
+    return loader.load_all()
+
+
+def get_available_skills() -> List[Skill]:
+    """
+    Get list of all available skills.
+
+    Loads skills if the registry is empty.
+
+    Returns:
+        List of available skills
+    """
+    registry = get_skill_registry()
+
+    if len(registry) == 0:
+        load_skills()
+
+    return registry.list_all()

minion_code/skills/skill_registry.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Skill Registry - manages loaded skills and provides lookup functionality.
+"""
+
+from typing import Dict, Optional, List
+from .skill import Skill
+
+
+class SkillRegistry:
+    """
+    Registry for managing loaded skills.
+
+    Skills are organized by name and can be looked up for execution.
+    The registry also handles skill deduplication (project skills override user skills).
+    """
+
+    def __init__(self):
+        self._skills: Dict[str, Skill] = {}
+        self._skills_by_location: Dict[str, List[Skill]] = {
+            "project": [],
+            "user": [],
+            "managed": [],
+        }
+
+    def register(self, skill: Skill) -> bool:
+        """
+        Register a skill in the registry.
+
+        Project skills take precedence over user skills.
+        If a skill with the same name already exists from a higher priority location,
+        the new skill is not registered.
+
+        Priority order: project > user > managed
+
+        Args:
+            skill: Skill instance to register
+
+        Returns:
+            True if the skill was registered, False if it was skipped
+        """
+        existing = self._skills.get(skill.name)
+
+        if existing:
+            # Check priority
+            priority = {"project": 0, "user": 1, "managed": 2}
+            existing_priority = priority.get(existing.location, 99)
+            new_priority = priority.get(skill.location, 99)
+
+            if new_priority >= existing_priority:
+                # Skip - existing skill has higher or equal priority
+                return False
+
+        self._skills[skill.name] = skill
+        self._skills_by_location[skill.location].append(skill)
+        return True
+
+    def get(self, name: str) -> Optional[Skill]:
+        """
+        Get a skill by name.
+
+        Args:
+            name: Name of the skill
+
+        Returns:
+            Skill instance or None if not found
+        """
+        return self._skills.get(name)
+
+    def exists(self, name: str) -> bool:
+        """
+        Check if a skill exists in the registry.
+
+        Args:
+            name: Name of the skill
+
+        Returns:
+            True if the skill exists
+        """
+        return name in self._skills
+
+    def list_all(self) -> List[Skill]:
+        """
+        Get all registered skills.
+
+        Returns:
+            List of all skills
+        """
+        return list(self._skills.values())
+
+    def list_by_location(self, location: str) -> List[Skill]:
+        """
+        Get skills by location type.
+
+        Args:
+            location: Location type (project, user, managed)
+
+        Returns:
+            List of skills from that location
+        """
+        return self._skills_by_location.get(location, [])
+
+    def clear(self):
+        """Clear all registered skills."""
+        self._skills.clear()
+        for location in self._skills_by_location:
+            self._skills_by_location[location].clear()
+
+    def generate_skills_prompt(self, char_budget: int = 10000) -> str:
+        """
+        Generate a prompt listing all available skills.
+
+        Limits output to character budget to manage context window.
+
+        Args:
+            char_budget: Maximum characters for skills list
+
+        Returns:
+            Formatted skills prompt
+        """
+        skills = self.list_all()
+
+        if not skills:
+            return ""
+
+        entries = []
+        total_chars = 0
+
+        for skill in skills:
+            entry = skill.to_xml()
+            if total_chars + len(entry) > char_budget:
+                break
+            entries.append(entry)
+            total_chars += len(entry)
+
+        if not entries:
+            return ""
+
+        skills_xml = "\n".join(entries)
+        return f"""<available_skills>
+{skills_xml}
+</available_skills>"""
+
+    def __len__(self) -> int:
+        return len(self._skills)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._skills
+
+    def __iter__(self):
+        return iter(self._skills.values())
+
+
+# Global skill registry instance
+_skill_registry: Optional[SkillRegistry] = None
+
+
+def get_skill_registry() -> SkillRegistry:
+    """
+    Get the global skill registry instance.
+
+    Creates the registry if it doesn't exist.
+
+    Returns:
+        SkillRegistry instance
+    """
+    global _skill_registry
+    if _skill_registry is None:
+        _skill_registry = SkillRegistry()
+    return _skill_registry
+
+
+def reset_skill_registry():
+    """Reset the global skill registry."""
+    global _skill_registry
+    _skill_registry = None

minion_code/subagents/__init__.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Subagents system for MinionCode
+
+Subagents are specialized agent configurations that can be invoked via the Task tool.
+Each subagent has specific tools, system prompts, and use cases.
+
+Subagent search paths (in priority order):
+- builtin (code-defined)
+- .claude/subagents or .minion/subagents (project-level, highest priority)
+- ~/.claude/subagents or ~/.minion/subagents (user-level)
+"""
+
+from .subagent import SubagentConfig
+from .subagent_registry import (
+    SubagentRegistry,
+    get_subagent_registry,
+    reset_subagent_registry,
+)
+from .subagent_loader import SubagentLoader, load_subagents, get_available_subagents
+
+__all__ = [
+    "SubagentConfig",
+    "SubagentRegistry",
+    "get_subagent_registry",
+    "reset_subagent_registry",
+    "SubagentLoader",
+    "load_subagents",
+    "get_available_subagents",
+]

minion_code/subagents/builtin/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Built-in subagent configurations."""
+
+from typing import List
+from ..subagent import SubagentConfig
+
+from .general_purpose import get_general_purpose_subagent
+from .explore import get_explore_subagent
+from .plan import get_plan_subagent
+from .claude_code_guide import get_claude_code_guide_subagent
+
+
+def get_all_builtin_subagents() -> List[SubagentConfig]:
+    """Get all built-in subagent configurations."""
+    return [
+        get_general_purpose_subagent(),
+        get_explore_subagent(),
+        get_plan_subagent(),
+        get_claude_code_guide_subagent(),
+    ]
+
+
+__all__ = [
+    "get_all_builtin_subagents",
+    "get_general_purpose_subagent",
+    "get_explore_subagent",
+    "get_plan_subagent",
+    "get_claude_code_guide_subagent",
+]

minion_code/subagents/builtin/claude_code_guide.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Built-in claude-code-guide subagent configuration."""
+
+from ..subagent import SubagentConfig
+
+GUIDE_SYSTEM_PROMPT = """You are a documentation lookup specialist for Claude Code and related tools.
+
+Your role is to help users understand:
+- How to use Claude Code features and commands
+- Best practices for working with AI coding assistants
+- Tool usage patterns and examples
+- Configuration and customization options
+
+Use web search and documentation fetching to find accurate, up-to-date information.
+Always cite your sources with URLs when providing information.
+
+Focus on practical, actionable guidance with clear examples."""
+
+
+def get_claude_code_guide_subagent() -> SubagentConfig:
+    """Get the claude-code-guide subagent configuration."""
+    return SubagentConfig(
+        name="claude-code-guide",
+        description="Documentation lookup agent for Claude Code features, commands, and best practices",
+        when_to_use="When you need to look up Claude Code documentation, understand tool usage, or find best practices for AI-assisted coding",
+        tools=["web_fetch", "web_search", "file_read"],
+        system_prompt=GUIDE_SYSTEM_PROMPT,
+        model_name="inherit",
+        location="builtin",
+        readonly=True,
+    )

minion_code/subagents/builtin/explore.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Built-in Explore subagent configuration."""
+
+from ..subagent import SubagentConfig
+
+EXPLORE_SYSTEM_PROMPT = """You are a fast codebase exploration specialist. Your role is to quickly navigate and understand codebases.
+
+Your capabilities:
+- Search for files using glob patterns
+- Search for content using grep/regex patterns
+- Read files to understand code structure
+- Fetch web documentation when needed
+- Search the web for relevant information
+
+Guidelines:
+- Be thorough but efficient - use glob and grep to narrow down before reading
+- Make multiple parallel tool calls when searching different patterns
+- Summarize findings clearly with file paths and line numbers
+- Do NOT modify any files - you are read-only
+
+Focus on answering the user's question with concrete file locations and code references."""
+
+
+def get_explore_subagent() -> SubagentConfig:
+    """Get the Explore subagent configuration."""
+    return SubagentConfig(
+        name="Explore",
+        description="Fast codebase exploration agent specialized for finding files, searching content, and understanding code structure",
+        when_to_use="When you need to quickly explore a codebase, find specific files or patterns, understand code structure, or gather information before making changes",
+        tools=["glob", "grep", "file_read", "ls", "web_fetch", "web_search"],
+        system_prompt=EXPLORE_SYSTEM_PROMPT,
+        model_name="inherit",
+        location="builtin",
+        readonly=True,
+    )

minion_code/subagents/builtin/general_purpose.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Built-in general-purpose subagent configuration."""
+
+from ..subagent import SubagentConfig
+
+
+def get_general_purpose_subagent() -> SubagentConfig:
+    """Get the general-purpose subagent configuration."""
+    return SubagentConfig(
+        name="general-purpose",
+        description="General-purpose agent for complex tasks requiring full tool access",
+        when_to_use="For complex, multi-step tasks that need full tool capabilities including file editing, bash, and code execution",
+        tools=["*"],
+        system_prompt=None,  # Uses default system prompt
+        model_name="inherit",
+        location="builtin",
+        readonly=False,
+    )