kodelyth-ecc 1.2.2 → 1.4.0

package/install.sh

@@ -47,7 +47,7 @@ echo -e "${RED}${BOLD}  ║   DANGER LEVEL: GOD TIER    ·    NOT FOR JUNIOR DEV
 echo -e "${RED}${BOLD}  ╚══════════════════════════════════════════════════════════════╝${RESET}"
 echo ""
 echo -e "${BOLD}  Kodelyth ECC — The most dangerous AI coding toolkit on the planet${RESET}"
-echo -e "${CYAN}  53 specialist agents  ·  185 skills  ·  79 commands  ·  18+ hooks${RESET}"
+echo -e "${CYAN}  59 specialist agents  ·  188 skills  ·  80 commands  ·  18+ hooks  ·  intent routing  ·  local memory${RESET}"
 echo -e "${CYAN}  Any language  ·  Any framework  ·  Any scale  ·  300B-level quality${RESET}"
 echo ""
 echo -e "  github.com/sifxprime/kodelyth-ecc"
@@ -344,8 +344,8 @@ echo ""
 
 case "$TARGET" in
   claude-home)
-    install_dir  "$SCRIPT_DIR/agents"   "$AGENTS_DEST"   "Agents   (53)"
-    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills   (185)"
+    install_dir  "$SCRIPT_DIR/agents"   "$AGENTS_DEST"   "Agents   (58)"
+    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills   (187)"
     install_dir  "$SCRIPT_DIR/commands" "$COMMANDS_DEST" "Commands (79)"
     install_hooks                       "$HOOKS_DEST"
     # Rules: install common + selected languages
@@ -387,19 +387,19 @@ case "$TARGET" in
 
   cursor-project)
     install_flat "$SCRIPT_DIR/rules"    "$RULES_DEST"    "Rules (flattened)"
-    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills (183)"
+    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills (187)"
     ;;
 
   codex-home)
-    install_dir  "$SCRIPT_DIR/agents"   "$AGENTS_DEST"   "Agents   (53)"
-    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills   (185)"
+    install_dir  "$SCRIPT_DIR/agents"   "$AGENTS_DEST"   "Agents   (58)"
+    install_dir  "$SCRIPT_DIR/skills"   "$SKILLS_DEST"   "Skills   (187)"
     install_dir  "$SCRIPT_DIR/commands" "$COMMANDS_DEST" "Commands (79)"
     install_flat "$SCRIPT_DIR/rules"    "$RULES_DEST"    "Rules (flattened)"
     ;;
 
   windsurf-project|windsurf-home)
-    install_dir  "$SCRIPT_DIR/agents"  "$AGENTS_DEST"  "Agents   (53)"
-    install_dir  "$SCRIPT_DIR/skills"  "$SKILLS_DEST"  "Skills   (185)"
+    install_dir  "$SCRIPT_DIR/agents"  "$AGENTS_DEST"  "Agents   (58)"
+    install_dir  "$SCRIPT_DIR/skills"  "$SKILLS_DEST"  "Skills   (187)"
     install_flat "$SCRIPT_DIR/rules"   "$RULES_DEST"   "Rules (flattened)"
     generate_windsurfrules "$SCRIPT_DIR/rules" "$WINDSURFRULES_DEST"
     ;;
@@ -409,31 +409,6 @@ case "$TARGET" in
     ;;
 esac
 
