@vodailoc/kilo-kit-mcp 1.1.0

package/skills/operations/server-management/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: server-management
+description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Server Management
+
+> Server management principles for production operations.
+> **Learn to THINK, not memorize commands.**
+
+---
+
+## 1. Process Management Principles
+
+### Tool Selection
+
+| Scenario | Tool |
+|----------|------|
+| **Node.js app** | PM2 (clustering, reload) |
+| **Any app** | systemd (Linux native) |
+| **Containers** | Docker/Podman |
+| **Orchestration** | Kubernetes, Docker Swarm |
+
+### Process Management Goals
+
+| Goal | What It Means |
+|------|---------------|
+| **Restart on crash** | Auto-recovery |
+| **Zero-downtime reload** | No service interruption |
+| **Clustering** | Use all CPU cores |
+| **Persistence** | Survive server reboot |
+
+---
+
+## 2. Monitoring Principles
+
+### What to Monitor
+
+| Category | Key Metrics |
+|----------|-------------|
+| **Availability** | Uptime, health checks |
+| **Performance** | Response time, throughput |
+| **Errors** | Error rate, types |
+| **Resources** | CPU, memory, disk |
+
+### Alert Severity Strategy
+
+| Level | Response |
+|-------|----------|
+| **Critical** | Immediate action |
+| **Warning** | Investigate soon |
+| **Info** | Review daily |
+
+### Monitoring Tool Selection
+
+| Need | Options |
+|------|---------|
+| Simple/Free | PM2 metrics, htop |
+| Full observability | Grafana, Datadog |
+| Error tracking | Sentry |
+| Uptime | UptimeRobot, Pingdom |
+
+---
+
+## 3. Log Management Principles
+
+### Log Strategy
+
+| Log Type | Purpose |
+|----------|---------|
+| **Application logs** | Debug, audit |
+| **Access logs** | Traffic analysis |
+| **Error logs** | Issue detection |
+
+### Log Principles
+
+1. **Rotate logs** to prevent disk fill
+2. **Structured logging** (JSON) for parsing
+3. **Appropriate levels** (error/warn/info/debug)
+4. **No sensitive data** in logs
+
+---
+
+## 4. Scaling Decisions
+
+### When to Scale
+
+| Symptom | Solution |
+|---------|----------|
+| High CPU | Add instances (horizontal) |
+| High memory | Increase RAM or fix leak |
+| Slow response | Profile first, then scale |
+| Traffic spikes | Auto-scaling |
+
+### Scaling Strategy
+
+| Type | When to Use |
+|------|-------------|
+| **Vertical** | Quick fix, single instance |
+| **Horizontal** | Sustainable, distributed |
+| **Auto** | Variable traffic |
+
+---
+
+## 5. Health Check Principles
+
+### What Constitutes Healthy
+
+| Check | Meaning |
+|-------|---------|
+| **HTTP 200** | Service responding |
+| **Database connected** | Data accessible |
+| **Dependencies OK** | External services reachable |
+| **Resources OK** | CPU/memory not exhausted |
+
+### Health Check Implementation
+
+- Simple: Just return 200
+- Deep: Check all dependencies
+- Choose based on load balancer needs
+
+---
+
+## 6. Security Principles
+
+| Area | Principle |
+|------|-----------|
+| **Access** | SSH keys only, no passwords |
+| **Firewall** | Only needed ports open |
+| **Updates** | Regular security patches |
+| **Secrets** | Environment vars, not files |
+| **Audit** | Log access and changes |
+
+---
+
+## 7. Troubleshooting Priority
+
+When something's wrong:
+
+1. **Check if running** (process status)
+2. **Check logs** (error messages)
+3. **Check resources** (disk, memory, CPU)
+4. **Check network** (ports, DNS)
+5. **Check dependencies** (database, APIs)
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Run as root | Use non-root user |
+| Ignore logs | Set up log rotation |
+| Skip monitoring | Monitor from day one |
+| Manual restarts | Auto-restart config |
+| No backups | Regular backup schedule |
+
+---
+
+> **Remember:** A well-managed server is boring. That's the goal.

