xtrm-tools 0.5.24 → 0.5.26

package/plugins/xtrm-tools/hooks/xtrm-session-logger.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// xtrm-session-logger.mjs — SessionStart hook
+// Logs session.start to .xtrm/debug.db so every session has a clear entry point.
+
+import { readFileSync } from 'node:fs';
+import { logEvent } from './xtrm-logger.mjs';
+import { resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
+
+function readInput() {
+  try { return JSON.parse(readFileSync(0, 'utf-8')); } catch { return null; }
+}
+
+const input = readInput();
+if (!input) process.exit(0);
+
+const cwd = resolveCwd(input) || process.cwd();
+const sessionId = resolveSessionId(input);
+
+logEvent({
+  cwd,
+  runtime: 'claude',
+  sessionId,
+  kind: 'session.start',
+  outcome: 'ok',
+});
+
+process.exit(0);

package/plugins/xtrm-tools/hooks/xtrm-tool-logger.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// xtrm-tool-logger.mjs — PostToolUse hook
+// Logs every tool call to .xtrm/debug.db with kind=tool.call.
+// Captures tool-specific context: cmd for Bash, file path for edits, etc.
+
+import { readFileSync } from 'node:fs';
+import { logEvent } from './xtrm-logger.mjs';
+import { resolveCwd, resolveSessionId } from './beads-gate-utils.mjs';
+
+function readInput() {
+  try { return JSON.parse(readFileSync(0, 'utf-8')); } catch { return null; }
+}
+
+function buildData(toolName, toolInput) {
+  if (!toolInput) return null;
+  if (toolName === 'Bash' || toolName === 'bash' || toolName === 'execute_shell_command') {
+    return { cmd: (toolInput.command || '').slice(0, 120) };
+  }
+  if (['Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit'].includes(toolName)) {
+    return toolInput.file_path ? { file: toolInput.file_path } : null;
+  }
+  if (toolName === 'Glob')      return { pattern: toolInput.pattern, path: toolInput.path };
+  if (toolName === 'Grep')      return { pattern: toolInput.pattern, path: toolInput.path };
+  if (toolName === 'WebFetch')  return { url: (toolInput.url   || '').slice(0, 100) };
+  if (toolName === 'WebSearch') return { query: (toolInput.query || '').slice(0, 100) };
+  if (toolName === 'Agent')     return { prompt: (toolInput.prompt || '').slice(0, 80) };
+  return null;
+}
+
+const input = readInput();
+if (!input || input.hook_event_name !== 'PostToolUse') process.exit(0);
+
+const toolName = input.tool_name;
+
+// Skip tools that would create noise or cause recursion
+const SKIP = new Set(['TodoRead', 'TodoWrite', 'Task', 'TaskCreate', 'TaskUpdate', 'TaskGet']);
+if (SKIP.has(toolName)) process.exit(0);
+
+const cwd = resolveCwd(input) || process.cwd();
+const sessionId = resolveSessionId(input);
+const isError = input.tool_response?.is_error === true;
+
+logEvent({
+  cwd,
+  runtime: 'claude',
+  sessionId,
+  kind: 'tool.call',
+  outcome: isError ? 'error' : 'ok',
+  toolName,
+  data: buildData(toolName, input.tool_input),
+});
+
+process.exit(0);

package/plugins/xtrm-tools/skills/README.txt

@@ -0,0 +1,31 @@
+# Local Agent Skills
+
+This directory contains specialized agent skills designed for the Gemini CLI. These skills extend the agent's capabilities for specific workflows like debugging, security auditing, and cross-model orchestration.
+
+## Skill Discovery
+
+All skills in this directory are automatically discovered by the `hooks/skill-discovery.py` hook at the start of each session. The hook injects a summarized list of these skills into the agent's initial context, ensuring the agent is aware of specialized tools from the first prompt.
+
+### How to Add a New Skill
+
+To add a new skill that is automatically discovered:
+
+1.  **Create a Directory**: Add a new folder in `skills/` (e.g., `skills/my-new-skill/`).
+2.  **Add `SKILL.md`**: Create a `SKILL.md` file in the new folder.
+3.  **Define Metadata**: The `SKILL.md` **MUST** start with YAML frontmatter containing `name` and `description`.
+4.  **Keep it Concise**: The `description` should ideally start with a single, clear sentence explaining *what* the skill does and *when* to use it. The discovery hook will only show the first sentence to keep the initial context efficient.
+
+#### Metadata Schema (Example)
+
+```yaml
+---
+name: my-new-skill
+description: Performs deep architectural analysis of the project's dependency graph. Use when planning major refactors or evaluating library updates.
+version: 1.0.0
+---
+```
+
+## Maintenance
+
+- **Update Descriptions**: If you significantly change a skill's purpose, ensure the first sentence of its description in `SKILL.md` is updated.
+- **Workflow Integrity**: Avoid creating empty skill directories or `SKILL.md` files without proper frontmatter.

package/plugins/xtrm-tools/skills/clean-code/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
+allowed-tools: Read, Write, Edit
+version: 2.0
+priority: CRITICAL
+---
+
+# Clean Code - Pragmatic AI Coding Standards
+
+> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+
+---
+
+## Core Principles
+
+| Principle | Rule |
+|-----------|------|
+| **SRP** | Single Responsibility - each function/class does ONE thing |
+| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
+| **KISS** | Keep It Simple - simplest solution that works |
+| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
+| **Boy Scout** | Leave code cleaner than you found it |
+
+---
+
+## Naming Rules
+
+| Element | Convention |
+|---------|------------|
+| **Variables** | Reveal intent: `userCount` not `n` |
+| **Functions** | Verb + noun: `getUserById()` not `user()` |
+| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
+| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Rule:** If you need a comment to explain a name, rename it.
+
+---
+
+## Function Rules
+
+| Rule | Description |
+|------|-------------|
+| **Small** | Max 20 lines, ideally 5-10 |
+| **One Thing** | Does one thing, does it well |
+| **One Level** | One level of abstraction per function |
+| **Few Args** | Max 3 arguments, prefer 0-2 |
+| **No Side Effects** | Don't mutate inputs unexpectedly |
+
+---
+
+## Code Structure
+
+| Pattern | Apply |
+|---------|-------|
+| **Guard Clauses** | Early returns for edge cases |
+| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
+| **Composition** | Small functions composed together |
+| **Colocation** | Keep related code close |
+
+---
+
+## AI Coding Style
+
+| Situation | Action |
+|-----------|--------|
+| User asks for feature | Write it directly |
+| User reports bug | Fix it, don't explain |
+| No clear requirement | Ask, don't assume |
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Pattern | ✅ Fix |
+|-----------|-------|
+| Comment every line | Delete obvious comments |
+| Helper for one-liner | Inline the code |
+| Factory for 2 objects | Direct instantiation |
+| utils.ts with 1 function | Put code where used |
+| "First we import..." | Just write code |
+| Deep nesting | Guard clauses |
+| Magic numbers | Named constants |
+| God functions | Split by responsibility |
+
+---
+
+## 🔴 Before Editing ANY File (THINK FIRST!)
+
+**Before changing a file, ask yourself:**
+
+| Question | Why |
+|----------|-----|
+| **What imports this file?** | They might break |
+| **What does this file import?** | Interface changes |
+| **What tests cover this?** | Tests might fail |
+| **Is this a shared component?** | Multiple places affected |
+
+**Quick Check:**
+```
+File to edit: UserService.ts
+└── Who imports this? → UserController.ts, AuthController.ts
+└── Do they need changes too? → Check function signatures
+```
+
+> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
+> 🔴 **Never leave broken imports or missing updates.**
+
+---
+
+## Summary
+
+| Do | Don't |
+|----|-------|
+| Write code directly | Write tutorials |
+| Let code self-document | Add obvious comments |
+| Fix bugs immediately | Explain the fix first |
+| Inline small things | Create unnecessary files |
+| Name things clearly | Use abbreviations |
+| Keep functions small | Write 100+ line functions |
+
+> **Remember: The user wants working code, not a programming lesson.**
+
+---
+
+## 🔴 Self-Check Before Completing (MANDATORY)
+
+**Before saying "task complete", verify:**
+
+| Check | Question |
+|-------|----------|
+| ✅ **Goal met?** | Did I do exactly what user asked? |
+| ✅ **Files edited?** | Did I modify all necessary files? |
+| ✅ **Code works?** | Did I test/verify the change? |
+| ✅ **No errors?** | Lint and TypeScript pass? |
+| ✅ **Nothing forgotten?** | Any edge cases missed? |
+
+> 🔴 **Rule:** If ANY check fails, fix it before completing.
+
+---
+
+## Verification Scripts (MANDATORY)
+
+> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
+
+### Agent → Script Mapping
+
+| Agent | Script | Command |
+|-------|--------|---------|
+| **frontend-specialist** | UX Audit | `python ~/.claude/skills/frontend-design/scripts/ux_audit.py .` |
+| **frontend-specialist** | A11y Check | `python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .` |
+| **backend-specialist** | API Validator | `python ~/.claude/skills/api-patterns/scripts/api_validator.py .` |
+| **mobile-developer** | Mobile Audit | `python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .` |
+| **database-architect** | Schema Validate | `python ~/.claude/skills/database-design/scripts/schema_validator.py .` |
+| **security-auditor** | Security Scan | `python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .` |
+| **seo-specialist** | SEO Check | `python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .` |
+| **seo-specialist** | GEO Check | `python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .` |
+| **performance-optimizer** | Lighthouse | `python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
+| **test-engineer** | Test Runner | `python ~/.claude/skills/testing-patterns/scripts/test_runner.py .` |
+| **test-engineer** | Playwright | `python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>` |
+| **Any agent** | Lint Check | `python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .` |
+| **Any agent** | Type Coverage | `python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .` |
+| **Any agent** | i18n Check | `python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .` |
+
+> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
+> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
+
+---
+
+### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
+
+**When running a validation script, you MUST:**
+
+1. **Run the script** and capture ALL output
+2. **Parse the output** - identify errors, warnings, and passes
+3. **Summarize to user** in this format:
+
+```markdown
+## Script Results: [script_name.py]
+
+### ❌ Errors Found (X items)
+- [File:Line] Error description 1
+- [File:Line] Error description 2
+
+### ⚠️ Warnings (Y items)
+- [File:Line] Warning description
+
+### ✅ Passed (Z items)
+- Check 1 passed
+- Check 2 passed
+
+**Should I fix the X errors?**
+```
+
+4. **Wait for user confirmation** before fixing
+5. **After fixing** → Re-run script to confirm
+
+> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
+> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
+> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
+