xtrm-tools 0.5.24 → 0.5.26

package/plugins/xtrm-tools/skills/using-service-skills/scripts/cataloger.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+Cataloger — SessionStart hook for using-service-skills.
+
+Reads .claude/skills/service-registry.json and prints a lightweight XML
+service catalog block (~150 tokens) to stdout. The SessionStart hook
+injects this as additional context so Claude knows which expert personas
+are available without loading full skill bodies (Progressive Disclosure).
+
+Configured in .claude/settings.json:
+  "SessionStart": [{"hooks": [{"type": "command",
+    "command": "python3 \\"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\\""}]}]
+
+Output format:
+  <project_service_catalog>
+  Available expert personas:
+  - db-expert: SQL & schema expert (Path: .claude/skills/db-expert/SKILL.md)
+  </project_service_catalog>
+  <instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>
+"""
+
+import sys
+from pathlib import Path
+
+# Bootstrap lives in creating-service-skills — shared utility
+BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
+sys.path.insert(0, str(BOOTSTRAP_DIR))
+
+from bootstrap import RootResolutionError, list_services  # noqa: E402
+
+
+def generate_catalog() -> str:
+    """
+    Generate the service catalog XML block.
+
+    Returns empty string if no services are registered or project root
+    cannot be determined (fails gracefully — never breaks session start).
+    """
+    try:
+        services = list_services()
+    except (RootResolutionError, Exception):
+        return ""
+
+    if not services:
+        return ""
+
+    lines = [
+        "<project_service_catalog>",
+        "Available expert personas:",
+    ]
+
+    for service_id, data in sorted(services.items()):
+        description = data.get("description", data.get("name", service_id))
+        skill_path = data.get("skill_path", f".claude/skills/{service_id}/SKILL.md")
+        lines.append(f"- {service_id}: {description} (Path: {skill_path})")
+
+    lines.append("</project_service_catalog>")
+    lines.append(
+        "<instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>"
+    )
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    """Print catalog to stdout — injected as SessionStart additional context."""
+    catalog = generate_catalog()
+    if catalog:
+        print(catalog)
+    # Silent if no services registered — don't break session start
+
+
+if __name__ == "__main__":
+    main()

package/plugins/xtrm-tools/skills/using-service-skills/scripts/skill_activator.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook: skill activator.
+
+Fires before Read, Write, Edit, Glob, Grep, or Bash operations.
+Checks whether the operation touches a registered service territory.
+If it does, injects additionalContext telling Claude to load the skill
+before proceeding — ensuring expert knowledge is always applied.
+
+Configured in .claude/settings.json PreToolUse hook.
+Must be fast: pure file I/O + string matching, no subprocess.
+"""
+
+import fnmatch
+import json
+import sys
+from pathlib import Path
+
+BOOTSTRAP_DIR = Path(__file__).parent.parent.parent / "creating-service-skills" / "scripts"
+sys.path.insert(0, str(BOOTSTRAP_DIR))
+
+from bootstrap import RootResolutionError, get_project_root, load_registry  # noqa: E402  # type: ignore[import-not-found]
+
+
+def match_territory(file_path: str, territory: list[str], project_root: Path) -> bool:
+    """Check if a file path matches any territory glob pattern."""
+    # Normalize to relative path
+    fp = Path(file_path)
+    if fp.is_absolute():
+        try:
+            fp = fp.relative_to(project_root)
+        except ValueError:
+            return False
+    rel = str(fp)
+
+    for pattern in territory:
+        # fnmatch handles * and ?, but not ** — handle ** manually
+        if "**" in pattern:
+            # Split on **/ and check prefix + suffix
+            parts = pattern.split("**/")
+            if len(parts) == 2:
+                prefix, suffix = parts
+                rel_check = rel[len(prefix) :] if rel.startswith(prefix) else rel
+                if fnmatch.fnmatch(rel_check, suffix) or fnmatch.fnmatch(
+                    rel, f"{prefix}*/{suffix}"
+                ):
+                    return True
+                # Also check if file is anywhere under the prefix dir
+                if prefix and rel.startswith(prefix.rstrip("/")):
+                    return True
+        else:
+            if fnmatch.fnmatch(rel, pattern):
+                return True
+        # Direct prefix match for broad patterns
+        base = pattern.split("/*")[0].split("/**")[0]
+        if base and (rel.startswith(base + "/") or rel == base):
+            return True
+
+    return False
+
+
+def find_service_for_file(
+    file_path: str, services: dict, project_root: Path
+) -> tuple[str, dict] | None:
+    """Return (service_id, service_data) if file is in any territory, else None."""
+    for service_id, data in services.items():
+        if match_territory(file_path, data.get("territory", []), project_root):
+            return service_id, data
+    return None
+
+
+def find_service_for_command(command: str, services: dict) -> tuple[str, dict] | None:
+    """Return (service_id, service_data) if command mentions a service name."""
+    cmd_lower = command.lower()
+    for service_id, data in services.items():
+        # Match service_id directly or as a container name in docker commands
+        if service_id in cmd_lower:
+            return service_id, data
+        # Match the container name pattern (service name with dashes/underscores)
+        if data.get("name") and data.get("name", "").lower().replace(" ", "-") in cmd_lower:
+            return service_id, data
+    return None
+
+
+def build_context(service_id: str, data: dict) -> str:
+    skill_path = data.get("skill_path", f".claude/skills/{service_id}/SKILL.md")
+    desc = data.get("description", "")
+    desc_line = f"\n  What it covers: {desc}" if desc else ""
+
+    return (
+        f"[Service Skill] You are about to work with the '{service_id}' service territory."
+        f"{desc_line}\n"
+        f"  Load the expert skill before proceeding: Read {skill_path}\n"
+        f"  The skill contains: operational knowledge, failure modes, diagnostic scripts, "
+        f"and the correct methods for managing this service.\n"
+        f"  Do not use ad-hoc approaches (raw SQL, improvised docker commands) "
+        f"when the skill defines the correct method."
+    )
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    try:
+        project_root = Path(get_project_root())
+        services = load_registry().get("services", {})
+    except (RootResolutionError, Exception):
+        sys.exit(0)
+
+    if not services:
+        sys.exit(0)
+
+    match = None
+
+    # File-based tools: check file_path against territory
+    if tool_name in ("Read", "Write", "Edit", "Glob", "Grep", "NotebookRead", "NotebookEdit"):
+        file_path = (
+            tool_input.get("file_path")
+            or tool_input.get("path")
+            or tool_input.get("notebook_path")
+            or ""
+        )
+        if file_path:
+            match = find_service_for_file(file_path, services, project_root)
+
+    # Bash: check command string for service names
+    elif tool_name == "Bash":
+        command = tool_input.get("command", "")
+        if command:
+            match = find_service_for_command(command, services)
+
+    if match:
+        service_id, service_data = match
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "additionalContext": build_context(service_id, service_data),
+            }
+        }
+        print(json.dumps(output))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/plugins/xtrm-tools/skills/using-service-skills/scripts/test_skill_activator.py

