emdash-core 0.1.7__py3-none-any.whl → 0.1.33__py3-none-any.whl

emdash_core/agent/skills.py

@@ -0,0 +1,358 @@
+"""Skill loader from .emdash/skills/*/SKILL.md files.
+
+Skills are markdown-based instruction files that teach the agent how to
+perform specific, repeatable tasks. They can be automatically applied
+when relevant or explicitly invoked via /skill_name.
+
+Similar to Claude Code's skills system:
+https://docs.anthropic.com/en/docs/claude-code/skills
+
+Skills are loaded from two locations:
+1. Built-in skills bundled with emdash_core (always available)
+2. User repo skills in .emdash/skills/ (can override built-in)
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from ..utils.logger import log
+
+
+def _get_builtin_skills_dir() -> Path:
+    """Get the directory containing built-in skills bundled with emdash_core."""
+    return Path(__file__).parent.parent / "skills"
+
+
+@dataclass
+class Skill:
+    """A skill configuration loaded from SKILL.md.
+
+    Attributes:
+        name: Unique skill identifier (from directory name or frontmatter)
+        description: Brief description of when to use this skill
+        instructions: The main prompt/instructions content
+        tools: List of tools this skill needs access to
+        user_invocable: Whether skill can be invoked with /name
+        file_path: Source file path
+        _builtin: Whether this is a built-in skill bundled with emdash_core
+    """
+
+    name: str
+    description: str = ""
+    instructions: str = ""
+    tools: list[str] = field(default_factory=list)
+    user_invocable: bool = False
+    file_path: Optional[Path] = None
+    _builtin: bool = False
+
+
+class SkillRegistry:
+    """Registry for managing loaded skills.
+
+    Singleton that maintains the list of available skills
+    and provides lookup functionality.
+    """
+
+    _instance: Optional["SkillRegistry"] = None
+    _skills: dict[str, Skill]
+    _skills_dir: Optional[Path]
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._skills = {}
+            cls._instance._skills_dir = None
+        return cls._instance
+
+    @classmethod
+    def get_instance(cls) -> "SkillRegistry":
+        """Get the singleton instance."""
+        return cls()
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance."""
+        if cls._instance is not None:
+            cls._instance._skills = {}
+            cls._instance._skills_dir = None
+
+    def load_skills(self, skills_dir: Optional[Path] = None) -> dict[str, Skill]:
+        """Load skills from built-in and user repo directories.
+
+        Skills are loaded from two locations (in order):
+        1. Built-in skills bundled with emdash_core (always available)
+        2. User repo skills in .emdash/skills/ (can override built-in)
+
+        Each skill is a directory containing a SKILL.md file:
+
+        ```
+        .emdash/skills/
+        ├── commit/
+        │   └── SKILL.md
+        └── review-pr/
+            └── SKILL.md
+        ```
+
+        SKILL.md format:
+        ```markdown
+        ---
+        name: commit
+        description: Generate commit messages following conventions
+        user_invocable: true
+        tools: [execute_command, read_file]
+        ---
+
+        # Commit Message Generation
+
+        Instructions for the skill...
+        ```
+
+        Args:
+            skills_dir: Directory containing user skill subdirectories.
+                       Defaults to .emdash/skills/ in cwd.
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
+        if skills_dir is None:
+            skills_dir = Path.cwd() / ".emdash" / "skills"
+
+        self._skills_dir = skills_dir
+
+        skills = {}
+
+        # First, load built-in skills bundled with emdash_core
+        builtin_dir = _get_builtin_skills_dir()
+        if builtin_dir.exists():
+            builtin_skills = self._load_skills_from_dir(builtin_dir, is_builtin=True)
+            skills.update(builtin_skills)
+
+        # Then, load user repo skills (can override built-in)
+        if skills_dir.exists():
+            user_skills = self._load_skills_from_dir(skills_dir, is_builtin=False)
+            skills.update(user_skills)
+
+        if skills:
+            log.info(f"Loaded {len(skills)} skills ({len([s for s in self._skills.values() if getattr(s, '_builtin', False)])} built-in)")
+
+        return skills
+
+    def _load_skills_from_dir(self, skills_dir: Path, is_builtin: bool = False) -> dict[str, Skill]:
+        """Load skills from a specific directory.
+
+        Args:
+            skills_dir: Directory containing skill subdirectories
+            is_builtin: Whether these are built-in skills
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
+        skills = {}
+
+        # Look for SKILL.md in subdirectories
+        for skill_dir in skills_dir.iterdir():
+            if not skill_dir.is_dir():
+                continue
+
+            skill_file = skill_dir / "SKILL.md"
+            if not skill_file.exists():
+                # Also try lowercase
+                skill_file = skill_dir / "skill.md"
+                if not skill_file.exists():
+                    continue
+
+            try:
+                skill = _parse_skill_file(skill_file, skill_dir.name)
+                if skill:
+                    skill._builtin = is_builtin  # Mark as built-in or user-defined
+                    skills[skill.name] = skill
+                    self._skills[skill.name] = skill
+                    source = "built-in" if is_builtin else "user"
+                    log.debug(f"Loaded {source} skill: {skill.name}")
+            except Exception as e:
+                log.warning(f"Failed to load skill from {skill_file}: {e}")
+
+        return skills
+
+    def get_skill(self, name: str) -> Optional[Skill]:
+        """Get a specific skill by name.
+
+        Args:
+            name: Skill name
+
+        Returns:
+            Skill or None if not found
+        """
+        return self._skills.get(name)
+
+    def list_skills(self) -> list[str]:
+        """List available skill names.
+
+        Returns:
+            List of skill names
+        """
+        return list(self._skills.keys())
+
+    def get_all_skills(self) -> dict[str, Skill]:
+        """Get all loaded skills.
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
+        return self._skills.copy()
+
+    def get_user_invocable_skills(self) -> list[Skill]:
+        """Get skills that can be invoked with /name.
+
+        Returns:
+            List of user-invocable skills
+        """
+        return [s for s in self._skills.values() if s.user_invocable]
+
+    def get_skills_for_prompt(self) -> str:
+        """Generate skills section for system prompt.
+
+        Returns:
+            Formatted string describing available skills
+        """
+        if not self._skills:
+            return ""
+
+        lines = ["## Available Skills\n"]
+        lines.append("The following skills are available. Use them when the task matches their description:\n")
+
+        for skill in self._skills.values():
+            invocable = " (user-invocable: /{})".format(skill.name) if skill.user_invocable else ""
+            lines.append(f"- **{skill.name}**: {skill.description}{invocable}")
+
+        lines.append("")
+        lines.append("To activate a skill, use the `skill` tool with the skill name.")
+        lines.append("")
+
+        return "\n".join(lines)
+
+
+def _parse_skill_file(file_path: Path, default_name: str) -> Optional[Skill]:
+    """Parse a single SKILL.md file.
+
+    Args:
+        file_path: Path to the SKILL.md file
+        default_name: Default name from directory (used if not in frontmatter)
+
+    Returns:
+        Skill or None if parsing fails
+    """
+    content = file_path.read_text()
+
+    # Extract frontmatter
+    frontmatter = {}
+    body = content
+
+    if content.startswith("---"):
+        parts = content.split("---", 2)
+        if len(parts) >= 3:
+            frontmatter = _parse_frontmatter(parts[1])
+            body = parts[2].strip()
+
+    # Get name from frontmatter or use directory name
+    name = frontmatter.get("name", default_name)
+
+    # Validate name format (lowercase, hyphens, max 64 chars)
+    if len(name) > 64:
+        log.warning(f"Skill name '{name}' exceeds 64 characters, truncating")
+        name = name[:64]
+
+    return Skill(
+        name=name,
+        description=frontmatter.get("description", ""),
+        instructions=body,
+        tools=frontmatter.get("tools", []),
+        user_invocable=frontmatter.get("user_invocable", False),
+        file_path=file_path,
+    )
+
+
+def _parse_frontmatter(frontmatter_str: str) -> dict:
+    """Parse YAML-like frontmatter.
+
+    Simple parser for key: value pairs.
+
+    Args:
+        frontmatter_str: Frontmatter string
+
+    Returns:
+        Dict of parsed values
+    """
+    result = {}
+
+    for line in frontmatter_str.strip().split("\n"):
+        if ":" not in line:
+            continue
+
+        key, value = line.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+
+        # Parse boolean values
+        if value.lower() == "true":
+            result[key] = True
+        elif value.lower() == "false":
+            result[key] = False
+        # Parse list values
+        elif value.startswith("[") and value.endswith("]"):
+            items = value[1:-1].split(",")
+            result[key] = [item.strip().strip("'\"") for item in items if item.strip()]
+        else:
+            result[key] = value.strip("'\"")
+
+    return result
+
+
+# Convenience functions
+
+
+def load_skills(skills_dir: Optional[Path] = None) -> dict[str, Skill]:
+    """Load skills from directory.
+
+    Args:
+        skills_dir: Optional skills directory
+
+    Returns:
+        Dict mapping skill name to Skill
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.load_skills(skills_dir)
+
+
+def get_skill(name: str) -> Optional[Skill]:
+    """Get a specific skill by name.
+
+    Args:
+        name: Skill name
+
+    Returns:
+        Skill or None if not found
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.get_skill(name)
+
+
+def list_skills() -> list[str]:
+    """List available skill names.
+
+    Returns:
+        List of skill names
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.list_skills()
+
+
+def get_user_invocable_skills() -> list[Skill]:
+    """Get skills that can be invoked with /name.
+
+    Returns:
+        List of user-invocable skills
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.get_user_invocable_skills()

emdash_core/agent/toolkit.py

@@ -41,6 +41,7 @@ class AgentToolkit:
         repo_root: Optional[Path] = None,
         plan_mode: bool = False,
         save_spec_path: Optional[Path] = None,
+        plan_file_path: Optional[str] = None,
     ):
         """Initialize the agent toolkit.
 
