xtrm-tools 2.0.0

package/project-skills/service-skills-set/.claude/skills/scoping-service-skills/scripts/scope.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+scope.py — Read service-registry.json and output a formatted service catalog.
+
+Used by the /scope skill to provide registry data for agent reasoning before
+any files are touched. The agent uses this output to map a task description
+to the relevant registered service(s).
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def find_registry() -> Path | None:
+    # 1. CLAUDE_PROJECT_DIR env var (set by Claude Code hooks)
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if project_dir:
+        p = Path(project_dir) / ".claude" / "skills" / "service-registry.json"
+        if p.exists():
+            return p
+
+    # 2. Walk up from CWD until .git boundary
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        p = parent / ".claude" / "skills" / "service-registry.json"
+        if p.exists():
+            return p
+        if (parent / ".git").exists():
+            break
+
+    return None
+
+
+def main() -> None:
+    registry_path = find_registry()
+
+    if not registry_path:
+        print("ERROR: service-registry.json not found.")
+        print("Run /creating-service-skills to set up service skills first.")
+        sys.exit(1)
+
+    try:
+        with open(registry_path, encoding="utf-8") as f:
+            registry = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"ERROR: service-registry.json is malformed: {e}")
+        sys.exit(1)
+
+    services = registry.get("services", {})
+    if not services:
+        print("Registry is empty — no services registered.")
+        sys.exit(0)
+
+    print(f"Registry  : {registry_path}")
+    print(f"Version   : {registry.get('version', 'unknown')}")
+    print(f"Services  : {len(services)} registered")
+    print("─" * 60)
+
+    for service_id, info in services.items():
+        territories = ", ".join(info.get("territory", [])) or "—"
+        print(f"\n[{service_id}]")
+        print(f"  Container  : {info.get('container', 'unknown')}")
+        print(f"  Territory  : {territories}")
+        print(f"  Skill      : {info.get('skill_path', 'unknown')}")
+        print(f"  Description: {info.get('description', '—')}")
+
+    print("\n" + "─" * 60)
+    print("Map the task description to the service(s) above, then load their skills.")
+
+
+if __name__ == "__main__":
+    main()

package/project-skills/service-skills-set/.claude/skills/updating-service-skills/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: updating-service-skills
+description: >-
+  Detect implementation drift and sync expert persona documentation.
+  Activates automatically via PostToolUse hook when files in a registered
+  service territory are modified. Use when a skill's documentation has
+  fallen behind the actual implementation.
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py\" check-hook"
+          timeout: 10
+allowed-tools: Read, Write, Grep, Glob
+---
+
+# Updating Service Skills
+
+## Role: The Librarian
+
+You are the **Service Skills Librarian**. Your job is to keep expert persona
+documentation in sync with the actual implementation as the codebase evolves.
+
+---
+
+## Automatic Drift Detection
+
+After any `Write` or `Edit` operation, the `PostToolUse` hook runs
+`drift_detector.py check-hook`. It reads the modified file path from stdin JSON
+and checks whether it falls within a registered service territory.
+
+If drift is detected, you will see this in your context:
+
+```
+[Skill Sync]: Implementation drift detected in 'db-expert'.
+File 'src/db/users.ts' was modified.
+Use '/updating-service-skills' to sync the Database Expert documentation.
+```
+
+---
+
+## Manual Sync Process
+
+### Step 1 — Scan for all drift
+
+```bash
+python3 "$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py" scan
+```
+
+### Step 2 — Read the current skill
+
+```
+Read: .claude/skills/<service-id>/SKILL.md
+```
+
+### Step 3 — Analyze changes using Serena tools
+
+Use Serena LSP tools (not raw file reads) to understand what changed:
+
+```
+get_symbols_overview(<modified-file>, depth=1)
+find_symbol(<changed-function>, include_body=True)
+search_for_pattern("<new-pattern>")
+```
+
+### Step 4 — Update the skill documentation
+
+- Add new patterns or conventions discovered
+- Update Failure Modes table if new exception handlers added
+- Update log patterns in `scripts/log_hunter.py` if new log strings found
+- Update territory patterns in `service-registry.json` if scope expanded
+- Preserve `<!-- SEMANTIC_START --> ... <!-- SEMANTIC_END -->` blocks
+
+### Step 5 — Mark as synced
+
+```bash
+python3 "$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py" \
+  sync <service-id>
+```
+
+---
+
+## Drift Scenarios
+
+### New error pattern added to codebase
+
+1. `search_for_pattern("raise.*New.*Error|logger.error.*new")` to find it
+2. Add to `scripts/log_hunter.py` PATTERNS list with correct severity
+3. Update Troubleshooting table in SKILL.md
+
+### Territory expanded (new directory added)
+
+1. Check if current glob patterns in `service-registry.json` cover new files
+2. If not, update `territory` array in `service-registry.json`
+3. Sync timestamp
+
+### Major refactor changes conventions
+
+1. `get_symbols_overview` on all changed files
+2. Rewrite relevant Guidelines section in SKILL.md
+3. Update health_probe.py if table structure or ports changed
+
+---
+
+## Tool Restrictions
+
+Write to:
+- ✅ `.claude/skills/*/SKILL.md` — skill documentation updates
+- ✅ `.claude/skills/service-registry.json` — territory and sync timestamp updates
+
+Do not:
+- ❌ Modify source code (read-only access to service territories)
+- ❌ Delete skills or registry entries
+
+---
+
+## Sync Output Format
+
+```
+✅ Skill Synced: `<service-id>`
+
+Updated:
+- log_hunter.py: added 2 new patterns from exception handlers
+- SKILL.md: Failure Modes table updated with OAuth expiry scenario
+- Territory: unchanged
+
+Next sync: triggers on next modification to <territory-patterns>
+```
+
+---
+
+## Related Skills
+
+- `/using-service-skills` — Discover and activate expert personas
+- `/creating-service-skills` — Scaffold new expert personas

