xtrm-tools 0.6.0 → 0.7.1

package/plugins/xtrm-tools/skills/using-tdd/SKILL.md

@@ -1,410 +0,0 @@
----
-name: using-TDD
-description: Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
-origin: ECC
----
-
-# Test-Driven Development Workflow
-
-This skill ensures all code development follows TDD principles with comprehensive test coverage.
-
-## When to Activate
-
-- Writing new features or functionality
-- Fixing bugs or issues
-- Refactoring existing code
-- Adding API endpoints
-- Creating new components
-
-## Core Principles
-
-### 1. Tests BEFORE Code
-ALWAYS write tests first, then implement code to make tests pass.
-
-### 2. Coverage Requirements
-- Minimum 80% coverage (unit + integration + E2E)
-- All edge cases covered
-- Error scenarios tested
-- Boundary conditions verified
-
-### 3. Test Types
-
-#### Unit Tests
-- Individual functions and utilities
-- Component logic
-- Pure functions
-- Helpers and utilities
-
-#### Integration Tests
-- API endpoints
-- Database operations
-- Service interactions
-- External API calls
-
-#### E2E Tests (Playwright)
-- Critical user flows
-- Complete workflows
-- Browser automation
-- UI interactions
-
-## TDD Workflow Steps
-
-### Step 1: Write User Journeys
-```
-As a [role], I want to [action], so that [benefit]
-
-Example:
-As a user, I want to search for markets semantically,
-so that I can find relevant markets even without exact keywords.
-```
-
-### Step 2: Generate Test Cases
-For each user journey, create comprehensive test cases:
-
-```typescript
-describe('Semantic Search', () => {
-  it('returns relevant markets for query', async () => {
-    // Test implementation
-  })
-
-  it('handles empty query gracefully', async () => {
-    // Test edge case
-  })
-
-  it('falls back to substring search when Redis unavailable', async () => {
-    // Test fallback behavior
-  })
-
-  it('sorts results by similarity score', async () => {
-    // Test sorting logic
-  })
-})
-```
-
-### Step 3: Run Tests (They Should Fail)
-```bash
-npm test
-# Tests should fail - we haven't implemented yet
-```
-
-### Step 4: Implement Code
-Write minimal code to make tests pass:
-
-```typescript
-// Implementation guided by tests
-export async function searchMarkets(query: string) {
-  // Implementation here
-}
-```
-
-### Step 5: Run Tests Again
-```bash
-npm test
-# Tests should now pass
-```
-
-### Step 6: Refactor
-Improve code quality while keeping tests green:
-- Remove duplication
-- Improve naming
-- Optimize performance
-- Enhance readability
-
-### Step 7: Verify Coverage
-```bash
-npm run test:coverage
-# Verify 80%+ coverage achieved
-```
-
-## Testing Patterns
-
-### Unit Test Pattern (Jest/Vitest)
-```typescript
-import { render, screen, fireEvent } from '@testing-library/react'
-import { Button } from './Button'
-
-describe('Button Component', () => {
-  it('renders with correct text', () => {
-    render(<Button>Click me</Button>)
-    expect(screen.getByText('Click me')).toBeInTheDocument()
-  })
-
-  it('calls onClick when clicked', () => {
-    const handleClick = jest.fn()
-    render(<Button onClick={handleClick}>Click</Button>)
-
-    fireEvent.click(screen.getByRole('button'))
-
-    expect(handleClick).toHaveBeenCalledTimes(1)
-  })
-
-  it('is disabled when disabled prop is true', () => {
-    render(<Button disabled>Click</Button>)
-    expect(screen.getByRole('button')).toBeDisabled()
-  })
-})
-```
-
-### API Integration Test Pattern
-```typescript
-import { NextRequest } from 'next/server'
-import { GET } from './route'
-
-describe('GET /api/markets', () => {
-  it('returns markets successfully', async () => {
-    const request = new NextRequest('http://localhost/api/markets')
-    const response = await GET(request)
-    const data = await response.json()
-
-    expect(response.status).toBe(200)
-    expect(data.success).toBe(true)
-    expect(Array.isArray(data.data)).toBe(true)
-  })
-
-  it('validates query parameters', async () => {
-    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
-    const response = await GET(request)
-
-    expect(response.status).toBe(400)
-  })
-
-  it('handles database errors gracefully', async () => {
-    // Mock database failure
-    const request = new NextRequest('http://localhost/api/markets')
-    // Test error handling
-  })
-})
-```
-
-### E2E Test Pattern (Playwright)
-```typescript
-import { test, expect } from '@playwright/test'
-
-test('user can search and filter markets', async ({ page }) => {
-  // Navigate to markets page
-  await page.goto('/')
-  await page.click('a[href="/markets"]')
-
-  // Verify page loaded
-  await expect(page.locator('h1')).toContainText('Markets')
-
-  // Search for markets
-  await page.fill('input[placeholder="Search markets"]', 'election')
-
-  // Wait for debounce and results
-  await page.waitForTimeout(600)
-
-  // Verify search results displayed
-  const results = page.locator('[data-testid="market-card"]')
-  await expect(results).toHaveCount(5, { timeout: 5000 })
-
-  // Verify results contain search term
-  const firstResult = results.first()
-  await expect(firstResult).toContainText('election', { ignoreCase: true })
-
-  // Filter by status
-  await page.click('button:has-text("Active")')
-
-  // Verify filtered results
-  await expect(results).toHaveCount(3)
-})
-
-test('user can create a new market', async ({ page }) => {
-  // Login first
-  await page.goto('/creator-dashboard')
-
-  // Fill market creation form
-  await page.fill('input[name="name"]', 'Test Market')
-  await page.fill('textarea[name="description"]', 'Test description')
-  await page.fill('input[name="endDate"]', '2025-12-31')
-
-  // Submit form
-  await page.click('button[type="submit"]')
-
-  // Verify success message
-  await expect(page.locator('text=Market created successfully')).toBeVisible()
-
-  // Verify redirect to market page
-  await expect(page).toHaveURL(/\/markets\/test-market/)
-})
-```
-
-## Test File Organization
-
-```
-src/
-├── components/
-│   ├── Button/
-│   │   ├── Button.tsx
-│   │   ├── Button.test.tsx          # Unit tests
-│   │   └── Button.stories.tsx       # Storybook
-│   └── MarketCard/
-│       ├── MarketCard.tsx
-│       └── MarketCard.test.tsx
-├── app/
-│   └── api/
-│       └── markets/
-│           ├── route.ts
-│           └── route.test.ts         # Integration tests
-└── e2e/
-    ├── markets.spec.ts               # E2E tests
-    ├── trading.spec.ts
-    └── auth.spec.ts
-```
-
-## Mocking External Services
-
-### Supabase Mock
-```typescript
-jest.mock('@/lib/supabase', () => ({
-  supabase: {
-    from: jest.fn(() => ({
-      select: jest.fn(() => ({
-        eq: jest.fn(() => Promise.resolve({
-          data: [{ id: 1, name: 'Test Market' }],
-          error: null
-        }))
-      }))
-    }))
-  }
-}))
-```
-
-### Redis Mock
-```typescript
-jest.mock('@/lib/redis', () => ({
-  searchMarketsByVector: jest.fn(() => Promise.resolve([
-    { slug: 'test-market', similarity_score: 0.95 }
-  ])),
-  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
-}))
-```
-
-### OpenAI Mock
-```typescript
-jest.mock('@/lib/openai', () => ({
-  generateEmbedding: jest.fn(() => Promise.resolve(
-    new Array(1536).fill(0.1) // Mock 1536-dim embedding
-  ))
-}))
-```
-
-## Test Coverage Verification
-
-### Run Coverage Report
-```bash
-npm run test:coverage
-```
-
-### Coverage Thresholds
-```json
-{
-  "jest": {
-    "coverageThresholds": {
-      "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
-      }
-    }
-  }
-}
-```
-
-## Common Testing Mistakes to Avoid
-
-### ❌ WRONG: Testing Implementation Details
-```typescript
-// Don't test internal state
-expect(component.state.count).toBe(5)
-```
-
-### ✅ CORRECT: Test User-Visible Behavior
-```typescript
-// Test what users see
-expect(screen.getByText('Count: 5')).toBeInTheDocument()
-```
-
-### ❌ WRONG: Brittle Selectors
-```typescript
-// Breaks easily
-await page.click('.css-class-xyz')
-```
-
-### ✅ CORRECT: Semantic Selectors
-```typescript
-// Resilient to changes
-await page.click('button:has-text("Submit")')
-await page.click('[data-testid="submit-button"]')
-```
-
-### ❌ WRONG: No Test Isolation
-```typescript
-// Tests depend on each other
-test('creates user', () => { /* ... */ })
-test('updates same user', () => { /* depends on previous test */ })
-```
-
-### ✅ CORRECT: Independent Tests
-```typescript
-// Each test sets up its own data
-test('creates user', () => {
-  const user = createTestUser()
-  // Test logic
-})
-
-test('updates user', () => {
-  const user = createTestUser()
-  // Update logic
-})
-```
-
-## Continuous Testing
-
-### Watch Mode During Development
-```bash
-npm test -- --watch
-# Tests run automatically on file changes
-```
-
-### Pre-Commit Hook
-```bash
-# Runs before every commit
-npm test && npm run lint
-```
-
-### CI/CD Integration
-```yaml
-# GitHub Actions
-- name: Run Tests
-  run: npm test -- --coverage
-- name: Upload Coverage
-  uses: codecov/codecov-action@v3
-```
-
-## Best Practices
-
-1. **Write Tests First** - Always TDD
-2. **One Assert Per Test** - Focus on single behavior
-3. **Descriptive Test Names** - Explain what's tested
-4. **Arrange-Act-Assert** - Clear test structure
-5. **Mock External Dependencies** - Isolate unit tests
-6. **Test Edge Cases** - Null, undefined, empty, large
-7. **Test Error Paths** - Not just happy paths
-8. **Keep Tests Fast** - Unit tests < 50ms each
-9. **Clean Up After Tests** - No side effects
-10. **Review Coverage Reports** - Identify gaps
-
-## Success Metrics
-
-- 80%+ code coverage achieved
-- All tests passing (green)
-- No skipped or disabled tests
-- Fast test execution (< 30s for unit tests)
-- E2E tests cover critical user flows
-- Tests catch bugs before production
-
----
-
-**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

