patchfeld 0.2.2__tar.gz → 0.2.4__tar.gz

{patchfeld-0.2.2 → patchfeld-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchfeld
-Version: 0.2.2
+Version: 0.2.4
 Summary: A Textual TUI for managing multiple Claude Code agent sessions
 Project-URL: Homepage, https://github.com/jimmymills/patchfeld
 Project-URL: Repository, https://github.com/jimmymills/patchfeld
@@ -330,6 +330,30 @@ pip install patchfeld
 patchfeld
 ```
 
+### Updating
+
+Same tool you installed with — patchfeld releases regularly, so check for
+updates whenever something feels stale:
+
+```bash
+pipx upgrade patchfeld                  # if installed via pipx
+uv tool upgrade patchfeld               # if installed via `uv tool`
+pip install --upgrade patchfeld         # if installed via pip in a venv
+```
+
+To force a specific version (e.g., pinning or rolling back):
+
+```bash
+pipx install --force patchfeld==0.2.2
+uv tool install --force patchfeld==0.2.2
+pip install patchfeld==0.2.2
+```
+
+The latest release lives on
+[PyPI](https://pypi.org/project/patchfeld/) and tagged releases on
+[GitHub](https://github.com/jimmymills/patchfeld/releases) — release
+notes call out behavior changes and any migration steps.
+
 ### From source (for hacking on patchfeld itself)
 
 ```bash

{patchfeld-0.2.2 → patchfeld-0.2.4}/README.md

@@ -295,6 +295,30 @@ pip install patchfeld
 patchfeld
 ```
 
+### Updating
+
+Same tool you installed with — patchfeld releases regularly, so check for
+updates whenever something feels stale:
+
+```bash
+pipx upgrade patchfeld                  # if installed via pipx
+uv tool upgrade patchfeld               # if installed via `uv tool`
+pip install --upgrade patchfeld         # if installed via pip in a venv
+```
+
+To force a specific version (e.g., pinning or rolling back):
+
+```bash
+pipx install --force patchfeld==0.2.2
+uv tool install --force patchfeld==0.2.2
+pip install patchfeld==0.2.2
+```
+
+The latest release lives on
+[PyPI](https://pypi.org/project/patchfeld/) and tagged releases on
+[GitHub](https://github.com/jimmymills/patchfeld/releases) — release
+notes call out behavior changes and any migration steps.
+
 ### From source (for hacking on patchfeld itself)
 
 ```bash

{patchfeld-0.2.2 → patchfeld-0.2.4}/patchfeld/app.py

@@ -23,6 +23,8 @@ from patchfeld.layout.local_widgets import LocalWidgetLoader, LoadOutcome
 from patchfeld.layout.registry import WidgetRegistry
 from patchfeld.layout.spec import LayoutSpec
 from patchfeld.orchestrator.session import OrchestratorSession
+from patchfeld.orchestrator.skills import SkillsIndex, default_skills_index
+from patchfeld.orchestrator.slash_completion import SlashCompleter
 from patchfeld.persistence.layouts_store import NamedLayoutsStore
 from patchfeld.persistence.themes_store import NamedThemesStore
 from patchfeld.persistence.paths import global_config_dir, local_widgets_dir
@@ -340,6 +342,27 @@ class PatchfeldApp(App):
         # Unsub callable for the PermissionRequested handler; None when bypass mode.
         self._unsub_permission_requested: "callable | None" = None
 
+        # Discover locally-installed skills once at app construction. The
+        # set is reused on every orchestrator rebuild (after /cd or
+        # /bypass-permissions) so the user sees a stable list of `/<skill>`
+        # commands across sessions. To pick up a newly-installed skill,
+        # restart the app — same as the widget loader.
+        from patchfeld.orchestrator.session import (
+            _BUILTIN_COMMAND_NAMES as _ORCH_BUILTINS,
+        )
+        self._skills_index: SkillsIndex = default_skills_index(
+            builtin_command_names=_ORCH_BUILTINS,
+        )
+        # Tab-completion engine for `/`-prefixed commands. Both the top
+        # CommandBar and any OrchestratorChat input read this attribute
+        # via `getattr(self.app, "slash_completer", None)`. It's a snapshot
+        # taken once here so the candidate list is stable across orchestrator
+        # rebuilds (mirrors how _skills_index is reused above).
+        self.slash_completer: SlashCompleter = SlashCompleter.build(
+            builtin_commands=_ORCH_BUILTINS,
+            skills_index=self._skills_index,
+        )
+
         self.manager = manager or AgentManager(
             cwd=self.cwd,
             bus=self.event_bus,
@@ -360,6 +383,7 @@ class PatchfeldApp(App):
             current_layout=lambda: self._active_layout(),
             app=self,
             permission_grants=self._permission_grants,
+            skills=self._skills_index,
         )
         # Production opts in to LLM-summarized session titles.
         self.orchestrator._auto_title_enabled = True
@@ -1071,6 +1095,7 @@ class PatchfeldApp(App):
                 current_layout=lambda: self._active_layout(),
                 app=self,
                 permission_grants=self._permission_grants,
+                skills=self._skills_index,
             )
             self.orchestrator._auto_title_enabled = True
             await self.orchestrator.start()