package/skills/problem-solving/collision-zone-thinking/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: Collision-Zone Thinking
+description: Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?"
+when_to_use: when conventional approaches feel inadequate and you need breakthrough innovation by forcing unrelated concepts together
+version: 1.1.0
+---
+
+# Collision-Zone Thinking
+
+## Overview
+
+Revolutionary insights come from forcing unrelated concepts to collide. Treat X like Y and see what emerges.
+
+**Core principle:** Deliberate metaphor-mixing generates novel solutions.
+
+## Quick Reference
+
+| Stuck On | Try Treating As | Might Discover |
+|----------|-----------------|----------------|
+| Code organization | DNA/genetics | Mutation testing, evolutionary algorithms |
+| Service architecture | Lego bricks | Composable microservices, plug-and-play |
+| Data management | Water flow | Streaming, data lakes, flow-based systems |
+| Request handling | Postal mail | Message queues, async processing |
+| Error handling | Circuit breakers | Fault isolation, graceful degradation |
+
+## Process
+
+1. **Pick two unrelated concepts** from different domains
+2. **Force combination**: "What if we treated [A] like [B]?"
+3. **Explore emergent properties**: What new capabilities appear?
+4. **Test boundaries**: Where does the metaphor break?
+5. **Extract insight**: What did we learn?
+
+## Example Collision
+
+**Problem:** Complex distributed system with cascading failures
+
+**Collision:** "What if we treated services like electrical circuits?"
+
+**Emergent properties:**
+- Circuit breakers (disconnect on overload)
+- Fuses (one-time failure protection)
+- Ground faults (error isolation)
+- Load balancing (current distribution)
+
+**Where it works:** Preventing cascade failures
+**Where it breaks:** Circuits don't have retry logic
+**Insight gained:** Failure isolation patterns from electrical engineering
+
+## Red Flags You Need This
+
+- "I've tried everything in this domain"
+- Solutions feel incremental, not breakthrough
+- Stuck in conventional thinking
+- Need innovation, not optimization
+
+## Remember
+
+- Wild combinations often yield best insights
+- Test metaphor boundaries rigorously
+- Document even failed collisions (they teach)
+- Best source domains: physics, biology, economics, psychology

package/skills/problem-solving/defense-in-depth/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: Defense-in-Depth Validation
+description: Validate at every layer data passes through to make bugs impossible
+when_to_use: when invalid data causes failures deep in execution, requiring validation at multiple system layers
+version: 1.1.0
+languages: all
+---
+
+# Defense-in-Depth Validation
+
+## Overview
+
+When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
+
+**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+
+## Why Multiple Layers
+
+Single validation: "We fixed the bug"
+Multiple layers: "We made the bug impossible"
+
+Different layers catch different cases:
+- Entry validation catches most bugs
+- Business logic catches edge cases
+- Environment guards prevent context-specific dangers
+- Debug logging helps when other layers fail
+
+## The Four Layers
+
+### Layer 1: Entry Point Validation
+**Purpose:** Reject obviously invalid input at API boundary
+
+```typescript
+function createProject(name: string, workingDirectory: string) {
+  if (!workingDirectory || workingDirectory.trim() === '') {
+    throw new Error('workingDirectory cannot be empty');
+  }
+  if (!existsSync(workingDirectory)) {
+    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
+  }
+  if (!statSync(workingDirectory).isDirectory()) {
+    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
+  }
+  // ... proceed
+}
+```
+
+### Layer 2: Business Logic Validation
+**Purpose:** Ensure data makes sense for this operation
+
+```typescript
+function initializeWorkspace(projectDir: string, sessionId: string) {
+  if (!projectDir) {
+    throw new Error('projectDir required for workspace initialization');
+  }
+  // ... proceed
+}
+```
+
+### Layer 3: Environment Guards
+**Purpose:** Prevent dangerous operations in specific contexts
+
+```typescript
+async function gitInit(directory: string) {
+  // In tests, refuse git init outside temp directories
+  if (process.env.NODE_ENV === 'test') {
+    const normalized = normalize(resolve(directory));
+    const tmpDir = normalize(resolve(tmpdir()));
+
+    if (!normalized.startsWith(tmpDir)) {
+      throw new Error(
+        `Refusing git init outside temp dir during tests: ${directory}`
+      );
+    }
+  }
+  // ... proceed
+}
+```
+
+### Layer 4: Debug Instrumentation
+**Purpose:** Capture context for forensics
+
+```typescript
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  logger.debug('About to git init', {
+    directory,
+    cwd: process.cwd(),
+    stack,
+  });
+  // ... proceed
+}
+```
+
+## Applying the Pattern
+
+When you find a bug:
+
+1. **Trace the data flow** - Where does bad value originate? Where used?
+2. **Map all checkpoints** - List every point data passes through
+3. **Add validation at each layer** - Entry, business, environment, debug
+4. **Test each layer** - Try to bypass layer 1, verify layer 2 catches it
+
+## Example from Session
+
+Bug: Empty `projectDir` caused `git init` in source code
+
+**Data flow:**
+1. Test setup → empty string
+2. `Project.create(name, '')`
+3. `WorkspaceManager.createWorkspace('')`
+4. `git init` runs in `process.cwd()`
+
+**Four layers added:**
+- Layer 1: `Project.create()` validates not empty/exists/writable
+- Layer 2: `WorkspaceManager` validates projectDir not empty
+- Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
+- Layer 4: Stack trace logging before git init
+
+**Result:** All 1847 tests passed, bug impossible to reproduce
+
+## Key Insight
+
+All four layers were necessary. During testing, each layer caught bugs the others missed:
+- Different code paths bypassed entry validation
+- Mocks bypassed business logic checks
+- Edge cases on different platforms needed environment guards
+- Debug logging identified structural misuse
+
+**Don't stop at one validation point.** Add checks at every layer.

