@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/system-context/SERVICE_LIFECYCLE_MANAGEMENT.md

@@ -0,0 +1,119 @@
+---
+name: service-lifecycle-management
+category: system-context
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [services, docker, qdrant, ollama, neo4j, lifecycle, startup]
+difficulty: easy
+---
+
+# Service Lifecycle Management
+
+## Problem
+
+Projects depend on background services (Qdrant, Ollama, Neo4j, MySQL). Agents waste time when services are down, get cryptic connection errors, and don't know how to start/stop/check each service.
+
+## Solution Pattern
+
+Standard check → start → verify flow for each service.
+
+## Service Quick Reference
+
+### Qdrant (Native — Primary)
+
+```bash
+# Check
+curl -s http://localhost:6335/healthz
+
+# Start (background)
+"C:/path/to/tools/qdrant/qdrant.exe" --config-path "C:/path/to/tools/qdrant/config.yaml" &
+
+# Collection stats
+curl -s http://localhost:6335/collections/power_flow_memory | jq '.result.points_count'
+```
+
+### Qdrant (Docker — Backup)
+
+```bash
+# Check
+docker ps | grep qdrant
+
+# Start
+docker start qdrant  # if container exists
+# OR create new:
+docker run -d --name qdrant -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
+
+# Verify
+curl -s http://localhost:6333/healthz
+```
+
+### Ollama
+
+```bash
+# Check
+curl -s http://localhost:11434/api/tags | jq '.models[].name'
+
+# Start (if not running)
+ollama serve &
+
+# Verify embedding model
+curl -s http://localhost:11434/api/tags | jq '.models[] | select(.name | contains("nomic"))'
+```
+
+### Neo4j (Docker — CodeGraphContext)
+
+```bash
+# Check
+docker ps | grep neo4j-cgc
+
+# Start
+docker start neo4j-cgc
+
+# Verify
+curl -s http://localhost:7474 -u neo4j:codegraph123
+```
+
+### XAMPP MySQL
+
+```bash
+# Check
+"C:/xampp/mysql/bin/mysqladmin" -u root status
+
+# Start via XAMPP control panel or:
+"C:/xampp/xampp_start.exe"
+
+# Connect
+"C:/xampp/mysql/bin/mysql" -u root -p
+```
+
+## Graceful Degradation Pattern
+
+When a service is unavailable, don't crash — degrade:
+
+```javascript
+// Pattern: try service, fall back gracefully
+async function searchMemory(query) {
+  try {
+    const results = await qdrantSearch(query)
+    return results
+  } catch (err) {
+    if (err.code === 'ECONNREFUSED') {
+      console.log('Qdrant unavailable — searching flat files instead')
+      return flatFileSearch(query)
+    }
+    throw err
+  }
+}
+```
+
+## When to Use
+
+- Starting a work session that depends on background services
+- Debugging connection refused / timeout errors
+- Setting up services on a fresh machine
+
+## When NOT to Use
+
+- Cloud-hosted services (they have their own health checks)
+- CI/CD (use Docker Compose for all services)