@@ -53,6 +54,7 @@ class AgentToolkit:
                       If None, uses repo_root from config or current working directory.
             plan_mode: Whether to include spec planning tools and restrict to read-only.
             save_spec_path: If provided, specs will be saved to this path.
+            plan_file_path: Path to the plan file (only writable file in plan mode).
         """
         self.connection = connection or get_connection()
         self.session = AgentSession() if enable_session else None
@@ -61,6 +63,7 @@ class AgentToolkit:
         self._mcp_config_path = mcp_config_path
         self.plan_mode = plan_mode
         self.save_spec_path = save_spec_path
+        self.plan_file_path = plan_file_path
 
         # Get repo_root from config if not explicitly provided
         if repo_root is None:
@@ -70,8 +73,12 @@ class AgentToolkit:
                 repo_root = Path(config.repo_root)
         self._repo_root = repo_root or Path.cwd()
 
-        # Configure spec state if plan mode
+        # Configure mode state and spec state if plan mode
         if plan_mode:
+            from .tools.modes import ModeState, AgentMode
+            mode_state = ModeState.get_instance()
+            mode_state.current_mode = AgentMode.PLAN
+
             from .tools.spec import SpecState
             spec_state = SpecState.get_instance()
             spec_state.configure(save_path=save_spec_path)
@@ -103,12 +110,25 @@ class AgentToolkit:
         self.register_tool(GlobTool(self.connection))
         self.register_tool(WebTool(self.connection))
 
+        # Register skill tools and load skills
+        self._register_skill_tools()
+
         # Register read-only file tools (always available)
         self.register_tool(ReadFileTool(self._repo_root, self.connection))
         self.register_tool(ListFilesTool(self._repo_root, self.connection))
 
-        # Register write tools (only in non-plan mode)
-        if not self.plan_mode:
+        # Register write tools
+        if self.plan_mode:
+            # In plan mode: only allow writing to the plan file
+            if self.plan_file_path:
+                from .tools.coding import WriteToFileTool
+                self.register_tool(WriteToFileTool(
+                    self._repo_root,
+                    self.connection,
+                    allowed_paths=[self.plan_file_path],
+                ))
+        else:
+            # In code mode: full write access
             from .tools.coding import (
                 WriteToFileTool,
                 ApplyDiffTool,
@@ -123,8 +143,15 @@ class AgentToolkit:
         # Register sub-agent tools for spawning lightweight agents
         self._register_subagent_tools()
 
-        # Register task management tools (not in plan mode)
-        if not self.plan_mode:
+        # Register mode tools
+        self._register_mode_tools()
+
+        # Register task management tools
+        # In plan mode: only register ask_followup_question for clarifications
+        # In code mode: register all task tools
+        if self.plan_mode:
+            self._register_plan_mode_task_tools()
+        else:
             self._register_task_tools()
 
         # Register spec planning tools (only in plan mode)
@@ -153,6 +180,36 @@ class AgentToolkit:
         self.register_tool(TaskTool(repo_root=self._repo_root, connection=self.connection))
         self.register_tool(TaskOutputTool(repo_root=self._repo_root, connection=self.connection))
 
+    def _register_mode_tools(self) -> None:
+        """Register mode switching tools.
+
+        - enter_plan_mode: Available in code mode to request entering plan mode
+        - exit_plan: Available in both modes to submit plan for approval
+        - get_mode: Always available to check current mode
+        """
+        from .tools.modes import EnterPlanModeTool, ExitPlanModeTool, GetModeTool
+
+        # get_mode is always available
+        self.register_tool(GetModeTool())
+
+        # exit_plan is available in both modes:
+        # - In plan mode: submit plan written to plan file
+        # - In code mode: submit plan received from Plan subagent
+        self.register_tool(ExitPlanModeTool())
+
+        if not self.plan_mode:
+            # In code mode: can also request to enter plan mode
+            self.register_tool(EnterPlanModeTool())
+
+    def _register_plan_mode_task_tools(self) -> None:
+        """Register subset of task tools for plan mode.
+
+        In plan mode, the agent can ask clarifying questions but
+        doesn't need completion/todo tools since exit_plan handles that.
+        """
+        from .tools.tasks import AskFollowupQuestionTool
+        self.register_tool(AskFollowupQuestionTool())
+
     def _register_task_tools(self) -> None:
         """Register task management tools.
 
