@ngockhoale/ukit 1.1.6

package/templates/.claude/skills/research/REFERENCE.md

@@ -0,0 +1,399 @@
+# Research Tools Reference
+
+Detailed documentation for all research tools.
+
+---
+
+## searchGitHub
+
+Search GitHub repositories for actual code patterns.
+
+### Basic Usage
+
+**CRITICAL**: Search for **literal code**, not keywords.
+
+✅ **Good queries**:
+```javascript
+// Finding React useState patterns
+query: "useState("
+language: ["TypeScript", "TSX"]
+
+// Finding error handling in async functions
+query: "(?s)try {.*await"
+useRegexp: true
+language: ["TypeScript"]
+
+// Finding specific API usage
+query: "betterAuth({"
+language: ["TypeScript"]
+```
+
+❌ **Bad queries**:
+```javascript
+// These are KEYWORDS, not code patterns
+query: "react hooks tutorial"  // Won't find code!
+query: "best practices"        // Won't find code!
+query: "how to use useState"   // Won't find code!
+```
+
+### Advanced Usage
+
+#### 1. Regex for flexible patterns
+```javascript
+{
+  query: "(?s)useState\\(.*loading",  // useState with loading variable
+  useRegexp: true,
+  language: ["TSX"]
+}
+```
+
+**Note**: Prefix with `(?s)` to match across multiple lines.
+
+#### 2. Filter by repository
+```javascript
+{
+  query: "getServerSession",
+  repo: "vercel/",  // All Vercel repos
+  language: ["TypeScript"]
+}
+```
+
+#### 3. Filter by file path
+```javascript
+{
+  query: "export default {",
+  path: "next.config.js",  // Only in Next.js config files
+}
+```
+
+#### 4. Case sensitivity
+```javascript
+{
+  query: "CORS(",
+  matchCase: true,  // Exact case match
+  language: ["Python"]
+}
+```
+
+### Hidden Tricks
+
+**Trick 1: Find specific library usage in popular projects**
+```javascript
+{
+  query: "figma: {",
+  repo: "better-auth/",
+  language: ["TypeScript"]
+}
+```
+
+**Trick 2: Search for error handling patterns**
+```javascript
+{
+  query: "(?s)try {.*catch.*error",
+  useRegexp: true,
+  language: ["TypeScript"]
+}
+```
+
+**Trick 3: Find configuration patterns**
+```javascript
+{
+  query: "export default {",
+  path: "*.config.ts",
+}
+```
+
+**Trick 4: Find how others handle edge cases**
+```javascript
+{
+  query: "if (!data)",
+  language: ["TypeScript"],
+  repo: "vercel/"  // Learn from production code
+}
+```
+
+### Watch Out For
+
+⚠️ **Pitfall 1: Using keywords instead of code**
+- Don't search for "react hooks best practices"
+- Search for `"useState("` instead
+
+⚠️ **Pitfall 2: Forgetting regex anchors**
+- Use `(?s)` for multiline matching
+- Escape special chars: `\\{` not `{`
+
+⚠️ **Pitfall 3: Too broad search**
+- `"export"` will return millions of results
+- Be specific: `"export const auth ="`
+
+⚠️ **Pitfall 4: Ignoring language filter**
+- Always specify language to reduce noise
+- Use `["TypeScript", "TSX"]` for React projects
+
+---
+
+## get_code_context_exa
+
+Get official documentation and high-quality examples for libraries/APIs.
+
+### Basic Usage
+
+✅ **Good queries**:
+```javascript
+{
+  query: "Next.js 15 server actions best practices",
+  tokensNum: 5000
+}
+
+{
+  query: "Better Auth Figma OAuth integration guide",
+  tokensNum: 3000
+}
+
+{
+  query: "Drizzle ORM PostgreSQL schema migration",
+  tokensNum: 8000
+}
+```
+
+### Advanced Usage
+
+#### 1. Adjust token count based on depth
+```javascript
+// Quick reference - 1000-3000 tokens
+{ query: "React useEffect cleanup", tokensNum: 2000 }
+
+// Comprehensive guide - 5000-10000 tokens
+{ query: "Next.js 15 full authentication flow", tokensNum: 8000 }
+
+// Deep dive - 15000-50000 tokens
+{ query: "Stripe webhook handling complete guide", tokensNum: 20000 }
+```
+
+#### 2. Include version/year for latest docs
+```javascript
+{
+  query: "Next.js 15 2025 app router",  // Specify year!
+  tokensNum: 5000
+}
+```
+
+#### 3. Focus on specific aspects
+```javascript
+// Not: "React hooks"
+// Better: "React hooks performance optimization patterns"
+
+{
+  query: "React hooks performance optimization patterns",
+  tokensNum: 5000
+}
+```
+
+### Hidden Tricks
+
+**Trick 1: Compare official docs across versions**
+```javascript
+// Search 1
+{ query: "Next.js 14 server components", tokensNum: 3000 }
+// Search 2
+{ query: "Next.js 15 server components", tokensNum: 3000 }
+// Compare the differences
+```
+
+**Trick 2: Get migration guides**
+```javascript
+{
+  query: "migrate from Next.js 14 to 15 breaking changes",
+  tokensNum: 8000
+}
+```
+
+**Trick 3: Find official examples**
+```javascript
+{
+  query: "Vercel Next.js 15 official examples repository",
+  tokensNum: 5000
+}
+```
+
+### Watch Out For
+
+⚠️ **Pitfall 1: Too generic queries**
+- "React" → Too broad
+- "React Server Components rendering patterns 2025" → Specific
+
+⚠️ **Pitfall 2: Wrong token count**
+- Too low (< 2000): May miss critical details
+- Too high (> 20000): Wastes time and tokens
+- Default 5000 is usually good
+
+⚠️ **Pitfall 3: Outdated docs**
+- ALWAYS include year: "2025" or "latest"
+- Check account for "Today's date" in context
+
+---
+
+## web_search_exa
+
+Real-time web search for articles, blog posts, discussions.
+
+### Basic Usage
+
+✅ **Good use cases**:
+```javascript
+// Find recent articles
+{
+  query: "Next.js 15 performance improvements 2025",
+  numResults: 8
+}
+
+// Find comparisons
+{
+  query: "Drizzle vs Prisma 2025 comparison",
+  numResults: 5
+}
+
+// Find official announcements
+{
+  query: "Better Auth 2.0 release notes",
+  numResults: 3
+}
+```
+
+### Advanced Usage
+
+#### 1. Adjust result count
+```javascript
+// Quick scan - 3-5 results
+{ query: "React 19 new features", numResults: 3 }
+
+// Comprehensive - 8-10 results
+{ query: "Next.js deployment best practices", numResults: 10 }
+```
+
+#### 2. Search type
+```javascript
+// Quick search
+{ query: "...", type: "fast" }
+
+// Deep research
+{ query: "...", type: "deep" }
+
+// Balanced (default)
+{ query: "...", type: "auto" }
+```
+
+#### 3. Livecrawl for latest content
+```javascript
+{
+  query: "Next.js 15 RC release notes",
+  livecrawl: "preferred",  // Get latest content
+  numResults: 3
+}
+```
+
+### Hidden Tricks
+
+**Trick 1: Find GitHub discussions**
+```javascript
+{
+  query: "site:github.com better-auth figma OAuth issue",
+  numResults: 5
+}
+```
+
+**Trick 2: Official docs only**
+```javascript
+{
+  query: "site:nextjs.org server actions",
+  numResults: 3
+}
+```
+
+**Trick 3: Find real-world war stories**
+```javascript
+{
+  query: "debugging Next.js server actions production",
+  type: "deep",
+  numResults: 8
+}
+```
+
+### Watch Out For
+
+⚠️ **Pitfall 1: Generic queries**
+- "Next.js tutorial" → Low quality
+- "Next.js 15 server actions error handling patterns" → High quality
+
+⚠️ **Pitfall 2: Too many results**
+- > 10 results is usually noise
+- 3-5 results is often enough
+
+⚠️ **Pitfall 3: Not using site: filter**
+- Use `site:` to focus on authoritative sources
+
+---
+
+## Token/Result Guidelines
+
+### searchGitHub
+- No limit on results, but first 10-20 are usually enough
+- Use specific queries to reduce noise
+
+### get_code_context_exa
+| Use Case | Tokens |
+|----------|--------|
+| Quick API reference | 1000-3000 |
+| Comprehensive guide | 5000-10000 |
+| Deep documentation | 15000-30000 |
+| Exhaustive research | 30000-50000 |
+
+### web_search_exa
+| Use Case | Results |
+|----------|---------|
+| Quick fact check | 1-3 |
+| Standard research | 5-8 |
+| Comprehensive | 8-10 |
+| Avoid > 10 | Too noisy |
+
+---
+
+## Common Patterns
+
+### Pattern 1: "How do I use X?"
+1. `get_code_context_exa`: Get official docs (5000 tokens)
+2. `searchGitHub`: Find real usage (3-5 examples)
+3. `web_search_exa`: Find best practices (5 results)
+
+### Pattern 2: "Why is X not working?"
+1. `web_search_exa`: Search exact error (deep, 5 results)
+2. `searchGitHub`: Find how others fixed it (regex search)
+3. `get_code_context_exa`: Check official troubleshooting (3000 tokens)
+
+### Pattern 3: "X vs Y?"
+1. `web_search_exa`: Find comparisons (8 results)
+2. `searchGitHub`: Check real adoption (compare result counts)
+3. `get_code_context_exa`: Read both official docs (5000 tokens each)
+
+### Pattern 4: "Latest version of X?"
+1. `get_code_context_exa`: "X 2025 latest docs" (5000 tokens)
+2. `web_search_exa`: "X release notes" (livecrawl: preferred, 3 results)
+3. `searchGitHub`: Find recent usage patterns
+
+---
+
+## Quick Troubleshooting
+
+**No results from searchGitHub?**
+- Check: Are you using code, not keywords?
+- Try: Simplify your query
+- Example: `"useState("` not `"react useState hook"`
+
+**Outdated docs from get_code_context_exa?**
+- Check: Did you include year in query?
+- Try: Add "2025" or "latest" to query
+
+**Too many irrelevant results from web_search_exa?**
+- Check: Is query too generic?
+- Try: Use `site:` filter for authoritative sources
+- Reduce: numResults to 3-5

