kodelyth-ecc 1.2.2 → 1.3.0

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/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.