@jhm1909/ag-kit 0.1.0

package/.agent/skills/context-engineering/references/project-development.md

@@ -0,0 +1,97 @@
+# Project Development
+
+Design and build LLM-powered projects from ideation to deployment.
+
+## Task-Model Fit
+
+**LLM-Suited**: Synthesis, subjective judgment, NL output, error-tolerant batches
+**LLM-Unsuited**: Precise computation, real-time, perfect accuracy, deterministic output
+
+## Manual Prototype First
+
+Test one example with target model before automation.
+
+## Pipeline Architecture
+
+```
+acquire → prepare → process → parse → render
+ (fetch)  (prompt)   (LLM)   (extract) (output)
+```
+
+Stages 1,2,4,5: Deterministic, cheap | Stage 3: Non-deterministic, expensive
+
+## File System as State
+
+```
+data/{id}/
+├── raw.json      # acquire done
+├── prompt.md     # prepare done
+├── response.md   # process done
+└── parsed.json   # parse done
+```
+
+```python
+def get_stage(id):
+    if exists(f"{id}/parsed.json"): return "render"
+    if exists(f"{id}/response.md"): return "parse"
+    # ... check backwards
+```
+
+**Benefits**: Idempotent, resumable, debuggable
+
+## Structured Output
+
+```markdown
+## SUMMARY
+[Overview]
+
+## KEY_FINDINGS
+- Finding 1
+
+## SCORE
+[1-5]
+```
+
+```python
+def parse(response):
+    return {
+        "summary": extract_section(response, "SUMMARY"),
+        "findings": extract_list(response, "KEY_FINDINGS"),
+        "score": extract_int(response, "SCORE")
+    }
+```
+
+## Cost Estimation
+
+```python
+def estimate(items, tokens_per, price_per_1k):
+    return len(items) * tokens_per / 1000 * price_per_1k * 1.1  # 10% buffer
+# 1000 items × 2000 tokens × $0.01/1k = $22
+```
+
+## Case Studies
+
+**Karpathy HN**: 930 items, $58, 1hr, 15 workers
+**Vercel d0**: 17→2 tools, 80%→100% success, 3.5x faster
+
+## Single vs Multi-Agent
+
+| Factor | Single | Multi |
+|--------|--------|-------|
+| Context | Fits window | Exceeds |
+| Tasks | Sequential | Parallel |
+| Tokens | Limited | 15x OK |
+
+## Guidelines
+
+1. Validate manually before automating
+2. Use 5-stage pipeline
+3. Track state via files
+4. Design structured output
+5. Estimate costs first
+6. Start single, add multi when needed
+
+## Related
+
+- [Context Optimization](./context-optimization.md)
+- [Multi-Agent Patterns](./multi-agent-patterns.md)

package/.agent/skills/context-engineering/references/tool-design.md

@@ -0,0 +1,86 @@
+# Tool Design
+
+Design effective tools for agent systems.
+
+## Consolidation Principle
+
+Single comprehensive tools > multiple narrow tools. **Target**: 10-20 tools max.
+
+## Architectural Reduction Evidence
+
+| Metric | 17 Tools | 2 Tools | Improvement |
+|--------|----------|---------|-------------|
+| Time | 274.8s | 77.4s | 3.5x faster |
+| Success | 80% | 100% | +20% |
+| Tokens | 102k | 61k | 37% fewer |
+
+**Key**: Good documentation replaces tool sophistication.
+
+## When Reduction Works
+
+**Prerequisites**: High docs quality, capable model, navigable problem
+**Avoid when**: Messy systems, specialized domain, safety-critical
+
+## Description Engineering
+
+Answer four questions:
+1. **What** does the tool do?
+2. **When** should it be used?
+3. **What inputs** does it accept?
+4. **What** does it return?
+
+### Good Example
+
+```json
+{
+  "name": "get_customer",
+  "description": "Retrieve customer profile by ID. Use for order processing, support. Returns 404 if not found.",
+  "parameters": {
+    "customer_id": {"type": "string", "pattern": "^CUST-[0-9]{6}$"},
+    "format": {"enum": ["concise", "detailed"]}
+  }
+}
+```
+
+### Poor Example
+
+```json
+{"name": "search", "description": "Search for things", "parameters": {"q": {}}}
+```
+
+## Error Messages
+
+```python
+def format_error(code, message, resolution):
+    return {
+        "error": {"code": code, "message": message,
+                  "resolution": resolution, "retryable": code in RETRYABLE}
+    }
+# "Use YYYY-MM-DD format, e.g., '2024-01-05'"
+```
+
+## Response Formats
+
+Offer concise vs detailed:
+
+```python
+def get_data(id, format="concise"):
+    if format == "concise":
+        return {"name": data.name}
+    return data.full()  # Detailed
+```
+
+## Guidelines
+
+1. Consolidate tools (target 10-20)
+2. Answer all four questions
+3. Use full parameter names
+4. Design errors for recovery
+5. Offer concise/detailed formats
+6. Test with agents before deploy
+7. Start minimal, add when proven
+
+## Related
+
+- [Context Fundamentals](./context-fundamentals.md)
+- [Multi-Agent Patterns](./multi-agent-patterns.md)

package/.agent/skills/debugging/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: debugging
+description: Systematic debugging frameworks for finding and fixing bugs. Use when encountering bugs, test failures, unexpected behavior, or needing to validate fixes before claiming completion.
+---
+
+# Debugging Skills
+
+Systematic debugging methodologies that ensure thorough investigation before attempting fixes.
+
+## Core Principle
+
+> "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"
+
+Systematic approach: 15-30 min to fix. Random fixes: 2-3 hours of thrashing.
+
+## Sub-Skills
+
+| How You're Stuck | Use This | Reference |
+|------------------|----------|-----------|
+| Bug, test failure, unexpected behavior | Systematic Debugging | [systematic-debugging.md](./references/systematic-debugging.md) |
+| Error deep in call stack | Root Cause Tracing | [root-cause-tracing.md](./references/root-cause-tracing.md) |
+| Same bug keeps recurring | Defense-in-Depth | [defense-in-depth.md](./references/defense-in-depth.md) |
+| About to claim "done" | Verification Before Completion | [verification-before-completion.md](./references/verification-before-completion.md) |
+
+## The Four Phases (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 |
+
+## Red Flags — STOP and Follow Process
+
+If thinking any of these → return to Phase 1:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+
+## 3+ Fixes Failed → Question Architecture
+
+Pattern: each fix reveals new shared state/coupling/problem → **STOP**.
+- Is this pattern fundamentally sound?
+- Should we refactor architecture vs. continue fixing symptoms?
+- Discuss with user before attempting more fixes.
+
+## Iron Law: Verification Before Completion
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code
+4. VERIFY: Does output confirm the claim?
+5. ONLY THEN: Make the claim
+```

package/.agent/skills/debugging/references/defense-in-depth.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/.agent/skills/debugging/references/root-cause-tracing.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