package/plugins/xtrm-tools/skills/using-xtrm/SKILL.md

@@ -1,127 +0,0 @@
----
-name: using-xtrm
-description: >
-  Behavioral operating manual for an xtrm-equipped Claude Code session.
-  Covers when to use which tool, how to handle questions and triggers,
-  workflow examples, and skill routing. Reference material (hook list,
-  gate rules, full bd commands, git workflow) lives in CLAUDE.md.
-  Injected automatically at session start via additionalSystemPrompt.
-priority: high
----
-
-# XTRM — When to Use What
-
-> Gates, commands, and git workflow are in CLAUDE.md.
-> This is the behavioral layer: triggers, patterns, examples.
-
-## Session Start
-
-```bash
-bd prime                          # load workflow context + active claims
-bd memories <today's topic>       # retrieve relevant past context
-bv --robot-triage                 # graph-ranked picks, quick wins, unblock targets
-bd update <id> --claim            # claim before any edit
-```
-
-> Use `bv --robot-next` for the single top pick. Use `bv --robot-triage --format toon` to save context tokens. **Never run bare `bv` — it launches an interactive TUI.**
-
----
-
-## Trigger Patterns
-
-| Situation | Action |
-|-----------|--------|
-| User prompt contains `?` | `bd memories <keywords>` before answering — check stored context first |
-| "What should I work on?" | `bv --robot-triage` — ranked picks with dependency context |
-| "What was I working on?" | `bd list --status=in_progress` |
-| Unfamiliar area of code | `gitnexus_query({query: "concept"})` before opening any file |
-| About to edit a symbol | `gitnexus_impact({target: "name", direction: "upstream"})` |
-| Before `git commit` | `gitnexus_detect_changes({scope: "staged"})` to verify scope |
-| Reading code | `get_symbols_overview` → `find_symbol` — never read whole files |
-| Task is tests | use /test-planning
-| Task is docs updates | use /sync-docs
-| Session end (issue closed) | Memory gate fires — evaluate `bd remember` for each closed issue |
-
----
-
-## Handling `?` Prompts
-
-When the user's message contains a question, check stored context before answering:
-
-```bash
-bd memories <keywords from question>   # search project memory
-bd recall <key>                        # retrieve specific memory if key is known
-```
-
-Example — user asks *"why does the quality gate run twice?"*:
-```bash
-bd memories "quality gate"
-# → "quality-check.cjs and quality-check.py are separate hooks —
-#    JS/TS and Python each get their own PostToolUse pass"
-```
-
-If it's a code question, also run:
-```bash
-gitnexus_query({query: "<topic>"})     # find relevant execution flows
-```
-
----
-
-## Workflow Examples
-
-**Fixing a bug:**
-```bash
-bd ready                                                        # find the issue
-bd update bd-xyz --claim                                        # claim it
-gitnexus_impact({target: "parseComposeServices", direction: "upstream"})
-# → 2 callers, LOW risk — safe to edit
-get_symbols_overview("hooks/init.ts")                           # map file
-find_symbol("parseComposeServices", include_body=True)          # read just this
-replace_symbol_body("parseComposeServices", newBody)            # Serena edit
-bd close bd-xyz --reason="Fix YAML parse edge case"            # close issue
-xt end                                                         # push, PR, merge, cleanup
-```
-
-**Exploring unfamiliar code:**
-```bash
-gitnexus_query({query: "session claim enforcement"})
-# → beads-gate-core.mjs, resolveClaimAndWorkState, decideCommitGate
-gitnexus_context({name: "resolveClaimAndWorkState"})            # callers + callees
-get_symbols_overview("hooks/beads-gate-core.mjs")               # map the file
-find_symbol("resolveClaimAndWorkState", include_body=True)      # read only this
-```
-
-**Persisting an insight:**
-```bash
-bd remember "quality-check runs twice: separate .cjs (JS) and .py (Python) hooks"
-# retrievable next session:
-bd memories "quality check"
-bd recall "quality-check-runs-twice-..."
-```
-
----
-
-## Prompt Shaping (silent, before every non-trivial task)
-
-| Task type | Apply |
-|-----------|-------|
-| `analyze / investigate / why` | `<thinking>` block + structured `<outputs>` |
-| `implement / build / fix` | 1-2 `<example>` blocks + `<constraints>` |
-| `refactor / simplify` | `<constraints>` (preserve behavior, tests pass) + `<current_state>` |
-
-Vague prompt (under 8 words, no specifics)? Ask one clarifying question before proceeding.
-
----
-
-## Skill Routing
-
-| Need | Use |
-|------|-----|
-| Code read / edit | Serena — `get_symbols_overview` → `find_symbol` → `replace_symbol_body` |
-| Blast radius before edit | `gitnexus-impact-analysis` |
-| Navigate unfamiliar code | `gitnexus-exploring` |
-| Trace a bug | `gitnexus-debugging` |
-| Safe rename / refactor | `gitnexus-refactoring` |
-| Docs maintenance | `sync-docs` |
-| Docker service project | `using-service-skills` |
-| Build / improve a skill | `skill-creator` |

