xtrm-tools 0.7.3 → 0.7.4

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/quality-gate-error-fix/with_skill/outputs/response.md

@@ -0,0 +1,74 @@
+# Eval 3: quality-gate-error-fix
+
+**Prompt:** I'm getting blocked by the quality gate with TypeScript errors. Here's the error: 'Type string is not assignable to type number'. How do I fix this?
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+You're encountering a **blocking error** from the TypeScript Quality Gate (exit code 2). Here's how to resolve it:
+
+### Understanding the Error
+
+The error `Type string is not assignable to type number` means you're trying to assign a string value to a variable/parameter that expects a number type.
+
+### Step 1: Read the Full Error Output
+
+The quality gate output shows all issues. Example:
+```
+[ERROR] TypeScript compilation failed:
+  src/user.ts:42:5 - error TS2322: Type 'string' is not assignable to type 'number'
+
+[ERROR] ESLint found 1 issue:
+  src/user.ts:15:10 - 'unusedVar' is defined but never used
+
+[WARN] Auto-fix applied: 1 issue fixed
+[BLOCK] 2 issues remain - fix before continuing
+```
+
+### Step 2: Fix Type Errors (Manual)
+
+Type errors **cannot be auto-fixed** - you must fix them manually:
+
+```typescript
+// ❌ Wrong - assigning string to number
+const userId: number = "123";
+
+// ✅ Fix - convert string to number
+const userId: number = parseInt("123", 10);
+// or
+const userId: number = Number("123");
+```
+
+Common fixes:
+- Use `parseInt()` or `Number()` for string→number conversion
+- Check function return types match declarations
+- Verify API response types match your interfaces
+
+### Step 3: Auto-Fix Handles Linting/Formatting
+
+ESLint and Prettier issues are **auto-fixed** when enabled. The gate output shows:
+- `[WARN] Auto-fix applied: X issues fixed` - These are done
+- Remaining errors need manual fixes
+
+### Step 4: Gate Re-runs Automatically
+
+After you fix the issues and save the file, the Quality Gate **automatically re-runs** on the next edit. No manual trigger needed.
+
+### Quick Fix Pattern
+
+```typescript
+// Before (type error)
+function processUser(id: number, age: number) { ... }
+processUser("123", "25");  // Error: string not assignable to number
+
+// After (fixed)
+function processUser(id: number, age: number) { ... }
+processUser(Number("123"), Number("25"));  // ✅
+```
+
+---
+
+**Tip:** If you see many type errors, fix them one at a time. The gate re-runs after each edit, giving you incremental feedback.

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/should-not-trigger-general-chat/with_skill/outputs/response.md

@@ -0,0 +1,18 @@
+# Eval 11: should-not-trigger-general-chat
+
+**Prompt:** What's the weather like today?
+
+**Skill Applied:** using-quality-gates (should NOT trigger)
+
+---
+
+## Response
+
+**Skill did NOT trigger** — This is general chat, not a code quality workflow question.
+
+Standard Claude response:
+> "I don't have access to real-time weather data. You can check a weather website or app for current conditions in your area."
+
+---
+
+**Result:** ✅ Correct — skill appropriately did not activate

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/should-not-trigger-math-question/with_skill/outputs/response.md

@@ -0,0 +1,18 @@
+# Eval 13: should-not-trigger-math-question
+
+**Prompt:** What's the time complexity of binary search?
+
+**Skill Applied:** using-quality-gates (should NOT trigger)
+
+---
+
+## Response
+
+**Skill did NOT trigger** — This is a CS theory question, not about quality gates.
+
+Standard Claude response:
+> "Binary search has O(log n) time complexity. It works by repeatedly dividing the search interval in half..."
+
+---
+
+**Result:** ✅ Correct — skill appropriately did not activate

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/should-not-trigger-unrelated-coding/with_skill/outputs/response.md