package/project-skills/service-skills-set/.claude/skills/updating-service-skills/scripts/drift_detector.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Drift detector — PostToolUse hook for updating-service-skills.
+
+Checks whether a modified file belongs to a registered service territory.
+If so, notifies Claude to sync the skill documentation.
+
+Configured via updating-service-skills/SKILL.md frontmatter hooks:
+  PostToolUse → matcher: "Write|Edit" → command: drift_detector.py check-hook
+
+Subcommands:
+  check-hook          Read file_path from stdin JSON (PostToolUse hook mode)
+  check <file>        Check a specific file path from CLI
+  sync <service-id>   Mark service as synced (update registry timestamp)
+  scan                Scan all territories for drifted services
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+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 (  # noqa: E402
+    RootResolutionError,
+    find_service_for_path,
+    get_project_root,
+    get_service,
+    load_registry,
+    save_registry,
+)
+
+
+def check_drift(file_path: str, project_root: str | None = None) -> dict:
+    """Check if a file change causes drift in any registered service territory."""
+    if project_root is None:
+        try:
+            project_root = get_project_root()
+        except RootResolutionError:
+            return {"drift": False, "reason": "Cannot resolve project root"}
+
+    # Normalize to relative path
+    fp = Path(file_path)
+    if fp.is_absolute():
+        try:
+            fp = fp.relative_to(project_root)
+            file_path = str(fp)
+        except ValueError:
+            pass
+
+    service_id = find_service_for_path(file_path, project_root)
+    if not service_id:
+        return {"drift": False, "reason": "No service owns this file"}
+
+    service = get_service(service_id, project_root)
+    if not service:
+        return {"drift": False, "reason": "Service not found in registry"}
+
+    return {
+        "drift": True,
+        "service_id": service_id,
+        "service_name": service.get("name", service_id),
+        "skill_path": service.get("skill_path"),
+        "last_sync": service.get("last_sync", ""),
+        "file_path": file_path,
+        "message": (
+            f"[Skill Sync]: Implementation drift detected in '{service_id}'. "
+            f"File '{file_path}' was modified. "
+            f"Use '/updating-service-skills' to sync the {service.get('name', service_id)} documentation."
+        ),
+    }
+
+
+def check_drift_from_hook_stdin() -> None:
+    """
+    PostToolUse hook mode: reads file_path from stdin JSON.
+
+    The PostToolUse hook delivers stdin JSON with shape:
+      {"tool_name": "Write", "tool_input": {"file_path": "/abs/path"}, ...}
+
+    Outputs drift message to stdout (shown to Claude via PostToolUse additionalContext).
+    Exits 0 always — drift detection is advisory, never blocking.
+    """
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        sys.exit(0)
+
+    tool_input = data.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not file_path:
+        sys.exit(0)
+
+    result = check_drift(file_path)
+
+    if result.get("drift"):
+        # Output additionalContext for Claude via PostToolUse JSON format
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": result["message"],
+            }
+        }
+        print(json.dumps(output))
+
+    sys.exit(0)
+
+
+def update_sync_time(service_id: str, project_root: str | None = None) -> bool:
+    """Update last_sync timestamp for a service in the registry."""
+    try:
+        registry = load_registry(project_root)
+    except Exception:
+        return False
+
+    if "services" not in registry or service_id not in registry["services"]:
+        return False
+
+    registry["services"][service_id]["last_sync"] = (
+        datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    try:
+        save_registry(registry, project_root)
+        return True
+    except Exception:
+        return False
+
+
+def scan_drift(project_root: str | None = None) -> list[dict]:
+    """Scan all territories and identify services with files modified since last sync."""
+    if project_root is None:
+        try:
+            project_root = get_project_root()
+        except RootResolutionError:
+            return []
+
+    root = Path(project_root)
+    registry = load_registry(project_root)
+    drifted: list[dict] = []
+
+    for service_id, service in registry.get("services", {}).items():
+        last_sync_str = service.get("last_sync", "")
+        if not last_sync_str:
+            continue
+        try:
+            sync_time = datetime.fromisoformat(last_sync_str.replace("Z", "+00:00"))
+        except ValueError:
+            continue
+
+        for pattern in service.get("territory", []):
+            for fp in root.glob(pattern):
+                if fp.is_file():
+                    try:
+                        mtime = datetime.fromtimestamp(fp.stat().st_mtime, tz=timezone.utc)
+                        if mtime > sync_time:
+                            drifted.append(
+                                {
+                                    "service_id": service_id,
+                                    "service_name": service.get("name", service_id),
+                                    "file_path": str(fp.relative_to(root)),
+                                    "last_sync": last_sync_str,
+                                }
+                            )
+                    except (OSError, ValueError):
+                        continue
+
+    return drifted
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python drift_detector.py <command> [args...]")
+        print("  check-hook          — Read file from stdin JSON (PostToolUse hook mode)")
+        print("  check <file>        — Check a specific file path")
+        print("  sync <service-id>   — Mark service as synced")
+        print("  scan                — Scan all territories for drift")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+
+    if cmd == "check-hook":
+        check_drift_from_hook_stdin()
+
+    elif cmd == "check" and len(sys.argv) > 2:
+        result = check_drift(sys.argv[2])
+        if result.get("drift"):
+            print(result["message"])
+        else:
+            print(f"No drift: {result.get('reason', 'OK')}")
+
+    elif cmd == "sync" and len(sys.argv) > 2:
+        service_id = sys.argv[2]
+        if update_sync_time(service_id):
+            print(f"✓ Synced: {service_id}")
+        else:
+            print(f"✗ Failed to sync: {service_id}")
+            sys.exit(1)
+
+    elif cmd == "scan":
+        drifted = scan_drift()
+        if drifted:
+            print(f"Found {len(drifted)} drifted service(s):")
+            for item in drifted:
+                print(
+                    f"  {item['service_id']}: {item['file_path']} "
+                    f"(last sync: {item['last_sync']})"
+                )
+        else:
+            print("No drift detected.")
+
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/project-skills/service-skills-set/.claude/skills/using-service-skills/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: using-service-skills
+description: >-
+  Service catalog discovery and expert persona activation.
+  At session start, a catalog of registered expert personas is injected
+  automatically. Use this skill to discover, understand, and activate
+  the right expert for any task.
+allowed-tools: Read, Glob
+---
+
+# Using Service Skills
+
+## Role: The Concierge
+
+You are the **Service Skills Concierge**. Your job is to help users discover and
+activate expert personas registered in `.claude/skills/service-registry.json`.
+
+---
+
+## How the Catalog Works
+
+At session start, the `SessionStart` hook (configured in `.claude/settings.json`)
+runs `cataloger.py` and injects a lightweight XML block into your context:
+
+```xml
+<project_service_catalog>
+Available expert personas:
+- db-expert: SQL & schema optimization (Path: .claude/skills/db-expert/SKILL.md)
+- auth-service: JWT authentication expert (Path: .claude/skills/auth-service/SKILL.md)
+</project_service_catalog>
+<instruction>To activate an expert, read its SKILL.md from the provided path.</instruction>
+```
+
+This costs ~150 tokens per session regardless of how many experts are registered
+(Progressive Disclosure: full skill bodies are loaded only when needed).
+
+---
+
+## Workflow
+
+### 1. Check the Injected Catalog
+
+When a user asks about a service or starts a related task, check whether a
+`<project_service_catalog>` block is present in your context.
+
+If no catalog was injected (e.g. first run, no services registered), generate one:
+
+```bash
+python3 "$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py"
+```
+
+### 2. Activate an Expert Persona
+
+When a task matches an expert's domain, read that skill's SKILL.md:
+
+```
+Read: .claude/skills/<service-id>/SKILL.md
+```
+
+Then adopt the expert's persona, constraints, and knowledge for the duration
+of the task.
+
+**Example:**
+```
+User: "Optimize this database query"
+You:  [Catalog shows db-expert matches]
+      [Read .claude/skills/db-expert/SKILL.md]
+      [Apply Senior Database Engineer persona and expertise]
+```
+
+### 3. Handle Missing Experts
+
+If no registered expert covers the user's need:
+1. Inform the user no expert exists for this domain
+2. Offer to create one: "I can create a service skill using `/creating-service-skills`"
+
+---
+
+## Session Start Hook
+
+The catalog injection is **not** handled by skill frontmatter hooks (SessionStart
+is not supported in skill-level hooks). It is configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""
+      }]
+    }]
+  }
+}
+```
+
+---
+
+## Tool Restrictions
+
+Read-only — no write access:
+- ✅ `Read` — read SKILL.md files to activate expert personas
+- ✅ `Glob` — browse `.claude/skills/` directory
+
+## Related Skills
+
+- `/creating-service-skills` — Scaffold new expert personas
+- `/updating-service-skills` — Sync skills when implementation drifts

package/project-skills/service-skills-set/.claude/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()