xtrm-tools 0.7.3 → 0.7.7

package/.xtrm/skills/default/using-specialists/evals/evals.json

@@ -0,0 +1,68 @@
+{
+  "skill_name": "specialists-usage",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "bug-investigation",
+      "prompt": "I'm seeing intermittent failures where specialist jobs show status 'done' in `specialists feed` but `specialists result` says they're still running. Can you investigate what's causing this inconsistency in the job lifecycle?",
+      "expected_output": "Agent delegates to a specialist (e.g. bug-hunt) rather than diving into the source code themselves. Should create a bead first, then run the specialist with --bead.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of reading source files directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_investigate",
+          "description": "Agent does not read supervisor.ts, status.json, or other source files to investigate the bug themselves"
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "eval_name": "code-review",
+      "prompt": "The specialist runner module at src/specialist/runner.ts is the core execution layer. Can you review it for bugs, edge cases, and code quality issues? It's about 300 lines and fairly complex.",
+      "expected_output": "Agent delegates to a specialist (e.g. parallel-review or codebase-explorer) rather than reading the file and writing a review themselves. Should create a bead first.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of reading runner.ts directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_review",
+          "description": "Agent does not read runner.ts and write their own code review"
+        }
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "eval_name": "test-coverage",
+      "prompt": "src/specialist/loader.ts handles YAML file discovery and caching. Looking at the tests in tests/unit/specialist/loader.test.ts, what's missing? Can you add the coverage gaps?",
+      "expected_output": "Agent delegates to a specialist (e.g. test-runner) rather than reading the files and writing tests themselves. Should create a bead first.",
+      "assertions": [
+        {
+          "name": "invokes_specialist",
+          "description": "Agent runs `specialists run` or calls use_specialist/start_specialist instead of writing tests directly"
+        },
+        {
+          "name": "creates_bead_first",
+          "description": "Agent creates a tracking bead before invoking the specialist"
+        },
+        {
+          "name": "does_not_self_write_tests",
+          "description": "Agent does not read loader.ts and loader.test.ts and write new test cases themselves"
+        }
+      ],
+      "files": []
+    }
+  ]
+}

package/.xtrm/skills/default/using-tdd/SKILL.md

@@ -0,0 +1,410 @@
+---
+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/.xtrm/skills/default/using-xtrm/SKILL.md

@@ -0,0 +1,127 @@
+---
+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` |