@@ -0,0 +1,58 @@
+"""Tests for skill_activator.py — load_registry integration."""
+import io
+import json
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+scripts_dir = Path(__file__).parent
+sys.path.insert(0, str(scripts_dir))
+sys.path.insert(0, str(scripts_dir.parent.parent / "creating-service-skills" / "scripts"))
+
+import skill_activator
+
+
+REGISTRY_WITH_VERSION = {
+    "version": "1.0",
+    "services": {
+        "my-service": {
+            "territory": ["src/my-service/**"],
+            "name": "My Service",
+            "skill_path": ".claude/skills/my-service/SKILL.md",
+        }
+    },
+}
+
+HOOK_INPUT = json.dumps({
+    "tool_name": "Write",
+    "tool_input": {"file_path": "src/my-service/foo.py"},
+    "hook_event_name": "PreToolUse",
+    "session_id": "test",
+    "cwd": "/fake/project",
+})
+
+
+class TestMainWithVersionedRegistry(unittest.TestCase):
+    def test_main_does_not_crash_when_registry_has_version_key(self):
+        """main() must not crash with AttributeError when load_registry returns
+        {"version": ..., "services": {...}} — the full registry dict.
+        It should output valid JSON context for the matched service.
+        """
+        with patch("skill_activator.load_registry", return_value=REGISTRY_WITH_VERSION), \
+             patch("skill_activator.get_project_root", return_value="/fake/project"), \
+             patch("sys.stdin", io.StringIO(HOOK_INPUT)), \
+             patch("sys.stdout", new_callable=io.StringIO) as mock_stdout:
+            try:
+                skill_activator.main()
+            except SystemExit:
+                pass
+            output = mock_stdout.getvalue()
+
+        self.assertTrue(output, "Expected JSON output but got nothing")
+        result = json.loads(output)
+        self.assertIn("hookSpecificOutput", result)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/xtrm-tools/skills/using-xtrm/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: using-xtrm
+description: >
+  Behavioral operating manual for an xtrm-equipped Claude Code session.
+  Covers when to use which tool, how to handle questions and triggers,
+  workflow examples, and skill routing. Reference material (hook list,
+  gate rules, full bd commands, git workflow) lives in CLAUDE.md.
+  Injected automatically at session start via additionalSystemPrompt.
+priority: high
+---
+
+# XTRM — When to Use What
+
+> Gates, commands, and git workflow are in CLAUDE.md.
+> This is the behavioral layer: triggers, patterns, examples.
+
+## Session Start
+
+```bash
+bd prime                          # load workflow context + active claims
+bd memories <today's topic>       # retrieve relevant past context
+bd ready                          # find available work
+bd update <id> --claim            # claim before any edit
+```
+
+---
+
+## Trigger Patterns
+
+| Situation | Action |
+|-----------|--------|
+| User prompt contains `?` | `bd memories <keywords>` before answering — check stored context first |
+| "What was I working on?" | `bd list --status=in_progress` |
+| Unfamiliar area of code | `gitnexus_query({query: "concept"})` before opening any file |
+| About to edit a symbol | `gitnexus_impact({target: "name", direction: "upstream"})` |
+| Before `git commit` | `gitnexus_detect_changes({scope: "staged"})` to verify scope |
+| Reading code | `get_symbols_overview` → `find_symbol` — never read whole files |
+| Task is tests | use /test-planning
+| Task is docs updates | use /sync-docs
+| Session end (issue closed) | Memory gate fires — evaluate `bd remember` for each closed issue |
+
+---
+
+## Handling `?` Prompts
+
+When the user's message contains a question, check stored context before answering:
+
+```bash
+bd memories <keywords from question>   # search project memory
+bd recall <key>                        # retrieve specific memory if key is known
+```
+
+Example — user asks *"why does the quality gate run twice?"*:
+```bash
+bd memories "quality gate"
+# → "quality-check.cjs and quality-check.py are separate hooks —
+#    JS/TS and Python each get their own PostToolUse pass"
+```
+
+If it's a code question, also run:
+```bash
+gitnexus_query({query: "<topic>"})     # find relevant execution flows
+```
+
+---
+
+## Workflow Examples
+
+**Fixing a bug:**
+```bash
+bd ready                                                        # find the issue
+bd update bd-xyz --claim                                        # claim it
+gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
+# → 2 callers, LOW risk — safe to edit
+get_symbols_overview("hooks/init.ts")                           # map file
+find_symbol("parseComposeServices", include_body=True)          # read just this
+replace_symbol_body("parseComposeServices", newBody)            # Serena edit
+bd close bd-xyz --reason="Fix YAML parse edge case"            # close + auto-commit
+xt end                                                         # push, PR, merge, cleanup
+```
+
+**Exploring unfamiliar code:**
+```bash
+gitnexus_query({query: "session claim enforcement"})
+# → beads-gate-core.mjs, resolveClaimAndWorkState, decideCommitGate
+gitnexus_context({name: "resolveClaimAndWorkState"})            # callers + callees
+get_symbols_overview("hooks/beads-gate-core.mjs")               # map the file
+find_symbol("resolveClaimAndWorkState", include_body=True)      # read only this
+```
+
+**Persisting an insight:**
+```bash
+bd remember "quality-check runs twice: separate .cjs (JS) and .py (Python) hooks"
+# retrievable next session:
+bd memories "quality check"
+bd recall "quality-check-runs-twice-..."
+```
+
+---
+
+## Prompt Shaping (silent, before every non-trivial task)
+
+| Task type | Apply |
+|-----------|-------|
+| `analyze / investigate / why` | `<thinking>` block + structured `<outputs>` |
+| `implement / build / fix` | 1-2 `<example>` blocks + `<constraints>` |
+| `refactor / simplify` | `<constraints>` (preserve behavior, tests pass) + `<current_state>` |
+
+Vague prompt (under 8 words, no specifics)? Ask one clarifying question before proceeding.
+
+---
+
+## Skill Routing
+
+| Need | Use |
+|------|-----|
+| Code read / edit | Serena — `get_symbols_overview` → `find_symbol` → `replace_symbol_body` |
+| Blast radius before edit | `gitnexus-impact-analysis` |
+| Navigate unfamiliar code | `gitnexus-exploring` |
+| Trace a bug | `gitnexus-debugging` |
+| Safe rename / refactor | `gitnexus-refactoring` |
+| Docs maintenance | `sync-docs` |
+| Docker service project | `using-service-skills` |
+| Build / improve a skill | `skill-creator` |