package/skills-library/system-context/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: system-context
+description: Hardware specs, system recovery history, and environment details for the current system
+user-invocable: false
+---
+
+# System Context
+
+## Hardware
+
+- **Laptop:** ASUS ROG Zephyrus M16 (GU603ZX-XS97)
+- **CPU:** Intel i9-12900H
+- **GPU:** NVIDIA RTX 3080 Ti
+- **RAM:** 32GB
+- **SSD:** Samsung 990 Pro 2TB (C:)
+- **BIOS:** GU603ZX.311
+
+## System Recovery (December 2025)
+
+The system recovered from a catastrophic SSD failure:
+- Old Samsung 2TB died after overheating during Windows Update
+- New Samsung 990 Pro 2TB installed
+- All applications migrated from D: to C:
+- D: drive (dying SSD) physically removed
+- BIOS updated to GU603ZX.311
+- Secure Boot enabled
+
+**If system issues arise, check the WARRIOR handoffs for detailed history.**
+
+## Database Backups
+
+- `C:\Users\FirstName\Downloads\mongodb_data_backup`
+- `C:\Users\FirstName\Downloads\bookcraft_db_backup_16959`
+
+## SessionStart Hook
+
+The `warrior-workflow` plugin includes a SessionStart hook:
+1. Runs on: `startup`, `resume`, `clear`, `compact`
+2. Location: `C:\Users\<username>\.claude\plugins\warrior-workflow\hooks\`
+3. Displays recent handoff files and reminds to read them

package/skills-library/system-context/WINDOWS_DEV_ENVIRONMENT.md

@@ -0,0 +1,73 @@
+---
+name: windows-dev-environment
+category: system-context
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [windows, development, environment, xampp, node, python, paths]
+difficulty: easy
+---
+
+# Windows Dev Environment Patterns
+
+## Problem
+
+Windows dev environments juggle multiple runtimes (Node, Python, PHP/XAMPP), services (Docker, Qdrant, Ollama, Neo4j), and path conventions (backslash vs forward slash). Agents frequently trip on path separators, missing executables, and port conflicts.
+
+## Solution Pattern
+
+Standardize environment assumptions and provide quick diagnostics.
+
+## Path Conventions
+
+```javascript
+// ALWAYS use forward slashes in code — Node/Git Bash handle them fine on Windows
+const repoPath = 'C:/path/to/repos/my-project'
+
+// NEVER hardcode backslashes in strings
+const bad = 'C:\\path\\to\\my-project'  // Escape hell
+
+// For path joining, use path.join() — it handles the OS separator
+const fullPath = path.join(process.cwd(), 'src', 'index.ts')
+```
+
+## Runtime Locations (This System)
+
+| Runtime | Path | Port |
+|---------|------|------|
+| Node.js | System PATH | — |
+| Python 3.12 | `C:\Users\FirstName\AppData\Local\Programs\Python\Python312\` | — |
+| XAMPP MySQL | `C:\xampp\mysql\bin\` | 3306 |
+| XAMPP Apache | `C:\xampp\apache\bin\` | 80/443 |
+| Qdrant (native) | `C:\path\to\qdrant\qdrant.exe` | 6335 |
+| Qdrant (Docker) | Docker container | 6333 |
+| Neo4j (Docker) | Container `neo4j-cgc` | 7474/7687 |
+| Ollama | System PATH | 11434 |
+
+## Port Conflict Resolution
+
+```bash
+# Find what's using a port
+netstat -ano | findstr :5001
+
+# Kill by PID (from the last column of netstat output)
+taskkill /PID 12345 /F
+```
+
+## Common Gotchas
+
+1. **XAMPP MySQL vs Docker MySQL** — Both default to 3306. XAMPP wins if started first.
+2. **Python `pip` vs `pip3`** — On Windows, `pip` usually maps to Python 3.12 already.
+3. **Git Bash vs PowerShell** — Git Bash uses Unix paths (`/c/Users/...`), PowerShell uses Windows paths. Agent shell is bash.
+4. **`node_modules/.bin`** — Use `npx` or `npm run` instead of direct paths.
+
+## When to Use
+
+- Setting up a new project on this machine
+- Debugging "command not found" or port conflicts
+- Choosing between Docker and native service instances
+
+## When NOT to Use
+
+- Linux/Mac environments
+- CI/CD pipelines (use Docker there)

package/skills-library/testing/E2E_PLAYWRIGHT_PATTERNS.md

@@ -0,0 +1,99 @@
+---
+name: e2e-playwright-patterns
+category: testing
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [testing, e2e, playwright, browser, ui]
+difficulty: medium
+---
+
+# E2E Playwright Patterns
+
+## Problem
+
+Frontend looks correct in development but breaks in production. User flows span multiple pages, involve authentication, form submissions, and API calls. Manual QA can't cover all paths.
+
+## Solution Pattern
+
+Playwright end-to-end tests that simulate real user behavior: login, navigate, fill forms, click buttons, verify results — all in a real browser.
+
+## Code Example
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Course enrollment flow', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login as student
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'student@test.com');
+    await page.fill('[name="password"]', 'testpass');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('/dashboard');
+  });
+
+  test('student can browse and enroll in a course', async ({ page }) => {
+    // Navigate to courses
+    await page.click('text=Browse Courses');
+    await expect(page.locator('h1')).toHaveText('Available Courses');
+
+    // Click first course
+    await page.click('.course-card >> nth=0');
+    await expect(page.locator('.course-title')).toBeVisible();
+
+    // Enroll
+    await page.click('button:has-text("Enroll")');
+    await expect(page.locator('.enrollment-success')).toBeVisible();
+
+    // Verify in dashboard
+    await page.goto('/dashboard');
+    await expect(page.locator('.my-courses')).toContainText('Test Course');
+  });
+});
+```
+
+## Key Patterns
+
+### 1. Page Object Model (for complex flows)
+```typescript
+class LoginPage {
+  constructor(private page: Page) {}
+  async login(email: string, password: string) {
+    await this.page.fill('[name="email"]', email);
+    await this.page.fill('[name="password"]', password);
+    await this.page.click('button[type="submit"]');
+  }
+}
+```
+
+### 2. Test Isolation
+- Each test should be independent
+- Use API calls for setup (faster than UI)
+- Clean state between tests
+
+### 3. Selectors Priority
+1. `getByRole()` — Best (accessibility-driven)
+2. `getByText()` — Good (user-visible)
+3. `data-testid` — Acceptable (stable but not semantic)
+4. CSS selectors — Last resort (fragile)
+
+### 4. Waiting
+```typescript
+// Good — explicit wait for condition
+await expect(page.locator('.result')).toBeVisible({ timeout: 5000 });
+
+// Bad — arbitrary sleep
+await page.waitForTimeout(3000);
+```
+
+## When to Use
+- Critical user flows (login, checkout, enrollment)
+- Multi-page interactions
+- Form submission and validation
+- After major UI changes
+
+## When NOT to Use
+- API testing (use integration tests)
+- Unit logic (use unit tests)
+- Visual regression (use screenshot comparison tools)