-# ── Install Kodelyth Lens dashboard ──────────────────────────────────────────
-LENS_DEST="$HOME_DIR/.kodelyth/lens"
-LENS_INSTALLED=false
-if [[ -d "$SCRIPT_DIR/dashboard" ]]; then
-  mkdir -p "$LENS_DEST"
-  cp -r "$SCRIPT_DIR/dashboard"/. "$LENS_DEST/"
-  echo -e "  ${GREEN}✓${RESET} Kodelyth Lens dashboard ${BLUE}(→ $LENS_DEST)${RESET}"
-  # Create launcher script
-  cat > "$HOME_DIR/.kodelyth/lens.sh" <<'LENS'
-#!/usr/bin/env bash
-cd "$HOME/.kodelyth/lens" && node server.js
-LENS
-  chmod +x "$HOME_DIR/.kodelyth/lens.sh"
-  echo -e "  ${GREEN}✓${RESET} Lens launcher ${BLUE}(→ ~/.kodelyth/lens.sh)${RESET}"
-  LENS_INSTALLED=true
-fi
-
-# ── Install agent-tracker hook script ─────────────────────────────────────────
-if [[ -f "$SCRIPT_DIR/scripts/agent-tracker-hook.js" ]] && [[ "$TARGET" == "claude-home" ]]; then
-  HOOKS_SCRIPTS="$HOME_DIR/.claude/hooks/scripts"
-  mkdir -p "$HOOKS_SCRIPTS"
-  cp "$SCRIPT_DIR/scripts/agent-tracker-hook.js" "$HOOKS_SCRIPTS/agent-tracker-hook.js"
-  echo -e "  ${GREEN}✓${RESET} Agent tracker hook ${BLUE}(→ $HOOKS_SCRIPTS)${RESET}"
-fi
-
 # ── Write install state ───────────────────────────────────────────────────────
 VERSION="$(cat "$SCRIPT_DIR/VERSION" 2>/dev/null || echo "1.0.0")"
 STATE_FILE="$DEST/kodelyth-ecc-install-state.json"
@@ -455,58 +430,6 @@ echo ""
 echo -e "${GREEN}${BOLD}  ARMED AND OPERATIONAL.${RESET}"
 echo ""
 
-# ── Auto-start Kodelyth Lens (claude-home only) ───────────────────────────────
-if [[ "$TARGET" == "claude-home" ]] && [[ "$LENS_INSTALLED" == "true" ]]; then
-  if command -v node &>/dev/null; then
-    LENS_PORT="${LENS_PORT:-3456}"
-    LENS_LOG="$HOME_DIR/.kodelyth/lens.log"
-
-    # Kill any existing Lens process on this port
-    if command -v lsof &>/dev/null; then
-      OLD_PID="$(lsof -ti ":$LENS_PORT" 2>/dev/null || true)"
-      if [[ -n "$OLD_PID" ]]; then
-        kill "$OLD_PID" 2>/dev/null || true
-      fi
-    fi
-
-    # Start Lens server in background
-    nohup node "$LENS_DEST/server.js" > "$LENS_LOG" 2>&1 &
-    LENS_PID=$!
-
-    # Wait up to 5 seconds for the server to be ready
-    LENS_READY=false
-    for i in 1 2 3 4 5; do
-      sleep 1
-      if command -v curl &>/dev/null && curl -sf "http://localhost:$LENS_PORT/api/stats" >/dev/null 2>&1; then
-        LENS_READY=true
-        break
-      elif command -v wget &>/dev/null && wget -qO- "http://localhost:$LENS_PORT/api/stats" >/dev/null 2>&1; then
-        LENS_READY=true
-        break
-      fi
-    done
-
-    if [[ "$LENS_READY" == "true" ]]; then
-      echo -e "  ${GREEN}✓${RESET} Kodelyth Lens started ${BLUE}(PID $LENS_PID · port $LENS_PORT)${RESET}"
-      # Open browser — macOS: open, Linux: xdg-open, WSL: explorer.exe
-      if [[ "$OSTYPE" == "darwin"* ]]; then
-        open "http://localhost:$LENS_PORT" 2>/dev/null || true
-        echo -e "  ${GREEN}✓${RESET} Dashboard opened in browser"
-      elif command -v xdg-open &>/dev/null; then
-        xdg-open "http://localhost:$LENS_PORT" 2>/dev/null &
-        echo -e "  ${GREEN}✓${RESET} Dashboard opened in browser"
-      elif command -v explorer.exe &>/dev/null; then
-        explorer.exe "http://localhost:$LENS_PORT" 2>/dev/null || true
-        echo -e "  ${GREEN}✓${RESET} Dashboard opened in browser"
-      fi
-    else
-      echo -e "  ${YELLOW}⚠${RESET}  Lens server started (PID $LENS_PID) — open http://localhost:$LENS_PORT manually"
-    fi
-
-    echo ""
-  fi
-fi
-
 case "$TARGET" in
   claude-home)
     echo -e "${BOLD}  Claude Code — what to do now:${RESET}"
