kodelyth-ecc 1.2.2 → 1.4.0

package/scripts/memory/store.js

@@ -0,0 +1,300 @@
+// =============================================================================
+// Kodelyth ECC — Memory Store
+// Local, zero-dependency, model-agnostic memory for AI coding sessions.
+//
+// Storage layout (all in ~/.kodelyth/memory/):
+//   memories.jsonl       Append-only log of every captured memory
+//   index.json           Inverted index: token -> [memory ids]
+//   patterns.json        User-level patterns (preferences, conventions)
+//   projects/<hash>.json Per-project memory shortcuts
+//
+// Retrieval: BM25 over tokenised problem + approach + tags. No embeddings,
+// no native deps, no network. Pure JS, runs anywhere Node 18+ runs.
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const MEMORY_DIR = process.env.KODELYTH_MEMORY_DIR
+  || path.join(os.homedir(), '.kodelyth', 'memory');
+
+const PATHS = {
+  dir:       MEMORY_DIR,
+  log:       path.join(MEMORY_DIR, 'memories.jsonl'),
+  index:     path.join(MEMORY_DIR, 'index.json'),
+  patterns:  path.join(MEMORY_DIR, 'patterns.json'),
+  projects:  path.join(MEMORY_DIR, 'projects'),
+};
+
+// ── Stop words (English + common code noise) ─────────────────────────────────
+const STOP_WORDS = new Set([
+  'the','a','an','and','or','but','if','then','else','for','to','of','in','on',
+  'is','are','was','were','be','been','being','have','has','had','do','does',
+  'did','will','would','should','can','could','may','might','must','this','that',
+  'these','those','it','its','as','at','by','from','with','about','i','you','we',
+  'they','he','she','my','your','our','their','use','using','used','set','get',
+  'fix','fixed','make','made','want','need','try','tried','run','running',
+]);
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function tokenise(text) {
+  if (!text) return [];
+  return String(text)
+    .toLowerCase()
+    .replace(/[^a-z0-9_\-/.\s]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length >= 2 && t.length <= 40 && !STOP_WORDS.has(t));
+}
+
+function projectHash(projectRoot) {
+  return crypto
+    .createHash('sha256')
+    .update(String(projectRoot))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+function newMemoryId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+// ── Index ────────────────────────────────────────────────────────────────────
+function loadIndex() {
+  if (!fs.existsSync(PATHS.index)) {
+    return { tokens: {}, docCount: 0, avgDocLength: 0, totalLength: 0 };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(PATHS.index, 'utf8'));
+  } catch {
+    return { tokens: {}, docCount: 0, avgDocLength: 0, totalLength: 0 };
+  }
+}
+
+function saveIndex(index) {
+  ensureDir(PATHS.dir);
+  fs.writeFileSync(PATHS.index, JSON.stringify(index, null, 2));
+}
+
+function indexMemory(index, memory) {
+  const text   = `${memory.problem || ''} ${memory.approach || ''} ${(memory.tags || []).join(' ')}`;
+  const tokens = tokenise(text);
+  const length = tokens.length;
+  if (length === 0) return index;
+
+  const tokenFreq = {};
+  for (const token of tokens) {
+    tokenFreq[token] = (tokenFreq[token] || 0) + 1;
+  }
+
+  for (const [token, freq] of Object.entries(tokenFreq)) {
+    if (!index.tokens[token]) {
+      index.tokens[token] = { docs: [], df: 0 };
+    }
+    index.tokens[token].docs.push({ id: memory.id, tf: freq, len: length });
+    index.tokens[token].df += 1;
+  }
+
+  index.totalLength += length;
+  index.docCount    += 1;
+  index.avgDocLength = index.totalLength / index.docCount;
+
+  return index;
+}
+
+// ── BM25 retrieval (k1=1.5, b=0.75) ──────────────────────────────────────────
+function search(query, options = {}) {
+  const { limit = 5, minScore = 0.5, projectFilter = null } = options;
+  const index   = loadIndex();
+  const tokens  = tokenise(query);
+  if (tokens.length === 0 || index.docCount === 0) return [];
+
+  const k1 = 1.5;
+  const b  = 0.75;
+  const N  = index.docCount;
+  const avgDl = index.avgDocLength || 1;
+  const scores = {};
+
+  for (const token of tokens) {
+    const entry = index.tokens[token];
+    if (!entry) continue;
+    const idf = Math.log(1 + (N - entry.df + 0.5) / (entry.df + 0.5));
+    for (const doc of entry.docs) {
+      const norm  = 1 - b + b * (doc.len / avgDl);
+      const score = idf * ((doc.tf * (k1 + 1)) / (doc.tf + k1 * norm));
+      scores[doc.id] = (scores[doc.id] || 0) + score;
+    }
+  }
+
+  const ranked = Object.entries(scores)
+    .filter(([, score]) => score >= minScore)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, limit * 3);
+
+  if (ranked.length === 0) return [];
+
+  const memories = readMemories(ranked.map(([id]) => id));
+  let results = ranked
+    .map(([id, score]) => {
+      const memory = memories[id];
+      return memory ? { ...memory, score } : null;
+    })
+    .filter(Boolean);
+
+  if (projectFilter) {
+    results = results.filter(m => m.project === projectFilter);
+  }
+
+  return results.slice(0, limit);
+}
+
+// ── Memory I/O ───────────────────────────────────────────────────────────────
+function readMemories(ids = null) {
+  if (!fs.existsSync(PATHS.log)) return ids ? {} : [];
+  const wantSet = ids ? new Set(ids) : null;
+  const lines = fs.readFileSync(PATHS.log, 'utf8').split('\n').filter(Boolean);
+  const out = ids ? {} : [];
+  for (const line of lines) {
+    let memory;
+    try { memory = JSON.parse(line); } catch { continue; }
+    if (memory.deleted) continue;
+    if (wantSet) {
+      if (wantSet.has(memory.id)) out[memory.id] = memory;
+    } else {
+      out.push(memory);
+    }
+  }
+  return out;
+}
+
+function appendMemory(memory) {
+  ensureDir(PATHS.dir);
+  fs.appendFileSync(PATHS.log, JSON.stringify(memory) + '\n');
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+function capture({
+  problem,
+  approach,
+  tags     = [],
+  project  = null,
+  language = null,
+  files    = [],
+  gotchas  = [],
+  source   = 'manual',
+}) {
+  if (!problem || !approach) {
+    throw new Error('capture requires both `problem` and `approach`');
+  }
+  const memory = {
+    id:          newMemoryId(),
+    captured_at: new Date().toISOString(),
+    problem:     String(problem).slice(0, 500),
+    approach:    String(approach).slice(0, 2000),
+    tags:        Array.from(new Set(tags.map(String))).slice(0, 20),
+    project:     project ? projectHash(project) : null,
+    project_path: project,
+    language,
+    files:       files.slice(0, 20),
+    gotchas:     gotchas.slice(0, 10),
+    source,
+  };
+  appendMemory(memory);
+  const index = loadIndex();
+  saveIndex(indexMemory(index, memory));
+  return memory;
+}
+
+function recall(query, options = {}) {
+  return search(query, options);
+}
+
+function recallForProject(projectRoot, query, options = {}) {
+  const opts = { ...options, projectFilter: projectHash(projectRoot) };
+  const results = search(query, opts);
+  if (results.length >= (options.limit || 5)) return results;
+  // Fall back to global memories if project-specific are sparse
+  const globalResults = search(query, options);
+  const seen = new Set(results.map(r => r.id));
+  for (const m of globalResults) {
+    if (!seen.has(m.id)) results.push(m);
+    if (results.length >= (options.limit || 5)) break;
+  }
+  return results;
+}
+
+function listAll() {
+  return readMemories();
+}
+
+function forget(memoryId) {
+  if (!fs.existsSync(PATHS.log)) return false;
+  const lines = fs.readFileSync(PATHS.log, 'utf8').split('\n').filter(Boolean);
+  let found = false;
+  const updated = lines.map(line => {
+    try {
+      const m = JSON.parse(line);
+      if (m.id === memoryId) {
+        found = true;
+        return JSON.stringify({ ...m, deleted: true, deleted_at: new Date().toISOString() });
+      }
+      return line;
+    } catch {
+      return line;
+    }
+  });
+  fs.writeFileSync(PATHS.log, updated.join('\n') + '\n');
+  if (found) rebuildIndex();
+  return found;
+}
+
+function rebuildIndex() {
+  const memories = readMemories();
+  let index = { tokens: {}, docCount: 0, avgDocLength: 0, totalLength: 0 };
+  for (const m of memories) {
+    index = indexMemory(index, m);
+  }
+  saveIndex(index);
+  return { count: memories.length };
+}
+
+function stats() {
+  const memories = readMemories();
+  const byProject = {};
+  const byLanguage = {};
+  const byTag = {};
+  for (const m of memories) {
+    if (m.project) byProject[m.project] = (byProject[m.project] || 0) + 1;
+    if (m.language) byLanguage[m.language] = (byLanguage[m.language] || 0) + 1;
+    for (const tag of m.tags || []) byTag[tag] = (byTag[tag] || 0) + 1;
+  }
+  return {
+    total: memories.length,
+    storageDir: PATHS.dir,
+    projects: Object.keys(byProject).length,
+    byLanguage,
+    topTags: Object.entries(byTag).sort(([, a], [, b]) => b - a).slice(0, 10),
+  };
+}
+
+module.exports = {
+  PATHS,
+  capture,
+  recall,
+  recallForProject,
+  listAll,
+  forget,
+  rebuildIndex,
+  stats,
+  tokenise,
+  projectHash,
+};

package/skills/agent-handoff/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: agent-handoff
+description: >
+  How to chain ECC specialist agents for multi-step problems —
+  pair-programmer → tdd-guide → code-reviewer → security-reviewer.
+  Use when one agent finishes its job and the next logical step needs
+  a different specialist. Documents the standard handoff protocol so
+  agents pass context cleanly.
+---
+
+# Agent Handoff Protocol
+
+Single agents handle single concerns. Real engineering tasks span multiple concerns. **Handoffs** are how ECC chains agents without losing context.
+
+## The 3-Line Handoff Protocol
+
+When an agent finishes its scope and the next step needs a different specialist, it ends with exactly this shape:
+
+```
+─────────────────────────────────────
+HANDOFF
+  From: <current-agent>
+  To:   <next-agent>
+  Why:  <one-line reason>
+  Carry: <what the next agent needs to know>
+─────────────────────────────────────
+```
+
+Then **stop**. The next agent picks up from `Carry:`.
+
+## Standard Chains
+
+These are the most common multi-agent flows. Memorize them.
+
+### Build something new (clean path)
+
+```
+pair-programmer  →  tdd-guide  →  code-reviewer  →  api-guardian (if API)
+                                              →  security-reviewer (if sensitive)
+                                              →  ux-reviewer (if UI)
+```
+
+`pair-programmer` agrees on approach. `tdd-guide` writes failing tests first. The implementer writes code. `code-reviewer` checks it. Specialist reviewers check their domain.
+
+### Bug in production
+
+```
+debug-detective  →  tdd-guide          →  refactor-cleaner (optional)
+                 (root cause)        (regression test)
+```
+
+Always add a regression test after a real-bug fix. Always.
+
+### Refactor a module
+
+```
+code-explorer    →  refactor-cleaner   →  tdd-guide        →  code-reviewer
+(map dependencies)  (cleanup)          (verify behavior)
+```
+
+### Performance investigation
+
+```
+performance-optimizer  →  tdd-guide       →  code-reviewer
+                       (perf regression test)
+```
+
+### API change
+
+```
+api-guardian  →  pair-programmer  →  tdd-guide  →  doc-updater
+(blast radius)  (impl approach)                   (changelog)
+```
+
+### Security audit
+
+```
+security-reviewer  →  tdd-guide               →  release-captain
+                   (security regression test)  (patch release)
+```
+
+### Open-source a private project
+
+```
+opensource-forker  →  opensource-sanitizer  →  opensource-packager  →  release-captain
+(make a clean fork) (strip secrets/PII)      (README, license, examples)  (cut v0.1.0)
+```
+
+### Framework migration
+
+```
+migration-guide  →  pair-programmer  →  tdd-guide  →  pr-test-analyzer
+(phase plan)        (per-phase impl)              (verify coverage on PR)
+```
+
+### Build is broken
+
+```
+build-error-resolver  →  dependency-doctor (if dep issue)
+                      →  env-debugger (if env issue)
+                      →  debug-detective (if it's actually a runtime bug surfacing at build)
+```
+
+### CI is flaky
+
+```
+flake-hunter  →  tdd-guide       →  release-captain (if it gates a release)
+              (deterministic test)
+```
+
+### Git is on fire
+
+```
+git-rescue  →  release-captain (if a release was midway)
+```
+
+## Carry Field — What to Pass Forward
+
+The `Carry:` line is the most important. Bad carry breaks the chain.
+
+**Good carry:**
+> "Bug is in `processPayment()` line 142 — race between `lockBalance()` and `commitTx()`. The lock returns before the DB transaction is durable. Add a regression test that simulates a 50ms commit delay and asserts no double-spend."
+
+**Bad carry:**
+> "There was a bug, please test it"
+
+The next agent should be able to start work from `Carry:` alone, without re-reading the whole conversation.
+
+## When NOT to Hand Off
+
+- The current agent's job isn't actually done. Finish it.
+- The user explicitly said "just do this one thing." Respect it.
+- The next step is **trivial** and a handoff would slow it down (e.g., a one-line change). Just do it.
+- The user is **already in flow** and a handoff context-switch would interrupt them. Wait for a natural pause.
+
+## Parallel Handoffs
+
+Some problems need multiple agents at once, not in sequence:
+
+```
+"Building a new payment endpoint" →
+
+  [PARALLEL]
+   ├─ api-guardian       (contract review)
+   ├─ security-reviewer  (auth, input validation, idempotency)
+   └─ pair-programmer    (overall approach)
+
+  [SEQUENTIAL after agreement]
+   tdd-guide → implementer → code-reviewer
+```
+
+Announce the parallel set up front so the user knows what's happening:
+
+```
+This touches three concerns at once. I'm consulting:
+  • api-guardian      — for contract design
+  • security-reviewer — for auth & validation
+  • pair-programmer   — for overall structure
+
+Then we'll move to tests + implementation.
+```
+
+## Handoff Hygiene
+
+- **Always** name both agents (from/to)
+- **Always** justify the handoff in one line (why this specialist now?)
+- **Always** package the carry — the next agent should not need to re-investigate
+- **Never** chain more than 4 agents in a single response — that's a sign the task is too big and needs decomposition (use `planner`)
+
+## Self-Handoff Rule
+
+An agent may **stay in role** for the next step if it's still within its specialty. Don't fake a handoff just because the conversation continues:
+
+- `debug-detective` may continue after finding the cause to **explain** the cause — that's still debugging.
+- `code-reviewer` may continue to suggest specific fixes — still review scope.
+- But `code-reviewer` writing the actual fix at scale → hand off to the implementer (or appropriate language reviewer with `code-architect` for blueprint).
+
+## The Master Conductor: kodelyth-advisor
+
+When in doubt about whom to hand off to, the user can always invoke `kodelyth-advisor`. The advisor doesn't do the work — it picks the right specialist and routes.
+
+```
+Any agent  →  kodelyth-advisor (if next step is unclear)  →  Right specialist
+```

package/skills/intent-routing/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: intent-routing
+description: >
+  How Kodelyth ECC auto-detects user intent and routes to the right
+  specialist agent without requiring explicit invocation. Read this when
+  you (the AI) want to understand the routing rule, when the user asks
+  "how does the toolkit decide which agent to use", or when designing a
+  new agent and need to know what trigger patterns it should claim.
+---
+
+# Intent Routing — How ECC Picks the Right Agent
+
+ECC has **two activation paths** for its 53 specialist agents:
+
+1. **Explicit** — user types `use <agent>`, `@agent`, or `invoke <agent>`
+2. **Implicit (intent routing)** — the AI reads the user's message, infers the right specialist, announces the routing, and behaves as that agent
+
+Most users never type `use ...`. Intent routing is what makes the toolkit feel **alive** instead of like a directory of files.
+
+## The Routing Contract
+
+When intent routing fires, the AI MUST do four things in order:
+
+1. **Acknowledge the routing** in one short line above the response:
+   ```
+   → Routing to debug-detective (your error message + frustration matches the bug-tracking signal)
+   ```
+2. **Behave as that agent** — adopt its persona, methodology, and constraints for the rest of the response
+3. **Suggest the explicit invocation** in one closing line:
+   ```
+   Tip: next time you can type "use debug-detective" to invoke me directly.
+   ```
+4. **Stay transparent** — never silently route. The user must always know which agent is "speaking".
+
+## The Source of Truth
+
+The full routing table lives in `rules/common/agent-intent-routing.md`. This skill is a **summary + design guide**.
+
+If you (an agent author) want to claim trigger patterns for a new agent, you must:
+
+1. Add your patterns to `agent-intent-routing.md`
+2. Pick a priority tier (1 = crisis, 10 = chaining)
+3. Verify your patterns don't collide with an existing higher-priority agent
+4. Add a counter-pattern (when NOT to route here)
+
+## Priority Tiers (Why They Matter)
+
+When two agents could match, the **higher tier wins**.
+
+| Tier | Theme | Example agents |
+|---|---|---|
+| 1 | Crisis & emotional state | kodelyth-advisor, pair-programmer |
+| 2 | Active pain (something broken) | debug-detective, build-error-resolver, env-debugger |
+| 3 | Quality & review | code-reviewer, security-reviewer, ux-reviewer, api-guardian |
+| 4 | Performance & scale | performance-optimizer |
+| 5 | Planning & architecture | planner, architect, code-architect, migration-guide |
+| 6 | Testing | tdd-guide, e2e-runner, pr-test-analyzer, flake-hunter |
+| 7 | Code hygiene | refactor-cleaner, code-simplifier, type-design-analyzer |
+| 8 | Documentation | doc-updater, docs-lookup, comment-analyzer |
+| 9 | Specialized | seo-specialist, opensource-*, dependency-doctor, git-rescue, release-captain |
+| 10 | Multi-agent chains | (handoffs between any two agents) |
+
+**Why crisis is tier 1:** if a user says "I'm stuck on this bug", we route to `kodelyth-advisor` first (emotional state) rather than `debug-detective` (the technical one). The advisor will then often hand off to `debug-detective` once the user describes the actual bug.
+
+## What Counts as a Trigger
+
+A trigger is a **regex or keyword pattern in the user's message**. Good triggers:
+
+- **Direct verbs**: "review", "debug", "optimize", "migrate"
+- **State words**: "broken", "slow", "stuck", "failing", "vulnerable"
+- **Domain terms**: "JWT", "SQL injection", "WCAG", "TypeScript", "Postgres"
+- **Emotional cues**: "I'm lost", "I've been trying for hours", "this won't work"
+
+Bad triggers (avoid):
+
+- Single common words like "and", "the", "code" (will match everything)
+- Words that are equally valid for two different agents without any disambiguator
+- Metaphors that are easy to miss ("my code is on fire" — too loose)
+
+## Counter-Patterns (When NOT to Route)
+
+Always include these in any new agent:
+
+- The user **already explicitly invoked** another agent — that wins
+- The message is a **one-line factual question** — answer directly, don't route
+- The message is **purely conversational** ("hi", "thanks") — don't route
+- The user explicitly says **"don't route" or "just answer me"** — respect it
+- The user is in a **defined multi-step workflow** with another agent — don't interrupt
+
+## Example: Designing a New Agent's Trigger Section
+
+```markdown
+### `dependency-doctor` — npm/pip/cargo/maven dep hell
+
+| Signal | Examples |
+|---|---|
+| Install failure | "npm install fails", "cannot resolve", "yarn install error" |
+| Lockfile drift | "package-lock conflict", "yarn.lock conflict", "lockfile diff" |
+| CVE | "audit shows", "CVE-", "vulnerable dependency" |
+| Version conflict | "ERESOLVE", "peer dep conflict", "conflicting versions" |
+| Bloat | "bundle too big", "node_modules huge", "dep audit" |
+
+Counter-signals (do NOT route here):
+- Generic "build failed" without dep mention → `build-error-resolver`
+- Runtime null pointer → `debug-detective`
+```
+
+## Example: Routing Decisions in the Wild
+
+| User says | Route to | Why |
+|---|---|---|
+| "I'm getting a TypeError on line 42" | `debug-detective` | T2 — specific error |
+| "Should I use React Context or Zustand?" | `pair-programmer` | T1 — pre-implementation question |
+| "Review my login component" | `typescript-reviewer` (if .ts file) or `code-reviewer` | T3 — review request |
+| "I have no idea where to start with this auth migration" | `kodelyth-advisor` | T1 — lost / overwhelmed |
+| "How do I make this faster?" | `performance-optimizer` | T4 — perf |
+| "Is my JWT signing secure?" | `security-reviewer` | T3 — security keyword |
+| "build failed on Vercel" | `build-error-resolver` | T2 — build failure |
+| "Tests pass locally but fail on CI" | `flake-hunter` then `env-debugger` | T2 — flake or env diff |
+| "Migrate Pages Router to App Router" | `migration-guide` | T5 — framework migration |
+| "Add accessibility to this form" | `ux-reviewer` | T3 — a11y |
+| "open source this project" | `opensource-forker` (chain start) | T9 — OSS chain |
+| "I lost my commits after `reset --hard`" | `git-rescue` | T9 — git crisis |
+
+## Anti-Patterns to Avoid
+
+- **Silent routing**: jumping into `debug-detective` without a "→ Routing to" line. The user thinks the AI just changed personality randomly.
+- **Over-routing**: claiming `code-reviewer` for every code-related message. Reserve it for explicit review intent.
+- **Under-routing**: ignoring obvious signals because the user didn't type the magic word.
+- **Stacking**: routing to 4 agents at once. Pick **one or at most two parallel agents**.
+
+## Skill Authors: Add Your Triggers Here
+
+When you build a new agent, update `rules/common/agent-intent-routing.md`. The intent rule is **the toolkit's nervous system**. Better intent rules = better routing = better user experience.