@@ -0,0 +1,56 @@
+# Eval 12: should-not-trigger-unrelated-coding (Re-run with Minimal Mode)
+
+**Prompt:** Write a Python script to scrape data from example.com and save it to CSV.
+
+**Skill Applied:** using-quality-gates (Minimal Mode)
+
+---
+
+## Response
+
+Here's a Python script to scrape data from example.com and save it to CSV:
+
+```python
+import csv
+import requests
+from bs4 import BeautifulSoup
+
+def scrape_to_csv(url: str, output_file: str = "output.csv"):
+    """Scrape data from a webpage and save to CSV."""
+    response = requests.get(url)
+    response.raise_for_status()
+    
+    soup = BeautifulSoup(response.text, 'html.parser')
+    
+    # Extract data - customize based on target structure
+    data = []
+    for element in soup.find_all('p'):  # Example: extract all paragraphs
+        text = element.get_text(strip=True)
+        if text:
+            data.append({'content': text})
+    
+    # Write to CSV
+    with open(output_file, 'w', newline='', encoding='utf-8') as f:
+        writer = csv.DictWriter(f, fieldnames=['content'])
+        writer.writeheader()
+        writer.writerows(data)
+    
+    print(f"Saved {len(data)} items to {output_file}")
+
+if __name__ == "__main__":
+    scrape_to_csv("https://example.com")
+```
+
+**Usage:**
+```bash
+pip install requests beautifulsoup4
+python scrape.py
+```
+
+---
+
+**Note:** Consider adding tests for this script. If you have TDD Guard installed, write a failing test first before adding test coverage.
+
+---
+
+**Result:** ✅ Minimal mode applied — Task completed directly, brief TDD mention at end, no full workflow explanation

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/tdd-guard-blocking-confusion/with_skill/outputs/response.md

@@ -0,0 +1,67 @@
+# Eval 5: tdd-guard-blocking-confusion
+
+**Prompt:** Why am I getting 'No failing test found' when I try to edit src/service.ts? I just want to add a logging statement.
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+You're encountering the **TDD Guard**, which enforces test-driven development for **all code changes** - including small changes like adding a logging statement.
+
+### Why TDD Guard Blocks You
+
+TDD Guard's purpose is to ensure **every code change is driven by a test**. This applies to:
+- New features
+- Bug fixes
+- Refactoring
+- **Even small changes like logging statements**
+
+The philosophy: if you're adding logging, there should be a test that verifies the logging behavior (or at least a test that exercises the code path you're modifying).
+
+### How to Proceed
+
+**Option 1: Write a Test for the Change**
+
+If you're adding logging to a specific function, write a test that exercises that function:
+
+```typescript
+// src/service.test.ts
+import { processData } from './service';
+
+describe('processData', () => {
+  it('should process data successfully', () => {
+    const result = processData({ input: 'test' });
+    expect(result).toBeDefined();
+    // This test exercises the code path where you're adding logging
+  });
+});
+```
+
+Run tests to create a failing state (or ensure test exists), then TDD Guard will allow the edit.
+
+**Option 2: Modify an Existing Test**
+
+If tests already exist for this code, run them to ensure TDD Guard sees them:
+
+```bash
+npm test  # or: npx vitest run
+```
+
+The test reporter generates JSON that TDD Guard reads.
+
+### Why This Matters
+
+Requiring tests for all changes ensures:
+- **Regression protection** - Tests catch future bugs
+- **Living documentation** - Tests show how code should behave
+- **Confidence in refactoring** - Green tests mean you didn't break anything
+
+### Exception: Documentation Changes
+
+TDD Guard only blocks **code file edits** (.ts, .js, .py, etc.). Documentation files (.md, .txt) can be edited without tests.
+
+---
+
+**Bottom line:** Write or run a test that exercises the code you're modifying, then TDD Guard will allow the logging change.

package/.xtrm/skills/default/quality-gates/workspace/iteration-1/typescript-feature-with-tests/with_skill/outputs/response.md

