@ngockhoale/ukit 1.6.8 → 2.0.1

package/templates/.claude/skills/sql-optimization-patterns/references/query-patterns.md

@@ -0,0 +1,204 @@
+# SQL Query Optimization Patterns (Detailed Examples)
+
+Full before/after code for each pattern summarized in the main skill.
+
+## Pattern 1: Eliminate N+1 Queries
+
+**Problem: N+1 Query Anti-Pattern**
+```python
+# Bad: Executes N+1 queries
+users = db.query("SELECT * FROM users LIMIT 10")
+for user in users:
+    orders = db.query("SELECT * FROM orders WHERE user_id = ?", user.id)
+    # Process orders
+```
+
+**Solution: Use JOINs or Batch Loading**
+```sql
+-- Solution 1: JOIN
+SELECT
+    u.id, u.name,
+    o.id as order_id, o.total
+FROM users u
+LEFT JOIN orders o ON u.id = o.user_id
+WHERE u.id IN (1, 2, 3, 4, 5);
+
+-- Solution 2: Batch query
+SELECT * FROM orders
+WHERE user_id IN (1, 2, 3, 4, 5);
+```
+
+```python
+# Good: Single query with JOIN or batch load
+# Using JOIN
+results = db.query("""
+    SELECT u.id, u.name, o.id as order_id, o.total
+    FROM users u
+    LEFT JOIN orders o ON u.id = o.user_id
+    WHERE u.id IN (1, 2, 3, 4, 5)
+""")
+
+# Or batch load
+users = db.query("SELECT * FROM users LIMIT 10")
+user_ids = [u.id for u in users]
+orders = db.query(
+    "SELECT * FROM orders WHERE user_id IN (?)",
+    user_ids
+)
+# Group orders by user_id
+orders_by_user = {}
+for order in orders:
+    orders_by_user.setdefault(order.user_id, []).append(order)
+```
+
+## Pattern 2: Optimize Pagination
+
+**Bad: OFFSET on Large Tables**
+```sql
+-- Slow for large offsets
+SELECT * FROM users
+ORDER BY created_at DESC
+LIMIT 20 OFFSET 100000;  -- Very slow!
+```
+
+**Good: Cursor-Based Pagination**
+```sql
+-- Much faster: Use cursor (last seen ID)
+SELECT * FROM users
+WHERE created_at < '2024-01-15 10:30:00'  -- Last cursor
+ORDER BY created_at DESC
+LIMIT 20;
+
+-- With composite sorting
+SELECT * FROM users
+WHERE (created_at, id) < ('2024-01-15 10:30:00', 12345)
+ORDER BY created_at DESC, id DESC
+LIMIT 20;
+
+-- Requires index
+CREATE INDEX idx_users_cursor ON users(created_at DESC, id DESC);
+```
+
+## Pattern 3: Aggregate Efficiently
+
+**Optimize COUNT Queries:**
+```sql
+-- Bad: Counts all rows
+SELECT COUNT(*) FROM orders;  -- Slow on large tables
+
+-- Good: Use estimates for approximate counts
+SELECT reltuples::bigint AS estimate
+FROM pg_class
+WHERE relname = 'orders';
+
+-- Good: Filter before counting
+SELECT COUNT(*) FROM orders
+WHERE created_at > NOW() - INTERVAL '7 days';
+
+-- Better: Use index-only scan
+CREATE INDEX idx_orders_created ON orders(created_at);
+SELECT COUNT(*) FROM orders
+WHERE created_at > NOW() - INTERVAL '7 days';
+```
+
+**Optimize GROUP BY:**
+```sql
+-- Bad: Group by then filter
+SELECT user_id, COUNT(*) as order_count
+FROM orders
+GROUP BY user_id
+HAVING COUNT(*) > 10;
+
+-- Better: Filter first, then group (if possible)
+SELECT user_id, COUNT(*) as order_count
+FROM orders
+WHERE status = 'completed'
+GROUP BY user_id
+HAVING COUNT(*) > 10;
+
+-- Best: Use covering index
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+```
+
+## Pattern 4: Subquery Optimization
+
+**Transform Correlated Subqueries:**
+```sql
+-- Bad: Correlated subquery (runs for each row)
+SELECT u.name, u.email,
+    (SELECT COUNT(*) FROM orders o WHERE o.user_id = u.id) as order_count
+FROM users u;
+
+-- Good: JOIN with aggregation
+SELECT u.name, u.email, COUNT(o.id) as order_count
+FROM users u
+LEFT JOIN orders o ON o.user_id = u.id
+GROUP BY u.id, u.name, u.email;
+
+-- Better: Use window functions
+SELECT DISTINCT ON (u.id)
+    u.name, u.email,
+    COUNT(o.id) OVER (PARTITION BY u.id) as order_count
+FROM users u
+LEFT JOIN orders o ON o.user_id = u.id;
+```
+
+**Use CTEs for Clarity:**
+```sql
+-- Using Common Table Expressions
+WITH recent_users AS (
+    SELECT id, name, email
+    FROM users
+    WHERE created_at > NOW() - INTERVAL '30 days'
+),
+user_order_counts AS (
+    SELECT user_id, COUNT(*) as order_count
+    FROM orders
+    WHERE created_at > NOW() - INTERVAL '30 days'
+    GROUP BY user_id
+)
+SELECT ru.name, ru.email, COALESCE(uoc.order_count, 0) as orders
+FROM recent_users ru
+LEFT JOIN user_order_counts uoc ON ru.id = uoc.user_id;
+```
+
+## Pattern 5: Batch Operations
+
+**Batch INSERT:**
+```sql
+-- Bad: Multiple individual inserts
+INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
+INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com');
+INSERT INTO users (name, email) VALUES ('Carol', 'carol@example.com');
+
+-- Good: Batch insert
+INSERT INTO users (name, email) VALUES
+    ('Alice', 'alice@example.com'),
+    ('Bob', 'bob@example.com'),
+    ('Carol', 'carol@example.com');
+
+-- Better: Use COPY for bulk inserts (PostgreSQL)
+COPY users (name, email) FROM '/tmp/users.csv' CSV HEADER;
+```
+
+**Batch UPDATE:**
+```sql
+-- Bad: Update in loop
+UPDATE users SET status = 'active' WHERE id = 1;
+UPDATE users SET status = 'active' WHERE id = 2;
+-- ... repeat for many IDs
+
+-- Good: Single UPDATE with IN clause
+UPDATE users
+SET status = 'active'
+WHERE id IN (1, 2, 3, 4, 5, ...);
+
+-- Better: Use temporary table for large batches
+CREATE TEMP TABLE temp_user_updates (id INT, new_status VARCHAR);
+INSERT INTO temp_user_updates VALUES (1, 'active'), (2, 'active'), ...;
+
+UPDATE users u
+SET status = t.new_status
+FROM temp_user_updates t
+WHERE u.id = t.id;
+```