package/templates/.claude/skills/research/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: research
+description: Research libraries, APIs, and patterns using searchGitHub and Exa tools. Finds real-world implementations and saves structured reports to docs/research/. Use when investigating technologies, debugging issues, or comparing options.
+allowed-tools: [mcp__mcp-router__searchGitHub, mcp__mcp-router__web_search_exa, mcp__mcp-router__get_code_context_exa, Write, Bash, Read, Glob]
+---
+
+# Technical Research Skill
+
+You are Linus Torvalds conducting technical research. Use `searchGitHub` and Exa tools to find **real-world implementations**, not tutorials.
+
+---
+
+## Available Tools
+
+### 1. `searchGitHub` - Find Real Code
+Search GitHub repositories for actual usage patterns.
+
+**CRITICAL**: This is **literal code search** (like grep), NOT keyword search.
+
+✅ Good: `"useState("`, `"betterAuth({"`, `"(?s)try {.*await"`
+❌ Bad: `"react tutorial"`, `"best practices"`, `"how to use"`
+
+See [REFERENCE.md](./REFERENCE.md#searchgithub) for detailed usage.
+
+### 2. `web_search_exa` - Web Search
+Real-time web search with content scraping.
+
+See [REFERENCE.md](./REFERENCE.md#web_search_exa) for detailed usage.
+
+### 3. `get_code_context_exa` - Code Context
+Get high-quality library/SDK/API documentation and examples.
+
+See [REFERENCE.md](./REFERENCE.md#get_code_context_exa) for detailed usage.
+
+---
+
+## Research Workflow
+
+When user asks to research a technology/library/pattern:
+
+### Step 1: Understand the question
+
+Identify what user needs:
+- **How-to**: "How do I implement X?"
+- **Best practices**: "What's the right way to do X?"
+- **Comparison**: "Should I use X or Y?"
+- **Debugging**: "Why is X not working?"
+
+### Step 2: Choose the right tool combination
+
+| User Need | Tool Strategy |
+|-----------|---------------|
+| "How to use library X?" | `get_code_context_exa` first, then `searchGitHub` for real usage |
+| "Real-world examples of X" | `searchGitHub` for actual code |
+| "Best practices for X" | `web_search_exa` for recent articles + `searchGitHub` for code |
+| "X vs Y comparison" | `web_search_exa` for analysis + `searchGitHub` to verify claims |
+| "Latest docs for X" | `get_code_context_exa` with specific version/year |
+
+See [EXAMPLES.md](./EXAMPLES.md) for detailed strategies.
+
+### Step 3: Execute search strategy
+
+Use the tools in combination. Always:
+- **Start specific**: Use precise queries
+- **Verify with code**: Don't trust opinions without evidence
+- **Check dates**: Prefer 2025 content over old posts
+- **Cross-reference**: Multiple sources confirm truth
+
+### Step 4: Synthesize findings
+
+Output format:
+```
+## 【Research Results】
+
+### Core Finding
+<One-sentence answer to the user's question>
+
+### Evidence from Real Code
+<2-3 examples from GitHub showing actual usage>
+
+### Official Context
+<Key points from Exa code context / web search>
+
+### Recommended Approach
+<Specific actionable recommendation based on evidence>
+
+### Watch Out For
+<Pitfalls found in research, anti-patterns to avoid>
+```
+
+### Step 5: Save research document
+
+**ALWAYS save research to `docs/research/`** using this format:
+
+**Filename**: `docs/research/<YYYY-MM-DD>_<topic-slug>.md`
+
+**Template**: See full template in [EXAMPLES.md](./EXAMPLES.md#output-template)
+
+**Process**:
+1. Check if `docs/research/` exists, create if needed
+2. Generate filename from topic (lowercase, hyphenated)
+3. Use Write tool to save the document
+4. Confirm to user: "Research saved to docs/research/[filename]"
+
+---
+
+## Linus's Research Philosophy
+
+> "Talk is cheap. Show me the code."
+
+**Priorities**:
+1. **Real code** > Blog posts
+2. **Production usage** > Tutorials
+3. **Official docs** > Medium articles
+4. **Recent content (2025)** > Old posts
+5. **Specific examples** > Generic advice
+
+**Anti-patterns**:
+- ❌ Relying on tutorials without checking real code
+- ❌ Using outdated documentation
+- ❌ Trusting opinions without evidence
+- ❌ Searching for keywords instead of code patterns
+
+**Good researcher**:
+- ✅ Checks multiple sources
+- ✅ Verifies with real code
+- ✅ Tests small examples
+- ✅ Questions everything
+
+---
+
+## Quick Reference
+
+- **Detailed tool documentation**: [REFERENCE.md](./REFERENCE.md)
+- **Research strategy examples**: [EXAMPLES.md](./EXAMPLES.md)
+- **Tool selection guide**: Step 2 above

package/templates/.claude/skills/root-cause-tracing/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: root-cause-tracing
+description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
+---
+
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in /Users/jesse/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script: @find-polluter.sh
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution