xtrm-tools 0.5.0

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-serena-lsp/README.md

@@ -0,0 +1,8 @@
+# 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.

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

@@ -0,0 +1,194 @@
+# Serena Tool Reference
+
+Detailed documentation for Serena MCP semantic tools.
+
+## Contents
+- [1. Exploration & Navigation](#1-exploration--navigation-tools)
+- [2. Editing Tools](#2-editing-tools)
+- [3. Memory Management](#3-memory-management-tools)
+- [4. Meta & Thinking](#4-meta--thinking-tools)
+
+---
+
+## 1. Exploration & Navigation Tools
+
+### `list_dir`
+List files and directories with optional recursion.
+```python
+mcp__serena__list_dir(
+    relative_path=".",  # or "src/analysis"
+    recursive=true,
+    skip_ignored_files=true
+)
+```
+
+### `find_file`
+Find files by name pattern (wildcards supported).
+```python
+mcp__serena__find_file(
+    file_mask="*volatility*.py",
+    relative_path="scripts"
+)
+```
+
+### `get_symbols_overview`
+Get high-level code structure (symbol tree) without reading the file body.
+```python
+mcp__serena__get_symbols_overview(
+    relative_path="scripts/core/analytics.py",
+    depth=1  # 0=top-level, 1=include children (methods)
+)
+```
+
+### `find_symbol`
+Locate specific symbols (functions, classes, methods) semantically.
+```python
+mcp__serena__find_symbol(
+    name_path_pattern="VolatilityCalculator/analyze_rv_trend",
+    relative_path="scripts/core/volatility_suite.py",
+    depth=1,
+    include_body=true,  # Set true only when needing source code
+    substring_matching=true,
+    include_kinds=[5, 6, 12]  # 5=Class, 6=Method, 12=Function
+)
+```
+
+**LSP Symbol Kinds Reference**:
+```
+1=file, 2=module, 3=namespace, 4=package, 5=class, 6=method,
+7=property, 8=field, 9=constructor, 10=enum, 11=interface,
+12=function, 13=variable, 14=constant, 15=string, 16=number,
+17=boolean, 18=array, 19=object, 20=key, 21=null,
+22=enum member, 23=struct, 24=event, 25=operator, 26=type parameter
+```
+
+### `find_referencing_symbols`
+Find all places that reference a symbol. Essential before editing.
+```python
+mcp__serena__find_referencing_symbols(
+    name_path="calculate_volatility",
+    relative_path="scripts/core/analytics.py"
+)
+```
+
+### `search_for_pattern`
+Flexible regex/substring search in code.
+```python
+mcp__serena__search_for_pattern(
+    substring_pattern="def.*volatility",  # Regex (DOTALL enabled)
+    relative_path="scripts/core",
+    restrict_search_to_code_files=true,
+    context_lines_before=2,
+    context_lines_after=2
+)
+```
+
+---
+
+## 2. Editing Tools
+
+### `replace_symbol_body`
+Replace entire symbol definition atomically.
+```python
+mcp__serena__replace_symbol_body(
+    name_path="get_db_engine",
+    relative_path="scripts/core/volatility_suite.py",
+    body="def get_db_engine(): ..."
+)
+```
+
+### `insert_after_symbol`
+Insert code after a symbol's definition ends.
+```python
+mcp__serena__insert_after_symbol(
+    name_path="VolatilityCalculator",
+    relative_path="scripts/core/analytics.py",
+    body="
+
+class RiskCalculator: ..."
+)
+```
+
+### `insert_before_symbol`
+Insert code before a symbol's definition starts (e.g., imports).
+```python
+mcp__serena__insert_before_symbol(
+    name_path="VolatilityCalculator",
+    relative_path="scripts/core/analytics.py",
+    body="from typing import Protocol
+
+"
+)
+```
+
+### `rename_symbol`
+Rename symbol across entire codebase using LSP.
+```python
+mcp__serena__rename_symbol(
+    name_path="calculate_volatility",
+    relative_path="scripts/core/analytics.py",
+    new_name="compute_volatility"
+)
+```
+
+---
+
+## 3. Memory Management Tools
+
+### `write_memory`
+Store project decisions, patterns, architecture notes.
+```python
+mcp__serena__write_memory(
+    memory_file_name="architecture_decision_auth",
+    content="# Auth Pattern
+..."
+)
+```
+
+### `read_memory`
+Retrieve stored project knowledge.
+```python
+mcp__serena__read_memory(memory_file_name="architecture_decision_auth")
+```
+
+### `list_memories`
+Discover available project knowledge.
+```python
+mcp__serena__list_memories()
+```
+
+### `edit_memory`
+Update existing memory files.
+```python
+mcp__serena__edit_memory(
+    memory_file_name="architecture_decision_auth",
+    mode="regex",
+    needle="Old",
+    repl="New"
+)
+```
+
+### `delete_memory`
+Remove obsolete memory files.
+```python
+mcp__serena__delete_memory(memory_file_name="deprecated_pattern")
+```
+
+---
+
+## 4. Meta & Thinking Tools
+
+### `check_onboarding_performed`
+Check if project onboarding was completed.
+
+### `onboarding`
+Get instructions for project onboarding.
+
+### `think_about_collected_information`
+Reflect after exploration/search operations.
+
+### `think_about_task_adherence`
+Verify you're still on track for the task.
+
+### `think_about_whether_you_are_done`
+Assess task completion.

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

@@ -0,0 +1,82 @@
+---
+name: using-serena-lsp
+description: Explores and edits code using semantic tools and LSP plugins. Use when reading code, understanding structure, finding symbols, or performing surgical edits to functions and classes.
+allowed-tools: mcp__serena__*, Read, Edit, Bash
+priority: high
+---
+
+# Using Serena LSP Workflow
+
+**Core Principle**: Use semantic, symbol-level access to understand and edit code without reading entire files. Combine with LSP plugins for real-time analysis.
+
+## Tools Reference
+
+**Full Tool Documentation**: See [REFERENCE.md](REFERENCE.md)
+
+| Tool | Purpose |
+|------|---------|
+| `get_symbols_overview` | **Start here.** See high-level structure of a file. |
+| `find_symbol` | Read specific functions/classes (set `include_body=true`). |
+| `find_referencing_symbols` | Find usages before editing. |
+| `replace_symbol_body` | Surgically replace a function/class. |
+| `insert_after_symbol` | Add new code after an existing symbol. |
+| `search_for_pattern` | Regex search when symbol names are unknown. |
+
+## Standard Workflows
+
+**🚨 MANDATORY FIRST STEP FOR ALL WORKFLOWS:**
+
+Before using ANY Serena semantic tools (`get_symbols_overview`, `find_symbol`, `replace_symbol_body`, etc.), you MUST activate the project:
+
+```javascript
+mcp__plugin_serena_serena__activate_project({ project: "/path/to/current/working/directory" })
+```
+
+**Why this is critical**: Without project activation, Serena cannot locate code symbols and will fail or loop indefinitely. This step establishes the working context for all symbolic operations.
+
+---
+
+### 1. Explore Code (The "Overview First" Pattern)
+
+Avoid reading full files >300 LOC.
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()`
+2.  **Understand Structure**: `get_symbols_overview(depth=1)`
+3.  **Drill Down**: `find_symbol(name_path="...", include_body=true)`
+4.  **Reflect**: `think_about_collected_information()`
+
+### 2. Surgical Editing
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
+2.  **Locate**: `find_symbol(include_body=true)` to get current code.
+3.  **Check Impact**: `find_referencing_symbols()` to find usages.
+4.  **Edit**: `replace_symbol_body(...)` to update.
+5.  **Verify**: Run tests or syntax checks (e.g., `python -m py_compile`).
+
+### 3. Adding Features
+
+1.  **Activate Project**: `mcp__plugin_serena_serena__activate_project()` (if not already done)
+2.  **Context**: `read_memory()` or `get_symbols_overview()` to understand patterns.
+3.  **Locate Anchor**: `find_symbol()` to find where to insert.
+4.  **Insert**: `insert_after_symbol(...)` to add new class/function.
+
+## File Size Guidelines
+
+| Lines of Code | Recommended Approach |
+|---------------|----------------------|
+| < 100 LOC | `Read` is acceptable. |
+| 100-300 LOC | `get_symbols_overview` → `find_symbol`. |
+| > 300 LOC | **Semantic only.** Do not read full file. |
+
+## Quick Tips
+
+*   **LSP Integration**: `Read()` on a Python file automatically triggers Pyright analysis. Use the feedback to fix type errors surgically.
+*   **Symbol Names**: Use `substring_matching=true` if you aren't sure of the exact name.
+*   **Safety**: Always find references before renaming or changing signatures.
+
+## ⚠️ Critical Constraints
+
+1. **NEVER skip project activation** - It must be the first Serena operation in any workflow
+2. **Use the current working directory** - Pass the actual project path, not a placeholder
+3. **Activate once per session** - After activation, all subsequent Serena tools will work correctly
+4. **Check activation status** - If Serena tools fail with "symbol not found" errors, you likely forgot to activate

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