@@ -187,6 +244,29 @@ class AgentToolkit:
         self.register_tool(GetSpecTool())
         self.register_tool(UpdateSpecTool())
 
+    def _register_skill_tools(self) -> None:
+        """Register skill tools and load skills from .emdash/skills/.
+
+        Skills are markdown-based instruction files that teach the agent
+        how to perform specific, repeatable tasks. Similar to Claude Code's
+        skills system.
+        """
+        from .tools.skill import SkillTool, ListSkillsTool
+        from .skills import SkillRegistry
+
+        # Load skills from .emdash/skills/
+        skills_dir = self._repo_root / ".emdash" / "skills"
+        registry = SkillRegistry.get_instance()
+        registry.load_skills(skills_dir)
+
+        # Register skill tools
+        self.register_tool(SkillTool(self.connection))
+        self.register_tool(ListSkillsTool(self.connection))
+
+        skills_count = len(registry.list_skills())
+        if skills_count > 0:
+            log.info(f"Registered skill tools with {skills_count} skills available")
+
     def _register_mcp_tools(self) -> None:
         """Register GitHub MCP tools if available.
 

emdash_core/agent/toolkits/plan.py

@@ -1,19 +1,22 @@
-"""Plan toolkit - exploration tools plus plan writing capability."""
+"""Plan toolkit - read-only exploration tools for planning.
+
+The Plan subagent explores the codebase and returns a plan as text.
+The main agent (in plan mode) writes the plan to .emdash/<feature>.md.
+"""
 
 from pathlib import Path
 
 from .base import BaseToolkit
 from ..tools.coding import ReadFileTool, ListFilesTool
 from ..tools.search import SemanticSearchTool, GrepTool, GlobTool
-from ..tools.plan_write import WritePlanTool
 from ...utils.logger import log
 
 
 class PlanToolkit(BaseToolkit):
-    """Toolkit for planning with limited write access (plan files only).
+    """Read-only toolkit for Plan subagent.
 
-    Provides all read-only exploration tools plus the ability to write
-    implementation plans to .emdash/plans/*.md.
+    The Plan subagent explores the codebase and returns a structured plan.
+    It does NOT write files - the main agent handles that.
 
     Tools available:
     - read_file: Read file contents
@@ -21,7 +24,6 @@ class PlanToolkit(BaseToolkit):
     - glob: Find files by pattern
     - grep: Search file contents
     - semantic_search: AI-powered code search
-    - write_plan: Write implementation plans (restricted to .emdash/plans/)
     """
 
     TOOLS = [
@@ -30,11 +32,10 @@ class PlanToolkit(BaseToolkit):
         "glob",
         "grep",
         "semantic_search",
-        "write_plan",
     ]
 
     def _register_tools(self) -> None:
