xtrm-tools 0.5.0

package/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/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/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/skills/using-xtrm/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: using-xtrm
+description: >
+  Operating manual for an xtrm-equipped Claude Code session. Activates automatically at
+  session start to orient the agent on how to work within the xtrm stack: when to apply
+  prompt improvement, how the beads issue-tracking gate works, which hooks enforce workflows,
+  and how to compose the full toolset (gitnexus, Serena, quality gates, delegation).
+  Use this skill whenever a new session begins in an xtrm-tools-installed environment, or
+  when the user asks how to work with the xtrm stack, what tools are available, or how any
+  xtrm workflow operates.
+priority: high
+---
+
+# Using xtrm — Session Operating Manual
+
+You are in an **xtrm-equipped Claude Code environment**. This skill orients you on *how to work*
+within this stack. Read it at session start and refer back when uncertain about a workflow.
+
+---
+
+## Stack at a Glance
+
+| Layer | What it provides |
+|---|---|
+| **Skills** | Domain expertise loaded on demand |
+| **Hooks** | Automated lifecycle enforcement (gates, suggestions, reminders) |
+| **Project Data (`xtrm init`)** | Per-repo bootstrap data (`.beads/`, `service-registry.json`, GitNexus index) |
+| **MCP Servers** | Semantic tools: Serena (code), gitnexus (graph), context7 (docs), deepwiki |
+| **CLI** | `xtrm install / status / finish / reset / help` — sync and closure tooling |
+| **beads (bd)** | Git-backed issue tracker with session gate enforcement |
+
+---
+
+## Core Principle: Prompt First, Then Work
+
+Before executing any non-trivial task, improve the prompt mentally using XML structure.
+Apply this silently — the user sees your improved execution, not the meta-work.
+
+### Prompt Classification
+
+Scan the user's message for task type:
+
+| Type | Keywords | Enhancement |
+|---|---|---|
+| **ANALYSIS** | analyze, investigate, research, explain, why | Add `<thinking>` block, structure `<outputs>` |
+| **DEV** | implement, create, build, add, fix, feature | Add 1-2 `<example>` blocks, define `<constraints>` |
+| **REFACTOR** | refactor, improve, optimize, clean, simplify | Add `<constraints>` (preserve behavior, tests pass) + `<current_state>` |
+
+### XML Prompt Structure
+
+```xml
+<task_name>
+  <description>What needs to be done and why</description>
+  <parameters>Relevant context: files, symbols, constraints</parameters>
+  <instructions>
+    Step-by-step approach
+  </instructions>
+  <!-- ANALYSIS tasks: -->
+  <thinking>Work through hypotheses before concluding</thinking>
+  <outputs>Expected result format</outputs>
+  <!-- DEV tasks: -->
+  <example>Concrete pattern to follow</example>
+  <!-- REFACTOR tasks: -->
+  <constraints>Must not break X, tests must pass, preserve API surface</constraints>
+</task_name>
+```
+
+When a prompt is vague (under 8 words, no specifics), ask one clarifying question before
+proceeding. Don't ask about things you can reasonably infer.
+
+---
+
+## Beads + Session Flow — Session Protocol
+
+This environment enforces a **beads session gate** plus **session-flow lifecycle gate**.
+You cannot edit files without a claim, and you cannot safely end a closure-in-progress session.
+
+```bash
+# 1. Claim before editing
+bd list --status=open
+bd update <id> --claim
+# hook auto-sets session claim + auto-creates worktree + writes .xtrm-session-state.json
+
+# 2. Work in the claimed branch/worktree
+
+# 3. Close issue when implementation is done
+bd close <id>
+
+# 4. Session close protocol (single command)
+xtrm finish
+# blocking: commit/push/pr-create/auto-merge poll/worktree cleanup
+```
+
+**Key rules:**
+- One active claim per session
+- Always work on a **feature branch**, never directly on `main`/`master`
+- `main-guard.mjs` blocks edits on protected branches
+- `beads-stop-gate.mjs` blocks stop for closure phases: `waiting-merge`, `conflicting`, `pending-cleanup`
+- If blocked on stop: resolve state then re-run `xtrm finish`
+
+---
+
+## Code Editing — Serena LSP Workflow
+
+Always use semantic tools. Never read entire large files or use generic Edit unless forced.
+
+```
+get_symbols_overview(file)           → map the file structure first
+find_symbol(name, include_body=true) → read only what you need
+find_referencing_symbols(name)       → check callers before changing signatures
+replace_symbol_body(name, body)      → atomic symbol-level edit
+insert_after_symbol / insert_before_symbol → add new code precisely
+```
+
+**Activate project first** (required once per session):
+```
+mcp__serena__activate_project("<project-name>")
+```
+
+**Fallback**: Use `Edit` only for non-code files or when a symbol can't be located.
+
+---
+
+## Code Intelligence — gitnexus Workflow
+
+Before editing any function, class, or method — always run impact analysis.
+
+```bash
+# 1. Before editing
+npx gitnexus impact <symbolName> --direction upstream
+
+# 2. Understand a symbol fully
+gitnexus_context({name: "symbolName"})
+
+# 3. Find code by concept (instead of grepping)
+gitnexus_query({query: "concept"})
+
+# 4. Before committing — verify scope
+gitnexus_detect_changes({scope: "staged"})
+```
+
+**Risk levels**: d=1 = WILL BREAK (must fix), d=2 = likely affected (should test), d=3 = transitive (test if critical).
+
+If index is stale: `npx gitnexus analyze` before using MCP tools.
+
+> **Note**: gitnexus MCP server and CLI share an exclusive DB lock — they cannot run concurrently.
+> Use CLI (`npx gitnexus ...`) when MCP is active, or stop MCP first.
+
+---
+
+## Quality Gates — Automatic on Every Edit
+
+After each file edit, quality-gates hooks run automatically:
+- **TypeScript**: ESLint + tsc type check
+- **Python**: Ruff lint + mypy type check
+
+You do not invoke these manually — they fire via PostToolUse hooks. If a gate fails, fix the
+lint/type error before continuing. Do not suppress errors with `// eslint-disable` or `# type: ignore`
+unless there is a genuine reason.
+
+> **Global-first behavior**: quality-gates hooks are global; no per-project install is needed.
+> Run `xtrm init` once per repository to bootstrap project data, then ensure the repo has
+> `eslint.config.*` (TS) or `pyproject.toml` / `ruff.toml` (Python) configured so checks can run.
+
+---
+
+## Skill Routing — When to Use What
+
+| Situation | Use |
+|---|---|
+| Short/vague user prompt | Apply XML structure silently (this skill) or `/prompt-improving` |
+| Simple task (tests, docs, typo fix) | `/delegating` → cost-optimized agent |
+| Complex task needing second opinion | `/orchestrate adversarial "task"` |
+| Reading/editing code | `using-serena-lsp` (Serena MCP) |
+| Understanding code architecture | `gitnexus-exploring` |
+| Tracing a bug | `gitnexus-debugging` |
+| Changing a function | `gitnexus-impact-analysis` first, then Serena edit |
+| Safe rename/refactor | `gitnexus-refactoring` |
+| Docker service project | `using-service-skills` → activate expert persona |
+| Writing new feature | Write tests alongside, quality gates auto-run after |
+| Maintaining docs | `/documenting` (Serena SSOT drift detection) |
+| Building/improving a skill | `skill-creator` |
+
+---
+
+## Available Skills (Full Catalog)
+
+**Workflow:**
+`prompt-improving`, `delegating`, `orchestrating-agents`, `using-serena-lsp`, `documenting`,
+`using-xtrm` (this skill), `skill-creator`, `find-skills`
+
+**Code Intelligence:**
+`gitnexus-exploring`, `gitnexus-debugging`, `gitnexus-impact-analysis`, `gitnexus-refactoring`
+
+**Domain Experts:**
+`senior-backend`, `senior-devops`, `senior-security`, `senior-data-scientist`,
+`docker-expert`, `python-testing`, `clean-code`
+
+**Integrations:**
+`obsidian-cli`, `hook-development`, `claude-api`
+
+**Global-first note:**
+`quality-gates` and `service-skills` workflows are globally available after `xtrm install all`.
+Use `xtrm init` to provision per-project data (beads + service-registry + GitNexus index).
+
+---
+
+## Hook Enforcement Summary
+
+These hooks run automatically — you cannot disable them mid-session:
+
+| Hook | Trigger | Effect |
+|---|---|---|
+| `main-guard.mjs` | PreToolUse (Edit/Write/Serena/Bash) | Blocks edits and unsafe Bash on protected branches |
+| `beads-edit-gate.mjs` | PreToolUse (Edit/Write/Serena) | Blocks edits without active claim |
+| `beads-commit-gate.mjs` | PreToolUse (Bash: git commit) | Blocks commit with unclosed claim |
+| `beads-claim-sync.mjs` | PostToolUse (Bash claim command) | Syncs claim + creates worktree + writes session state |
+| `beads-stop-gate.mjs` | Stop | Blocks stop for unresolved session-flow phases |
+| `beads-memory-gate.mjs` | Stop | Prompts for persistent insights after closure |
+| `beads-compact-save/restore.mjs` | PreCompact / SessionStart | Preserves claim + session state across compact |
+| `serena-workflow-reminder.py` | SessionStart | Reminds semantic editing workflow |
+| `quality-check.(cjs|py)` | PostToolUse (Edit/Write) | Runs lint + type checks automatically |
+
+---
+
+## MCP Servers
+
+| Server | Use for | Setup |
+|---|---|---|
+| `serena` | Semantic code reading/editing | Auto-detected; activate project per session |
+| `gitnexus` | Knowledge graph, impact analysis | `npm install -g gitnexus` + `npx gitnexus analyze` per project |
+| `context7` | Library documentation lookup | No setup needed (free stdio transport) |
+| `deepwiki` | Technical docs for GitHub repos | No setup needed |
+| `github-grep` | Code search across GitHub | No setup needed |
+
+---
+
+## Checklist Before Finishing Any Task
+
+1. `gitnexus_detect_changes(...)` — confirms only expected files/flows changed
+2. All d=1 dependents updated (if any signal from impact analysis)
+3. Tests pass (targeted + relevant integration)
+4. Beads issue closed: `bd close <id>`
+5. Run `xtrm finish` for blocking closure lifecycle
+6. Verify session state reached `cleanup-done` (or intentional re-entry state)

package/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.