patchfeld 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchfeld
-Version: 0.2.2
+Version: 0.2.3
 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

{patchfeld-0.2.2 → patchfeld-0.2.3}/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.3}/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.3/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,
+    )

patchfeld-0.2.3/patchfeld/orchestrator/slash_completion.py

@@ -0,0 +1,247 @@
+"""Tab completion for `/`-prefixed slash commands in chat input boxes.
+
+Both the top `CommandBar` and the `OrchestratorChat` input use this helper to
+turn a Tab keypress into an in-place completion against the union of:
+
+  - the orchestrator's built-in slash commands (`/help`, `/cd`, ...) — i.e.
+    the same names that drive `_BUILTIN_COMMAND_NAMES` in
+    `patchfeld.orchestrator.session`, AND
+  - every locally-installed skill discovered by
+    `patchfeld.orchestrator.skills.discover_skills`.
+
+The candidate set is a snapshot taken at orchestrator-session-start (matching
+how the slash-dispatch path freezes the same set), so the same `SkillsIndex`
+is reused — discovery is *not* duplicated.
+
+Behaviour (v1):
+
+  - First Tab on `/<prefix>` completes to the first alphabetical match plus
+    a single trailing space; cursor goes to end-of-text.
+  - Repeated Tabs without intervening edits cycle through subsequent matches
+    (Shift+Tab cycles backward). After the last, wrap.
+  - Any text edit (typing or Backspace) breaks the cycle anchor — the next
+    Tab starts a fresh cycle from the new prefix.
+  - No completion is offered when the input does not start with `/`, is
+    empty, or contains a space outside an active cycle (so `/cd /Use<Tab>`
+    falls through to Textual's default Tab focus traversal — path
+    completion is out of scope).
+  - Cycle state is per-widget (keyed by an opaque string) so two inputs do
+    not interfere.
+
+No dropdown UI in v1; the input value just changes in place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from textual.suggester import Suggester
+
+from patchfeld.orchestrator.skills import SkillsIndex
+
+
+@dataclass(frozen=True)
+class CompletionResult:
+    """Outcome of a single Tab press the input widget should apply.
+
+    Attributes
+    ----------
+    text:
+        The full new value of the input box (already includes leading slash
+        and trailing space).
+    cursor:
+        Position to move the input cursor to. Always end-of-text in v1.
+    """
+
+    text: str
+    cursor: int
+
+
+@dataclass
+class SlashCompleter:
+    """Per-session completion engine.
+
+    Construct via :meth:`build` so the candidate list is computed once,
+    sorted, and deduped. The instance is shared across input widgets — cycle
+    state is partitioned by `key` (typically the Input widget's id).
+    """
+
+    _candidates: tuple[str, ...]
+    """Bare command names (without leading slash), sorted alphabetically."""
+
+    _cycle_state: dict[str, dict] = field(default_factory=dict)
+    """Per-key snapshot of the active cycle.
+
+    Shape: `{key: {"matches": [...], "index": int, "last_set": str}}`. The
+    `last_set` value is the full text we last wrote into the widget — when
+    the next Tab arrives we compare to detect "user did not edit between
+    presses", which is what licences cycling instead of restarting.
+    """
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        builtin_commands: Iterable[str],
+        skills_index: SkillsIndex | None = None,
+    ) -> "SlashCompleter":
+        """Snapshot the candidate set.
+
+        Names from `builtin_commands` and `skills_index.names()` are merged
+        (set-union for dedupe) and sorted alphabetically. Pass an empty
+        index for tests/headless callers.
+        """
+        names: set[str] = set(builtin_commands)
+        if skills_index is not None:
+            names.update(skills_index.names())
+        return cls(_candidates=tuple(sorted(names)))
+
+    # --- read-only inspection --------------------------------------------
+
+    def candidates(self) -> tuple[str, ...]:
+        """Bare names, sorted. Useful for diagnostics; widgets call `match`
+        or `cycle` instead."""
+        return self._candidates
+
+    # --- pure prefix matching --------------------------------------------
+
+    def match(self, prefix: str) -> list[str]:
+        """Return commands (with leading slash) whose name starts with
+        `prefix`, case-insensitively. `prefix` must include the leading
+        slash; pass `/` to retrieve every candidate.
+
+        Returns `[]` if `prefix` does not start with `/` so callers can
+        delegate the "is this even a slash" check to one place.
+        """
+        if not prefix.startswith("/"):
+            return []
+        pfx_lower = prefix.lower()
+        return [
+            f"/{name}"
+            for name in self._candidates
+            if f"/{name}".lower().startswith(pfx_lower)
+        ]
+
+    # --- cycle bookkeeping -----------------------------------------------
+
+    def reset(self, key: str) -> None:
+        """Forget any cycle state for `key`. Inputs call this on edit
+        events (typing, Backspace, value programmatically cleared) so the
+        next Tab starts fresh."""
+        self._cycle_state.pop(key, None)
+
+    @staticmethod
+    def _is_fresh_trigger(text: str) -> bool:
+        """A Tab press starts a fresh cycle only when the value looks like
+        a single command word: leading `/`, no whitespace anywhere. Empty
+        strings and free-form prose return False so the binding falls
+        through to Textual's default Tab focus traversal."""
+        if not text.startswith("/"):
+            return False
+        # Any whitespace (including the trailing-space we ourselves write
+        # after a completion) disqualifies a fresh trigger; the cycle path
+        # below recognises our own writes via `last_set` so the user can
+        # still continue an in-flight cycle.
+        return not any(ch.isspace() for ch in text)
+
+    def cycle(
+        self,
+        *,
+        key: str,
+        current_text: str,
+        direction: int = 1,
+    ) -> CompletionResult | None:
+        """Compute the next completion for input identified by `key`.
+
+        Returns ``None`` when the keypress should fall through to Textual's
+        default Tab handling — the widget reads ``None`` as "I'm not
+        consuming this Tab".
+
+        Parameters
+        ----------
+        key:
+            Stable identifier for the input widget (typically its DOM id).
+        current_text:
+            The input's current value.
+        direction:
+            ``+1`` to advance through matches (Tab); ``-1`` to step back
+            (Shift+Tab).
+        """
+        # --- continuing an in-flight cycle? ---
+        state = self._cycle_state.get(key)
+        if state is not None and state.get("last_set") == current_text:
+            matches: list[str] = state["matches"]
+            if not matches:
+                return None
+            new_idx = (state["index"] + direction) % len(matches)
+            return self._record_and_emit(key, matches, new_idx)
+
+        # --- otherwise, must look like a fresh `/<word>` trigger ---
+        if not self._is_fresh_trigger(current_text):
+            self._cycle_state.pop(key, None)
+            return None
+
+        matches = self.match(current_text)
+        if not matches:
+            self._cycle_state.pop(key, None)
+            return None
+
+        # Forward starts at index 0; backward starts at the last match so
+        # Shift+Tab on a fresh trigger jumps to the alphabetical tail (the
+        # natural inverse of forward-from-zero).
+        start_idx = 0 if direction >= 0 else len(matches) - 1
+        return self._record_and_emit(key, matches, start_idx)
+
+    def _record_and_emit(
+        self, key: str, matches: list[str], idx: int,
+    ) -> CompletionResult:
+        """Persist cycle state and return the rendered completion. Always
+        appends a single trailing space — every slash command can take args,
+        so the unconditional space is the cheapest right-default."""
+        chosen = matches[idx]
+        new_text = chosen + " "
+        self._cycle_state[key] = {
+            "matches": matches,
+            "index": idx,
+            "last_set": new_text,
+        }
+        return CompletionResult(text=new_text, cursor=len(new_text))
+
+
+class SlashSuggester(Suggester):
+    """Textual `Suggester` adapter exposing a `SlashCompleter`'s first
+    match as in-input ghost text.
+
+    The Textual `Input` widget polls a `Suggester` whenever its value
+    changes; if `get_suggestion(value)` returns a string that has `value`
+    as a (case-insensitive) prefix, Input renders the suffix in a faded
+    color after the cursor — the user sees what Tab is about to fill.
+
+    We share `SlashCompleter` rather than carry our own candidate set so
+    the preview cannot drift from the Tab-completion behaviour: identical
+    trigger predicate, identical match function, identical sort order →
+    the previewed command is always the very command Tab will fill.
+    """
+
+    def __init__(self, completer: SlashCompleter) -> None:
+        # use_cache=False because the underlying SkillsIndex is already a
+        # cheap dict lookup — caching adds nothing — and disabling it
+        # avoids surprising staleness if anyone ever swaps the completer
+        # at runtime. case_sensitive=False so the user sees a sensible
+        # preview when they type `/K` and the canonical command is
+        # lowercase (`/kb-query`).
+        super().__init__(use_cache=False, case_sensitive=False)
+        self._completer = completer
+
+    async def get_suggestion(self, value: str) -> str | None:
+        # Re-use the same trigger predicate that gates the Tab handler so
+        # the preview can never appear in positions where Tab is a no-op
+        # (mid-argument, no leading slash, trailing space after a fresh
+        # completion, …).
+        if not SlashCompleter._is_fresh_trigger(value):
+            return None
+        matches = self._completer.match(value)
+        if not matches:
+            return None
+        return matches[0]

{patchfeld-0.2.2 → patchfeld-0.2.3}/patchfeld/widgets/chrome.py

@@ -6,6 +6,7 @@ from textual.containers import Horizontal
 from textual.widgets import Input, Static
 
 from patchfeld.events import EventBus, OrchestratorReply, UserMessageToOrchestrator
+from patchfeld.orchestrator.slash_completion import SlashCompleter, SlashSuggester
 
 
 def _format_cwd(path: Path, *, available_width: int) -> str:
@@ -54,9 +55,19 @@ class CommandBar(Horizontal):
     }
     """
 
-    def __init__(self, *, event_bus: EventBus | None = None) -> None:
+    def __init__(
+        self,
+        *,
+        event_bus: EventBus | None = None,
+        slash_completer: SlashCompleter | None = None,
+    ) -> None:
         super().__init__()
         self._bus = event_bus
+        # Optional injected completer. When unset we fall back to the host
+        # app's `slash_completer` attribute on first use — production wiring
+        # exposes one there at app construction so newly-mounted CommandBars
+        # share the same snapshot across `/cd` rebuilds.
+        self._completer = slash_completer
         # True between a command-bar submit and the next OrchestratorReply.
         # Gates the toast so replies from other input surfaces (the
         # orchestrator chat panel) don't pop a toast as well.
@@ -74,6 +85,18 @@ class CommandBar(Horizontal):
         bus = self._bus or getattr(self.app, "event_bus", None)
         if bus is not None:
             self._unsub_reply = bus.subscribe(OrchestratorReply, self._on_reply)
+        # Attach the ghost-text suggester after mount so we can fall back to
+        # `app.slash_completer` when no completer was injected at construction.
+        # Set every time on_mount fires (theme/cwd swap rebuilds the widget)
+        # so the suggester always points at the live completer instance.
+        completer = self._resolve_completer()
+        if completer is not None:
+            try:
+                self.query_one("#cmd-input", Input).suggester = (
+                    SlashSuggester(completer)
+                )
+            except Exception:
+                pass
 
     def on_unmount(self) -> None:
         self._unsub_reply()
@@ -81,6 +104,66 @@ class CommandBar(Horizontal):
     def focus_input(self) -> None:
         self.query_one("#cmd-input", Input).focus()
 
+    def _resolve_completer(self) -> SlashCompleter | None:
+        """Late-bound completer lookup: prefer the constructor-injected one,
+        fall back to whatever the host app exposes. Returning None disables
+        completion entirely (Tab falls through)."""
+        if self._completer is not None:
+            return self._completer
+        return getattr(self.app, "slash_completer", None)
+
+    def on_key(self, event) -> None:
+        """Intercept Tab / Shift+Tab to apply slash-command completion in
+        place. When completion does not apply (no completer, empty input,
+        text without a leading slash, mid-argument), we leave the event
+        alone so Textual's default focus traversal still runs."""
+        if event.key not in ("tab", "shift+tab"):
+            return
+        completer = self._resolve_completer()
+        if completer is None:
+            return
+        try:
+            inp = self.query_one("#cmd-input", Input)
+        except Exception:
+            return
+        # Only intercept when the input owns focus — otherwise we'd shadow
+        # Tab traversal between widgets.
+        if not inp.has_focus:
+            return
+        direction = -1 if event.key == "shift+tab" else 1
+        result = completer.cycle(
+            key=inp.id or "cmd-input",
+            current_text=inp.value,
+            direction=direction,
+        )
+        if result is None:
+            return  # let Tab fall through to focus_next/_previous
+        inp.value = result.text
+        try:
+            inp.cursor_position = result.cursor
+        except Exception:
+            pass
+        event.stop()
+        event.prevent_default()
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Reset the completer's cycle state on any user-driven edit. The
+        cycle path detects "user did not edit between Tabs" by comparing
+        the input value to its own last write — that comparison stays
+        correct without an explicit reset, but wiping state here also
+        frees memory once the user moves on to a different prefix."""
+        if event.input.id != "cmd-input":
+            return
+        completer = self._resolve_completer()
+        if completer is None:
+            return
+        # Skip resets that fired as a side-effect of our own write — those
+        # cases keep the cycle anchor intact so consecutive Tabs advance.
+        state = completer._cycle_state.get(event.input.id or "cmd-input")
+        if state is not None and state.get("last_set") == event.input.value:
+            return
+        completer.reset(event.input.id or "cmd-input")
+
     def on_input_submitted(self, event: Input.Submitted) -> None:
         if not event.value.strip():
             return

patchfeld-0.2.3/patchfeld/widgets/orchestrator_chat.py

@@ -0,0 +1,140 @@
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.widgets import Input
+
+from patchfeld.events import EventBus, UserMessageToOrchestrator
+from patchfeld.orchestrator.slash_completion import SlashCompleter, SlashSuggester
+from patchfeld.widgets.rich_transcript import RichTranscript
+
+
+class OrchestratorChat(Vertical):
+    """Manager-Claude chat panel: RichTranscript + input box."""
+
+    AGENT_ID = "orchestrator"
+    DEFAULT_BORDER_TITLE = "Orchestrator"
+
+    DEFAULT_CSS = """
+    OrchestratorChat {
+        border: round $primary;
+        padding: 0 1;
+    }
+    OrchestratorChat > RichTranscript {
+        height: 1fr;
+    }
+    OrchestratorChat #orch-input {
+        dock: bottom;
+        height: 3;
+    }
+    """
+
+    # priority=True so the binding fires even when the Input child has
+    # focus — without it, ctrl+c is consumed by Textual's default driver
+    # handling (which would quit the app).
+    BINDINGS = [
+        Binding("ctrl+c", "interrupt", "interrupt orchestrator", priority=True),
+    ]
+
+    def __init__(self, *, event_bus: EventBus | None = None) -> None:
+        super().__init__()
+        self._bus = event_bus
+
+    def compose(self) -> ComposeResult:
+        path = None
+        try:
+            orch = getattr(self.app, "orchestrator", None)
+            if orch is not None:
+                path = orch.active_transcript_path
+        except Exception:
+            path = None
+        yield RichTranscript(
+            agent_id=self.AGENT_ID, event_bus=self._bus, transcript_path=path,
+        )
+        yield Input(
+            placeholder=(
+                "Message orchestrator… "
+                "(/reset, /resume, /rename, /help, ctrl+c to interrupt)"
+            ),
+            id="orch-input",
+        )
+
+    def on_mount(self) -> None:
+        """Attach the ghost-text suggester to the chat input as soon as we
+        have access to the host app's `slash_completer`. Re-runs on every
+        remount (theme/cwd swap rebuilds this widget) so the suggester
+        always points at the live completer instance."""
+        completer = self._resolve_completer()
+        if completer is not None:
+            try:
+                self.query_one("#orch-input", Input).suggester = (
+                    SlashSuggester(completer)
+                )
+            except Exception:
+                pass
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        if not event.value.strip():
+            return
+        text = event.value
+        bus = self._bus or getattr(self.app, "event_bus", None)
+        event.input.value = ""
+        if bus is not None:
+            bus.publish(UserMessageToOrchestrator(text))
+
+    def _resolve_completer(self) -> SlashCompleter | None:
+        """Late-bound lookup of the host app's SlashCompleter. None disables
+        Tab completion (Tab falls through to default focus traversal)."""
+        return getattr(self.app, "slash_completer", None)
+
+    def on_key(self, event) -> None:
+        """Apply slash-command completion in place when the chat input owns
+        focus, the value triggers completion (`/` prefix, no whitespace
+        outside an active cycle), and there is at least one match. Falls
+        through silently otherwise — Textual's default Tab traversal still
+        runs."""
+        if event.key not in ("tab", "shift+tab"):
+            return
+        completer = self._resolve_completer()
+        if completer is None:
+            return
+        try:
+            inp = self.query_one("#orch-input", Input)
+        except Exception:
+            return
+        if not inp.has_focus:
+            return
+        direction = -1 if event.key == "shift+tab" else 1
+        result = completer.cycle(
+            key=inp.id or "orch-input",
+            current_text=inp.value,
+            direction=direction,
+        )
+        if result is None:
+            return
+        inp.value = result.text
+        try:
+            inp.cursor_position = result.cursor
+        except Exception:
+            pass
+        event.stop()
+        event.prevent_default()
+
+    def on_input_changed(self, event: Input.Changed) -> None:
+        """Drop cycle state on edits the user (not us) made — keeps the
+        completer's per-widget state from leaking across unrelated prefixes.
+        Detection mirrors `CommandBar.on_input_changed`."""
+        if event.input.id != "orch-input":
+            return
+        completer = self._resolve_completer()
+        if completer is None:
+            return
+        state = completer._cycle_state.get(event.input.id or "orch-input")
+        if state is not None and state.get("last_set") == event.input.value:
+            return
+        completer.reset(event.input.id or "orch-input")
+
+    async def action_interrupt(self) -> None:
+        orch = getattr(self.app, "orchestrator", None)
+        if orch is None:
+            return
+        await orch.interrupt()

{patchfeld-0.2.2 → patchfeld-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchfeld"
-version = "0.2.2"
+version = "0.2.3"
 description = "A Textual TUI for managing multiple Claude Code agent sessions"
 readme = "README.md"
 requires-python = ">=3.11"

patchfeld-0.2.2/patchfeld/widgets/orchestrator_chat.py

@@ -1,73 +0,0 @@
-from textual.app import ComposeResult
-from textual.binding import Binding
-from textual.containers import Vertical
-from textual.widgets import Input
-
-from patchfeld.events import EventBus, UserMessageToOrchestrator
-from patchfeld.widgets.rich_transcript import RichTranscript
-
-
-class OrchestratorChat(Vertical):
-    """Manager-Claude chat panel: RichTranscript + input box."""
-
-    AGENT_ID = "orchestrator"
-    DEFAULT_BORDER_TITLE = "Orchestrator"
-
-    DEFAULT_CSS = """
-    OrchestratorChat {
-        border: round $primary;
-        padding: 0 1;
-    }
-    OrchestratorChat > RichTranscript {
-        height: 1fr;
-    }
-    OrchestratorChat #orch-input {
-        dock: bottom;
-        height: 3;
-    }
-    """
-
-    # priority=True so the binding fires even when the Input child has
-    # focus — without it, ctrl+c is consumed by Textual's default driver
-    # handling (which would quit the app).
-    BINDINGS = [
-        Binding("ctrl+c", "interrupt", "interrupt orchestrator", priority=True),
-    ]
-
-    def __init__(self, *, event_bus: EventBus | None = None) -> None:
-        super().__init__()
-        self._bus = event_bus
-
-    def compose(self) -> ComposeResult:
-        path = None
-        try:
-            orch = getattr(self.app, "orchestrator", None)
-            if orch is not None:
-                path = orch.active_transcript_path
-        except Exception:
-            path = None
-        yield RichTranscript(
-            agent_id=self.AGENT_ID, event_bus=self._bus, transcript_path=path,
-        )
-        yield Input(
-            placeholder=(
-                "Message orchestrator… "
-                "(/reset, /resume, /rename, /help, ctrl+c to interrupt)"
-            ),
-            id="orch-input",
-        )
-
-    def on_input_submitted(self, event: Input.Submitted) -> None:
-        if not event.value.strip():
-            return
-        text = event.value
-        bus = self._bus or getattr(self.app, "event_bus", None)
-        event.input.value = ""
-        if bus is not None:
-            bus.publish(UserMessageToOrchestrator(text))
-
-    async def action_interrupt(self) -> None:
-        orch = getattr(self.app, "orchestrator", None)
-        if orch is None:
-            return
-        await orch.interrupt()