-        """Register exploration and plan writing tools."""
+        """Register read-only exploration tools."""
         # All read-only exploration tools
         self.register_tool(ReadFileTool(repo_root=self.repo_root))
         self.register_tool(ListFilesTool(repo_root=self.repo_root))
@@ -49,7 +50,4 @@ class PlanToolkit(BaseToolkit):
         except Exception as e:
             log.debug(f"Semantic search not available: {e}")
 
-        # Special: can only write to .emdash/plans/*.md
-        self.register_tool(WritePlanTool(repo_root=self.repo_root))
-
         log.debug(f"PlanToolkit registered {len(self._tools)} tools")

emdash_core/agent/tools/__init__.py

@@ -43,7 +43,7 @@ from .tasks import (
 from .plan import PlanExplorationTool
 
 # Mode tools
-from .modes import AgentMode, ModeState, SwitchModeTool, GetModeTool
+from .modes import AgentMode, ModeState, EnterPlanModeTool, ExitPlanModeTool, GetModeTool
 
 # Spec tools
 from .spec import SubmitSpecTool, GetSpecTool, UpdateSpecTool
@@ -111,7 +111,8 @@ __all__ = [
     # Mode
     "AgentMode",
     "ModeState",
-    "SwitchModeTool",
+    "EnterPlanModeTool",
+    "ExitPlanModeTool",
     "GetModeTool",
     # Spec
     "SubmitSpecTool",

emdash_core/agent/tools/coding.py

@@ -64,6 +64,8 @@ Returns the file content as text."""
         path: str,
         start_line: Optional[int] = None,
         end_line: Optional[int] = None,
+        offset: Optional[int] = None,
+        limit: Optional[int] = None,
     ) -> ToolResult:
         """Read a file.
 
@@ -71,6 +73,8 @@ Returns the file content as text."""
             path: Path to the file
             start_line: Optional starting line (1-indexed)
             end_line: Optional ending line (1-indexed)
+            offset: Alternative to start_line - line number to start from (1-indexed)
+            limit: Alternative to end_line - number of lines to read
 
         Returns:
             ToolResult with file content
@@ -89,8 +93,14 @@ Returns the file content as text."""
             content = full_path.read_text()
             lines = content.split("\n")
 
-            # Handle line ranges
-            if start_line or end_line:
+            # Handle line ranges - support both start_line/end_line and offset/limit
+            # offset/limit take precedence if provided
+            if offset is not None or limit is not None:
+                start_idx = (offset - 1) if offset else 0
+                end_idx = start_idx + limit if limit else len(lines)
+                lines = lines[start_idx:end_idx]
+                content = "\n".join(lines)
+            elif start_line or end_line:
                 start_idx = (start_line - 1) if start_line else 0
                 end_idx = end_line if end_line else len(lines)
                 lines = lines[start_idx:end_idx]
@@ -123,6 +133,14 @@ Returns the file content as text."""
                     "type": "integer",
                     "description": "Ending line number (1-indexed)",
                 },
+                "offset": {
+                    "type": "integer",
+                    "description": "Line number to start reading from (1-indexed). Alternative to start_line.",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Number of lines to read. Alternative to end_line.",
+                },
             },
             required=["path"],
         )
@@ -135,6 +153,18 @@ class WriteToFileTool(CodingTool):
     description = """Write content to a file.
 Creates the file if it doesn't exist, or overwrites if it does."""
 
+    def __init__(self, repo_root: Path, connection=None, allowed_paths: list[str] | None = None):
+        """Initialize with optional path restrictions.
+
+        Args:
+            repo_root: Root directory of the repository
+            connection: Optional connection (not used for file ops)
+            allowed_paths: If provided, only these paths can be written to.
+                          Used in plan mode to restrict writes to the plan file.
+        """
+        super().__init__(repo_root, connection)
+        self.allowed_paths = allowed_paths
+
     def execute(
         self,
         path: str,
@@ -153,6 +183,19 @@ Creates the file if it doesn't exist, or overwrites if it does."""
         if not valid:
             return ToolResult.error_result(error)
 
+        # Check allowed paths restriction (used in plan mode)
+        if self.allowed_paths is not None:
+            path_str = str(full_path)
+            is_allowed = any(
+                path_str == allowed or path_str.endswith(allowed.lstrip("/"))
+                for allowed in self.allowed_paths
+            )
+            if not is_allowed:
+                return ToolResult.error_result(
+                    f"In plan mode, you can only write to: {', '.join(self.allowed_paths)}",
+                    suggestions=["Write your plan to the designated plan file"],
+                )
+
         try:
             # Create parent directories
             full_path.parent.mkdir(parents=True, exist_ok=True)
@@ -218,8 +261,9 @@ The diff should be in standard unified diff format."""
 
         try:
             # Try to apply with patch command
+            # --batch: suppress questions, --forward: skip already-applied patches
             result = subprocess.run(
-                ["patch", "-p0", "--forward"],
+                ["patch", "-p0", "--forward", "--batch"],
                 input=diff,
                 capture_output=True,
                 text=True,
@@ -230,7 +274,7 @@ The diff should be in standard unified diff format."""
             if result.returncode != 0:
                 # Try with -p1
                 result = subprocess.run(
-                    ["patch", "-p1", "--forward"],
+                    ["patch", "-p1", "--forward", "--batch"],
                     input=diff,
                     capture_output=True,
                     text=True,