xtrm-tools 2.4.1 → 2.4.2

package/skills/using-quality-gates/SKILL.md

@@ -0,0 +1,254 @@
+---
+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-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. 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/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()