@@ -1169,6 +1194,7 @@ class PatchfeldApp(App):
                 current_layout=lambda: self._active_layout(),
                 app=self,
                 permission_grants=self._permission_grants,
+                skills=self._skills_index,
             )
             self.orchestrator._auto_title_enabled = True
             await self.orchestrator.start()
@@ -1341,7 +1367,9 @@ class PatchfeldApp(App):
     # --- composition & lifecycle -------------------------------------------
 
     def compose(self) -> ComposeResult:
-        yield CommandBar(event_bus=self.event_bus)
+        yield CommandBar(
+            event_bus=self.event_bus, slash_completer=self.slash_completer,
+        )
         yield TabbedContent(id="app-tabs")
         yield StatusBar(event_bus=self.event_bus)
 

{patchfeld-0.2.2 → patchfeld-0.2.4}/patchfeld/orchestrator/session.py

@@ -38,6 +38,7 @@ from patchfeld.events import (
     UserMessageToOrchestrator,
 )
 
+from patchfeld.orchestrator.skills import SkillsIndex
 from patchfeld.orchestrator.tools import build_orchestrator_mcp_server
 from patchfeld.persistence.orchestrator_sessions import (
     OrchestratorSessionEntry,
@@ -58,8 +59,23 @@ _HELP_RE = re.compile(r"^/help\s*$")
 _CD_RE = re.compile(r"^/cd\s+(.+?)\s*$")
 _BYPASS_PERMS_RE = re.compile(r"^/bypass-permissions\s*$")
 _REQUIRE_PERMS_RE = re.compile(r"^/require-permissions\s*$")
-
-_HELP_TEXT = (
+# /<skill-name> <args...> — dispatch order is: built-in first, then skill,
+# then unknown-slash error. Name alphabet matches `_SKILL_NAME_RE` in
+# `patchfeld.orchestrator.skills`, anchored so we never match accidental
+# leading-slash text like "/path/to/file".
+_SKILL_RE = re.compile(r"^/([A-Za-z0-9][A-Za-z0-9_\-]*)(?:\s+(.*))?$")
+
+# Names of all built-in slash commands. Used for two purposes:
+#   1) Skill discovery logs a warning when a skill collides with one of these.
+#   2) An "unknown slash command" reply must NOT fire for these — but in
+#      practice the explicit per-command regexes already handle them, so this
+#      list is informational. Keep it in sync with the regexes above.
+_BUILTIN_COMMAND_NAMES: frozenset[str] = frozenset({
+    "reset", "resume", "rename", "help", "cd",
+    "bypass-permissions", "require-permissions",
+})
+
+_HELP_TEXT_BASE = (
     "Available commands:\n"
     "  /reset                     Start a fresh orchestrator session\n"
     "  /resume [<session_id>]     Resume a past session (no arg → picker)\n"
@@ -70,6 +86,42 @@ _HELP_TEXT = (
     "  /help                      Show this list"
 )
 
+
+def _format_skill_invocation(name: str, args: str) -> str:
+    """Translate `/<skill> <args>` into a prose prompt that nudges the LLM
+    to call the `Skill` tool with `skill=<name>` and `args=<args>`.
+
+    Implementation note: the harness's `Skill` tool uses two parameters —
+    `skill` (the bare name) and `args` (a free-form string). We surface both
+    explicitly. We also tell the model to invoke the skill *immediately* so
+    it doesn't ask clarifying questions before reading the SKILL.md body.
+    """
+    if args:
+        return (
+            f"Use the `Skill` tool to invoke the `{name}` skill now. "
+            f"Pass the following text as the `args` parameter: {args}"
+        )
+    return (
+        f"Use the `Skill` tool to invoke the `{name}` skill now "
+        f"(no extra arguments)."
+    )
+
+
+def _format_help_text(skills: SkillsIndex) -> str:
+    """Compose the /help reply: built-in commands plus a `Skills:` section
+    listing discovered skill names. The skills section is omitted entirely
+    when the index is empty so the output stays clean on bare installs."""
+    text = _HELP_TEXT_BASE
+    names = skills.names()
+    if not names:
+        return text
+    skills_line = "Skills: " + ", ".join(f"/{n}" for n in names)
+    note = (
+        "  (run any with `/<name> <args>` to invoke. Built-in commands above "
+        "win on name collisions — collided skills are still reachable via prose.)"
+    )
+    return text + "\n\n" + skills_line + "\n" + note
+
 _TITLE_PROMPT = (
     "Summarize the following user message in 5-7 words for use as a session "
     "title. Respond with ONLY the title — no quotes, no punctuation, no "
@@ -137,6 +189,7 @@ class OrchestratorSession:
         current_layout=None,
         app=None,
         permission_grants: PermissionGrants | None = None,
+        skills: SkillsIndex | None = None,
     ) -> None:
         self._cwd = cwd
         self._bus = bus
@@ -179,6 +232,9 @@ class OrchestratorSession:
         self._auto_title_enabled: bool = False
         self._title_task: asyncio.Task | None = None
         self._grants = permission_grants
+        # Skills registry (immutable for the lifetime of the session). Empty
+        # default keeps tests and headless callers from having to pass one.
+        self._skills: SkillsIndex = skills if skills is not None else SkillsIndex()
         self._can_use_tool_callback: CanUseTool | None = None
         if permission_grants is not None:
             self._perm_inbox: PermissionInbox | None = PermissionInbox(
@@ -509,9 +565,36 @@ class OrchestratorSession:
             )
             return
         if _HELP_RE.match(text):
-            self._publish_notice(_HELP_TEXT)
+            self._publish_notice(_format_help_text(self._skills))
+            return
+        # --- skill slash commands (after all built-ins) -------------------
+        # Built-ins win on name collisions: by the time we get here, every
+        # built-in regex has had its chance, so any `/name ...` left over is
+        # either a skill or unknown.
+        m = _SKILL_RE.match(text)
+        if m:
+            name = m.group(1)
+            args = (m.group(2) or "").strip()
+            entry = self._skills.get(name)
+            if entry is not None:
+                # Translate (design decision a): rewrite the slash line into a
+                # prose prompt that nudges the orchestrator's LLM to invoke
+                # the matching `Skill` tool. We don't synthesize a tool_use
+                # block ourselves — the SDK has no public seam for that.
+                self._send_tasks = [t for t in self._send_tasks if not t.done()]
+                rewritten = _format_skill_invocation(name, args)
+                task = self._inner.queue_send(rewritten)
+                self._send_tasks.append(task)
+                return
+            # Unknown slash — clear error rather than wasting tokens by
+            # forwarding `/<typo>` to the LLM as a raw prompt.
+            self._publish_notice(
+                f"unknown command or skill: /{name}. Try /help."
+            )
             return
-        # Fall through: ordinary prompt.
+        # Fall through: ordinary prompt (no leading slash, or a slash followed
+        # by something that doesn't look like a skill name — e.g. the user
+        # pasted "/path/to/file" as part of a sentence).
         if self._current_session_first_message is None:
             self._current_session_first_message = text
         self._send_tasks = [t for t in self._send_tasks if not t.done()]

patchfeld-0.2.4/patchfeld/orchestrator/skills.py

@@ -0,0 +1,193 @@
+"""Discovery + indexing of locally-installed Claude Code skills.
+
+A "skill" lives at one of:
+
+  - `~/.claude/skills/<name>/SKILL.md`
+      User-installed skills. Highest priority on collisions.
+  - `~/.claude/plugins/cache/<plugin>/<version>/skills/<name>/SKILL.md`
+      Plugin-shipped skills. Walked second; first occurrence per bare name
+      wins (subsequent duplicates log a `collision` warning).
+
+The orchestrator uses this index to expose `/<skill-name>` slash commands in
+the chat input. Discovery is performed once at orchestrator-session start
+(see `OrchestratorSession.__init__`) — re-scans require a restart, same as
+the existing widget loader. Per the implementation plan we picked design (a)
+"translate": when the user types `/<skill> <args>`, the orchestrator
+synthesizes a prose prompt that nudges the LLM to invoke the matching `Skill`
+tool. Discovery only needs the skill's *name* (not the body) — we never read
+SKILL.md content here.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+log = logging.getLogger(__name__)
+
+# Reused for the slash-command dispatch — only names matching this pattern
+# are exposed. Keeping it tight avoids weird shell-escaping edge cases. The
+# orchestrator's _SKILL_RE is anchored on this same alphabet.
+_SKILL_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_\-]*$")
+
+
+@dataclass(frozen=True)
+class SkillEntry:
+    """A discovered skill the orchestrator can route slash commands to."""
+
+    name: str
+    """Bare skill name (the directory name, e.g. `kb-query`)."""
+
+    path: str
+    """Absolute path to the `SKILL.md` file. Stored for diagnostics; we don't
+    need to read the body to invoke a skill via the `Skill` tool."""
+
+    source: str
+    """Where the skill was found: `"user"` for `~/.claude/skills/<name>` or
+    `"plugin"` for `~/.claude/plugins/cache/.../<name>`. Used for logging
+    and for collision-resolution rules (user wins)."""
+
+
+@dataclass
+class SkillsIndex:
+    """Bare-name → SkillEntry, populated by `discover_skills`."""
+
+    entries: dict[str, SkillEntry] = field(default_factory=dict)
+
+    def get(self, name: str) -> SkillEntry | None:
+        return self.entries.get(name)
+
+    def names(self) -> list[str]:
+        """Lexicographically-sorted skill names. Used by `/help` so output is
+        deterministic regardless of filesystem walk order."""
+        return sorted(self.entries.keys())
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self.entries
+
+
+def discover_skills(
+    *,
+    user_skills_dir: Path | None,
+    plugin_cache_dir: Path | None,
+    builtin_command_names: Iterable[str] = (),
+) -> SkillsIndex:
+    """Walk known locations, return a `SkillsIndex`.
+
+    Parameters
+    ----------
+    user_skills_dir : Path | None
+        Typically `~/.claude/skills`. If None or missing, skipped.
+    plugin_cache_dir : Path | None
+        Typically `~/.claude/plugins/cache`. If None or missing, skipped.
+    builtin_command_names : iterable of str
+        Names of orchestrator-internal slash commands (e.g. `cd`, `help`).
+        These do NOT cause the skill to be excluded — built-ins win at
+        dispatch time and the skill remains reachable via prose. We just
+        log a warning here so it's visible in production logs.
+
+    Notes
+    -----
+    - Each skill must live in its own directory containing a `SKILL.md` file.
+      We do not read the SKILL.md frontmatter — Claude Code's `Skill` tool
+      uses the directory name as the canonical identifier, and that's what
+      the orchestrator passes through.
+    - Walk order: user dir first (so user-installed copies win on collision),
+      then plugin cache. The plugin walk is bounded to depth 4 from the
+      cache root: `<plugin>/<version>/skills/<name>/SKILL.md`.
+    - Plugin-namespaced skills (e.g. `Notion:search`) are exposed under
+      their bare name (`search`). On collisions the first occurrence wins
+      — typically driven by directory iteration order, which is filesystem
+      dependent. A warning identifies the loser so a user can rename if
+      they care which copy is reachable via slash.
+    """
+    builtin_set = set(builtin_command_names)
+    entries: dict[str, SkillEntry] = {}
+
+    def _try_add(name: str, path: Path, source: str) -> None:
+        if not _SKILL_NAME_RE.match(name):
+            log.debug("skipping skill with non-slash-safe name: %r at %s",
+                      name, path)
+            return
+        if name in entries:
+            existing = entries[name]
+            log.warning(
+                "skill name collision: %r (kept %s copy at %s; "
+                "ignored %s copy at %s)",
+                name, existing.source, existing.path, source, path,
+            )
+            return
+        if name in builtin_set:
+            log.warning(
+                "skill name %r collides with a built-in slash command; the "
+                "built-in wins at dispatch but the skill remains reachable "
+                "via prose. (path=%s, source=%s)",
+                name, path, source,
+            )
+        entries[name] = SkillEntry(
+            name=name, path=str(path), source=source,
+        )
+
+    # --- user dir ---------------------------------------------------------
+    if user_skills_dir is not None and user_skills_dir.is_dir():
+        for child in sorted(user_skills_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            skill_md = child / "SKILL.md"
+            if not skill_md.is_file():
+                continue
+            _try_add(child.name, skill_md, source="user")
+
+    # --- plugin cache -----------------------------------------------------
+    if plugin_cache_dir is not None and plugin_cache_dir.is_dir():
+        # Layout: <cache>/<vendor>/<plugin>/<version>/skills/<skill_name>/SKILL.md
+        # Example: ~/.claude/plugins/cache/claude-plugins-official/superpowers/
+        #          5.1.0/skills/writing-plans/SKILL.md
+        # Per-plugin we pick the *highest lexicographic version directory*
+        # — for typical semver this lines up with the latest release (5.1.0
+        # > 5.0.7 lexicographically). Edge cases (5.10.0 vs 5.2.0) sort
+        # incorrectly under this rule; that's a known v1 limitation, and
+        # the workaround is to delete stale cache versions.
+        for vendor_dir in sorted(plugin_cache_dir.iterdir()):
+            if not vendor_dir.is_dir():
+                continue
+            for plugin_dir in sorted(vendor_dir.iterdir()):
+                if not plugin_dir.is_dir():
+                    continue
+                version_dirs = sorted(
+                    [d for d in plugin_dir.iterdir() if d.is_dir()],
+                )
+                if not version_dirs:
+                    continue
+                # Highest version wins.
+                version_dir = version_dirs[-1]
+                skills_root = version_dir / "skills"
+                if not skills_root.is_dir():
+                    continue
+                for skill_dir in sorted(skills_root.iterdir()):
+                    if not skill_dir.is_dir():
+                        continue
+                    skill_md = skill_dir / "SKILL.md"
+                    if not skill_md.is_file():
+                        continue
+                    _try_add(skill_dir.name, skill_md, source="plugin")
+
+    log.info("discovered %d skill(s): %s",
+             len(entries), sorted(entries.keys()))
+    return SkillsIndex(entries=entries)
+
+
+def default_skills_index(builtin_command_names: Iterable[str] = ()) -> SkillsIndex:
+    """Convenience wrapper that scans the canonical user paths.
+
+    Used by production wiring; tests pass a hand-built `SkillsIndex` instead.
+    """
+    home = Path.home()
+    return discover_skills(
+        user_skills_dir=home / ".claude" / "skills",
+        plugin_cache_dir=home / ".claude" / "plugins" / "cache",
+        builtin_command_names=builtin_command_names,
+    )