xtrm-tools 2.0.1 → 2.0.3

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/SKILL.md

@@ -20,7 +20,7 @@ immediately useful to any agent working on the service.
 
 ## Mandatory Two-Phase Workflow
 
-**Both phases are required. Never skip Phase 2.**
+**Use both phases every time.** Phase 1 gives structure; Phase 2 grounds the skill in real service behavior.
 
 ---
 
@@ -65,7 +65,7 @@ python3 "$CLAUDE_PROJECT_DIR/.claude/skills/creating-service-skills/scripts/deep
 
 ---
 
-### Phase 2: Agentic Deep Dive (Non-Negotiable)
+### Phase 2: Agentic Deep Dive
 
 After the skeleton exists, answer every research question by reading the actual
 source code. Use **Serena LSP tools exclusively** — never read entire files.
@@ -118,10 +118,10 @@ source code. Use **Serena LSP tools exclusively** — never read entire files.
 
 ---
 
-### Phase 2 Script Writing (Required — No Stubs)
+### Phase 2 Script Writing (Complete Implementation)
 
-After research is complete, replace ALL `[PENDING RESEARCH]` stubs in `scripts/`.
-Each script must be fully implemented — no TODOs, no placeholder SQL.
+After research is complete, replace all `[PENDING RESEARCH]` stubs in `scripts/`.
+Scripts should be ready to run end-to-end, without TODO markers or placeholder SQL.
 
 #### Mandatory DB Connection Pattern (all scripts that touch the DB)
 
@@ -207,10 +207,10 @@ Required features:
 
 See [references/script_quality_standards.md](references/script_quality_standards.md) for complete templates.
 
-#### `scripts/Makefile` (required — always present)
+#### `scripts/Makefile` (required)
 
-The scaffolder creates a stub `Makefile` in Phase 1. In Phase 2 you **must verify it is
-correct and complete** — it is the primary entry point users and agents use to run diagnostics.
+The scaffolder creates a stub `Makefile` in Phase 1. In Phase 2, verify it is
+correct and complete because it is the primary entry point for diagnostics.
 
 **Standard template** (copy verbatim, replace `<service-id>` comment only):
 
@@ -261,11 +261,11 @@ db:
 
 **Rules for the delegated Phase 2 agent:**
 
-1. **Do not remove or rename the standard targets** — they form the stable interface.
+1. **Keep standard targets stable** — avoid removing or renaming them because downstream workflows depend on them.
 2. **Add service-specific targets** below the standard block if the service needs them (e.g. `make auth`, `make schema`, `make backfill`).
-3. **The `_VENV` auto-detect path (`../../../../venv/bin/python3`) is fixed** — it resolves from `scripts/` → service dir → `skills/` → `.claude/` → project root → `venv/`. Do not change the depth.
-4. **Recipe lines use a real tab character**, not spaces. Makefile syntax requires this.
-5. **Verify with `make help`** after writing — the Python path shown must resolve to the project venv, not system python.
+3. **Keep the `_VENV` auto-detect path (`../../../../venv/bin/python3`) unchanged** — it resolves from `scripts/` → service dir → `skills/` → `.claude/` → project root → `venv/`.
+4. **Use real tab characters in recipe lines** so Makefile parsing works consistently.
+5. **Run `make help` after updates** and confirm the Python path resolves to the project venv.
 
 ---
 

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/references/script_quality_standards.md

@@ -6,6 +6,19 @@
 
 ---
 
