kodelyth-ecc 1.5.2 → 1.5.4

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

@@ -14,32 +14,52 @@ If multiple agents match, pick the **highest priority** below (priority decrease
 
 ---
 
+## How to Apply This Rule — Semantic Intent, Not Keyword Matching
+
+**Read the intent behind the words, not just the words.**
+
+- If someone says "this thing is broken", they mean `debug-detective` even though they didn't say "bug"
+- If someone says "help me make a todo app", they mean `/project-launch` even though they didn't say "project-launch"
+- If someone pastes a block of code with no context, treat it as a review request → `code-reviewer`
+- If someone pastes a stack trace or error log with no context, treat it as a debug request → `debug-detective`
+- If the user's message expresses **emotion** (frustration, excitement, confusion, worry), that is a routing signal
+
+**The signal tables are examples, not exhaustive lists.** Use them to understand the category of intent, then reason freely about whether the current message fits.
+
+**When in doubt between two agents:** name both options in one line and ask "Which fits your situation better?" — do not silently pick one.
+
+---
+
 ## 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 |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Stuck / lost | "I'm stuck", "I'm lost", "I have no idea", "I don't know where to start", "no clue what to do" |
+| Overwhelmed | "this is too much", "I'm overwhelmed", "where do I even begin", "there's so much to think about" |
+| Asking for direction | "what should I do", "help me figure out", "should I X or Y", "I'm not sure which way to go" |
+| Confused about the codebase | "I don't understand this code", "how does this even work", "what is all this doing" |
+| First-time on a problem | "first time doing X", "never done this before", "is there a right way", "I'm new to this" |
+| Seeking reassurance | "am I doing this right?", "is this approach okay?", "what would you do here?" |
+| General help request | "can someone help me with this?", "any advice?", "I need guidance" |
 
-**Counter-signals (do NOT route here):** specific technical question, error message, or named file/function.
+**Counter-signals (do NOT route here):** specific error message, stack trace, named file/function, or a direct technical question with a clear answer.
 
 ### `pair-programmer` — User is about to write code
 
 Trigger if the user describes **what they're about to build** before they start.
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Pre-implementation | "I want to build", "I'm going to add", "let's create", "I need to make a", "let me add", "I'm starting to work on" |
+| Approach question | "how should I implement", "what's the best way to", "should I use X pattern", "which approach is better" |
+| Architecture sketch | "I'm thinking of doing X then Y", "my plan is to", "I was thinking maybe" |
+| Pre-flight check | "before I start", "thinking about", "planning to", "about to write" |
+| Asking how | "how do I build", "how would you do", "what's the pattern for", "is there a standard way" |
+| Single feature | User describes adding ONE feature or function to an existing codebase |
 
 ---
 
@@ -47,31 +67,35 @@ Trigger if the user describes **what they're about to build** before they start.
 
 ### `debug-detective` — Bug, error, unexpected behavior
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Direct bug report | "bug", "broken", "crashed", "exception", "stack trace", "traceback", "error" |
+| Frustration | "I've been trying for hours", "can't figure out why", "this won't work", "driving me crazy", "nothing works", "I'm losing my mind" |
+| Unexpected behavior | "why is this X", "shouldn't this Y", "not what I expected", "acting weird", "behaving strangely" |
+| Something is wrong | "something's wrong", "it's broken again", "stopped working", "used to work and now doesn't" |
+| Specific error keywords | `TypeError`, `NullPointerException`, `panic`, `segfault`, `undefined`, `cannot read property`, `500 error`, `404` |
+| Test failures | "test fails", "expected X got Y", "assertion failed", "tests are red", "CI is failing" |
+| Implicit (code paste) | User pastes a stack trace, error log, or failing test output with no other context |
 
 **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 |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Mismatch without error | "no error but wrong result", "data is wrong", "looks fine but isn't working", "getting the wrong output" |
+| Silent state corruption | "X happened but Y didn't fire", "the value is off", "race condition", "something is off" |
+| Swallowed exceptions | "try/catch", "fallback", "default value", "it just returns null", "it silently fails" |
+| Puzzling behavior | "it's doing something unexpected", "the numbers don't add up", "data seems off", "I'm confused by the output" |
 
 ### `build-error-resolver` — Build / compile / type errors
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Build failed | "build failed", "compile error", "won't compile", "cargo build", "npm run build", "build is red", "failing to build" |
+| Type errors | "type error", "TS2322", "type mismatch", "cannot assign", "incompatible types", "TypeScript is yelling at me" |
+| Module/import | "module not found", "cannot resolve", "import error", "can't find the module" |
+| Deploy errors | "Vercel build failed", "Railway is erroring", "can't deploy", "deployment is broken" |
 
 **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`.
 
@@ -81,11 +105,16 @@ Trigger if the user describes **what they're about to build** before they start.
 
 ### `code-reviewer` — User wants feedback on existing code
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Direct review request | "review this", "code review", "LGTM?", "thoughts?", "feedback", "take a look at this", "eyes on this" |
+| Quality check | "is this good", "is this clean", "anything wrong", "what do you think of this code", "can you check this" |
+| Refactor opportunity | "is there a better way", "smell test", "looks ugly", "feels messy", "is this readable" |
+| Implicit (code paste) | User pastes code with minimal text — treat as a review request |
+| Sanity check | "does this make sense?", "is this the right approach?", "would you write it differently?" |
+| Before merge | "about to merge this", "is this PR-ready?", "pre-merge check" |
+
+**Key rule:** Single-file or single-function review → language reviewer. Full project or multiple files → `/team-review`.
 
 **Language-specific routing (if file extension or language is mentioned):**
 
@@ -105,30 +134,32 @@ Trigger if the user describes **what they're about to build** before they start.
 
 ### `security-reviewer` — Security concern
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Direct security question | "is this secure", "vulnerability", "CVE", "audit", "any security issues", "is this safe" |
+| Common attacks | "SQL injection", "XSS", "CSRF", "SSRF", "auth bypass", "RCE", "path traversal", "injection" |
+| Auth & secrets | "auth flow", "JWT", "session", "API key in code", "leaked secret", "exposed credential", "token in code" |
+| Crypto | "encryption", "hashing passwords", "salt", "AES", "RSA", "how to store passwords" |
+| Input handling | "user input", "sanitize", "escape", "validation", "user-submitted data" |
+| Worry signal | "I'm worried this might be insecure", "is there a risk here", "could someone exploit this" |
 
 ### `api-guardian` — API contract changes
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| API change | "breaking change", "deprecate", "API version", "backwards compat", "changing the endpoint" |
+| Contract concern | "consumer impact", "client breakage", "field removal", "rename endpoint", "will this break clients" |
+| Spec work | "OpenAPI", "GraphQL schema", "REST design", "idempotent", "API design review" |
 
 ### `ux-reviewer` — Frontend / UX / Accessibility
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| UI feedback | "feels off", "looks weird", "UX", "user experience", "interaction", "the UI is confusing" |
+| Accessibility | "a11y", "WCAG", "screen reader", "ARIA", "keyboard nav", "color contrast", "accessible" |
+| Form / interaction | "form validation", "loading state", "error state", "empty state", "the form feels clunky" |
+| Mobile / responsive | "mobile", "responsive", "viewport", "touch target", "doesn't look right on phone" |
+| Usability | "users are confused by", "hard to use", "the flow is broken", "nobody can find the button" |
 
 ---
 
@@ -138,36 +169,37 @@ Trigger if the user describes **what they're about to build** before they start.
 
 Route here FIRST for any active production incident. This takes priority over `debug-detective` when the incident is live in production.
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Production down | "production is down", "outage", "site is down", "service unavailable" |
-| P0 / P1 | "P0", "P1", "incident", "on-call", "pagerduty fired", "alert triggered" |
-| Blast radius | "10% of users affected", "all requests failing", "error rate spiked" |
-| Active degradation | "production is throwing 500s", "latency is through the roof", "database is down" |
-| Postmortem | "postmortem", "incident review", "blameless review", "what went wrong" |
+| Production down | "production is down", "outage", "site is down", "service unavailable", "prod is broken" |
+| P0 / P1 | "P0", "P1", "incident", "on-call", "pagerduty fired", "alert triggered", "woke up to alerts" |
+| Blast radius | "10% of users affected", "all requests failing", "error rate spiked", "users can't login" |
+| Active degradation | "production is throwing 500s", "latency is through the roof", "database is down", "everything is slow in prod" |
+| Postmortem | "postmortem", "incident review", "blameless review", "what went wrong", "write up the incident" |
 
 **Counter-signals:** development bug (not production), staging environment, local testing — route to `debug-detective` instead.
 
 ### `load-tester` — Load, stress, and capacity testing
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Load test request | "load test", "stress test", "performance test", "capacity test" |
+| Load test request | "load test", "stress test", "performance test", "capacity test", "can it handle X users" |
 | Tools | "k6", "Locust", "Artillery", "wrk", "Gatling", "hey", "ab test" |
-| Capacity planning | "how many users can we handle", "what's our breaking point", "max RPS" |
-| Pre-launch validation | "will this hold under load", "ready for launch traffic", "scale test" |
-| Soak test | "soak test", "memory leak under load", "sustained load test" |
+| Capacity planning | "how many users can we handle", "what's our breaking point", "max RPS", "will it scale" |
+| Pre-launch validation | "will this hold under load", "ready for launch traffic", "scale test", "launch is tomorrow" |
+| Soak test | "soak test", "memory leak under load", "sustained load test", "long-running load" |
 
 **Counter-signal:** "make this code faster" → `performance-optimizer`. Load-tester handles test design, not code optimization.
 
 ### `performance-optimizer` — Slowness / bottleneck in code
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Slow | "slow", "sluggish", "laggy", "takes forever", "timing out", "too slow", "feels sluggish" |
+| Resource | "high CPU", "memory leak", "OOM", "out of memory", "cpu pinned", "memory keeps growing" |
+| Frontend perf | "FCP", "LCP", "INP", "bundle size", "render time", "jank", "the page loads slowly" |
+| Backend perf | "N+1", "slow query", "throughput", "latency", "p99", "the API is slow" |
+| Optimization request | "make this faster", "optimize this", "reduce the load time", "improve performance" |
 
 ---
 
@@ -175,29 +207,36 @@ Route here FIRST for any active production incident. This takes priority over `d
 
 ### `planner` — Feature planning
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Plan a feature | "plan this", "roadmap", "break down", "sprint plan", "milestones" |
-| Decompose | "where do I start with X feature", "tasks for", "work items" |
+| Plan a feature | "plan this", "roadmap", "break down", "sprint plan", "milestones", "break this into tasks" |
+| Decompose | "where do I start with X feature", "tasks for", "work items", "list the steps for" |
+| Scope definition | "what do we need to build for X", "what's involved in adding X" |
 
 ### `architect` — System design
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| System-level | "architecture", "system design", "how should the services interact", "what's the overall design" |
+| Choosing tech | "should I use Postgres or Mongo", "monorepo vs polyrepo", "REST vs GraphQL", "which database" |
+| Scaling | "horizontal scaling", "sharding", "queue", "event-driven", "how do I scale this" |
+| Design decision | "what's the right architecture for X", "how should I structure this", "where should this live" |
 
 ### `code-architect` — Single-feature blueprint
 
 Trigger when the user wants a **detailed implementation blueprint for one specific feature**, not the whole system.
 
+| Signal | Real human phrasing |
+|---|---|
+| Feature blueprint | "how do I implement X", "give me a blueprint for X", "design the X feature", "how should X work technically" |
+
 ### `migration-guide` — Framework / language version upgrade
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
 | 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" |
+| Major version | "major version bump", "breaking deps", "node 18 → 22", "TS 4 → 5", "moving to the new version" |
+| Deprecation | "this is deprecated", "the old way is removed", "I need to update away from X" |
 
 ---
 
@@ -205,24 +244,25 @@ Trigger when the user wants a **detailed implementation blueprint for one specif
 
 ### `tdd-guide` — Tests, coverage, TDD
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Write tests | "write a test", "unit test", "integration test", "test for this", "I need tests for" |
+| TDD | "TDD", "test driven", "red green refactor", "write the test first" |
+| Coverage | "coverage", "what's not tested", "coverage gap", "my coverage is low", "what am I missing in tests" |
+| No tests yet | "I haven't written any tests", "there are no tests", "need to add tests" |
 
 ### `e2e-runner` — End-to-end Playwright tests
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| E2E | "Playwright", "end-to-end", "E2E", "browser test", "user flow test" |
-| Critical path | "checkout flow", "signup flow", "happy path test" |
+| E2E | "Playwright", "end-to-end", "E2E", "browser test", "user flow test", "test the whole flow" |
+| Critical path | "checkout flow", "signup flow", "happy path test", "test the full user journey" |
 
 ### `pr-test-analyzer` — Test coverage on PRs
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| PR | "review my PR tests", "did I cover everything", "PR test gaps" |
+| PR | "review my PR tests", "did I cover everything", "PR test gaps", "is my PR well tested" |
 
 ---
 
@@ -230,24 +270,25 @@ Trigger when the user wants a **detailed implementation blueprint for one specif
 
 ### `refactor-cleaner` — Dead code, cleanup
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Cleanup | "clean up", "dead code", "unused", "remove old", "tech debt" |
-| Duplicate | "duplicate", "DRY", "extract function" |
+| Cleanup | "clean up", "dead code", "unused", "remove old", "tech debt", "time to clean this up" |
+| Duplicate | "duplicate", "DRY", "extract function", "this is copy-pasted everywhere" |
+| Cruft | "old stuff hanging around", "deprecated code we never removed", "vestigial code" |
 
 ### `code-simplifier` — Reduce complexity
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Simplify | "simpler", "too complex", "hard to read", "convoluted" |
-| Readability | "easier to follow", "more readable" |
+| Simplify | "simpler", "too complex", "hard to read", "convoluted", "this is too complicated" |
+| Readability | "easier to follow", "more readable", "nobody can understand this", "even I can't read it" |
 
 ### `type-design-analyzer` — Type system improvements
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
 | Type design | "better types", "stricter types", "type safety", "discriminated union", "generics" |
-| `any` cleanup | "remove any", "stricter typing", "narrow type" |
+| `any` cleanup | "remove any", "stricter typing", "narrow type", "too many anys", "weaken the types" |
 
 ---
 
@@ -255,23 +296,25 @@ Trigger when the user wants a **detailed implementation blueprint for one specif
 
 ### `doc-updater` — Update docs/README
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Docs | "update README", "document this", "add docs", "JSDoc", "docstring" |
-| Onboarding | "explain how this works", "doc for new devs" |
+| Docs | "update README", "document this", "add docs", "JSDoc", "docstring", "write the docs for" |
+| Onboarding | "explain how this works", "doc for new devs", "I need to document this for my team" |
+| Missing docs | "nobody knows how this works", "there are no docs", "write documentation" |
 
 ### `docs-lookup` — Library / framework API question
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| 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" |
+| Library API | "how do I use X library", "what's the signature", "API for X", "how does X work" |
+| Framework feature | "Next.js App Router", "React Suspense", "Django ORM", "Rails 7", "how does X handle Y" |
+| Usage question | "what's the syntax for", "what parameters does X take", "how do I call" |
 
 ### `comment-analyzer` — Comment quality
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Comments | "are my comments good", "comment hygiene", "explain why not what" |
+| Comments | "are my comments good", "comment hygiene", "explain why not what", "are these comments useful" |
 
 ---
 
@@ -281,17 +324,22 @@ Trigger when the user wants a **detailed implementation blueprint for one specif
 
 Trigger for non-code workflow tasks: drafting emails, scheduling, status updates, multi-channel coordination.
 
+| Signal | Real human phrasing |
+|---|---|
+| Communication | "draft an email", "write a message", "reply to this", "how should I say this", "slack message" |
+| Status | "status update", "what do I tell the team", "write the incident update" |
+
 ### `seo-specialist` — SEO / metadata / search
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| SEO | "SEO", "meta tags", "schema.org", "structured data", "Core Web Vitals", "sitemap" |
+| SEO | "SEO", "meta tags", "schema.org", "structured data", "Core Web Vitals", "sitemap", "my page doesn't rank", "Google isn't indexing" |
 
 ### `opensource-forker` + `opensource-sanitizer` + `opensource-packager` — Open-sourcing a project
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| OSS prep | "open source this", "make this public", "publish to GitHub", "strip secrets", "remove credentials" |
+| OSS prep | "open source this", "make this public", "publish to GitHub", "strip secrets", "remove credentials", "I want to release this as open source" |
 
 Use the chain: `forker` → `sanitizer` → `packager`.
 
@@ -313,66 +361,99 @@ Use the chain: `forker` → `sanitizer` → `packager`.
 | `load-tester` (bottleneck found) | `performance-optimizer` to fix the code |
 | `incident-commander` (incident resolved) | `debug-detective` for deeper root cause, then postmortem |
 
+---
+
 ### `image-architect` — Image and visual generation
 
-Trigger if the user wants any visual asset generated:
+Trigger on ANY request for a visual, image, picture, graphic, or design asset. Cast wide — users rarely say "generate"; they say "I need" or "add" or "make it look nice".
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Hero / banner | "generate a hero image", "I need a banner", "create a header image" |
-| Social / OG | "OG image", "social preview", "GitHub card", "Twitter card", "Facebook post image" |
-| Thumbnails | "product thumbnail", "feature image", "cover image" |
-| Landing page | "visuals for landing page", "marketing images", "I need graphics" |
-| General | "generate an image", "create artwork", "I need a picture", "make a visual" |
+| Explicit request | "generate an image", "create a picture", "make a visual", "I need graphics", "make an illustration" |
+| Hero / banner | "hero image", "header image", "banner", "background image for my site", "the top image" |
+| Social assets | "OG image", "social preview", "GitHub card", "Twitter card", "Facebook image", "LinkedIn banner", "thumbnail for my post", "share image" |
+| Landing page | "images for my landing page", "visuals for the site", "add some images to my app", "make the landing page look good" |
+| Marketing | "marketing images", "product screenshots", "cover image", "feature image", "promotional graphic" |
+| Design ask | "design a logo", "create artwork", "make it look good", "I need something for the homepage", "make it more visual", "give it some flair" |
+| Implicit visual need | "my site looks plain", "the site looks boring", "it looks empty", "it needs something visual", "it's too plain", "the page looks bare" |
+| App branding | "app icon", "brand image", "I need a visual identity", "something that looks professional" |
 
 Platform routing inside `image-architect`:
 - Google Antigravity → Gemini Imagen 3 (native, no key needed)
 - Codex CLI → DALL-E 3 (native, no key needed)
 - Claude Code → fal.ai MCP → SVG fallback
 - Windsurf / Cursor → native model image gen → fal.ai → SVG fallback
+- Any platform → SVG (always available, always free)
+
+---
 
 ### `/project-launch` — New project parallel founding team
 
-Trigger when starting something new and needing full team analysis at once:
+Trigger when someone is starting something new — ANY new build, app, service, or feature of meaningful scope. Do not wait for the user to say "launch" or "project-launch". If they are clearly at the start of building something non-trivial, this is always the right move.
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| New project | "I'm starting a new project", "planning a new app", "building from scratch" |
-| Pre-code analysis | "analyse this before I start coding", "what should I think about first" |
-| Multiple concerns at once | Architecture + security + UX + tests all in one ask |
+| New build | "help me build X", "I want to build X", "I'm building X", "I want to create X", "let's make X" |
+| Greenfield | "starting from scratch", "new project", "new app", "new service", "new API", "I'm starting a new" |
+| Idea phase | "I have this idea", "I want to create", "I'm thinking of building", "I want to make a" |
+| Planning start | "where do I start", "how should I approach building X", "what do I need to build X" |
+| Product description | User describes a product they haven't started yet — what it does, who uses it |
+| New SaaS / startup | "I'm building a SaaS", "side project", "startup idea", "I want to launch" |
+| Multi-component new thing | "an app that does X, Y, and Z" — multiple features described together |
+
+**Key rule:** If the user describes a non-trivial new thing to build (more than a single function), default to `/project-launch`. Five expert agents analyzing simultaneously catches mistakes before they cost hours of rework. Always better to over-plan than under-plan.
 
-Route to `/project-launch` — fires `architect` + `pair-programmer` + `security-reviewer` + `tdd-guide` + `ux-reviewer` simultaneously.
+**Counter-signals (do NOT route here):** User is adding one feature to an existing codebase → `pair-programmer`. User is describing an existing project to fix a bug → `debug-detective`.
+
+Route to `/project-launch` — fires `architect` + `pair-programmer` + `security-reviewer` + `tdd-guide` + `ux-reviewer` simultaneously. Parallel analysis: 10 min instead of 45 min.
+
+---
 
 ### `/team-review` — Existing project parallel full audit
 
-Trigger when the user wants comprehensive review of existing code:
+Trigger when someone wants their existing code reviewed and the scope is broad (more than one file), or when they're asking "is this ready?". Also trigger before any deployment, release, or launch of an existing project.
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Full audit | "full audit of my codebase", "review everything", "complete code review" |
-| Pre-release | "before I ship", "is this ready to release", "pre-launch review" |
-| Parallel review | "check security AND performance AND code quality at once" |
+| Review request (broad) | "review my code", "review my project", "check my codebase", "look at my code", "audit my code" |
+| Full audit | "audit everything", "full review", "review everything", "check the whole project", "go through my code" |
+| Pre-release | "before I ship", "ready to release?", "can I deploy this?", "pre-launch check", "about to go live" |
+| Quality check | "is my code good?", "what's wrong with my project?", "code quality check", "is this production-ready?" |
+| Multiple concerns | User mentions security AND performance AND quality — parallel review is the right answer |
+| Readiness check | "is this ready?", "should I launch?", "any issues before I ship?", "what am I missing?" |
 
-Route to `/team-review` — fires `code-reviewer` + `security-reviewer` + `performance-optimizer` + `api-guardian` simultaneously.
+**Key rule:** Single-file review → language-specific reviewer (e.g., `typescript-reviewer`). Full project or multi-file → `/team-review`. When in doubt about scope, ask.
+
+Route to `/team-review` — fires `code-reviewer` + `security-reviewer` + `performance-optimizer` + `api-guardian` simultaneously. Parallel review: 15 min instead of 60 min.
+
+---
 
 ### `/lessons` — Project lessons management
 
-Trigger when the user wants to work with project-level learned rules:
+Trigger when the user references project rules, preferences, corrections, or past instructions. Also trigger proactively at session start if `tasks/lessons.md` exists in the project root.
 
-| Signal | Examples |
+| Signal | Real human phrasing |
 |---|---|
-| Load lessons | "load my lessons", "what rules do we have for this project", "apply lessons" |
-| Save corrections | "save what I corrected", "encode today's corrections", "write to lessons" |
-| Add a rule | "remember we always use pnpm", "add a rule: never use var" |
+| Load rules | "load my lessons", "what rules do we have", "what do you know about this project", "show me the rules" |
+| Remember something | "remember that we use pnpm", "remember I always want X", "don't forget Y", "note that we do X" |
+| Preference | "I prefer X", "we always do X here", "never do Y in this project", "always use X not Y" |
+| Save corrections | "save what I told you today", "write that down", "remember this for next time", "add this to the rules" |
+| Habit encode | "from now on always X", "make it a rule that", "I want you to always" |
+| Session start trigger | If `tasks/lessons.md` exists in the project root — proactively offer: "Found project lessons. Load them now?" |
+
+---
 
 ### Parallel suggestions
 
-If the user has a multi-faceted concern, name the parallel agents:
+When the user's request spans multiple concerns, name the parallel agents and explain the time saving rather than picking just one:
+
 - "I'm building a payment endpoint" → `pair-programmer` + `security-reviewer` + `api-guardian`
 - "Refactoring the auth module" → `refactor-cleaner` + `security-reviewer` + `tdd-guide`
-- "Starting a new project" → `/project-launch`
-- "Is this ready to ship?" → `/team-review`
-- "I need visuals for my landing page" → `image-architect`
+- "help me build a SaaS app" → `/project-launch` (5 agents, 10 min vs 45 min)
+- "review my project before I deploy" → `/team-review` (4 agents, 15 min vs 60 min)
+- "my site needs visuals" → `image-architect`
+- "new feature that touches the API" → `pair-programmer` + `api-guardian` + `security-reviewer`
+- "big refactor of core module" → `architect` + `refactor-cleaner` + `tdd-guide`
 
 ---
 
@@ -382,9 +463,10 @@ If the user has a multi-faceted concern, name the parallel agents:
 
 - 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 message is **purely conversational** ("hi", "thanks", "ok", "got it") — 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
+- The request is **trivially simple** (rename a variable, change one line, answer a "what is X?" question)
 
 ---
 
@@ -392,35 +474,45 @@ If the user has a multi-faceted concern, name the parallel agents:
 
 | 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 |
+| "I'm getting a TypeError on line 42" | `debug-detective` | Specific error |
+| "something is wrong but there's no error" | `silent-failure-hunter` | Silent failure pattern |
+| "Should I use React Context or Zustand here?" | `pair-programmer` | Pre-implementation approach |
+| "Review my login component" | `typescript-reviewer` | Single file + likely TS |
+| "I have no idea where to start" | `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 |
+| "Tests are slow / red" | `tdd-guide` then `debug-detective` | 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 |
 | "production is down, getting 500s" | `incident-commander` | Active production incident |
-| "will this hold under 10k concurrent users" | `load-tester` | Capacity / load testing question |
-| "run a load test before launch" | `load-tester` | Pre-launch load validation |
+| "will this hold under 10k users?" | `load-tester` | Capacity question |
 | "postmortem for yesterday's outage" | `incident-commander` | Postmortem workflow |
-| "generate a hero image for my landing page" | `image-architect` | Image generation request |
-| "I need an OG image / GitHub social card" | `image-architect` | Social preview asset |
-| "create visuals for the app" | `image-architect` | Marketing asset generation |
-| "I'm starting a new SaaS project, help me plan it" | `/project-launch` | New project, all concerns at once |
-| "full audit before we ship v2" | `/team-review` | Pre-release parallel audit |
-| "load my project lessons" | `/lessons` | Cross-platform lesson loading |
+| "generate a hero image" | `image-architect` | Explicit image request |
+| "my site looks plain, needs something visual" | `image-architect` | Implicit visual need |
+| "make it look good / less empty" | `image-architect` | Visual quality signal |
+| "help me build a todo app" | `/project-launch` | New build — founding team |
+| "I want to create a REST API from scratch" | `/project-launch` | New build |
+| "I have this idea for a SaaS dashboard" | `/project-launch` | Greenfield project |
+| "I'm starting a new side project" | `/project-launch` | New project |
+| "can you review my code?" | `code-reviewer` or `/team-review` | Narrow → reviewer, broad → team |
+| "review my code before I deploy" | `/team-review` | Pre-release, full scope |
+| "is my project ready to ship?" | `/team-review` | Readiness check |
+| "full audit before we release v2" | `/team-review` | Explicit full audit |
+| "remember we always use pnpm here" | `/lessons` | Preference to encode |
+| "what rules do we follow in this project?" | `/lessons` | Load lessons |
+| "from now on never use var" | `/lessons` | Rule to save |
+| [user pastes code with no text] | `code-reviewer` | Implicit review |
+| [user pastes stack trace with no text] | `debug-detective` | Implicit debug |
 
 ---
 
 ## Output Format When Routing
 
 ```
-→ Routing to debug-detective (your error message + frustration matches the bug-tracking signal)
+→ Routing to debug-detective (stack trace + frustration signals match the bug-tracking pattern)
 
 [response in debug-detective's style — methodical, hypothesis-driven, asks for repro]