xtrm-tools 0.6.0 → 0.7.1

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

@@ -1,74 +0,0 @@
-#!/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

@@ -1,136 +0,0 @@
----
-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
-
-Avoid:
-- ❌ 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

@@ -1,222 +0,0 @@
-#!/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

@@ -1,108 +0,0 @@
----
-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. Configure it in
-`.claude/settings.json` using `SessionStart`:
-
-```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

@@ -1,74 +0,0 @@
-#!/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()