xtrm-tools 0.7.0 → 0.7.2

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

@@ -1,254 +0,0 @@
----
-name: using-quality-gates
-description: 'Quality Gates workflow for Claude Code. Use when editing code in projects with quality enforcement. Covers the full cycle: TDD guard (write failing test first) → implement → auto-lint/typecheck. Activates on code edits, quality issues, or when user asks about testing/linting workflow.'
----
-
-# Using Quality Gates
-
-**Quality Gates** provides automated code quality enforcement through PostToolUse hooks:
-
-1. **TypeScript Quality Gate** — Runs after TS/JS edits: TypeScript + ESLint + Prettier
-2. **Python Quality Gate** — Runs after Python edits: Ruff + Mypy
-
-**Separate Installation Required for TDD:**
-- **TDD Guard** is a separate tool (not included) — See "TDD Guard Setup" below
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  QUALITY GATES (this skill)                                     │
-│  ─────────────────────────────                                  │
-│  PostToolUse Hooks (installed by this skill):                   │
-│  • .claude/hooks/quality-check.cjs  → TS/JS files              │
-│  • .claude/hooks/quality-check.py   → Python files             │
-│  • .claude/settings.json            → Hook registration        │
-└─────────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────────┐
-│  TDD GUARD (separate installation)                              │
-│  ───────────────────────────────────                            │
-│  PreToolUse Hook (requires xtrm install project tdd-guard):    │
-│  • Global CLI: npm install -g tdd-guard                        │
-│  • Test reporter: tdd-guard-vitest / tdd-guard-pytest / etc.   │
-│  • Hook: .claude/hooks/tdd-guard-pretool-bridge.cjs            │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Installation
-
-### Step 1: Install This Skill
-
-```bash
-xtrm install project quality-gates
-```
-
-This installs:
-- `.claude/hooks/quality-check.cjs` — TypeScript/JavaScript checks
-- `.claude/hooks/quality-check.py` — Python checks
-- `.claude/settings.json` — PostToolUse hook registration
-- `.claude/skills/using-quality-gates/` — This documentation
-
-### Step 2: Install Language Dependencies
-
-**TypeScript Projects:**
-```bash
-npm install --save-dev typescript eslint prettier
-```
-
-**Python Projects:**
-```bash
-pip install ruff mypy
-```
-
-### Step 3: (Optional) Install TDD Guard
-
-For test-first enforcement, install TDD Guard separately:
-
-```bash
-# 1. Install global CLI
-npm install -g tdd-guard
-
-# 2. Install project-skill for hook wiring
-xtrm install project tdd-guard
-
-# 3. Install test reporter (choose one)
-npm install --save-dev tdd-guard-vitest    # Vitest
-npm install --save-dev tdd-guard-jest      # Jest
-pip install tdd-guard-pytest               # pytest
-```
-
-**Configure test reporter** (see https://github.com/nizos/tdd-guard):
-
-**Vitest:**
-```typescript
-// vitest.config.ts
-import { defineConfig } from 'vitest/config'
-import { VitestReporter } from 'tdd-guard-vitest'
-
-export default defineConfig({
-  test: {
-    reporters: ['default', new VitestReporter('/path/to/project')],
-  },
-})
-```
-
-**pytest:**
-```toml
-# pyproject.toml
-[tool.pytest.ini_options]
-tdd_guard_project_root = "/path/to/project"
-```
-
-## How Quality Gates Work
-
-### TypeScript Quality Gate (PostToolUse)
-
-**Runs after:** Every `.ts`, `.tsx`, `.js`, `.jsx` file edit
-
-**Checks:**
-1. TypeScript compilation (type errors)
-2. ESLint validation (style, best practices)
-3. Prettier formatting (consistency)
-
-**Configuration** (`.claude/hooks/hook-config.json`):
-```json
-{
-  "typescript": { "enabled": true, "showDependencyErrors": false },
-  "eslint": { "enabled": true, "autofix": true },
-  "prettier": { "enabled": true, "autofix": true },
-  "general": { "autofixSilent": true }
-}
-```
-
-### Python Quality Gate (PostToolUse)
-
-**Runs after:** Every `.py` file edit
-
-**Checks:**
-1. Ruff linting (errors, style, best practices)
-2. Ruff formatting (Black-compatible)
-3. Mypy type checking (static types)
-
-**Configuration** (environment variables):
-```bash
-CLAUDE_HOOKS_RUFF_ENABLED=true
-CLAUDE_HOOKS_MYPY_ENABLED=true
-CLAUDE_HOOKS_AUTOFIX=true
-```
-
-## Exit Codes
-
-| Code | Meaning | Action |
-|------|---------|--------|
-| 0 | All checks passed | Continue |
-| 1 | Fatal error (missing deps) | Install missing tool |
-| 2 | Blocking errors | Claude must fix |
-
-## Handling Quality Gate Errors
-
-When blocked with exit code 2:
-
-1. **Read the error output** — Specific issues listed
-2. **Auto-fix applies automatically** — ESLint/Prettier/Ruff fix what they can
-3. **Fix remaining issues manually** — Type errors, complex violations
-4. **Gate re-runs on next edit** — No manual trigger needed
-
-**Example:**
-```
-[ERROR] TypeScript compilation failed:
-  src/auth.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'
-
-[WARN] Auto-fix applied: 2 issues fixed
-[BLOCK] 1 issue remains - fix before continuing
-```
-
-## TDD Guard Integration
-
-When TDD Guard is installed alongside Quality Gates:
-
-```
-User Request: "Add feature X"
-        ↓
-┌───────────────────────────────────┐
-│ TDD Guard (PreToolUse)            │
-│ Checks: Failing test exists?      │
-│ • NO → BLOCK: "Write test first"  │
-│ • YES → Allow implementation      │
-└───────────────────────────────────┘
-        ↓
-Implementation (Write/Edit)
-        ↓
-┌───────────────────────────────────┐
-│ Quality Gates (PostToolUse)       │
-│ Runs: Lint + Typecheck + Format   │
-│ • Errors → BLOCK, fix issues      │
-│ • Pass → Continue                 │
-└───────────────────────────────────┘
-        ↓
-Tests pass → Commit
-```
-
-## Troubleshooting
-
-**"ESLint not found" / "Prettier not found"**
-```bash
-npm install --save-dev eslint prettier
-```
-
-**"Ruff not found" / "Mypy not found"**
-```bash
-pip install ruff mypy
-```
-
-**"tdd-guard: command not found"**
-```bash
-npm install -g tdd-guard
-```
-
-**"TDD Guard: No failing test found"**
-- Write a failing test first
-- Ensure test reporter is configured
-- Run tests to generate reporter JSON
-
-**Hook not running**
-- Verify `.claude/settings.json` exists
-- Check hook script paths are correct
-- Ensure file extension matches (`.ts`/`.py`)
-
-## When This Skill Activates
-
-**Triggers:**
-- Quality gate reports errors
-- User asks about linting, type checking, or quality workflow
-- Session starts in a project with quality gates installed
-
-**Response Modes:**
-
-**Full Workflow Mode** (user mentions quality/testing, blocked by gate errors):
-- Explain complete quality pipeline
-- Provide troubleshooting guidance
-
-**Minimal Mode** (general coding tasks without quality context):
-- Complete the task directly
-- Brief note: "Consider adding tests. If TDD Guard is installed, write failing test first."
-
-## Files Installed
-
-```
-.claude/
-├── settings.json              # PostToolUse hook registration
-├── hooks/
-│   ├── quality-check.cjs      # TypeScript/JavaScript checks
-│   ├── quality-check.py       # Python checks
-│   └── hook-config.json       # TS hook configuration
-├── skills/
-│   └── using-quality-gates/   # This skill
-└── docs/
-    └── quality-gates-readme.md
-```
-
-## Related
-
-- **TDD Guard**: https://github.com/nizos/tdd-guard
-- **xtrm install project tdd-guard**: Install TDD Guard hooks

package/skills/using-serena-lsp/README.md

@@ -1,8 +0,0 @@
-# serena-lsp-workflow
-Master workflow combining Serena MCP semantic tools with LSP plugins.
-## Origin
-Provided by Serena MCP project.
-## Associated Hook
-- serena-workflow-reminder.sh
-## Documentation
-See Serena MCP documentation.