package/skills/problem-solving/inversion-exercise/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: Inversion Exercise
+description: Flip core assumptions to reveal hidden constraints and alternative approaches - "what if the opposite were true?"
+when_to_use: when stuck on unquestioned assumptions or feeling forced into "the only way" to do something
+version: 1.1.0
+---
+
+# Inversion Exercise
+
+## Overview
+
+Flip every assumption and see what still works. Sometimes the opposite reveals the truth.
+
+**Core principle:** Inversion exposes hidden assumptions and alternative approaches.
+
+## Quick Reference
+
+| Normal Assumption | Inverted | What It Reveals |
+|-------------------|----------|-----------------|
+| Cache to reduce latency | Add latency to enable caching | Debouncing patterns |
+| Pull data when needed | Push data before needed | Prefetching, eager loading |
+| Handle errors when occur | Make errors impossible | Type systems, contracts |
+| Build features users want | Remove features users don't need | Simplicity >> addition |
+| Optimize for common case | Optimize for worst case | Resilience patterns |
+
+## Process
+
+1. **List core assumptions** - What "must" be true?
+2. **Invert each systematically** - "What if opposite were true?"
+3. **Explore implications** - What would we do differently?
+4. **Find valid inversions** - Which actually work somewhere?
+
+## Example
+
+**Problem:** Users complain app is slow
+
+**Normal approach:** Make everything faster (caching, optimization, CDN)
+
+**Inverted:** Make things intentionally slower in some places
+- Debounce search (add latency → enable better results)
+- Rate limit requests (add friction → prevent abuse)
+- Lazy load content (delay → reduce initial load)
+
+**Insight:** Strategic slowness can improve UX
+
+## Red Flags You Need This
+
+- "There's only one way to do this"
+- Forcing solution that feels wrong
+- Can't articulate why approach is necessary
+- "This is just how it's done"
+
+## Remember
+
+- Not all inversions work (test boundaries)
+- Valid inversions reveal context-dependence
+- Sometimes opposite is the answer
+- Question "must be" statements

package/skills/problem-solving/meta-pattern-recognition/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: Meta-Pattern Recognition
+description: Spot patterns appearing in 3+ domains to find universal principles
+when_to_use: when noticing the same pattern across 3+ different domains or experiencing déjà vu in problem-solving
+version: 1.1.0
+---
+
+# Meta-Pattern Recognition
+
+## Overview
+
+When the same pattern appears in 3+ domains, it's probably a universal principle worth extracting.
+
+**Core principle:** Find patterns in how patterns emerge.
+
+## Quick Reference
+
+| Pattern Appears In | Abstract Form | Where Else? |
+|-------------------|---------------|-------------|
+| CPU/DB/HTTP/DNS caching | Store frequently-accessed data closer | LLM prompt caching, CDN |
+| Layering (network/storage/compute) | Separate concerns into abstraction levels | Architecture, organization |
+| Queuing (message/task/request) | Decouple producer from consumer with buffer | Event systems, async processing |
+| Pooling (connection/thread/object) | Reuse expensive resources | Memory management, resource governance |
+
+## Process
+
+1. **Spot repetition** - See same shape in 3+ places
+2. **Extract abstract form** - Describe independent of any domain
+3. **Identify variations** - How does it adapt per domain?
+4. **Check applicability** - Where else might this help?
+
+## Example
+
+**Pattern spotted:** Rate limiting in API throttling, traffic shaping, circuit breakers, admission control
+
+**Abstract form:** Bound resource consumption to prevent exhaustion
+
+**Variation points:** What resource, what limit, what happens when exceeded
+
+**New application:** LLM token budgets (same pattern - prevent context window exhaustion)
+
+## Red Flags You're Missing Meta-Patterns
+
+- "This problem is unique" (probably not)
+- Multiple teams independently solving "different" problems identically
+- Reinventing wheels across domains
+- "Haven't we done something like this?" (yes, find it)
+
+## Remember
+
+- 3+ domains = likely universal
+- Abstract form reveals new applications
+- Variations show adaptation points
+- Universal patterns are battle-tested

package/skills/problem-solving/root-cause-tracing/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: Root Cause Tracing
+description: Systematically trace bugs backward through call stack to find original trigger
+when_to_use: when errors occur deep in execution and you need to trace back to find the original trigger
+version: 1.1.0
+languages: all
+---
+
+# 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

package/skills/problem-solving/root-cause-tracing/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0