@@ -0,0 +1,97 @@
+# Eval 1: typescript-feature-with-tests
+
+**Prompt:** Add a new authentication middleware to src/auth.ts that validates JWT tokens. The middleware should check the Authorization header, verify the token, and attach the user to the request object.
+
+**Skill Applied:** using-quality-gates
+
+---
+
+## Response (with skill active)
+
+To add the authentication middleware, we need to follow the **TDD workflow** enforced by Quality Gates:
+
+### Step 1: Write a Failing Test First
+
+Before implementing the middleware, you need to write a test that will fail without the implementation. The TDD Guard will block implementation until a failing test exists.
+
+**Create** `src/auth.test.ts` or add to existing test file:
+
+```typescript
+import { authMiddleware } from './auth';
+
+describe('authMiddleware', () => {
+  it('should reject requests without Authorization header', async () => {
+    const req = { headers: {} } as Request;
+    const next = vi.fn();
+    
+    await authMiddleware(req, {} as Response, next);
+    
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('should attach user to request with valid JWT', async () => {
+    const token = generateValidToken(); // your test helper
+    const req = { headers: { authorization: `Bearer ${token}` } } as Request;
+    const next = vi.fn();
+    
+    await authMiddleware(req, {} as Response, next);
+    
+    expect(next).toHaveBeenCalled();
+    expect(req.user).toBeDefined();
+  });
+});
+```
+
+Run tests to confirm they fail:
+```bash
+npm test  # or: npx vitest run
+```
+
+### Step 2: Implement the Middleware
+
+Once tests are failing, TDD Guard will allow implementation:
+
+```typescript
+// src/auth.ts
+import jwt from 'jsonwebtoken';
+
+export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+  const authHeader = req.headers.authorization;
+  
+  if (!authHeader?.startsWith('Bearer ')) {
+    res.status(401).json({ error: 'No token provided' });
+    return;
+  }
+  
+  const token = authHeader.substring(7);
+  
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
+    (req as any).user = decoded;
+    next();
+  } catch (err) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+}
+```
+
+### Step 3: Quality Gate Validation
+
+After editing `src/auth.ts`, the **TypeScript Quality Gate** will automatically run:
+- **TypeScript compilation** - Checks types
+- **ESLint** - Validates code style (auto-fixes if enabled)
+- **Prettier** - Formats code (auto-fixes if enabled)
+
+If any issues are found, you'll see error output. Fix remaining issues manually (type errors can't be auto-fixed).
+
+### Step 4: Verify Tests Pass
+
+```bash
+npm test  # All tests should now pass
+```
+
+---
+
+**Note:** Ensure you have the required dependencies installed:
+- `npm install --save-dev tdd-guard-vitest` (for Vitest test reporter)
+- `npm install --save-dev typescript eslint prettier` (for quality gate)