@@ -519,13 +442,8 @@ case "$TARGET" in
     echo "    use ux-reviewer            ← after touching any UI"
     echo "    /kodelyth-quickstart       ← full onboarding guide"
     echo ""
-    echo -e "${BOLD}  Kodelyth Lens — Usage Dashboard:${RESET}"
-    echo ""
-    echo "    node ~/.kodelyth/lens/server.js"
-    echo "    Open: http://localhost:3456"
-    echo ""
-    echo "    Tracks agents, costs, cache savings across"
-    echo "    Claude Code · Cursor · Windsurf · Codex · OpenCode · Antigravity"
+    echo "  Intent routing is god-tier — describe your problem in plain words"
+    echo "  and the right specialist agent is auto-suggested."
     ;;
   antigravity)
     echo -e "${BOLD}  Google Antigravity — what to do now:${RESET}"
@@ -557,17 +475,13 @@ case "$TARGET" in
     echo -e "${BOLD}  Windsurf — what to do now:${RESET}"
     echo ""
     echo "  Open your project in Windsurf (Cascade)."
-    echo "  .windsurfrules is active — 12 coding rules loaded automatically."
+    echo "  .windsurfrules is active — 15 coding rules + intent routing loaded automatically."
     echo "  Agents available in .windsurf/agents/"
     echo ""
     echo "    use kodelyth-advisor       ← not sure where to start"
     echo "    use debug-detective        ← trace any bug to root cause"
     echo "    use ux-reviewer            ← after touching any UI"
     echo "    use api-guardian           ← API contract protection"
-    echo ""
-    echo "  Kodelyth Lens — Usage Dashboard:"
-    echo "    node ~/.kodelyth/lens/server.js"
-    echo "    Open: http://localhost:3456"
     ;;
   *)
     echo -e "${BOLD}  What to do now:${RESET}"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kodelyth-ecc",
-  "version": "1.2.2",
-  "description": "Production-grade AI coding toolkit — 53 agents, 185 skills, 79 commands. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
+  "version": "1.4.0",
+  "description": "Production-grade AI coding toolkit — 59 agents, 188 skills, 79 commands, god-tier intent routing, local self-learning memory. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,8 @@
     "ai-agents",
     "coding-toolkit",
     "llm",
