xtrm-tools 0.5.0

package/skills/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/skills/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()

package/skills/senior-backend/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: senior-backend
+description: Comprehensive backend development skill for building scalable backend systems using NodeJS, Express, Go, Python, Postgres, GraphQL, REST APIs. Includes API scaffolding, database optimization, security implementation, and performance tuning. Use when designing APIs, optimizing database queries, implementing business logic, handling authentication/authorization, or reviewing backend code.
+---
+
+# Senior Backend
+
+Complete toolkit for senior backend with modern tools and best practices.
+
+## Quick Start
+
+### Main Capabilities
+
+This skill provides three core capabilities through automated scripts:
+
+```bash
+# Script 1: Api Scaffolder
+python scripts/api_scaffolder.py [options]
+
+# Script 2: Database Migration Tool
+python scripts/database_migration_tool.py [options]
+
+# Script 3: Api Load Tester
+python scripts/api_load_tester.py [options]
+```
+
+## Core Capabilities
+
+### 1. Api Scaffolder
+
+Automated tool for api scaffolder tasks.
+
+**Features:**
+- Automated scaffolding
+- Best practices built-in
+- Configurable templates
+- Quality checks
+
+**Usage:**
+```bash
+python scripts/api_scaffolder.py <project-path> [options]
+```
+
+### 2. Database Migration Tool
+
+Comprehensive analysis and optimization tool.
+
+**Features:**
+- Deep analysis
+- Performance metrics
+- Recommendations
+- Automated fixes
+
+**Usage:**
+```bash
+python scripts/database_migration_tool.py <target-path> [--verbose]
+```
+
+### 3. Api Load Tester
+
+Advanced tooling for specialized tasks.
+
+**Features:**
+- Expert-level automation
+- Custom configurations
+- Integration ready
+- Production-grade output
+
+**Usage:**
+```bash
+python scripts/api_load_tester.py [arguments] [options]
+```
+
+## Reference Documentation
+
+### Api Design Patterns
+
+Comprehensive guide available in `references/api_design_patterns.md`:
+
+- Detailed patterns and practices
+- Code examples
+- Best practices
+- Anti-patterns to avoid
+- Real-world scenarios
+
+### Database Optimization Guide
+
+Complete workflow documentation in `references/database_optimization_guide.md`:
+
+- Step-by-step processes
+- Optimization strategies
+- Tool integrations
+- Performance tuning
+- Troubleshooting guide
+
+### Backend Security Practices
+
+Technical reference guide in `references/backend_security_practices.md`:
+
+- Technology stack details
+- Configuration examples
+- Integration patterns
+- Security considerations
+- Scalability guidelines
+
+## Tech Stack
+
+**Languages:** TypeScript, JavaScript, Python, Go, Swift, Kotlin
+**Frontend:** React, Next.js, React Native, Flutter
+**Backend:** Node.js, Express, GraphQL, REST APIs
+**Database:** PostgreSQL, Prisma, NeonDB, Supabase
+**DevOps:** Docker, Kubernetes, Terraform, GitHub Actions, CircleCI
+**Cloud:** AWS, GCP, Azure
+
+## Development Workflow
+
+### 1. Setup and Configuration
+
+```bash
+# Install dependencies
+npm install
+# or
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+```
+
+### 2. Run Quality Checks
+
+```bash
+# Use the analyzer script
+python scripts/database_migration_tool.py .
+
+# Review recommendations
+# Apply fixes
+```
+
+### 3. Implement Best Practices
+
+Follow the patterns and practices documented in:
+- `references/api_design_patterns.md`
+- `references/database_optimization_guide.md`
+- `references/backend_security_practices.md`
+
+## Best Practices Summary
+
+### Code Quality
+- Follow established patterns
+- Write comprehensive tests
+- Document decisions
+- Review regularly
+
+### Performance
+- Measure before optimizing
+- Use appropriate caching
+- Optimize critical paths
+- Monitor in production
+
+### Security
+- Validate all inputs
+- Use parameterized queries
+- Implement proper authentication
+- Keep dependencies updated
+
+### Maintainability
+- Write clear code
+- Use consistent naming
+- Add helpful comments
+- Keep it simple
+
+## Common Commands
+
+```bash
+# Development
+npm run dev
+npm run build
+npm run test
+npm run lint
+
+# Analysis
+python scripts/database_migration_tool.py .
+python scripts/api_load_tester.py --analyze
+
+# Deployment
+docker build -t app:latest .
+docker-compose up -d
+kubectl apply -f k8s/
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Check the comprehensive troubleshooting section in `references/backend_security_practices.md`.
+
+### Getting Help
+
+- Review reference documentation
+- Check script output messages
+- Consult tech stack documentation
+- Review error logs
+
+## Resources
+
+- Pattern Reference: `references/api_design_patterns.md`
+- Workflow Guide: `references/database_optimization_guide.md`
+- Technical Guide: `references/backend_security_practices.md`
+- Tool Scripts: `scripts/` directory

package/skills/senior-backend/references/api_design_patterns.md

@@ -0,0 +1,103 @@
+# Api Design Patterns
+
+## Overview
+
+This reference guide provides comprehensive information for senior backend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior backend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.

package/skills/senior-backend/references/backend_security_practices.md

@@ -0,0 +1,103 @@
+# Backend Security Practices
+
+## Overview
+
+This reference guide provides comprehensive information for senior backend.
+
+## Patterns and Practices
+
+### Pattern 1: Best Practice Implementation
+
+**Description:**
+Detailed explanation of the pattern.
+
+**When to Use:**
+- Scenario 1
+- Scenario 2
+- Scenario 3
+
+**Implementation:**
+```typescript
+// Example code implementation
+export class Example {
+  // Implementation details
+}
+```
+
+**Benefits:**
+- Benefit 1
+- Benefit 2
+- Benefit 3
+
+**Trade-offs:**
+- Consider 1
+- Consider 2
+- Consider 3
+
+### Pattern 2: Advanced Technique
+
+**Description:**
+Another important pattern for senior backend.
+
+**Implementation:**
+```typescript
+// Advanced example
+async function advancedExample() {
+  // Code here
+}
+```
+
+## Guidelines
+
+### Code Organization
+- Clear structure
+- Logical separation
+- Consistent naming
+- Proper documentation
+
+### Performance Considerations
+- Optimization strategies
+- Bottleneck identification
+- Monitoring approaches
+- Scaling techniques
+
+### Security Best Practices
+- Input validation
+- Authentication
+- Authorization
+- Data protection
+
+## Common Patterns
+
+### Pattern A
+Implementation details and examples.
+
+### Pattern B
+Implementation details and examples.
+
+### Pattern C
+Implementation details and examples.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern 1
+What not to do and why.
+
+### Anti-Pattern 2
+What not to do and why.
+
+## Tools and Resources
+
+### Recommended Tools
+- Tool 1: Purpose
+- Tool 2: Purpose
+- Tool 3: Purpose
+
+### Further Reading
+- Resource 1
+- Resource 2
+- Resource 3
+
+## Conclusion
+
+Key takeaways for using this reference guide effectively.