+## Table of Contents
+
+- [Mandatory DB Connection Pattern](#mandatory-db-connection-pattern)
+- [Schema Verification Before Writing Any SQL](#schema-verification-before-writing-any-sql)
+- [Makefile Standard](#makefile-standard)
+- [Design Principles](#design-principles)
+- [health_probe.py Standards](#health_probepy-standards)
+- [log_hunter.py Standards](#log_hunterpy-standards)
+- [Specialist Script Standards](#specialist-script-standards)
+- [Common Pitfalls](#common-pitfalls)
+
+---
+
 ## Mandatory DB Connection Pattern
 
 **Every script that touches the database MUST use this exact pattern.** No exceptions.

package/project-skills/service-skills-set/.claude/skills/creating-service-skills/references/service_skill_system_guide.md

@@ -5,6 +5,20 @@
 
 ---
 
+## Table of Contents
+
+- [1. System Overview](#1-system-overview)
+- [2. System Architecture](#2-system-architecture)
+- [3. Mandatory Two-Phase Workflow](#3-mandatory-two-phase-workflow)
+- [4. Service Type Classification](#4-service-type-classification)
+- [5. Directory Structure](#5-directory-structure)
+- [6. Skill Lifecycle](#6-skill-lifecycle)
+- [7. Quality Gates](#7-quality-gates)
+- [8. Best Practices](#8-best-practices)
+- [9. Anti-Patterns](#9-anti-patterns)
+
+---
+
 ## 1. System Overview
 
 The **Service Skill System** transforms an AI agent from a generic assistant into a service-aware operator. Each Docker service in your project gets a dedicated **skill package**: a structured combination of operational documentation and executable diagnostic scripts.

package/project-skills/service-skills-set/.claude/skills/scoping-service-skills/SKILL.md

@@ -24,7 +24,7 @@ in the conversation.
 
 ### Step 1 — Read the Registry
 
-Run this **immediately**, before any reasoning:
+Run this at the start, before deep task reasoning:
 
 ```bash
 python3 "$CLAUDE_PROJECT_DIR/.claude/skills/scoping-service-skills/scripts/scope.py"
@@ -73,7 +73,7 @@ Using the registry output, reason about which service(s) the task involves. Matc
 
 ### Step 4 — Output XML Scope Block
 
-Emit this block **before doing anything else**:
+Emit this block before moving into implementation:
 
 ```xml
 <scope>
@@ -120,15 +120,15 @@ For each `<service>` with `<load>now</load>`, immediately read the skill file:
 Read: .claude/skills/<service-id>/SKILL.md
 ```
 
-**Do not proceed with the task until all matched skills are loaded.**
+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, **never skip the
-regression-test phase** — a fix without a test is incomplete.
+Follow the workflow phases in order. For `investigation` tasks, include the
+regression-test phase — it keeps fixes durable.
 
 ---
 
@@ -187,7 +187,7 @@ load-skill → answer
 
 ## Regression Test Binding
 
-When `intent = investigation` and a fix has been applied, always write a regression
+When `intent = investigation` and a fix has been applied, write a regression
 test. Use this decision tree:
 
 ```

package/project-skills/service-skills-set/.claude/skills/updating-service-skills/SKILL.md

@@ -109,7 +109,7 @@ Write to:
 - ✅ `.claude/skills/*/SKILL.md` — skill documentation updates
 - ✅ `.claude/skills/service-registry.json` — territory and sync timestamp updates
 
-Do not:
+Avoid:
 - ❌ Modify source code (read-only access to service territories)
 - ❌ Delete skills or registry entries
 

package/project-skills/service-skills-set/.claude/skills/using-service-skills/SKILL.md

@@ -78,8 +78,8 @@ If no registered expert covers the user's need:
 
 ## Session Start Hook
 
-The catalog injection is **not** handled by skill frontmatter hooks (SessionStart
-is not supported in skill-level hooks). It is configured in `.claude/settings.json`:
+The catalog injection is not handled by skill frontmatter hooks. Configure it in
+`.claude/settings.json` using `SessionStart`:
 
 ```json
 {

package/project-skills/service-skills-set/.claude/skills/using-service-skills/scripts/skill_activator.py

@@ -19,7 +19,7 @@ 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
+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:
@@ -109,7 +109,7 @@ def main() -> None:
 
     try:
         project_root = Path(get_project_root())
-        services = load_registry()
+        services = load_registry().get("services", {})
     except (RootResolutionError, Exception):
         sys.exit(0)
 

package/project-skills/service-skills-set/.claude/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()

package/project-skills/ts-quality-gate/.claude/settings.json

@@ -2,7 +2,7 @@
   "hooks": {
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit",
         "hooks": [
           {
             "type": "command",

package/project-skills/main-guard/.claude/hooks/main-guard.cjs

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-/**
- * Main Guard - Git branch protection hook for Claude Code.
- * Blocks direct edits to main/master branches and enforces feature branch workflow.
- * 
- * Exit codes:
- *   0 - Allowed (not on protected branch, or operation allowed)
- *   1 - Fatal error
- *   2 - Blocked (attempted edit on protected branch)
- */
-
-const { execSync } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-// Colors
-const colors = {
-  red: '\x1b[0;31m',
-  green: '\x1b[0;32m',
-  yellow: '\x1b[0;33m',
-  blue: '\x1b[0;34m',
-  cyan: '\x1b[0;36m',
-  reset: '\x1b[0m',
-};
-
-function log(msg, color = '') {
-  console.error(`${color}${msg}${colors.reset}`);
-}
-
-function logInfo(msg) { log(`[INFO] ${msg}`, colors.blue); }
-function logError(msg) { log(`[ERROR] ${msg}`, colors.red); }
-function logSuccess(msg) { log(`[OK] ${msg}`, colors.green); }
-function logWarning(msg) { log(`[WARN] ${msg}`, colors.yellow); }
-
-/**
- * Get current git branch name
- */
-function getCurrentBranch() {
-  try {
-    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
-  } catch (e) {
-    logWarning('Could not determine git branch');
-    return null;
-  }
-}
-
-/**
- * Check if branch is protected
- */
-function isProtectedBranch(branch) {
-  if (!branch) return false;
-  
-  // Get protected branches from config or use defaults
-  const protectedPatterns = process.env.MAIN_GUARD_PROTECTED_BRANCHES 
-    ? process.env.MAIN_GUARD_PROTECTED_BRANCHES.split(',') 
-    : ['main', 'master', 'develop'];
-  
-  return protectedPatterns.some(pattern => {
-    const regex = new RegExp(`^${pattern.replace('*', '.*')}$`);
-    return regex.test(branch);
-  });
-}
-
-/**
- * Get feature branch name suggestion based on task
- */
-function suggestBranchName(input) {
-  const toolName = input.tool_name || '';
-  const prompt = input.user_prompt || '';
-  
-  // Extract potential task identifier
-  const match = prompt.match(/(?:issue|ticket|task|bug|feat)[#:-]?\s*(\d+|[a-z-]+)/i) ||
-                prompt.match(/^([a-z-]+)/i);
-  
-  if (match) {
-    const prefix = toolName.includes('Edit') || toolName.includes('Write') ? 'fix' : 'feat';
-    return `${prefix}/${match[1].toLowerCase().replace(/\s+/g, '-')}`;
-  }
-  
-  return 'feature/task';
-}
-
-/**
- * Parse JSON input from stdin
- */
-function parseInput() {
-  let inputData = '';
-  
-  try {
-    inputData = fs.readFileSync(0, 'utf8');
-  } catch (e) {
-    return null;
-  }
-  
-  if (!inputData.trim()) {
-    return null;
-  }
-  
-  try {
-    return JSON.parse(inputData);
-  } catch (e) {
-    logWarning('Invalid JSON input');
-    return null;
-  }
-}
-
-/**
- * Print blocked message with instructions
- */
-function printBlocked(branch, suggestedBranch) {
-  log('', colors.red);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('  🛑 BLOCKED: Direct edits to protected branches', colors.red);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('', colors.reset);
-  log(`  Current branch: ${colors.yellow}${branch}${colors.reset}`, colors.reset);
-  log('', colors.reset);
-  log('  You cannot edit files directly on a protected branch.', colors.reset);
-  log('  This prevents accidental commits and enforces code review.', colors.reset);
-  log('', colors.reset);
-  log('  📋 To proceed:', colors.cyan);
-  log(`     1. Create a feature branch: ${colors.green}git checkout -b ${suggestedBranch}${colors.reset}`, colors.reset);
-  log(`     2. Make your changes on that branch`, colors.reset);
-  log(`     3. Push and create a pull request`, colors.reset);
-  log('', colors.reset);
-  log('═══════════════════════════════════════════════════════════', colors.red);
-  log('', colors.reset);
-}
-
-/**
- * Print success message
- */
-function printSuccess(branch) {
-  log('', colors.green);
-  log(`✅ Git workflow check passed`, colors.green);
-  log(`   Branch: ${branch}`, colors.green);
-  log('', colors.reset);
-}
-
-/**
- * Main entry point
- */
-function main() {
-  log('');
-  log('🔒 Main Guard - Branch Protection Check', colors.blue);
-  log('─────────────────────────────────────────', colors.blue);
-  
-  // Parse input
-  const input = parseInput();
-  
-  // Get current branch
-  const branch = getCurrentBranch();
-  
-  if (!branch) {
-    logWarning('Not in a git repository - skipping branch protection');
-    log('', colors.yellow);
-    log('👉 Not a git repository - continuing without branch protection', colors.yellow);
-    log('', colors.reset);
-    process.exit(0);
-  }
-  
-  logInfo(`Current branch: ${branch}`);
-  
-  // Check if protected
-  if (isProtectedBranch(branch)) {
-    const suggestedBranch = suggestBranchName(input || {});
-    printBlocked(branch, suggestedBranch);
-    process.exit(2);
-  }
-  
-  // Not a protected branch - allow
-  printSuccess(branch);
-  process.exit(0);
-}
-
-// Handle errors
-process.on('unhandledRejection', (error) => {
-  logError(`Unhandled error: ${error.message}`);
-  process.exit(1);
-});
-
-// Run
-try {
-  main();
-} catch (error) {
-  logError(`Fatal error: ${error.message}`);
-  process.exit(1);
-}

package/project-skills/main-guard/.claude/settings.json

@@ -1,16 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/main-guard.cjs\"",
-            "timeout": 5
-          }
-        ]
-      }
-    ]
-  }
-}

package/project-skills/main-guard/.claude/skills/using-main-guard/SKILL.md

@@ -1,135 +0,0 @@
-# Using Main Guard
-
-**Main Guard** enforces Git branch protection by blocking direct edits to protected branches (main, master, develop).
-
-## What It Does
-
-- **Blocks direct edits** to protected branches
-- **Enforces feature branch workflow**
-- **Suggests branch names** based on your task
-- **Prevents accidental commits** to main/master
-
-## How It Works
-
-When you attempt to write or edit files:
-
-1. PreToolUse hook fires before Write/Edit
-2. Runs `main-guard.js` to check current branch
-3. If on protected branch: **blocks the action**
-4. If on feature branch: **allows the action**
-
-## Protected Branches
-
-By default, these branches are protected:
-- `main`
-- `master`
-- `develop`
-
-Customize via environment variable:
-```bash
-export MAIN_GUARD_PROTECTED_BRANCHES="main,master,develop,production"
-```
-
-## Installation
-
-```bash
-# Install project skill
-xtrm install project main-guard
-```
-
-## Usage
-
-### When Blocked
-
-If you try to edit files on a protected branch, you'll see:
-
-```
-🛑 BLOCKED: Direct edits to protected branches
-
-  Current branch: main
-
-  You cannot edit files directly on a protected branch.
-
-  📋 To proceed:
-     1. Create a feature branch: git checkout -b feat/task-name
-     2. Make your changes on that branch
-     3. Push and create a pull request
-```
-
-### Branch Name Suggestions
-
-The hook suggests branch names based on your task:
-- `feat/issue-123` - For feature requests
-- `fix/bug-456` - For bug fixes
-- `feat/description` - For general features
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Custom protected branches
-export MAIN_GUARD_PROTECTED_BRANCHES="main,master,develop,staging"
-
-# Support wildcards
-export MAIN_GUARD_PROTECTED_BRANCHES="main,master,release/*,hotfix/*"
-```
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Allowed (not on protected branch) |
-| 1 | Fatal error |
-| 2 | Blocked (on protected branch) |
-
-## Workflow
-
-### Recommended Git Flow
-
-```bash
-# Start new feature
-git checkout main
-git pull origin main
-git checkout -b feat/my-feature
-
-# Make changes (main-guard allows this)
-# ... edit files ...
-
-# Commit and push
-git add .
-git commit -m "feat: add my feature"
-git push -u origin feat/my-feature
-
-# Create PR on GitHub/GitLab
-```
-
-### Hotfix Flow
-
-```bash
-# Emergency fix
-git checkout main
-git checkout -b hotfix/urgent-fix
-
-# Make changes, commit, push
-# Create PR with expedited review
-```
-
-## Troubleshooting
-
-**"Not in a git repository"**
-- Hook skips gracefully when not in git repo
-- No protection applied outside git projects
-
-**"Could not determine git branch"**
-- Ensure git is installed and working
-- Check if `.git` folder exists
-
-**Hook not running**
-- Verify PreToolUse hook in `.claude/settings.json`
-- Check Node.js is installed
-
-## See Also
-
-- Full documentation: `.claude/docs/main-guard-readme.md`
-- Git flow: https://nvie.com/posts/a-successful-git-branching-model/