package/plugins/xtrm-tools/skills/xt-debugging/SKILL.md

@@ -1,149 +0,0 @@
----
-name: xt-debugging
-description: Complete debugging workflow — error analysis, log interpretation, performance profiling, and GitNexus call-chain tracing. Use when investigating bugs, errors, crashes, or performance issues.
----
-
-# xt-debugging
-
-Systematic debugging using the GitNexus knowledge graph for call-chain tracing, combined with error analysis, log interpretation, and performance profiling.
-
-## When to Use
-
-- "Why is this function failing?"
-- "Trace where this error comes from"
-- "This endpoint returns 500"
-- Investigating crashes, unexpected behavior, or regressions
-- Performance issues
-- Reading logs or stack traces
-
----
-
-## Prerequisites
-
-GitNexus must be indexed before starting. If you see "index is stale" or no results:
-
-```bash
-npx gitnexus analyze   # re-index the repo (run this, then retry)
-npx gitnexus status    # verify freshness
-```
-
----
-
-## Phase 1 — Triage
-
-Understand the symptom before touching any code.
-
-1. Read the full error message and stack trace
-2. Identify the suspect symbol (function, class, endpoint)
-3. Check for regressions — what changed recently?
-   ```
-   gitnexus_detect_changes({scope: "compare", base_ref: "main"})
-   ```
-
----
-
-## Phase 2 — Knowledge Graph Investigation
-
-```
-1. gitnexus_query({query: "<error text or symptom>"})   → Related execution flows + symbols
-2. gitnexus_context({name: "<suspect>"})                → Callers, callees, process participation
-3. READ gitnexus://repo/{name}/process/{processName}    → Full step-by-step execution trace
-4. gitnexus_cypher({...})                               → Custom call chain if needed
-```
-
-### Patterns by Symptom
-
-| Symptom | Approach |
-|---------|----------|
-| Error message | `query` for error text → `context` on throw site |
-| Wrong return value | `context` on function → trace callees for data flow |
-| Intermittent failure | `context` → look for external calls, async deps, race conditions |
-| Performance issue | `context` → find hot-path symbols with many callers |
-| Recent regression | `detect_changes` to see what changed |
-
-### Example — "Payment endpoint returns 500 intermittently"
-
-```
-1. gitnexus_query({query: "payment error handling"})
-   → Processes: CheckoutFlow, ErrorHandling
-   → Symbols: validatePayment, handlePaymentError
-
-2. gitnexus_context({name: "validatePayment"})
-   → Outgoing calls: verifyCard, fetchRates (external API!)
-
-3. READ gitnexus://repo/my-app/process/CheckoutFlow
-   → Step 3: validatePayment → calls fetchRates (external, no timeout)
-
-4. Root cause: fetchRates has no timeout → intermittent failures under load
-```
-
----
-
-## Phase 3 — Root Cause Analysis
-
-1. **Reproduce** — Identify minimal reproduction steps
-2. **Trace data flow** — Follow the value/control flow from input to error
-3. **Isolate** — Narrow to the smallest failing unit
-4. **Hypothesize** — Form explicit hypothesis before reading more code
-5. **Confirm** — Verify hypothesis against source, not just symptoms
-
-Common root cause categories:
-- **Null/undefined** — missing guard, wrong assumption about data shape
-- **Race condition** — async ordering, missing await, shared mutable state
-- **External dependency** — timeout, API contract change, env difference
-- **Type mismatch** — serialization, casting, implicit coercion
-- **Configuration** — env var missing, wrong default, deployment drift
-
----
-
-## Phase 4 — Log Analysis
-
-1. Read the full log output (not just the last line)
-2. Identify: timestamps, error levels, request IDs, correlation tokens
-3. Correlate events across log lines to build timeline
-4. Look for: first occurrence, frequency, affected subset, preceding events
-5. Summarize: what happened, when, why, and what was affected
-
----
-
-## Phase 5 — Performance Profiling
-
-1. **Measure baseline** — Never optimize blind
-   ```bash
-   time <command>
-   ```
-2. **Profile** — Language-appropriate tools:
-   - Node.js: `--prof`, `clinic.js`, `0x`
-   - Python: `cProfile`, `py-spy`, `line_profiler`
-   - Go: `pprof`
-3. **Identify hotspot** — Usually 1–2 functions account for >80% of time; use `gitnexus_context` to confirm call frequency
-4. **Fix the bottleneck** — Minimal targeted change
-5. **Verify** — Measure again, compare against baseline
-
----
-
-## Phase 6 — Remediation
-
-1. **Fix** — Minimal change that addresses the confirmed root cause
-2. **Verify** — Run the failing case to confirm fix
-3. **Regression test** — Add a test that would have caught this bug
-4. **Check blast radius** — `gitnexus_impact({target: "fixedSymbol", direction: "upstream"})`
-5. **Pre-commit scope check** — `gitnexus_detect_changes({scope: "staged"})`
-
----
-
-## Checklist
-
-```
-- [ ] Read full error / stack trace
-- [ ] Identify suspect symbol
-- [ ] gitnexus_detect_changes to check for regressions
-- [ ] gitnexus_query for error text or symptom
-- [ ] gitnexus_context on suspect (callers, callees, processes)
-- [ ] Trace execution flow via process resource
-- [ ] Read source files to confirm root cause
-- [ ] Form explicit hypothesis before fixing
-- [ ] Verify fix against failing reproduction
-- [ ] Add regression test
-- [ ] gitnexus_detect_changes() before committing
-```