xtrm-tools 0.7.3 → 0.7.7

package/.xtrm/skills/default/service-skills-set/README.md

@@ -0,0 +1,93 @@
+# Service Skills Set
+
+**Service Skills** give Claude persistent, project-specific operational knowledge about your Docker services. Instead of re-explaining your architecture every session, each service gets a dedicated skill package that Claude loads on demand.
+
+## What It Does
+
+### Three Workflow Skills (Trinity)
+
+| Skill | Role | Invocation |
+|-------|------|------------|
+| `creating-service-skills` | Builds new skill packages via 3-phase workflow | `/creating-service-skills` |
+| `using-service-skills` | Discovers and activates expert personas | Auto (SessionStart hook) |
+| `updating-service-skills` | Detects drift when code changes | Auto (PostToolUse hook) |
+
+### Five Hooks
+
+| Hook | Type | Trigger | Effect |
+|------|------|---------|--------|
+| `SessionStart` | Claude Code | Session opens | Injects service catalog (~150 tokens) |
+| `PreToolUse` | Claude Code | Read/Write/Edit/Grep/Glob/Bash | Checks service territory, activates skills |
+| `PostToolUse` | Claude Code | Write/Edit | Detects drift, notifies to sync docs |
+| `pre-commit` | Git | `git commit` | Warns if source changed without SSOT update |
+| `pre-push` | Git | `git push` | Warns if service skills are stale |
+
+## Installation
+
+```bash
+# From your project directory
+xtrm install project service-skills-set
+```
+
+**Post-install:** The Service Skills Set requires Python scripts to be executable. The installer will:
+1. Copy skills to `.claude/skills/`
+2. Wire `settings.json` hooks
+3. Activate git hooks (`pre-commit`, `pre-push`)
+
+## Creating a Service Skill
+
+After installation, invoke the skill in Claude Code:
+
+```bash
+/creating-service-skills
+```
+
+This runs a 3-phase workflow:
+
+### Phase 1: Automated Skeleton
+- Reads `docker-compose*.yml`, `Dockerfile`, dependency files
+- Produces `SKILL.md` with `[PENDING RESEARCH]` markers
+- Generates script stubs in `scripts/`
+- Creates entry in `.claude/skills/service-registry.json`
+
+### Phase 2: Agentic Deep Dive
+- Uses Serena LSP for codebase research (75-80% token savings)
+- Fills `[PENDING RESEARCH]` markers with actual knowledge
+- Sources troubleshooting tables from real failure modes
+
+### Phase 3: Hook Registration
+- Verifies `PreToolUse` hook in `settings.json`
+- Confirms service territory globs in registry
+- Skill now auto-activates on territory file access
+
+## Generated Skill Structure
+
+```
+.claude/skills/<service-name>/
+├── SKILL.md                  — architecture, failure modes, operations
+├── scripts/
+│   ├── health_probe.py       — container status check
+│   ├── log_hunter.py         — log pattern analysis
+│   ├── data_explorer.py      — read-only DB inspection
+│   └── <specialist>.py       — service-type inspector
+└── references/
+    ├── deep_dive.md          — Phase 2 research notes
+    └── architecture_ssot.md  — link to project SSOT
+```
+
+## Auto-Activation
+
+Skills activate automatically when Claude:
+- Operates on files matching territory globs (e.g., `src/auth/**/*.py`)
+- Runs Bash commands mentioning service/container name
+
+## Requirements
+
+- Python 3.8+
+- Git repository
+- Docker Compose project
+
+## Documentation
+
+- Full guide: `.claude/docs/service-skills-set-readme.md`
+- Original: `project-skills/service-skills-set/service-skills-readme.md`