package/.xtrm/skills/default/scoping-service-skills/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: scoping-service-skills
+description: >-
+  Task intake and service routing for any task type. Reads service-registry.json
+  directly, detects intent, maps to the right expert skill(s), and emits a
+  structured XML scope plan before any files are touched. Invoke via
+  /scope "task description" before starting any investigation, feature,
+  refactor, config-change, or exploration task.
+allowed-tools: Bash(python3 *), Read
+---
+
+# Scoping Service Skills ( /scope )
+
+Ground every task in the right expert context **before any files are touched**.
+
+## Trigger
+
+User types `/scope "task description"` — or `/scope` with task context already
+in the conversation.
+
+---
+
+## Execution Flow
+
+### Step 1 — Read the Registry
+
+Run this at the start, before deep task reasoning:
+
+```bash
+python3 "$CLAUDE_PROJECT_DIR/.claude/skills/scoping-service-skills/scripts/scope.py"
+```
+
+This outputs every registered service: ID, container, territory paths, skill path,
+and description. If the registry is missing, report:
+
+> "No service-registry.json found at this project. Run /creating-service-skills first."
+
+---
+
+### Step 2 — Detect Intent
+
+Scan the task description for keywords:
+
+| Intent | Signal keywords |
+|---|---|
+| `investigation` | broken, error, failing, problem, not working, issue, crash, down, missing, slow, 502, 404, 429, timeout |
+| `feature` | add, implement, create, new, build, introduce, support |
+| `refactor` | refactor, restructure, clean, reorganize, simplify, rename, extract |
+| `config-change` | update, change, modify, set, configure, adjust, tune |
+| `exploration` | how, explain, understand, what is, show me, why, walk me through |
+
+**Default when ambiguous → `investigation`** (safer: check first, act second).
+
+---
+
+### Step 3 — Map to Services
+
+Using the registry output, reason about which service(s) the task involves. Match on:
+
+- Explicit service name in task description (`traefik`, `grafana`, `loki` …)
+- Symptom-to-service knowledge:
+  - `502 / route not found` → traefik
+  - `logs not appearing` → loki / promtail
+  - `alert not firing` → alertmanager / prometheus
+  - `dashboard broken` → grafana
+  - `API key rejected` → api-gateway
+  - `disk full` → node-exporter / loki (chunks)
+  - `container memory` → cadvisor
+- Config file or directory mentioned (`routes.yml` → traefik, `prometheus.yml` → prometheus)
+- Container name mentioned (`infra-*`)
+
+---
+
+### Step 4 — Output XML Scope Block
+
+Emit this block before moving into implementation:
+
+```xml
+<scope>
+  <task>"user's original description"</task>
+  <intent>investigation</intent>
+  <confidence>high|medium|low</confidence>
+  <services>
+    <service id="traefik" confidence="high">
+      <reason>user mentioned 502 on dashboard route</reason>
+      <skill>.claude/skills/traefik/SKILL.md</skill>
+      <load>now</load>
+    </service>
+  </services>
+  <workflow>
+    <phase order="1" name="diagnose">
+      Consult traefik SKILL.md failure modes table.
+      Run health_probe.py and log_hunter.py before any ad-hoc docker commands.
+    </phase>
+    <phase order="2" name="fix">
+      Apply targeted fix based on diagnosis.
+    </phase>
+    <phase order="3" name="regression-test">
+      <decision>
+        Code behavior bug → write test in repo test suite (pytest/unit).
+        Operational/infra issue → extend health_probe.py OR add script to
+          .claude/skills/traefik/scripts/.
+      </decision>
+      Name the function after the failure mode it catches.
+      Commit the test alongside the fix — never separately.
+    </phase>
+  </workflow>
+</scope>
+```
+
+Adapt the phases to the detected intent (see Intent Workflows below).
+
+---
+
+### Step 5 — Load Skills
+
+For each `<service>` with `<load>now</load>`, immediately read the skill file:
+
+```
+Read: .claude/skills/<service-id>/SKILL.md
+```
+
+Load all matched skills before proceeding with the task.
+Adopt the expert persona, constraints, and diagnostic approach from each loaded skill.
+
+---
+
+### Step 6 — Execute
+
+Follow the workflow phases in order. For `investigation` tasks, include the
+regression-test phase — it keeps fixes durable.
+
+---
+
+## Intent Workflows
+
+### `investigation` — Problem / Error / Broken
+
+```
+diagnose → fix → regression-test
+```
+
+- Start with the skill's **failure modes table** — not ad-hoc docker commands.
+- Use the skill's **diagnostic scripts** (`health_probe.py`, `log_hunter.py`) first.
+- After the fix is applied and verified: write a regression test (see below).
+
+### `feature` — New Capability
+
+```
+design → skill-check → implement → test
+```
+
+- Read the skill's **architecture section** before designing anything.
+- Check integration points (what calls this service, what does it call).
+- Write tests alongside implementation, not as a follow-up.
+
+### `refactor` — Structural Change
+
+```
+scope → skill-check → change → verify
+```
+
+- Read the skill's **integration diagram** to understand what depends on this.
+- Use `find_referencing_symbols` before renaming or restructuring.
+- Verify no external callers break after the change.
+
+### `config-change` — Setting / Parameter
+
+```
+read-current → validate → modify → confirm
+```
+
+- Read the current config state before touching anything.
+- Validate the intended change against the skill's known constraints and limits.
+- After applying: confirm the service is healthy (`health_probe.py`).
+
+### `exploration` — Understanding / Analysis
+
+```
+load-skill → answer
+```
+
+- Load the skill and answer from its documented knowledge.
+- No file modification. No action needed unless user explicitly asks.
+
+---
+
+## Regression Test Binding
+
+When `intent = investigation` and a fix has been applied, write a regression
+test. Use this decision tree:
+
+```
+Is the bug in application code logic?
+  YES → write pytest/unit test in repo's test suite
+
+  NO  (operational / infra / config issue) →
+        Does the skill's health_probe.py already check this condition?
+          YES → extend the existing check function
+          NO  → add a new check function to health_probe.py
+                OR create a dedicated script in .claude/skills/<service>/scripts/
+```
+
+**Naming convention** — name after the failure mode, not the fix:
+
+```python
+def check_route_not_returning_502():    # ✅ descriptive
+def check_cert_not_expiring_soon():     # ✅ descriptive
+def test_fix():                         # ❌ meaningless
+def test_issue_123():                   # ❌ meaningless
+```
+
+Commit the test in the same commit as the fix.
+
+---
+
+## No Match Handling
+
+If no registered service matches the task:
+
+1. Report: `"No registered skill covers this area."`
+2. Offer: `"I can create one — use /creating-service-skills."`
+3. Fall back to general expert mode (no skill enforcement).
+
+---
+
+## Related Skills
+
+- `/using-service-skills` — Passive catalog at session start
+- `/creating-service-skills` — Scaffold new expert skill packages
+- `/updating-service-skills` — Sync skills after implementation drift

package/.xtrm/skills/default/scoping-service-skills/scripts/scope.py

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