package/templates/.claude/skills/subagent-driven-development/SKILL.md

@@ -106,60 +106,15 @@ After final review passes:
 - **REQUIRED SUB-SKILL:** Use finishing-a-development-branch
 - Follow that skill to verify tests, present options, execute choice
 
-## Example Workflow
-
-```
-You: I'm using Subagent-Driven Development to execute this plan.
-
-[Load plan, create TodoWrite]
-
-Task 1: Hook installation script
-
-[Dispatch implementation subagent]
-Subagent: Implemented install-hook with tests, 5/5 passing
-
-[Get git SHAs, dispatch code-reviewer]
-Reviewer: Strengths: Good test coverage. Issues: None. Ready.
-
-[Mark Task 1 complete]
-
-Task 2: Recovery modes
-
-[Dispatch implementation subagent]
-Subagent: Added verify/repair, 8/8 tests passing
-
-[Dispatch code-reviewer]
-Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
-
-[Dispatch fix subagent]
-Fix subagent: Added progress every 100 conversations
-
-[Verify fix, mark Task 2 complete]
-
-...
-
-[After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
-
-Done!
-```
+Worked two-task example (dispatch → review → fix → complete): [`example-workflow.md`](example-workflow.md).
 
 ## Advantages
 
-**vs. Manual execution:**
-- Subagents follow TDD naturally
-- Fresh context per task (no confusion)
-- Parallel-safe (subagents don't interfere)
+**vs. Manual execution:** subagents follow TDD naturally, fresh context per task (no confusion), parallel-safe (subagents don't interfere).
 
-**vs. Executing Plans:**
-- Same session (no handoff)
-- Continuous progress (no waiting)
-- Review checkpoints automatic
+**vs. Executing Plans:** see Overview above (same session, no handoff, continuous progress).
 
-**Cost:**
-- More subagent invocations
-- But catches issues early (cheaper than debugging later)
+**Cost:** more subagent invocations, but catches issues early (cheaper than debugging later).
 
 ## Red Flags
 
@@ -185,5 +140,3 @@ Done!
 
 **Alternative workflow:**
 - **executing-plans** - Use for parallel session instead of same-session execution
-
-See code-reviewer template: requesting-code-review/code-reviewer.md

package/templates/.claude/skills/subagent-driven-development/example-workflow.md

@@ -0,0 +1,40 @@
+# Subagent-Driven Development — Example Workflow
+
+Worked example of the 7-step process in `SKILL.md`, showing two tasks running through dispatch → review → fix → complete.
+
+```
+You: I'm using Subagent-Driven Development to execute this plan.
+
+[Load plan, create TodoWrite]
+
+Task 1: Hook installation script
+
+[Dispatch implementation subagent]
+Subagent: Implemented install-hook with tests, 5/5 passing
+
+[Get git SHAs, dispatch code-reviewer]
+Reviewer: Strengths: Good test coverage. Issues: None. Ready.
+
+[Mark Task 1 complete]
+
+Task 2: Recovery modes
+
+[Dispatch implementation subagent]
+Subagent: Added verify/repair, 8/8 tests passing
+
+[Dispatch code-reviewer]
+Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting
+
+[Dispatch fix subagent]
+Fix subagent: Added progress every 100 conversations
+
+[Verify fix, mark Task 2 complete]
+
+...
+
+[After all tasks]
+[Dispatch final code-reviewer]
+Final reviewer: All requirements met, ready to merge
+
+Done!
+```

package/templates/.claude/skills/systematic-debugging/SKILL.md

@@ -242,27 +242,7 @@ If you catch yourself thinking:
 
 **When you see these:** STOP. Return to Phase 1.
 
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
-| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
-| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
-| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
-| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
-| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
-| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
-| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
-
-## Quick Reference
-
-| Phase | Key Activities | Success Criteria |
-|-------|---------------|------------------|
-| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identify differences |
-| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
-| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+Compact rationalization/quick-reference/impact tables: [`reference-tables.md`](reference-tables.md).
 
 ## When Process Reveals "No Root Cause"
 
@@ -286,10 +266,4 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 - **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2
 - **verification-before-completion** - Verify fix worked before claiming success
 
-## Real-World Impact
-
-From debugging sessions:
-- Systematic approach: 15-30 minutes to fix
-- Random fixes approach: 2-3 hours of thrashing
-- First-time fix rate: 95% vs 40%
-- New bugs introduced: Near zero vs common
+Real-world before/after impact numbers: [`reference-tables.md`](reference-tables.md#real-world-impact).

package/templates/.claude/skills/systematic-debugging/reference-tables.md

@@ -0,0 +1,33 @@
+# Systematic Debugging — Reference Tables
+
+Compact restatements of the four-phase process in `SKILL.md`, plus supporting data. Read the phases in `SKILL.md` first; these tables are for quick lookup during a session, not a substitute for the phases.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/templates/.claude/skills/test-driven-development/SKILL.md

@@ -253,21 +253,7 @@ Tests-first force edge case discovery before implementing. Tests-after verify yo
 
 30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
 
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
-| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
-| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
-| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
-| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
-| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
-| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
-| "Existing code has no tests" | You're improving it. Add tests for existing code. |
+Table of common rationalizations and why each is wrong: [`reference-tables.md`](reference-tables.md).
 
 ## Red Flags - STOP and Start Over
 
@@ -287,42 +273,7 @@ Tests-first force edge case discovery before implementing. Tests-after verify yo
 
 **All of these mean: Delete code. Start over with TDD.**
 
-## Example: Bug Fix
-
-**Bug:** Empty email accepted
-
-**RED**
-```typescript
-test('rejects empty email', async () => {
-  const result = await submitForm({ email: '' });
-  expect(result.error).toBe('Email required');
-});
-```
-
-**Verify RED**
-```bash
-$ npm test
-FAIL: expected 'Email required', got undefined
-```
-
-**GREEN**
-```typescript
-function submitForm(data: FormData) {
-  if (!data.email?.trim()) {
-    return { error: 'Email required' };
-  }
-  // ...
-}
-```
-
-**Verify GREEN**
-```bash
-$ npm test
-PASS
-```
-
-**REFACTOR**
-Extract validation for multiple fields if needed.
+Worked RED-GREEN-REFACTOR example for a bug fix: [`reference-tables.md`](reference-tables.md#example-bug-fix).
 
 ## Verification Checklist
 

package/templates/.claude/skills/test-driven-development/reference-tables.md

@@ -0,0 +1,56 @@
+# TDD — Reference Tables and Worked Example
+
+Compact restatements of the Red-Green-Refactor cycle in `SKILL.md`, plus a worked example. Read `SKILL.md` first; these are for quick lookup during a session.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
+| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
+| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
+| "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
+| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
+| "Existing code has no tests" | You're improving it. Add tests for existing code. |
+
+## Example: Bug Fix
+
+**Bug:** Empty email accepted
+
+**RED**
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**Verify RED**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**GREEN**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**Verify GREEN**
+```bash
+$ npm test
+PASS
+```
+
+**REFACTOR**
+Extract validation for multiple fields if needed.

package/templates/.claude/skills/testing-anti-patterns/SKILL.md

@@ -273,16 +273,7 @@ TDD cycle:
 
 **If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
 
-## Quick Reference
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Assert on mock elements | Test real component or unmock it |
-| Test-only methods in production | Move to test utilities |
-| Mock without understanding | Understand dependencies first, mock minimally |
-| Incomplete mocks | Mirror real API completely |
-| Tests as afterthought | TDD - tests first |
-| Over-complex mocks | Consider integration tests |
+Compact anti-pattern → fix table: [`reference-tables.md`](reference-tables.md).
 
 ## Red Flags
 

package/templates/.claude/skills/testing-anti-patterns/reference-tables.md

@@ -0,0 +1,14 @@
+# Testing Anti-Patterns — Quick Reference
+
+Compact restatement of the five anti-patterns in `SKILL.md`. Read the full anti-pattern sections first for the violation/fix code examples; this table is for quick lookup during a session.
+
+## Quick Reference
+
+| Anti-Pattern | Fix |
+|--------------|-----|
+| Assert on mock elements | Test real component or unmock it |
+| Test-only methods in production | Move to test utilities |
+| Mock without understanding | Understand dependencies first, mock minimally |
+| Incomplete mocks | Mirror real API completely |
+| Tests as afterthought | TDD - tests first |
+| Over-complex mocks | Consider integration tests |

package/templates/.claude/skills/verification-before-completion/SKILL.md

@@ -73,37 +73,7 @@ Skip any step = lying, not verifying
 | "Partial check is enough" | Partial proves nothing |
 | "Different words so rule doesn't apply" | Spirit over letter |
 
-## Key Patterns
-
-**Tests:**
-```
-✅ [Run test command] [See: 34/34 pass] "All tests pass"
-❌ "Should pass now" / "Looks correct"
-```
-
-**Regression tests (TDD Red-Green):**
-```
-✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
-❌ "I've written a regression test" (without red-green verification)
-```
-
-**Build:**
-```
-✅ [Run build] [See: exit 0] "Build passes"
-❌ "Linter passed" (linter doesn't check compilation)
-```
-
-**Requirements:**
-```
-✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
-❌ "Tests pass, phase complete"
-```
-
-**Agent delegation:**
-```
-✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
-❌ Trust agent report
-```
+Worked ✅/❌ examples for each claim type above: [`key-patterns.md`](key-patterns.md).
 
 ## Why This Matters
 

package/templates/.claude/skills/verification-before-completion/key-patterns.md

@@ -0,0 +1,33 @@
+# Verification Before Completion — Key Patterns
+
+Worked ✅/❌ examples for each claim type in the "Common Failures" table in `SKILL.md`.
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```

package/templates/CLAUDE.md

@@ -66,6 +66,10 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
+## Skill Quality (maintainer-only)
+
+- When editing a template skill/agent under `templates/.claude/`, read `.claude/skills/skill-quality/SKILL.md` before shipping the change.
+
 ## UKit v{{ukit.version}} Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.

package/src/core/memory/index.js

@@ -1,2 +0,0 @@
-export { detectConflict, runHygiene } from './hygiene.js';
-export { expand, getContextInjection, search } from './retrieval.js';

package/src/core/router/index.js

@@ -1,2 +0,0 @@
-export { askAdvisor, shouldEscalate } from './advisor.js';
-export { classifyTask, detectComplexity, selectModel } from './router.js';

package/src/core/validation/index.js

@@ -1,2 +0,0 @@
-export { scoreConfidence } from './confidence.js';
-export { validateOutput } from './validator.js';