package/.xtrm/skills/default/service-skills-set/git-hooks/doc_reminder.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook: Documentation reminder.
+
+Warns when behavior-changing source files are staged for commit without
+corresponding SSOT documentation updates. Always exits 0 (non-blocking).
+
+Usage: called automatically by .githooks/pre-commit
+"""
+import subprocess
+import sys
+
+# Source paths that indicate behavior-changing code.
+# If any staged file starts with one of these, the reminder fires.
+SOURCE_PATHS = [
+    "scripts/core/",
+    "scripts/data/",
+    "scripts/ingestion/",
+    "mcp_server/",
+    "alembic/",
+]
+
+# Proxy for "agent already ran /documenting".
+# If any of these are also staged, the reminder is suppressed.
+SSOT_PATHS = [
+    ".serena/memories/",
+]
+
+# Colors
+YELLOW = "\033[1;33m"
+BLUE   = "\033[0;34m"
+NC     = "\033[0m"
+
+
+def get_staged_files() -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--name-only"],
+        capture_output=True, text=True
+    )
+    return [f for f in result.stdout.splitlines() if f]
+
+
+def main() -> None:
+    staged = get_staged_files()
+    if not staged:
+        sys.exit(0)
+
+    source_changed = [f for f in staged if any(f.startswith(p) for p in SOURCE_PATHS)]
+    ssot_changed   = [f for f in staged if any(f.startswith(p) for p in SSOT_PATHS)]
+
+    if source_changed and not ssot_changed:
+        print()
+        print(f"{YELLOW}[doc-hook] ⚠  Source changes staged without SSOT updates.{NC}")
+        print(f"{BLUE}[doc-hook]    If this commit changes behavior or architecture, run /documenting first.{NC}")
+        print(f"[doc-hook]    Changed source paths:")
+        for f in source_changed[:6]:
+            print(f"[doc-hook]      - {f}")
+        if len(source_changed) > 6:
+            print(f"[doc-hook]      ... and {len(source_changed) - 6} more")
+        print(f"[doc-hook]    Commit proceeds — this is a reminder, not a block.")
+        print()
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.xtrm/skills/default/service-skills-set/git-hooks/skill_staleness.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Pre-push hook: Skill staleness check.
+
+Reads the git push range from stdin, identifies which source files changed,
+and warns if any service skill's SKILL.md is older than the changed source files.
+
+Non-blocking by default. Set SKILL_HOOK_STRICT=1 to block the push on staleness.
+
+Usage: called automatically by .githooks/pre-push (reads from stdin)
+Manual: python3 skill_staleness.py --check-all
+"""
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Per-service source path prefixes — derived from docker-compose + entrypoint.
+# A skill is flagged as potentially stale if any changed file in the push
+# starts with one of these paths for that service.
+#
+# Customise this dict to match your project's layout.
+# ---------------------------------------------------------------------------
+SERVICE_SOURCE_PATHS: dict[str, list[str]] = {
+    "mmd-data-feed":          ["scripts/data/import_unified.py",
+                                "scripts/database/unified_import.py"],
+    "mmd-snapshot-feed":      ["scripts/data/feeds/snapshot_feed.py",
+                                "scripts/core/"],
+    "mmd-curve-feed":         ["scripts/data/feeds/spread_feed.py"],
+    "mmd-curve-backfill":     ["scripts/data/feeds/spread_feed.py"],
+    "mmd-stir-feed":          ["scripts/data/feeds/stir_feed.py"],
+    "mmd-api":                ["mcp_server/"],
+    "mmd-mcp-server":         ["mcp_server/mcp_server.py",
+                                "mcp_server/docstrings/"],
+    "mmd-cme-ingestion":      ["scripts/ingestion/cme/"],
+    "mmd-migrations":         ["alembic/", "scripts/data/migrations.py",
+                                "scripts/database/run_migrations.py"],
+    "mmd-tick-ingestor-rust": ["rust_ingestor/"],
+    "mmd-backup-service":     ["scripts/backup/"],
+    "mmd-timescaledb":        ["docker-compose.yml"],
+}
+
+# These files, if changed, flag ALL skills for review
+GLOBAL_TRIGGERS = [
+    "docker-compose.yml",
+    "scripts/docker-entrypoint.sh",
+    ".env.TEMPLATE",
+]
+
+NULL_SHA    = "0" * 40
+SKILLS_DIR  = Path(".claude/skills")
+STRICT      = os.getenv("SKILL_HOOK_STRICT", "0") == "1"
+
+# Colors
+YELLOW = "\033[1;33m"
+RED    = "\033[0;31m"
+GREEN  = "\033[0;32m"
+BLUE   = "\033[0;34m"
+NC     = "\033[0m"
+
+
+def get_push_ranges() -> list[tuple[str, str]]:
+    """Read push ranges from stdin (pre-push hook protocol)."""
+    ranges = []
+    for line in sys.stdin:
+        parts = line.strip().split()
+        if len(parts) == 4:
+            _, local_sha, _, remote_sha = parts
+            if local_sha != NULL_SHA:
+                ranges.append((remote_sha, local_sha))
+    return ranges
+
+
+def get_changed_files(old_sha: str, new_sha: str) -> set[str]:
+    """Get set of file paths changed between two commits."""
+    if old_sha == NULL_SHA:
+        # First push — compare against empty tree
+        result = subprocess.run(
+            ["git", "diff-tree", "--name-only", "-r", new_sha],
+            capture_output=True, text=True
+        )
+    else:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", old_sha, new_sha],
+            capture_output=True, text=True
+        )
+    return {f for f in result.stdout.splitlines() if f}
+
+
+def file_touches_service(filepath: str, service: str) -> bool:
+    """Return True if filepath is tracked by this service's source paths."""
+    for prefix in SERVICE_SOURCE_PATHS.get(service, []):
+        if filepath.startswith(prefix) or filepath == prefix:
+            return True
+    return False
+
+
+def is_globally_triggered(changed_files: set[str]) -> bool:
+    return any(f in GLOBAL_TRIGGERS for f in changed_files)
+
+
+def check_skill_staleness(
+    service: str,
+    changed_files: set[str],
+    global_trigger: bool,
+) -> str | None:
+    """
+    Return a warning message if the skill for `service` is stale,
+    or None if healthy.
+    """
+    skill_md = SKILLS_DIR / service / "SKILL.md"
+    if not skill_md.exists():
+        return None  # Missing skills are a separate concern
+
+    if not global_trigger and not any(
+        file_touches_service(f, service) for f in changed_files
+    ):
+        return None  # No relevant changes for this service
+
+    # Compare SKILL.md mtime against the most recently modified source file
+    skill_mtime = skill_md.stat().st_mtime
+    relevant_files = (
+        [f for f in changed_files if f in GLOBAL_TRIGGERS]
+        if global_trigger
+        else [f for f in changed_files if file_touches_service(f, service)]
+    )
+
+    stale_triggers = []
+    for rel_path in relevant_files:
+        abs_path = Path(rel_path)
+        if abs_path.exists() and abs_path.stat().st_mtime > skill_mtime:
+            stale_triggers.append(rel_path)
+
+    if stale_triggers:
+        return (
+            f"  {service}: SKILL.md older than changed source\n"
+            f"    Trigger: {stale_triggers[0]}\n"
+            f"    Action:  python3 /path/to/jaggers-agent-tools/project-skills/install.py {service} --force\n"
+            f"             Then perform Phase 2 deep dive (see SKILL.md)"
+        )
+    return None
+
+
+def main() -> None:
+    # Allow manual invocation: python3 skill_staleness.py --check-all
+    if "--check-all" in sys.argv:
+        changed_files = set()
+        global_trigger = True
+    else:
+        ranges = get_push_ranges()
+        if not ranges:
+            sys.exit(0)
+
+        changed_files: set[str] = set()
+        for old_sha, new_sha in ranges:
+            changed_files |= get_changed_files(old_sha, new_sha)
+
+        if not changed_files:
+            sys.exit(0)
+
+        global_trigger = is_globally_triggered(changed_files)
+
+    # Check each service that has a skill
+    warnings = []
+    services_to_check = sorted(SERVICE_SOURCE_PATHS.keys())
+
+    for service in services_to_check:
+        msg = check_skill_staleness(service, changed_files, global_trigger)
+        if msg:
+            warnings.append(msg)
+
+    if not warnings:
+        sys.exit(0)
+
+    print()
+    print(f"{YELLOW}[skill-hook] ⚠  The following service skills may be stale:{NC}")
+    for w in warnings:
+        print(f"{YELLOW}{w}{NC}")
+    print()
+
+    if STRICT:
+        print(f"{RED}[skill-hook] SKILL_HOOK_STRICT=1: blocking push until skills are updated.{NC}")
+        print(f"[skill-hook] Bypass: git push --no-verify")
+        print()
+        sys.exit(1)
+    else:
+        print(f"{BLUE}[skill-hook] Set SKILL_HOOK_STRICT=1 to block pushes on staleness.{NC}")
+        print()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.xtrm/skills/default/service-skills-set/install-service-skills.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+Install the Service Skill Trinity into the current project.
+
+Run from inside your target project directory:
+    python3 /path/to/jaggers-agent-tools/project-skills/install-service-skills.py
+
+Installs:
+  .claude/skills/creating-service-skills/   — scaffold new service skills
+  .claude/skills/using-service-skills/      — session-start catalog injection
+  .claude/skills/updating-service-skills/   — drift detection on file writes
+  .claude/skills/scoping-service-skills/    — task intake and service routing
+  .claude/settings.json                     — SessionStart + PostToolUse hooks
+  .githooks/pre-commit                      — doc-reminder (non-blocking)
+  .githooks/pre-push                        — skill-staleness (non-blocking)
+  .git/hooks/pre-commit + pre-push          — activated
+
+Idempotent. Safe to re-run.
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).parent.resolve()            # project-skills/service-skills-set/
+REPO_ROOT  = SCRIPT_DIR.parent.parent.resolve()         # jaggers-agent-tools/
+SKILLS_SRC = SCRIPT_DIR / ".claude"                     # service-skills-set/.claude/<skill>/
+GIT_HOOKS  = SKILLS_SRC / "git-hooks"                   # service-skills-set/.claude/git-hooks/
+
+GREEN  = "\033[0;32m"
+YELLOW = "\033[1;33m"
+NC     = "\033[0m"
+
+TRINITY = ["creating-service-skills", "using-service-skills", "updating-service-skills", "scoping-service-skills"]
+
+SETTINGS_HOOKS = {
+    "SessionStart": [
+        {"hooks": [{"type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/cataloger.py\""}]}
+    ],
+    "PreToolUse": [
+        {"matcher": "Read|Write|Edit|Glob|Grep|Bash|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+         "hooks": [{"type": "command",
+             "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/using-service-skills/scripts/skill_activator.py\""}]}
+    ],
+    "PostToolUse": [
+        {"matcher": "Write|Edit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
+         "hooks": [{"type": "command",
+             "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/skills/updating-service-skills/scripts/drift_detector.py\" check-hook",
+             "timeout": 10}]}
+    ]
+}
+
+MARKER_DOC       = "# [jaggers] doc-reminder"
+MARKER_STALENESS = "# [jaggers] skill-staleness"
+MARKER_CHAIN     = "# [jaggers] chain-githooks"
+
+
+def get_project_root() -> Path:
+    try:
+        r = subprocess.run(["git", "rev-parse", "--show-toplevel"],
+                           capture_output=True, text=True, check=True, timeout=5)
+        root = Path(r.stdout.strip())
+        if root == REPO_ROOT:
+            print("Error: run this from inside your TARGET project, not jaggers-agent-tools itself.")
+            sys.exit(1)
+        return root
+    except subprocess.CalledProcessError:
+        print("Error: not inside a git repository.")
+        sys.exit(1)
+
+
+def install_skills(project_root: Path) -> None:
+    print("\n── Skills ──────────────────────────────")
+    for skill in TRINITY:
+        src  = SKILLS_SRC / skill
+        dest = project_root / ".claude" / "skills" / skill
+        if dest.exists():
+            shutil.rmtree(dest)
+        shutil.copytree(src, dest, ignore=shutil.ignore_patterns("*.Zone.Identifier"))
+        print(f"{GREEN}  ✓{NC} .claude/skills/{skill}/")
+
+
+def install_settings(project_root: Path) -> None:
+    print("\n── settings.json ───────────────────────")
+    path = project_root / ".claude" / "settings.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = {}
+    if path.exists():
+        try:
+            existing = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            pass
+
+    hooks = existing.setdefault("hooks", {})
+    for event, config in SETTINGS_HOOKS.items():
+        if event not in hooks:
+            hooks[event] = config
+            print(f"{GREEN}  ✓{NC} added hook: {event}")
+        else:
+            print(f"{YELLOW}  ○{NC} hook already present: {event} (not overwritten)")
+
+    path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+
+
+def install_git_hooks(project_root: Path) -> None:
+    print("\n── Git hooks ───────────────────────────")
+    doc_script      = GIT_HOOKS / "doc_reminder.py"
+    staleness_script = GIT_HOOKS / "skill_staleness.py"
+
+    pre_commit = project_root / ".githooks" / "pre-commit"
+    pre_push   = project_root / ".githooks" / "pre-push"
+
+    for hp in (pre_commit, pre_push):
+        if not hp.exists():
+            hp.parent.mkdir(parents=True, exist_ok=True)
+            hp.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+            hp.chmod(0o755)
+
+    snippets = [
+        (pre_commit, MARKER_DOC,
+         f"\n{MARKER_DOC}\nif command -v python3 &>/dev/null && [ -f \"{doc_script}\" ]; then\n    python3 \"{doc_script}\" || true\nfi\n"),
+        (pre_push, MARKER_STALENESS,
+         f"\n{MARKER_STALENESS}\nif command -v python3 &>/dev/null && [ -f \"{staleness_script}\" ]; then\n    python3 \"{staleness_script}\" || true\nfi\n"),
+    ]
+
+    for hook_path, marker, snippet in snippets:
+        content = hook_path.read_text(encoding="utf-8")
+        if marker not in content:
+            hook_path.write_text(content + snippet, encoding="utf-8")
+            print(f"{GREEN}  ✓{NC} {hook_path.relative_to(project_root)}")
+        else:
+            print(f"{YELLOW}  ○{NC} already installed: {hook_path.name}")
+
+    hooks_path = ""
+    try:
+        r = subprocess.run(
+            ["git", "config", "--get", "core.hooksPath"],
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        if r.returncode == 0:
+            hooks_path = r.stdout.strip()
+    except Exception:
+        hooks_path = ""
+
+    active_hooks_dir = (Path(hooks_path) if Path(hooks_path).is_absolute() else project_root / hooks_path) if hooks_path else (project_root / ".git" / "hooks")
+    activation_targets = {project_root / ".git" / "hooks", active_hooks_dir}
+
+    for hooks_dir in activation_targets:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        for name, source_hook in (("pre-commit", pre_commit), ("pre-push", pre_push)):
+            target_hook = hooks_dir / name
+            if not target_hook.exists():
+                target_hook.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+            target_hook.chmod(0o755)
+
+            if target_hook.resolve() == source_hook.resolve():
+                continue
+
+            chain_snippet = (
+                f"\n{MARKER_CHAIN}\n"
+                f"if [ -x \"{source_hook}\" ]; then\n"
+                f"    \"{source_hook}\" \"$@\"\n"
+                "fi\n"
+            )
+            target_content = target_hook.read_text(encoding="utf-8")
+            if MARKER_CHAIN not in target_content:
+                target_hook.write_text(target_content + chain_snippet, encoding="utf-8")
+
+    print(f"{GREEN}  ✓{NC} activated in .git/hooks/")
+
+
+def main() -> None:
+    project_root = get_project_root()
+    print(f"Installing into: {project_root}")
+
+    install_skills(project_root)
+    install_settings(project_root)
+    install_git_hooks(project_root)
+
+    print(f"\n{GREEN}Done.{NC}")
+    print(f"  Hooks active: SessionStart (catalog) · PreToolUse (skill activator) · PostToolUse (drift) · pre-commit · pre-push")
+
+
+if __name__ == "__main__":
+    main()

package/.xtrm/skills/default/service-skills-set/service-registry.json

@@ -0,0 +1,4 @@
+{
+  "version": "1.0.0",
+  "services": {}
+}