package/skills-library/testing/INTEGRATION_TEST_STRATEGY.md

@@ -0,0 +1,82 @@
+---
+name: integration-test-strategy
+category: testing
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [testing, integration, api, database, supertest]
+difficulty: medium
+---
+
+# Integration Test Strategy
+
+## Problem
+
+Unit tests pass but the app breaks because components don't work together. Database queries, API routes, middleware chains, and authentication flows have integration seams that unit tests miss.
+
+## Solution Pattern
+
+Test real interactions between components with a test database, actual HTTP requests, and real middleware — but with controlled test data and isolated state.
+
+## Code Example
+
+```typescript
+// Express API integration test
+import request from 'supertest';
+import { app } from '../src/app';
+import { db } from '../src/database';
+
+describe('POST /api/courses', () => {
+  beforeAll(async () => {
+    await db.migrate.latest();
+    await db.seed.run();
+  });
+
+  afterAll(async () => {
+    await db.destroy();
+  });
+
+  test('creates course with valid data and auth', async () => {
+    const token = await getTestToken('admin');
+
+    const res = await request(app)
+      .post('/api/courses')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ title: 'Test Course', description: 'Integration test' });
+
+    expect(res.status).toBe(201);
+    expect(res.body.course.title).toBe('Test Course');
+
+    // Verify side effects
+    const saved = await db('courses').where({ id: res.body.course.id }).first();
+    expect(saved).toBeTruthy();
+  });
+
+  test('rejects unauthenticated request', async () => {
+    const res = await request(app)
+      .post('/api/courses')
+      .send({ title: 'Test' });
+
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+## Key Principles
+
+1. **Real database** — Use test database, not mocks
+2. **Real HTTP** — Use supertest, not function calls
+3. **Real middleware** — Auth, validation, rate limiting all active
+4. **Isolated state** — Each test suite seeds and cleans its own data
+5. **Test the contract** — Status codes, response shapes, error formats
+
+## When to Use
+- API route testing
+- Database query testing with real SQL
+- Authentication/authorization flows
+- Middleware chain behavior
+
+## When NOT to Use
+- Pure business logic (use unit tests)
+- UI rendering (use component tests)
+- Performance benchmarks (use load testing)

package/skills-library/testing/RED_GREEN_BUGFIX_GATE.md

@@ -0,0 +1,203 @@
+---
+name: red-green-bugfix-gate
+category: testing
+version: 1.0.0
+contributed: 2026-03-10
+contributor: scribe-bible
+last_updated: 2026-03-10
+tags: [debugging, tdd, regression, playwright, vitest, bugfix]
+difficulty: medium
+scope: general
+---
+
+# Red-Green Bugfix Gate
+
+## Problem
+
+Bug fixes applied without tests have three failure modes:
+1. **The fix doesn't actually work** — you think it's fixed because the error message changed, but the underlying behavior is still wrong.
+2. **The bug comes back** — a future change re-introduces it because nothing enforces the correct behavior.
+3. **The fix masks a deeper issue** — the symptom disappears but the root cause persists.
+
+Writing a test AFTER the fix proves nothing — you're just writing a test that passes. The test must fail FIRST (proving it captures the bug), then pass AFTER the fix (proving the fix works).
+
+## Solution Pattern
+
+**Red-Green Gate:** Insert a mandatory step between "root cause confirmed" and "apply fix":
+
+```
+ROOT CAUSE CONFIRMED
+        │
+        ▼
+  Write failing test  ← RED: test reproduces the bug
+        │
+        ▼
+    Apply the fix
+        │
+        ▼
+   Run test again     ← GREEN: test passes, proving fix works
+        │
+        ▼
+  Run full test suite ← NO REGRESSIONS
+        │
+        ▼
+     RESOLVED
+```
+
+### Decision Matrix: What Kind of Test?
+
+Not every bug needs the same test type. Pick based on where the bug lives:
+
+| Bug Location | Test Type | Tool | Speed |
+|-------------|-----------|------|-------|
+| Pure function / service logic | Unit test | Vitest | <1s |
+| API endpoint response | Integration test | Vitest + supertest | <3s |
+| Database query / ORM | Integration test | Vitest + test DB | <5s |
+| UI interaction / render | Component test | Vitest + testing-library | <3s |
+| Multi-page flow / auth | E2E test | Playwright | <30s |
+| Race condition / timing | E2E or manual | Playwright | varies |
+| Environment / config | Smoke test or skip | curl / manual | <1s |
+
+### When to SKIP the test gate:
+
+- **Typo fixes** — wrong import path, misspelled variable. The existing test suite catches these.
+- **Config/environment bugs** — wrong port, missing env var. Not worth a test.
+- **One-line obvious fixes** — wrong model ID, missing `await`. If the fix is self-evident from the root cause AND existing tests cover the area, skip.
+- **Third-party API changes** — the bug is external. Mock-based tests would be brittle.
+
+**Rule of thumb:** If you eliminated 2+ hypotheses to find the root cause, the bug is non-obvious enough to deserve a test.
+
+## Code Example
+
+### Before (no test gate — fix applied blind)
+
+```typescript
+// Developer sees: "Cannot read properties of undefined (reading 'length')"
+// Developer adds optional chaining:
+results.entities?.length  // "fixed"
+// But: did this actually fix the user-facing behavior? Is the data still wrong?
+// No test exists to answer this.
+```
+
+### After (Red-Green Gate)
+
+```typescript
+// Step 1: RED — Write test that reproduces the bug
+test('LightRAG search returns valid result shape even with no data', async () => {
+  const res = await request.post('/api/lightrag/search', {
+    data: { userId: 'test', query: 'nonexistent', mode: 'hybrid' },
+  })
+  expect(res.status()).toBe(200)
+  const data = await res.json()
+  // This is what crashed — accessing .length on undefined arrays
+  expect(data.entities).toBeDefined()
+  expect(Array.isArray(data.entities)).toBe(true)
+})
+// Run → FAILS (reproduces the bug) ✓
+
+// Step 2: Apply the fix (optional chaining + default empty arrays)
+
+// Step 3: GREEN — Run same test → PASSES ✓
+// Step 4: Run full suite → NO REGRESSIONS ✓
+```
+
+### Playwright E2E Example (UI bugs)
+
+```typescript
+// RED: Write test that reproduces the UI crash
+test('Settings page shows ElevenLabs without crash', async ({ page }) => {
+  await page.goto('/settings')
+  const apiKeysTab = page.locator('button:has-text("API Keys")')
+  await apiKeysTab.click()
+  // This crashed before the fix
+  await expect(page.locator('text=ElevenLabs').first()).toBeVisible()
+  // Verify no JS errors
+  const body = page.locator('body')
+  await expect(body).not.toContainText('Cannot read properties')
+})
+```
+
+## Integration with fire-debugger
+
+This gate injects between the existing Steps 4 and 5 of the fire-debugger agent:
+
+```
+Step 4: Root Cause Confirmed
+              │
+     ┌────────┴────────┐
+     │  RED-GREEN GATE  │  ← NEW
+     │                  │
+     │  Skip if:        │
+     │  • Typo/config   │
+     │  • Existing test │
+     │    covers it     │
+     │  • Self-evident  │
+     │    one-liner     │
+     │                  │
+     │  Otherwise:      │
+     │  1. Write RED    │
+     │  2. Verify FAIL  │
+     │  3. Apply fix    │
+     │  4. Verify GREEN │
+     └────────┬────────┘
+              │
+Step 5: Apply Fix (fix already applied in gate)
+Step 6: Verify Fix (test already passes from gate)
+Step 7: Regression Check (run full suite)
+```
+
+### What to add to fire-debugger.md (Step 4.5):
+
+```markdown
+### Step 4.5: Red-Green Bugfix Gate
+
+After confirming root cause, decide: does this bug warrant a regression test?
+
+**Write a test if ANY of:**
+- 2+ hypotheses were eliminated (non-obvious bug)
+- The bug is in business logic, not config
+- The area has no existing test coverage
+- The bug could recur from future changes
+
+**Skip the test if ALL of:**
+- Fix is a one-line typo/config change
+- Existing tests already cover this path
+- Bug is environmental (ports, env vars, OS-specific)
+
+**If writing a test:**
+1. Write the test BEFORE applying the fix
+2. Run it — must FAIL (RED) to prove it captures the bug
+3. Apply the fix
+4. Run it — must PASS (GREEN) to prove the fix works
+5. Continue to Step 7 (regression check)
+
+**Test placement:**
+- Unit/integration → alongside existing test files
+- E2E → `frontend/e2e/` or project's E2E directory
+- Name: `{bug-slug}.regression.test.ts` or add to existing spec
+```
+
+## When to Use
+
+- After confirming a bug's root cause, before applying the fix
+- When the bug was non-obvious (required hypothesis elimination)
+- When the fixed area lacks test coverage
+- When the bug could silently recur
+
+## When NOT to Use
+
+- Typo fixes (wrong import, misspelled variable)
+- Environment/config bugs (missing env var, wrong port)
+- Bugs in third-party dependencies (test the workaround, not the library)
+- Emergency hotfixes where time pressure overrides (but file a TODO to add the test later)
+
+## Related Skills
+
+- [VITEST_UNIT_TEST_PATTERNS](./VITEST_UNIT_TEST_PATTERNS.md) — unit test patterns
+- [E2E_PLAYWRIGHT_PATTERNS](./E2E_PLAYWRIGHT_PATTERNS.md) — E2E test patterns
+- [INTEGRATION_TEST_STRATEGY](./INTEGRATION_TEST_STRATEGY.md) — integration test strategy
+
+## References
+
+- TDD for bug fixes: Kent Beck's "make the failing test pass" principle
+- Today's real-world example: Scribe Bible v3.0 — LightRAG crash, FFmpeg lavfi, login rate limiter. The rate limiter bug was only caught because a screenshot (the test's failure artifact) showed "Too many login attempts" — without that test, we'd have debugged auth logic for hours.

package/skills-library/testing/TEST_DATA_MANAGEMENT.md

@@ -0,0 +1,69 @@
+---
+name: test-data-management
+category: testing
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+tags: [testing, fixtures, seeds, factories, test-data]
+difficulty: easy
+---
+
+# Test Data Management
+
+## Problem
+
+Tests break when shared test data changes. Tests depend on specific database state. Seed data grows stale and doesn't match the current schema. Tests that modify data break other tests.
+
+## Solution Pattern
+
+Use factories for dynamic data, seeds for reference data, and transaction rollback for isolation.
+
+## Code Example
+
+```typescript
+// Factory pattern — create data on demand
+function createTestUser(overrides = {}) {
+  return {
+    email: `test-${Date.now()}@example.com`,
+    name: 'Test User',
+    role: 'student',
+    ...overrides,
+  };
+}
+
+function createTestCourse(overrides = {}) {
+  return {
+    title: `Course ${Date.now()}`,
+    description: 'Test course',
+    instructor_id: null,
+    ...overrides,
+  };
+}
+
+// Usage in tests
+test('enrolled student sees course content', async () => {
+  const user = await db('users').insert(createTestUser({ role: 'student' })).returning('*');
+  const course = await db('courses').insert(createTestCourse()).returning('*');
+  await db('enrollments').insert({ user_id: user[0].id, course_id: course[0].id });
+
+  // Test with fresh, isolated data
+  const content = await getCourseContent(user[0].id, course[0].id);
+  expect(content).toBeDefined();
+});
+```
+
+## Key Patterns
+
+1. **Factories > Fixtures** — Generate unique data per test to prevent collisions
+2. **Transaction rollback** — Wrap each test in a transaction, rollback after
+3. **Minimal data** — Only create what the test needs, nothing more
+4. **No shared mutable state** — Each test creates its own data
+
+## When to Use
+- Any test that requires database state
+- Integration tests with multiple related records
+- Tests that verify data relationships
+
+## When NOT to Use
+- Unit tests with mocked data
+- Tests that don't touch the database