package/plugins/xtrm-tools/skills/xt-end/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: xt-end
+description: |
+  Autonomous session close flow for xt worktree sessions. Use this skill whenever
+  the user says "done", "finished", "wrap up", "close session", "ship it", "I'm done",
+  "ready to merge", or similar. Also activate when all beads issues in the session
+  are closed, or when the user explicitly runs /xt-end. This skill guides the agent
+  through pre-flight checks, commit cleanup, PR creation via 'xt end', conflict
+  resolution, and worktree cleanup — handling every edge case so the agent doesn't
+  need to figure it out from scratch.
+---
+
+# xt-end — Session Close Flow
+
+You are closing an `xt` worktree session. The canonical CLI is `xt end`, but it has preconditions you need to satisfy first. Work through these stages in order.
+
+## Stage 1 — Pre-flight: close all open work
+
+Run:
+```bash
+bd list --status=in_progress
+bd list --status=open
+```
+
+If any issues are still open or in_progress, **do not proceed**. Guide the user to finish them first:
+- For in-progress work: complete it, then `bd close <id> --reason "what was done"`
+- For open issues that won't be done in this session: ask the user — close as deferred, or leave for next session?
+
+Only continue when `bd list --status=in_progress` returns empty (or the user explicitly says to skip unfinished issues).
+
+## Stage 2 — Uncommitted changes
+
+```bash
+git status
+```
+
+If the working tree is dirty:
+- If the changes belong to a beads issue you just closed: `git add -A && git commit -m "<close_reason> (<id>)"` (or a descriptive summary)
+- If the changes are unrelated WIP: consider stashing with `git stash` and noting what was stashed
+- Never run `xt end` with a dirty working tree — it will abort with an error
+
+## Stage 3 — Dry run (preview the PR)
+
+```bash
+xt end --dry-run
+```
+
+This shows the PR title, body, files changed, and issues that will be linked. Review with the user:
+- Does the PR title accurately reflect the work?
+- Are all the right issues captured?
+- Is the scope correct?
+
+If something looks wrong, adjust (e.g., add a missing commit message or close a forgotten issue) and re-run the dry run.
+
+## Stage 4 — Run xt end
+
+```bash
+xt end
+```
+
+### If it succeeds
+You'll see:
+- ✓ Rebased onto origin/main
+- ✓ Pushed branch
+- ✓ PR created: <url>
+- ✓ Linked PR to N issue(s)
+
+Capture the PR URL for Stage 6.
+
+### If rebase conflicts occur
+
+`xt end` will abort cleanly with a list of conflicted files. Guide the agent through:
+
+```bash
+git status                          # see conflicted files
+# Edit each conflicted file to resolve <<<< ==== >>>> markers
+git add <resolved-files>
+git rebase --continue
+```
+
+Then re-run `xt end`. If the conflicts are complex, explain what each file conflict is about before resolving.
+
+### If the push fails
+
+Usually a stale remote ref. Try:
+```bash
+git fetch origin main
+xt end
+```
+
+## Stage 5 — Worktree cleanup
+
+After a clean PR creation, ask the user:
+
+> "PR is open at <url>. Should I remove this worktree? (Recommended: yes, since the branch is pushed and the PR is open. Keep only if you plan to do follow-up work here.)"
+
+Default recommendation: **remove** (the branch is safe on remote, the worktree is just disk space).
+
+If removing:
+```bash
+xt end --keep   # was already run; use git worktree remove directly
+git worktree remove <path> --force
+```
+
+Or if `xt end` was run interactively, it already prompted for this — just confirm.
+
+## Stage 6 — Report
+
+Tell the user:
+- PR URL
+- Which issues were linked
+- Reminder: "Monitor CI — merge when green. No auto-merge."
+
+If the worktree was removed: confirm that too.
+
+---
+
+## Edge cases
+
+**Already on main branch**: `xt end` will error — you're not in an xt session. Don't run it from main.
+
+**No commits yet on branch**: The PR will have no changes. This usually means something went wrong earlier. Verify with `git log origin/main..HEAD`.
+
+**`gh` CLI not authenticated**: `gh pr create` will fail. Fix: `gh auth login`, then re-run `xt end`.
+
+**Multiple conflicts**: Resolve all files before `git rebase --continue`. If `git status` shows unmerged paths, keep resolving.
+
+**beads not available**: `xt end` gracefully skips beads linkage if `bd` isn't running. The PR still gets created. Let the user know.