@thispointon/kondi-chat 0.1.2

package/src/context/memory.ts

@@ -0,0 +1,160 @@
+/**
+ * Memory System — persistent KONDI.md + AGENTS.md files injected into
+ * the system prompt.
+ *
+ * Hierarchy (lowest to highest priority; later overrides earlier):
+ *   1. user memory       ~/.kondi-chat/KONDI.md (+ AGENTS.md)
+ *   2. project memory    <workingDir>/KONDI.md (+ AGENTS.md)
+ *   3. subdir memory     nearest-ancestor KONDI.md or AGENTS.md from the active file
+ *
+ * AGENTS.md is an open convention supported by Claude Code, Cursor,
+ * Copilot, Gemini CLI, Windsurf, Aider, Zed, and others. kondi-chat
+ * reads it at the same levels as KONDI.md. If both files exist at the
+ * same level, both are loaded (AGENTS.md first, then KONDI.md).
+ *
+ * No YAML frontmatter parsing, no file watcher — load() re-stats on each call
+ * and re-reads only files whose mtime changed.
+ */
+
+import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, relative } from 'node:path';
+
+/** Files to search at each level, in load order. */
+const MEMORY_FILENAMES = ['AGENTS.md', 'KONDI.md'];
+const MAX_FILE_BYTES = 50_000;
+const MAX_SUBDIR_DEPTH = 5;
+
+export interface MemoryEntry {
+  source: 'user' | 'project' | 'subdirectory';
+  path: string;
+  content: string;
+}
+
+interface Cached {
+  mtimeMs: number;
+  content: string;
+}
+
+function readCapped(path: string): string {
+  const buf = readFileSync(path, 'utf-8');
+  return buf.length > MAX_FILE_BYTES
+    ? buf.slice(0, MAX_FILE_BYTES) + '\n\n(truncated)'
+    : buf;
+}
+
+export class MemoryManager {
+  private workingDir: string;
+  private cache = new Map<string, Cached>();
+
+  constructor(workingDir: string) {
+    this.workingDir = resolve(workingDir);
+  }
+
+  /**
+   * Read user-level + project-level memory, plus the nearest-ancestor
+   * KONDI.md or AGENTS.md for activeFile. Both filenames are checked at
+   * every level; if both exist, both are loaded (AGENTS.md first).
+   */
+  load(activeFile?: string): MemoryEntry[] {
+    const entries: MemoryEntry[] = [];
+
+    // User level: ~/.kondi-chat/AGENTS.md, ~/.kondi-chat/KONDI.md
+    const userDir = join(homedir(), '.kondi-chat');
+    for (const fn of MEMORY_FILENAMES) {
+      const e = this.readIfPresent(join(userDir, fn), 'user');
+      if (e) entries.push(e);
+    }
+
+    // Project level: <workingDir>/AGENTS.md, <workingDir>/KONDI.md
+    const projectPaths = new Set<string>();
+    for (const fn of MEMORY_FILENAMES) {
+      const p = join(this.workingDir, fn);
+      projectPaths.add(p);
+      const e = this.readIfPresent(p, 'project');
+      if (e) entries.push(e);
+    }
+
+    // Subdirectory: walk up from activeFile toward workingDir, stop at project root.
+    if (activeFile) {
+      const full = resolve(this.workingDir, activeFile);
+      if (!relative(this.workingDir, full).startsWith('..')) {
+        let dir = dirname(full);
+        let depth = 0;
+        let found = false;
+        while (!found && depth < MAX_SUBDIR_DEPTH && dir.length >= this.workingDir.length && dir !== this.workingDir) {
+          for (const fn of MEMORY_FILENAMES) {
+            const candidate = join(dir, fn);
+            if (projectPaths.has(candidate)) continue;
+            const e = this.readIfPresent(candidate, 'subdirectory');
+            if (e) { entries.push(e); found = true; }
+          }
+          if (found) break;
+          const parent = dirname(dir);
+          if (parent === dir) break;
+          dir = parent;
+          depth++;
+        }
+      }
+    }
+
+    return entries;
+  }
+
+  private readIfPresent(path: string, source: MemoryEntry['source']): MemoryEntry | null {
+    if (!existsSync(path)) { this.cache.delete(path); return null; }
+    try {
+      const stat = statSync(path);
+      const cached = this.cache.get(path);
+      if (cached && cached.mtimeMs === stat.mtimeMs) {
+        return { source, path, content: cached.content };
+      }
+      const content = readCapped(path);
+      this.cache.set(path, { mtimeMs: stat.mtimeMs, content });
+      return { source, path, content };
+    } catch {
+      return null;
+    }
+  }
+
+  /** Render memory entries as a delimited system-prompt section. Lower-priority first. */
+  formatForPrompt(entries: MemoryEntry[]): string {
+    if (entries.length === 0) return '';
+    const order: MemoryEntry['source'][] = ['user', 'project', 'subdirectory'];
+    const sorted = [...entries].sort(
+      (a, b) => order.indexOf(a.source) - order.indexOf(b.source),
+    );
+    const parts: string[] = ['## Memory (advisory, not safety-critical; higher sections override lower)'];
+    for (const e of sorted) {
+      parts.push(`### Memory: ${e.source} (${e.path})\n${e.content.trim()}`);
+    }
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Write a KONDI.md file. `append` concatenates to the existing file; `replace` overwrites.
+   * Returns the absolute path written.
+   */
+  updateMemory(
+    scope: 'user' | 'project',
+    operation: 'append' | 'replace',
+    content: string,
+  ): { path: string } {
+    // Writes always go to KONDI.md (the kondi-chat-specific file).
+    // AGENTS.md is a cross-tool convention and is typically hand-authored
+    // or maintained by a separate process — the agent shouldn't overwrite it.
+    const target = scope === 'user'
+      ? join(homedir(), '.kondi-chat', 'KONDI.md')
+      : join(this.workingDir, 'KONDI.md');
+    mkdirSync(dirname(target), { recursive: true });
+    if (operation === 'append' && existsSync(target)) {
+      const existing = readFileSync(target, 'utf-8');
+      const sep = existing.endsWith('\n') ? '' : '\n';
+      writeFileSync(target, existing + sep + content + '\n');
+    } else {
+      writeFileSync(target, content.endsWith('\n') ? content : content + '\n');
+    }
+    this.cache.delete(target);
+    return { path: target };
+  }
+}

package/src/context/preflight.ts

@@ -0,0 +1,176 @@
+/**
+ * Preflight Investigation — automatically reads relevant files before
+ * the agent loop starts so the model begins each turn already knowing
+ * the relevant code.
+ *
+ * Instead of the agent spending its first 3-4 tool calls on read_file,
+ * the preflight infers which files matter from the task text and injects
+ * a compact snapshot into the system prompt. Zero LLM calls — just
+ * regex matching against the file tree + reading the matches.
+ *
+ * The router is unaffected — this runs before router.select() and
+ * provides context that any model can use regardless of which one
+ * is selected for the phase.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, extname } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const MAX_FILE_SIZE = 8_000;  // chars per file
+const MAX_TOTAL_SIZE = 30_000; // total preflight context chars
+const MAX_FILES = 8;
+
+const CODE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.py', '.rs', '.go', '.java',
+  '.cpp', '.cc', '.c', '.h', '.hpp', '.cs', '.rb', '.php',
+  '.swift', '.kt', '.sh', '.sql', '.md', '.json', '.yml', '.yaml', '.toml',
+]);
+
+interface PreflightResult {
+  filesRead: string[];
+  context: string;
+  gitDiff?: string;
+}
+
+/**
+ * Scan the task text for file references, find related files, read
+ * them, and assemble a preflight context block.
+ */
+export function runPreflight(
+  workingDir: string,
+  taskText: string,
+): PreflightResult {
+  const filesRead: string[] = [];
+  const sections: string[] = [];
+  let totalChars = 0;
+
+  // 1. Extract explicit file references from the task text.
+  const explicitFiles = extractFileReferences(taskText);
+
+  // 2. Infer related files from keywords in the task.
+  const inferredFiles = inferRelatedFiles(workingDir, taskText);
+
+  // 3. Merge, deduplicate, cap at MAX_FILES.
+  const candidates = [...new Set([...explicitFiles, ...inferredFiles])].slice(0, MAX_FILES);
+
+  // 4. Read each file.
+  for (const relPath of candidates) {
+    if (totalChars >= MAX_TOTAL_SIZE) break;
+    const absPath = join(workingDir, relPath);
+    if (!existsSync(absPath)) continue;
+    try {
+      const stat = statSync(absPath);
+      if (!stat.isFile() || stat.size > 100_000) continue;
+      let content = readFileSync(absPath, 'utf-8');
+      if (content.length > MAX_FILE_SIZE) {
+        content = content.slice(0, MAX_FILE_SIZE) + `\n... (${content.length - MAX_FILE_SIZE} chars truncated)`;
+      }
+      sections.push(`### ${relPath}\n\`\`\`\n${content}\n\`\`\``);
+      filesRead.push(relPath);
+      totalChars += content.length;
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  // 5. Recent git diff (last commit or uncommitted changes).
+  let gitDiff: string | undefined;
+  try {
+    const diff = execSync('git diff --stat HEAD 2>/dev/null || git diff --stat 2>/dev/null', {
+      cwd: workingDir,
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+    if (diff && diff.length < 2000) {
+      gitDiff = diff;
+      sections.push(`### Recent changes (git diff --stat)\n${diff}`);
+    }
+  } catch {
+    // Not a git repo or git not available
+  }
+
+  const context = sections.length > 0
+    ? `## Preflight: relevant files (auto-loaded)\n\n${sections.join('\n\n')}`
+    : '';
+
+  return { filesRead, context, gitDiff };
+}
+
+/**
+ * Extract explicit file paths from the task text.
+ * Matches patterns like "src/foo.ts", "package.json", "./bar/baz.py".
+ */
+function extractFileReferences(text: string): string[] {
+  const refs: string[] = [];
+  // Match file paths with known extensions
+  const pathRe = /(?:^|\s|["'`(])([.\w/-]+(?:\.\w{1,10}))(?=[\s"'`),.:;]|$)/gm;
+  let match;
+  while ((match = pathRe.exec(text)) !== null) {
+    const candidate = match[1].replace(/^\.\//, '');
+    const ext = extname(candidate).toLowerCase();
+    if (CODE_EXTENSIONS.has(ext) || candidate === 'package.json' || candidate === 'Cargo.toml') {
+      refs.push(candidate);
+    }
+  }
+  return refs;
+}
+
+/**
+ * Infer related files from keywords in the task. Scans the file tree
+ * (shallow, no node_modules) for filenames that match significant
+ * words from the task.
+ */
+function inferRelatedFiles(workingDir: string, text: string): string[] {
+  // Extract significant words (3+ chars, not common stop words)
+  const stopWords = new Set(['the', 'this', 'that', 'with', 'from', 'have', 'been', 'will',
+    'can', 'should', 'would', 'could', 'make', 'like', 'just', 'also', 'into', 'about',
+    'what', 'when', 'where', 'which', 'there', 'their', 'them', 'then', 'than', 'some',
+    'more', 'most', 'very', 'each', 'every', 'all', 'any', 'both', 'few', 'other',
+    'such', 'only', 'same', 'how', 'does', 'did', 'has', 'had', 'not', 'but', 'for',
+    'are', 'was', 'were', 'and', 'the', 'add', 'fix', 'update', 'change', 'remove',
+    'write', 'read', 'create', 'delete', 'implement', 'refactor', 'test', 'run', 'build',
+    'use', 'using', 'file', 'code', 'function', 'method', 'class', 'module',
+  ]);
+
+  const words = text.toLowerCase()
+    .replace(/[^a-z0-9_-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length >= 3 && !stopWords.has(w));
+
+  if (words.length === 0) return [];
+
+  // Scan the file tree (max 2 levels deep, skip heavy dirs)
+  const skipDirs = new Set(['node_modules', '.git', '.kondi-chat', '.claude', 'dist', 'target', '__pycache__', '.next', '.venv', 'venv']);
+  const matches: string[] = [];
+
+  function scan(dir: string, depth: number) {
+    if (depth > 2) return;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (skipDirs.has(entry.name)) continue;
+        const rel = relative(workingDir, join(dir, entry.name));
+        if (entry.isDirectory()) {
+          scan(join(dir, entry.name), depth + 1);
+        } else if (entry.isFile()) {
+          const ext = extname(entry.name).toLowerCase();
+          if (!CODE_EXTENSIONS.has(ext)) continue;
+          const nameLower = entry.name.toLowerCase().replace(extname(entry.name), '');
+          // Check if any task word appears in the filename
+          for (const word of words) {
+            if (nameLower.includes(word) || word.includes(nameLower)) {
+              matches.push(rel);
+              break;
+            }
+          }
+        }
+      }
+    } catch {
+      // Permission error or similar
+    }
+  }
+
+  scan(workingDir, 0);
+  return matches;
+}

package/src/context/project-brain.ts

@@ -0,0 +1,101 @@
+/**
+ * Project Brain — unified context assembler.
+ *
+ * Pulls together every context source into one coherent block that
+ * gets injected into the system prompt before every model call:
+ *
+ *   1. AGENTS.md / KONDI.md (project conventions)
+ *   2. Recent receipts (what happened in prior turns)
+ *   3. Relevant skills (procedures for this type of task)
+ *   4. Preflight files (auto-loaded relevant code)
+ *   5. Repo summary (from bootstrap)
+ *
+ * The brain doesn't decide which model runs — that's the router's
+ * job. The brain decides what context that model should see.
+ */
+
+import { ReceiptStore } from './receipts.ts';
+import { MemoryManager } from './memory.ts';
+import { runPreflight } from './preflight.ts';
+import { loadSkills, selectSkills, formatSkillsForContext, seedDefaultSkills } from './skills.ts';
+import { TaskStore } from '../engine/task-store.ts';
+import type { Session } from '../types.ts';
+
+export interface BrainContext {
+  /** Full assembled context for injection into system prompt. */
+  fullContext: string;
+  /** Files auto-loaded by preflight. */
+  preflightFiles: string[];
+  /** Skills matched for this task. */
+  skillsUsed: string[];
+}
+
+/**
+ * Assemble all context sources for a given task.
+ * Called once per turn, before the agent loop starts.
+ */
+export function assembleBrainContext(
+  workingDir: string,
+  session: Session,
+  task: string,
+  opts?: { skipPreflight?: boolean },
+): BrainContext {
+  const sections: string[] = [];
+  const preflightFiles: string[] = [];
+  const skillsUsed: string[] = [];
+
+  // 1. Memory (AGENTS.md, KONDI.md)
+  const memory = new MemoryManager(workingDir);
+  const entries = memory.load();
+  if (entries.length > 0) {
+    sections.push(
+      '## Project conventions\n\n' +
+      entries.map(e => `### ${e.source}: ${e.path}\n${e.content}`).join('\n\n')
+    );
+  }
+
+  // 2. Active task (persisted across sessions)
+  const storageDir = `${workingDir}/.kondi-chat`;
+  const taskStore = new TaskStore(storageDir);
+  const activeTask = taskStore.formatForContext();
+  if (activeTask) {
+    sections.push(activeTask);
+  }
+
+  // 3. Recent receipts
+  const receipts = new ReceiptStore(storageDir, session.id);
+  const recentReceipts = receipts.formatForContext(3);
+  if (recentReceipts) {
+    sections.push(recentReceipts);
+  }
+
+  // 3. Skills
+  seedDefaultSkills(workingDir);
+  const skills = loadSkills(workingDir);
+  const matched = selectSkills(task, skills, 2);
+  if (matched.length > 0) {
+    sections.push(formatSkillsForContext(matched));
+    skillsUsed.push(...matched.map(s => s.name));
+  }
+
+  // 4. Preflight (relevant files) — skipped for short/follow-up messages
+  if (!opts?.skipPreflight) {
+    const preflight = runPreflight(workingDir, task);
+    if (preflight.context) {
+      sections.push(preflight.context);
+      preflightFiles.push(...preflight.filesRead);
+    }
+  }
+
+  // 5. Repo summary (grounding context from bootstrap, if available)
+  if (session.groundingContext) {
+    // Already in the system prompt via cacheablePrefix — don't duplicate.
+    // Just note it so the model knows it's there.
+  }
+
+  return {
+    fullContext: sections.join('\n\n'),
+    preflightFiles,
+    skillsUsed,
+  };
+}

package/src/context/receipts.ts

@@ -0,0 +1,108 @@
+/**
+ * Context Receipts — structured per-turn summaries that persist
+ * across turns and sessions.
+ *
+ * After every turn, a receipt records what changed, why, which files
+ * were touched, and what comes next. The last N receipts are injected
+ * into the system prompt so the model has cross-turn continuity
+ * without re-reading the entire conversation history.
+ *
+ * Receipts are cheap: no LLM call needed. They're assembled from
+ * data already available in the turn (tool calls, model responses,
+ * ledger entries). Storage is a simple JSONL file under the session.
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export interface TurnReceipt {
+  turnNumber: number;
+  timestamp: string;
+  userGoal: string;
+  modelUsed: string;
+  filesRead: string[];
+  filesWritten: string[];
+  toolsCalled: string[];
+  outcome: string;
+  remainingWork?: string;
+}
+
+export class ReceiptStore {
+  private path: string;
+
+  constructor(storageDir: string, sessionId: string) {
+    const dir = join(storageDir, 'sessions');
+    mkdirSync(dir, { recursive: true });
+    this.path = join(dir, `${sessionId}-receipts.jsonl`);
+  }
+
+  /** Append a receipt after a turn completes. */
+  record(receipt: TurnReceipt): void {
+    appendFileSync(this.path, JSON.stringify(receipt) + '\n');
+  }
+
+  /** Get the last N receipts for injection into context. */
+  getRecent(count = 3): TurnReceipt[] {
+    if (!existsSync(this.path)) return [];
+    try {
+      const lines = readFileSync(this.path, 'utf-8').trim().split('\n').filter(Boolean);
+      return lines.slice(-count).map(l => JSON.parse(l));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Format receipts for injection into the system prompt. */
+  formatForContext(count = 3): string {
+    const receipts = this.getRecent(count);
+    if (receipts.length === 0) return '';
+
+    const lines = ['## Recent turns'];
+    for (const r of receipts) {
+      lines.push(`Turn ${r.turnNumber}: ${r.userGoal.slice(0, 100)}`);
+      if (r.filesWritten.length > 0) lines.push(`  wrote: ${r.filesWritten.join(', ')}`);
+      if (r.filesRead.length > 0) lines.push(`  read: ${r.filesRead.join(', ')}`);
+      lines.push(`  outcome: ${r.outcome.slice(0, 200)}`);
+      if (r.remainingWork) lines.push(`  remaining: ${r.remainingWork}`);
+      lines.push('');
+    }
+    return lines.join('\n');
+  }
+}
+
+/**
+ * Build a receipt from turn data. Called at the end of handleSubmit
+ * with whatever data is available — no LLM call needed.
+ */
+export function buildReceipt(
+  turnNumber: number,
+  userGoal: string,
+  modelUsed: string,
+  toolCalls: Array<{ name: string; args: string; is_error: boolean }>,
+  finalContent: string,
+): TurnReceipt {
+  const filesRead: string[] = [];
+  const filesWritten: string[] = [];
+  const toolsCalled: string[] = [];
+
+  for (const tc of toolCalls) {
+    toolsCalled.push(tc.name);
+    if (tc.name === 'read_file') filesRead.push(tc.args);
+    if (tc.name === 'write_file' || tc.name === 'edit_file') filesWritten.push(tc.args);
+  }
+
+  // Extract a short outcome from the final content.
+  const outcomeLines = finalContent.split('\n').filter(l => l.trim().length > 0);
+  const outcome = outcomeLines.slice(0, 3).join(' ').slice(0, 300);
+
+  return {
+    turnNumber,
+    timestamp: new Date().toISOString(),
+    userGoal: userGoal.slice(0, 200),
+    modelUsed,
+    filesRead: [...new Set(filesRead)],
+    filesWritten: [...new Set(filesWritten)],
+    toolsCalled: [...new Set(toolsCalled)],
+    outcome,
+  };
+}

package/src/context/skills.ts

@@ -0,0 +1,154 @@
+/**
+ * Skills — reusable task procedures loaded from .kondi-chat/skills/.
+ *
+ * Each skill is a SKILL.md file with structured instructions for how
+ * to approach a category of task (debugging, adding features, refactoring,
+ * code review, etc.). The skill router picks 1-3 relevant skills per
+ * task and injects them into the system prompt so the model follows
+ * a proven procedure instead of winging it.
+ *
+ * The router picks models. Skills teach models HOW to work.
+ */
+
+import { readFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+export interface Skill {
+  name: string;
+  content: string;
+  /** First line of the file, used as a short description for matching. */
+  description: string;
+}
+
+const MAX_SKILL_SIZE = 5_000;
+
+/**
+ * Load skills from user-level + project-level .kondi-chat/skills/.
+ * Project-level overrides user-level on name collision.
+ */
+export function loadSkills(workingDir: string): Skill[] {
+  const skills = new Map<string, Skill>();
+
+  // User-level first
+  loadFromDir(join(homedir(), '.kondi-chat', 'skills'), skills);
+  // Project-level overrides
+  loadFromDir(join(workingDir, '.kondi-chat', 'skills'), skills);
+
+  return [...skills.values()];
+}
+
+function loadFromDir(dir: string, skills: Map<string, Skill>): void {
+  if (!existsSync(dir)) return;
+  try {
+    for (const file of readdirSync(dir).filter(f => f.endsWith('.md'))) {
+      try {
+        let content = readFileSync(join(dir, file), 'utf-8');
+        if (content.length > MAX_SKILL_SIZE) {
+          content = content.slice(0, MAX_SKILL_SIZE) + '\n(truncated)';
+        }
+        const name = basename(file, '.md').toLowerCase();
+        const firstLine = content.split('\n').find(l => l.trim().length > 0 && !l.startsWith('#')) || '';
+        skills.set(name, { name, content, description: firstLine.slice(0, 200) });
+      } catch { /* skip unreadable */ }
+    }
+  } catch { /* dir not readable */ }
+}
+
+/**
+ * Pick the most relevant skills for a given task. Simple keyword
+ * matching — no LLM call needed.
+ */
+export function selectSkills(task: string, skills: Skill[], max = 2): Skill[] {
+  if (skills.length === 0) return [];
+  const taskLower = task.toLowerCase();
+
+  const scored = skills.map(skill => {
+    let score = 0;
+    // Match skill name against task words
+    if (taskLower.includes(skill.name)) score += 10;
+    // Match keywords from the skill description
+    const descWords = skill.description.toLowerCase().split(/\s+/);
+    for (const word of descWords) {
+      if (word.length >= 4 && taskLower.includes(word)) score += 1;
+    }
+    return { skill, score };
+  });
+
+  return scored
+    .filter(s => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, max)
+    .map(s => s.skill);
+}
+
+/**
+ * Format selected skills for injection into the system prompt.
+ */
+export function formatSkillsForContext(skills: Skill[]): string {
+  if (skills.length === 0) return '';
+  const sections = skills.map(s => `### Skill: ${s.name}\n${s.content}`);
+  return `## Relevant procedures\n\n${sections.join('\n\n')}`;
+}
+
+/**
+ * Seed default skills if the skills directory doesn't exist.
+ */
+export function seedDefaultSkills(workingDir: string): void {
+  const dir = join(workingDir, '.kondi-chat', 'skills');
+  if (existsSync(dir)) return;
+  mkdirSync(dir, { recursive: true });
+
+  const defaults: Record<string, string> = {
+    'debug': `# Debug
+
+When debugging an issue:
+1. Reproduce the problem — read the error message carefully
+2. Find the source: search_code for the error text, read the relevant file
+3. Understand the context: read related_files to see dependencies
+4. Form a hypothesis about the root cause
+5. Make the minimal fix — don't refactor while debugging
+6. Verify: run the tests or typecheck to confirm the fix
+7. Check for similar patterns elsewhere in the codebase`,
+
+    'add-feature': `# Add Feature
+
+When implementing a new feature:
+1. Read existing code in the area — understand conventions, patterns, types
+2. Check for tests — understand how existing features are tested
+3. Plan the change: which files need modification, which are new
+4. Implement incrementally — write, then verify with typecheck/tests
+5. Follow existing patterns — don't introduce new conventions
+6. Add tests if the project has them
+7. Review your own diff before reporting done`,
+
+    'refactor': `# Refactor
+
+When refactoring code:
+1. Understand WHY it needs refactoring — state the goal clearly
+2. Read all the code you'll touch + its tests
+3. Make sure existing tests pass BEFORE you start
+4. Refactor in small steps — one file or one concept at a time
+5. Run tests after each step
+6. Don't change behavior — only structure
+7. If you find bugs during refactoring, note them but don't fix them in the same change`,
+
+    'review': `# Code Review
+
+When reviewing code:
+1. Read the full diff, not just the changed lines
+2. Check: does it do what it claims? Are edge cases handled?
+3. Look for: security issues, error handling gaps, race conditions
+4. Check naming: are new names consistent with existing conventions?
+5. Check tests: are new behaviors tested? Are old tests still valid?
+6. Be specific: "line 42 misses the null case" not "needs more error handling"
+7. Distinguish blocking issues from suggestions`,
+  };
+
+  for (const [name, content] of Object.entries(defaults)) {
+    const path = join(dir, `${name}.md`);
+    if (!existsSync(path)) {
+      try { require('node:fs').writeFileSync(path, content); } catch { /* ignore */ }
+    }
+  }
+}