+    "memory",
+    "self-learning",
     "kodelyth"
   ],
   "bin": {

package/rules/common/agent-intent-routing.md

@@ -0,0 +1,337 @@
+# Agent Intent Routing — Auto-Detect User Intent → Right Specialist Agent
+
+This rule teaches the AI to **automatically route the user to the correct specialist agent** based on what they say, write, or feel — without requiring `use <agent-name>` syntax.
+
+When any of the patterns below match the user's message, the AI MUST:
+
+1. **Acknowledge** the routing in one short line: `→ Routing to <agent-name>`
+2. **Behave as that agent** for the rest of that response (apply its persona, methodology, and constraints)
+3. **Suggest the explicit invocation** at the end so the user learns the toolkit: `Tip: next time you can type "use <agent-name>"`
+
+If multiple agents match, pick the **highest priority** below (priority decreases top-to-bottom). If two are equally relevant, name both and ask the user which to use.
+
+**Never silently route.** Always be transparent about which agent is taking over.
+
+---
+
+## Priority 1 — Crisis & Emotional Signals
+
+### `kodelyth-advisor` — User is lost, stuck, overwhelmed
+
+Trigger if the user expresses **uncertainty about direction**, not a specific technical question.
+
+| Signal | Examples |
+|---|---|
+| Stuck / lost | "I'm stuck", "I'm lost", "I have no idea", "I don't know where to start" |
+| Overwhelmed | "this is too much", "I'm overwhelmed", "where do I even begin" |
+| Asking for direction | "what should I do", "help me figure out", "should I X or Y", "I'm not sure" |
+| Confused about the codebase | "I don't understand this code", "how does this even work" |
+| First-time on a problem | "first time doing X", "never done this before", "is there a right way" |
+
+**Counter-signals (do NOT route here):** specific technical question, error message, or named file/function.
+
+### `pair-programmer` — User is about to write code
+
+Trigger if the user describes **what they're about to build** before they start.
+
+| Signal | Examples |
+|---|---|
+| Pre-implementation | "I want to build", "I'm going to add", "let's create", "I need to make a" |
+| Approach question | "how should I implement", "what's the best way to", "should I use X pattern" |
+| Architecture sketch | "I'm thinking of doing X then Y", "my plan is to" |
+| Pre-flight check | "before I start", "thinking about", "planning to" |
+
+---
+
+## Priority 2 — Active Pain (something is broken)
+
+### `debug-detective` — Bug, error, unexpected behavior
+
+| Signal | Examples |
+|---|---|
+| Direct bug report | "bug", "broken", "crashed", "exception", "stack trace", "traceback" |
+| Frustration | "I've been trying for hours", "can't figure out why", "this won't work" |
+| Unexpected behavior | "why is this X", "shouldn't this Y", "not what I expected" |
+| Specific error keywords | `TypeError`, `NullPointerException`, `panic`, `segfault`, `undefined`, `cannot read property` |
+| Test failures | "test fails", "expected X got Y", "assertion failed" |
+
+**Always:** ask for the exact error, the minimal repro, and what was changed last.
+
+### `silent-failure-hunter` — Something is wrong but no error
+
+| Signal | Examples |
+|---|---|
+| Mismatch w/o error | "no error but wrong result", "data is wrong", "looks fine but isn't working" |
+| Silent state corruption | "X happened but Y didn't fire", "the value is off", "race condition" |
+| Swallowed exceptions | "try/catch", "fallback", "default value", "it just returns null" |
+
+### `build-error-resolver` — Build / compile / type errors
+
+| Signal | Examples |
+|---|---|
+| Build failed | "build failed", "compile error", "won't compile", "cargo build", "npm run build" |
+| Type errors | "type error", "TS2322", "type mismatch", "cannot assign", "incompatible types" |
+| Module/import | "module not found", "cannot resolve", "import error" |
+
+**Language-specific routing:** Go → `go-build-resolver`, Rust → `rust-build-resolver`, Java → `java-build-resolver`, Kotlin → `kotlin-build-resolver`, C++ → `cpp-build-resolver`, Dart/Flutter → `dart-build-resolver`, PyTorch → `pytorch-build-resolver`.
+
+---
+
+## Priority 3 — Quality & Review
+
+### `code-reviewer` — User wants feedback on existing code
+
+| Signal | Examples |
+|---|---|
+| Direct review request | "review this", "code review", "LGTM?", "thoughts?", "feedback" |
+| Quality check | "is this good", "is this clean", "anything wrong" |
+| Refactor opportunity | "is there a better way", "smell test", "looks ugly" |
+
+**Language-specific routing (if file extension or language is mentioned):**
+
+| Language | Agent |
+|---|---|
+| TypeScript / JavaScript | `typescript-reviewer` |
+| Python | `python-reviewer` |
+| Go | `go-reviewer` |
+| Rust | `rust-reviewer` |
+| Java / Spring | `java-reviewer` |
+| Kotlin / Android | `kotlin-reviewer` |
+| C++ | `cpp-reviewer` |
+| C# / .NET | `csharp-reviewer` |
+| Flutter / Dart | `flutter-reviewer` |
+| SQL / Postgres / Supabase | `database-reviewer` |
+| Healthcare / EMR / PHI | `healthcare-reviewer` |
+
+### `security-reviewer` — Security concern
+
+| Signal | Examples |
+|---|---|
+| Direct security question | "is this secure", "vulnerability", "CVE", "audit" |
+| Common attacks | "SQL injection", "XSS", "CSRF", "SSRF", "auth bypass", "RCE", "path traversal" |
+| Auth & secrets | "auth flow", "JWT", "session", "API key in code", "leaked secret", "exposed credential" |
+| Crypto | "encryption", "hashing passwords", "salt", "AES", "RSA" |
+| Input handling | "user input", "sanitize", "escape", "validation" |
+
+### `api-guardian` — API contract changes
+
+| Signal | Examples |
+|---|---|
+| API change | "breaking change", "deprecate", "API version", "backwards compat" |
+| Contract concern | "consumer impact", "client breakage", "field removal", "rename endpoint" |
+| Spec work | "OpenAPI", "GraphQL schema", "REST design", "idempotent" |
+
+### `ux-reviewer` — Frontend / UX / Accessibility
+
+| Signal | Examples |
+|---|---|
+| UI feedback | "feels off", "looks weird", "UX", "user experience", "interaction" |
+| Accessibility | "a11y", "WCAG", "screen reader", "ARIA", "keyboard nav", "color contrast" |
+| Form / interaction | "form validation", "loading state", "error state", "empty state" |
+| Mobile / responsive | "mobile", "responsive", "viewport", "touch target" |
+
+---
+
+## Priority 4 — Performance & Scale
+
+### `performance-optimizer` — Slowness / bottleneck
+
+| Signal | Examples |
+|---|---|
+| Slow | "slow", "sluggish", "laggy", "takes forever", "timing out" |
+| Resource | "high CPU", "memory leak", "OOM", "out of memory", "cpu pinned" |
+| Frontend perf | "FCP", "LCP", "INP", "bundle size", "render time", "jank" |
+| Backend perf | "N+1", "slow query", "throughput", "latency", "p99" |
+
+---
+
+## Priority 5 — Planning & Architecture
+
+### `planner` — Feature planning
+
+| Signal | Examples |
+|---|---|
+| Plan a feature | "plan this", "roadmap", "break down", "sprint plan", "milestones" |
+| Decompose | "where do I start with X feature", "tasks for", "work items" |
+
+### `architect` — System design
+
+| Signal | Examples |
+|---|---|
+| System-level | "architecture", "system design", "how should the services interact" |
+| Choosing tech | "should I use Postgres or Mongo", "monorepo vs polyrepo", "REST vs GraphQL" |
+| Scaling | "horizontal scaling", "sharding", "queue", "event-driven" |
+
+### `code-architect` — Single-feature blueprint
+
+Trigger when the user wants a **detailed implementation blueprint for one specific feature**, not the whole system.
+
+### `migration-guide` — Framework / language version upgrade
+
+| Signal | Examples |
+|---|---|
+| Upgrade | "upgrade from X to Y", "migrate to", "Next.js 12 → 15", "Python 2 → 3", "React 18 → 19" |
+| Major version | "major version bump", "breaking deps", "node 18 → 22", "TS 4 → 5" |
+
+---
+
+## Priority 6 — Testing
+
+### `tdd-guide` — Tests, coverage, TDD
+
+| Signal | Examples |
+|---|---|
+| Write tests | "write a test", "unit test", "integration test", "test for this" |
+| TDD | "TDD", "test driven", "red green refactor" |
+| Coverage | "coverage", "what's not tested", "coverage gap" |
+
+### `e2e-runner` — End-to-end Playwright tests
+
+| Signal | Examples |
+|---|---|
+| E2E | "Playwright", "end-to-end", "E2E", "browser test", "user flow test" |
+| Critical path | "checkout flow", "signup flow", "happy path test" |
+
+### `pr-test-analyzer` — Test coverage on PRs
+
+| Signal | Examples |
+|---|---|
+| PR | "review my PR tests", "did I cover everything", "PR test gaps" |
+
+---
+
+## Priority 7 — Code Hygiene
+
+### `refactor-cleaner` — Dead code, cleanup
+
+| Signal | Examples |
+|---|---|
+| Cleanup | "clean up", "dead code", "unused", "remove old", "tech debt" |
+| Duplicate | "duplicate", "DRY", "extract function" |
+
+### `code-simplifier` — Reduce complexity
+
+| Signal | Examples |
+|---|---|
+| Simplify | "simpler", "too complex", "hard to read", "convoluted" |
+| Readability | "easier to follow", "more readable" |
+
+### `type-design-analyzer` — Type system improvements
+
+| Signal | Examples |
+|---|---|
+| Type design | "better types", "stricter types", "type safety", "discriminated union", "generics" |
+| `any` cleanup | "remove any", "stricter typing", "narrow type" |
+
+---
+
+## Priority 8 — Documentation
+
+### `doc-updater` — Update docs/README
+
+| Signal | Examples |
+|---|---|
+| Docs | "update README", "document this", "add docs", "JSDoc", "docstring" |
+| Onboarding | "explain how this works", "doc for new devs" |
+
+### `docs-lookup` — Library / framework API question
+
+| Signal | Examples |
+|---|---|
+| Library API | "how do I use X library", "what's the signature", "API for X" |
+| Framework feature | "Next.js App Router", "React Suspense", "Django ORM", "Rails 7" |
+
+### `comment-analyzer` — Comment quality
+
+| Signal | Examples |
+|---|---|
+| Comments | "are my comments good", "comment hygiene", "explain why not what" |
+
+---
+
+## Priority 9 — Specialized Workflows
+
+### `chief-of-staff` — Communication, email, multi-channel ops
+
+Trigger for non-code workflow tasks: drafting emails, scheduling, status updates, multi-channel coordination.
+
+### `seo-specialist` — SEO / metadata / search
+
+| Signal | Examples |
+|---|---|
+| SEO | "SEO", "meta tags", "schema.org", "structured data", "Core Web Vitals", "sitemap" |
+
+### `opensource-forker` + `opensource-sanitizer` + `opensource-packager` — Open-sourcing a project
+
+| Signal | Examples |
+|---|---|
+| OSS prep | "open source this", "make this public", "publish to GitHub", "strip secrets", "remove credentials" |
+
+Use the chain: `forker` → `sanitizer` → `packager`.
+
+---
+
+## Priority 10 — Multi-Agent Patterns
+
+### Sequential chains (suggest the next agent)
+
+| Just used | Suggest next |
+|---|---|
+| `pair-programmer` (approach agreed) | `code-reviewer` after implementation |
+| `debug-detective` (root cause found) | `tdd-guide` to add a regression test |
+| `code-reviewer` (issues found) | `refactor-cleaner` to fix |
+| `security-reviewer` (vuln found) | `tdd-guide` to add a security test |
+| `migration-guide` (plan made) | `pr-test-analyzer` after PR is up |
+| `architect` (design done) | `code-architect` for the first feature |
+| `performance-optimizer` (bottleneck found) | `tdd-guide` for a perf regression test |
+
+### Parallel suggestions
+
+If the user has a multi-faceted concern, name the parallel agents:
+- "I'm building a payment endpoint" → `pair-programmer` + `security-reviewer` + `api-guardian`
+- "Refactoring the auth module" → `refactor-cleaner` + `security-reviewer` + `tdd-guide`
+
+---
+
+## Counter-Patterns — Do NOT Route
+
+**Skip routing if:**
+
+- The user **already explicitly invoked** an agent (`use <agent>`, `@agent`, `invoke <agent>`) — that takes precedence
+- The message is **a one-liner factual question** ("what does `git stash pop` do?") — answer directly
+- The message is **purely conversational** ("hi", "thanks", "ok") — respond normally
+- The user says **"just answer me directly"** or **"don't route"** — respect it
+- The user is in the middle of a **defined multi-step workflow** initiated by another agent
+
+---
+
+## Example Routing Decisions
+
+| User says | Route to | Why |
+|---|---|---|
+| "I'm getting a TypeError on line 42" | `debug-detective` | Specific error, frustration implied |
+| "Should I use React Context or Zustand here?" | `pair-programmer` | Pre-implementation approach question |
+| "Review my login component" | `typescript-reviewer` (or `code-reviewer`) | Explicit review + likely TS |
+| "I have no idea where to start with this auth migration" | `kodelyth-advisor` | Lost / overwhelmed |
+| "How do I make this faster?" | `performance-optimizer` | Direct perf question |
+| "Is my JWT signing secure?" | `security-reviewer` | Auth + security keyword |
+| "build failed on Vercel" | `build-error-resolver` | Build failure |
+| "Tests are slow / red" | `tdd-guide` first, then `debug-detective` if reds | Test-first reasoning |
+| "Migrate from Pages Router to App Router" | `migration-guide` | Framework migration |
+| "Add accessibility to this form" | `ux-reviewer` | a11y |
+| "Plan the v2 redesign" | `planner` → `architect` | Plan + design |
+| "open source this project" | `opensource-forker` | OSS chain start |
+
+---
+
+## Output Format When Routing
+
+```
+→ Routing to debug-detective (your error message + frustration matches the bug-tracking signal)
+
+[response in debug-detective's style — methodical, hypothesis-driven, asks for repro]
+
+Tip: next time you can type "use debug-detective" to invoke me directly.
+```
+
+This keeps the user **informed**, **never surprised**, and **learning the toolkit** with every interaction.

package/rules/common/memory-protocol.md

@@ -0,0 +1,56 @@
+# Kodelyth Memory Protocol
+
+> Auto-loaded every session. Tells the AI when to consult and contribute to local memory.
+
+## What is Kodelyth Memory
+
+A local file at `~/.kodelyth/memory/memories.jsonl` storing solutions, patterns, and gotchas extracted from past sessions. Retrieval is BM25 (keyword + tag matching). It is **not** a learned model — it is a retrieval store that gives you better context.
+
+If the SessionStart hook ran, you have already received a memory block in your initial context with:
+- The user's recurring patterns (tags seen across multiple sessions)
+- Recent solutions in this project
+- Their detected stack
+
+## When to recall memory mid-session
+
+Trigger a memory recall (run the `kodelyth-memory` agent or `node scripts/memory/cli.js search "<query>"`) when **any** of these is true:
+
+1. The user describes a task in a domain that matches a tag in their memory (`payments`, `auth`, `database`, `deployment`, etc.)
+2. The user asks "have I done this before?" or "how did I solve X last time?"
+3. The user mentions a library, framework, or service by name that appears in past memories
+4. You're about to commit to an architectural decision and want to check past precedent
+
+## How to surface a recalled memory
+
+Naturally, never robotically. Pattern:
+
+> I checked your memory — you solved a similar problem in `<project>` on `<date>`. The approach that worked was `<approach>`. Want me to apply the same here, or is this case different?
+
+Always end by giving the user the option to override. Memory is a hint, not a command.
+
+## When to capture a new memory
+
+Capture when **all** are true:
+- The user signals success (`"that worked"`, `"perfect"`, `"fixed it"`, `"thanks"`, `"done"`)
+- The work involved real iteration (not a one-shot trivial fix)
+- The lesson is reusable (would help in another similar problem, not just this exact file)
+
+Show the user the draft memory before storing. Never silently capture.
+
+## What you must not do
+
+- **Never** auto-recall the same memory twice in one session (the user has seen it)
+- **Never** capture without explicit confirmation (`yes`, `store it`, `remember`)
+- **Never** treat a recalled memory as ground truth — it could be stale
+- **Never** transmit memory data anywhere — it is local-only by design
+- **Never** fabricate a memory ("you usually...") if no relevant memory exists — say nothing
+
+## Cache-aware behaviour
+
+The injected memory block is structured so its prefix is identical across calls in the same project. Do not rewrite or reorder this block during a session — that defeats the prompt cache and burns tokens. If you need to add session-specific notes, append them after the block.
+
+## Honest disclosure
+
+If the user asks "how do you know that about me?", answer plainly:
+
+> "It's in your local Kodelyth Memory at `~/.kodelyth/memory/`. You can inspect it, edit it, or delete it any time. Nothing was sent anywhere."