@booklib/core 2.0.0

package/skills/skill-router/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: skill-router
+version: "1.0"
+license: MIT
+tags: [meta, routing, agent-skills]
+description: >
+  Select the 1-2 most relevant @booklib/skills for a given file, PR, or task.
+  Use before applying any skill when unsure which book's lens applies, or when
+  multiple skills could apply. Trigger on "which skill", "which book", "route this",
+  "what skill should I use", or whenever a user describes a task without specifying
+  a skill. Returns a ranked recommendation with rationale and anti-triggers.
+---
+
+# Skill Router
+
+You are a skill selector for the `@booklib/skills` library — a collection of book-based and community AI skills covering code quality, architecture, language best practices, design, product management, writing, legal, and business strategy. Your job is to identify the **1-2 most relevant skills** for a given task or file and explain why, so the user can immediately apply the right expertise.
+
+## When You're Triggered
+
+- User says "which skill should I use for..."
+- User says "route this to the right skill"
+- User describes a task without naming a skill
+- User asks "what book applies here?"
+- Multiple skills seem to apply and you need to rank them
+
+---
+
+## Routing Process
+
+### Step 0 — Establish Input Scope
+
+Before routing, pin what you're actually reviewing:
+
+1. **Prefer `git diff` as default scope.** If the user asks to review code without specifying files, default to the current diff — not the entire codebase. Routing a skill against 10,000 lines of unchanged code wastes context and dilutes findings.
+2. **Check for a CLAUDE.md.** If one exists, read it before routing. Project conventions (language standards, test requirements, banned patterns) affect which skill is most relevant and what the selected skill should prioritize.
+3. **Identify the specific files or scope** from the user's message. If genuinely ambiguous, ask before routing.
+
+### Step 1 — Classify the Work Type
+
+Identify what the user is trying to do:
+
+| Work Type | Description | Example |
+|-----------|-------------|---------|
+| **review** | Evaluate existing code for quality, patterns, or correctness | "Review my Python class" |
+| **generate** | Create new code following a book's patterns | "Generate a saga for order processing" |
+| **migrate** | Incrementally improve legacy code toward a better architecture | "Help me ratchet this legacy codebase toward clean code" |
+| **design** | Make architectural or system-level decisions | "How should I decompose this monolith?" |
+| **learn** | Understand a concept or pattern | "What is the Strangler Fig pattern?" |
+| **visualize** | Create or critique data visualizations or UI | "Review my chart / UI component" |
+| **document** | Review or draft contracts, specs, briefs, policies | "Review this contract" |
+| **plan** | Product or business strategy decisions | "How should we prioritize this?" |
+
+### Step 2 — Identify Language + Domain
+
+From the file extension, imports, description, or code provided:
+
+- **Language signals:** `.py` → Python skills; `.java` → `effective-java` or `clean-code-reviewer`; `.kt` → `effective-kotlin` or `kotlin-in-action`; `.ts`/`.tsx` → `effective-typescript`; `.rs` → `programming-with-rust`; `.js` → `clean-code-reviewer` or `design-patterns`
+- **Domain signals:** "microservice", "saga" → microservices-patterns; "bounded context", "aggregate" → domain-driven-design; "chart", "visualization" → storytelling-with-data; "UI", "layout", "typography" → refactoring-ui; "web scraping", "BeautifulSoup" → web-scraping-python; "asyncio", "coroutine" → using-asyncio-python; "data pipeline", "ETL" → data-pipelines; "replication", "partitioning", "database internals" → data-intensive-patterns
+- **Architecture signals:** "monolith decomposition", "distributed systems" → microservices-patterns or system-design-interview
+- **Product/PM signals:** "PRD", "product requirements", "user story", "acceptance criteria", "roadmap", "prioritization", "OKR", "jobs to be done", "JTBD" → `writing-plans` or `product-lens`
+- **Legal/contracts signals:** "contract", "clause", "NDA", "SLA", "indemnification", "IP assignment", "terms of service", "liability" → `writing-plans` (for structure) or a specialist legal community skill
+- **Writing/content signals:** "blog post", "copy", "content brief", "editorial", "tone of voice", "article", "draft", "long-form" → `writing-skills` or `article-writing`
+- **Strategy signals:** "competitive analysis", "market positioning", "go-to-market", "GTM", "SWOT", "business model", "strategic plan" → `lean-startup` (startup) or `strategic-compact` (corporate)
+- **Design/brand signals:** "brand identity", "logo", "color palette", "design system", "style guide", "visual language" → `brand-guidelines`
+
+Read `references/skill-catalog.md` for the full list of all 17 skills with their trigger keywords and anti-triggers.
+
+### Step 3 — Match to Skill(s)
+
+Apply these primary routing rules:
+
+1. **Code quality review (any language)** → `clean-code-reviewer`
+2. **Java best practices** → `effective-java`
+3. **Kotlin best practices** → `effective-kotlin` or `kotlin-in-action` (see conflict rules)
+4. **Python best practices** → `effective-python`
+5. **Python asyncio/concurrency** → `using-asyncio-python` (overrides effective-python for async topics)
+6. **Python web scraping** → `web-scraping-python`
+7. **TypeScript best practices, type design, any, migration** → `effective-typescript`
+8. **Rust, ownership, borrowing, lifetimes, traits, concurrency** → `programming-with-rust`
+9. **OO design patterns (GoF)** → `design-patterns`
+10. **Domain modeling, DDD** → `domain-driven-design`
+11. **Microservices, sagas, decomposition** → `microservices-patterns`
+12. **System scalability, estimation** → `system-design-interview`
+13. **Data storage internals, replication** → `data-intensive-patterns`
+14. **Data pipelines, ETL** → `data-pipelines`
+15. **UI design, visual hierarchy** → `refactoring-ui`
+16. **Charts, data visualization** → `storytelling-with-data`
+17. **Web animation** → `animation-at-work`
+18. **Startup strategy, MVP** → `lean-startup`
+19. **Routing help** → `skill-router` (this skill)
+20. **Product requirements, user stories, roadmaps** → `writing-plans` or `product-lens`
+21. **Business writing, copy, articles** → `writing-skills` or `article-writing`
+22. **Business or corporate strategy** → `lean-startup` (startup/product) or `strategic-compact` (corporate)
+23. **Brand identity, design systems** → `brand-guidelines`
+24. **Web design, layout, typography** → `web-design-guidelines` or `refactoring-ui` (if UI components)
+
+Read `references/routing-heuristics.md` for detailed decision rules and conflict resolution.
+
+### Step 4 — Check for Conflicts
+
+Some skill pairs can conflict. Resolve using these rules:
+
+| Conflict | Resolution |
+|----------|------------|
+| `effective-typescript` vs `clean-code-reviewer` | Use `effective-typescript` for TypeScript-specific concerns (type system, any, type design); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
+| `clean-code-reviewer` vs `effective-java` | Use `effective-java` for Java-specific idioms (generics, enums, builders); use `clean-code-reviewer` for naming/functions/readability which applies cross-language |
+| `effective-kotlin` vs `kotlin-in-action` | `effective-kotlin` for best practices and pitfall avoidance; `kotlin-in-action` for learning Kotlin language features |
+| `domain-driven-design` vs `microservices-patterns` | `domain-driven-design` for domain model design; `microservices-patterns` for service decomposition and inter-service communication. Apply both if designing a new microservice with rich domain model |
+| `clean-code-reviewer` vs `domain-driven-design` | Clean Code says "small functions"; DDD encourages "rich domain models." Clean Code wins for code-level review; DDD wins for model design |
+| `data-intensive-patterns` vs `system-design-interview` | `data-intensive-patterns` for storage engine internals, replication, and consistency; `system-design-interview` for scalability estimates and high-level architecture |
+| `effective-python` vs `using-asyncio-python` | `using-asyncio-python` wins for any async/concurrent Python topic; `effective-python` for everything else |
+| `lean-startup` vs `writing-plans` | Use `lean-startup` for strategy and hypothesis validation; `writing-plans` for document structure and requirements writing |
+| `refactoring-ui` vs `brand-guidelines` | `refactoring-ui` for component/UI design decisions; `brand-guidelines` for logo, color palette, and brand identity |
+| `writing-skills` vs `article-writing` | `writing-skills` for general clarity and prose quality; `article-writing` for narrative structure and long-form pieces |
+
+### Step 5 — Return Recommendation
+
+Format your output as:
+
+```
+**Scope:** [files or git diff being reviewed]
+**Primary skill:** `skill-name`
+**Why:** [1-2 sentence rationale tying the task to the skill's domain]
+**Secondary (optional):** `skill-name` — [brief rationale] OR none
+**Don't apply:** `skill-name` — [why it would produce irrelevant feedback]
+```
+
+When instructing the selected skill(s), tell them to:
+- Classify each finding as **HIGH** (correctness/security/data loss), **MEDIUM** (design/maintainability), or **LOW** (style/naming)
+- Reference findings as `file.ext:line` — not just "line 42" or "the function"
+- Skip findings below the threshold for the work type: **review** → HIGH + MEDIUM; **migrate/design** → all tiers
+
+If you're genuinely uncertain between two equally applicable skills, say so and recommend applying both in sequence, primary first.
+
+---
+
+## Anti-Trigger Rules
+
+Do NOT route to a skill if:
+- The task is too simple for that skill's complexity (don't route a 5-line script to `domain-driven-design`)
+- The language doesn't match (don't route Python to `effective-java`)
+- The domain doesn't match (don't route UI code to `microservices-patterns`)
+- The user has already specified a skill (respect their choice; only offer alternatives if asked)
+
+---
+
+## Examples
+
+**Example 1 — Clear single-skill case:**
+```
+User: "Review my Python class for code quality"
+
+Scope: orders/service.py (specified file)
+Primary skill: clean-code-reviewer
+Why: Language-agnostic code quality review is exactly Clean Code's domain — naming, functions, comments, classes.
+Secondary: none
+Don't apply: effective-python — Python-specific idioms are not the concern here; effective-python would focus on list comprehensions and context managers, not the general code quality issues Clean Code addresses.
+
+→ Instruct clean-code-reviewer to classify findings as HIGH/MEDIUM/LOW and reference each as orders/service.py:line.
+```
+
+**Example 2 — Conflict case:**
+```
+User: "I'm building a new microservice for our e-commerce platform. Review the domain model."
+
+Scope: git diff (new files in src/domain/)
+Primary skill: domain-driven-design
+Why: The request is about domain model design — Aggregates, Value Objects, Bounded Contexts. DDD is the authoritative source.
+Secondary: microservices-patterns — apply after DDD review to check service boundaries, database ownership, and communication patterns.
+Don't apply: clean-code-reviewer — code quality review is premature at the design stage; apply later when implementation code exists.
+
+→ Instruct both skills to classify findings as HIGH/MEDIUM/LOW and reference each as file:line.
+```
+
+**Example 3 — Already routed (positive case):**
+```
+User: "Use the effective-java skill to review my builder pattern"
+
+Scope: user specified — confirm with them if files aren't clear
+Primary skill: effective-java (already specified by user — confirm and proceed)
+Why: User correctly identified the skill. effective-java Item 2 covers the Builder pattern directly.
+Secondary: none
+Don't apply: design-patterns — GoF Builder pattern is covered, but Effective Java's opinionated take on Java-specific Builder is more directly applicable.
+
+→ Instruct effective-java to classify findings as HIGH/MEDIUM/LOW and reference each as file:line.
+```

package/skills/skill-router/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-clear-single-skill",
+      "prompt": "Which skill should I use? I have this Python function and want to make it more Pythonic:\n\n```python\ndef get_items(items_list, filter_value, sort_by_name):\n    result = []\n    for item in items_list:\n        if item['category'] == filter_value:\n            result.append(item)\n    if sort_by_name:\n        result = sorted(result, key=lambda x: x['name'])\n    return result\n```",
+      "expectations": [
+        "Recommends effective-python as primary skill",
+        "Mentions that Pythonic idioms (list comprehensions, key functions, boolean flags) are effective-python's domain",
+        "Does NOT recommend clean-code-reviewer as primary (it's secondary at most)",
+        "Explains why (language-specific Pythonic advice vs general code quality)",
+        "Optionally mentions clean-code-reviewer as secondary for the flag argument (sort_by_name)"
+      ]
+    },
+    {
+      "id": "eval-02-conflict-case",
+      "prompt": "I'm designing a new service for our e-commerce platform. The service will handle order creation and needs to coordinate with the inventory and payment services. Here's a rough sketch:\n\n```python\nclass OrderService:\n    def create_order(self, customer_id, items):\n        # 1. Check inventory availability\n        # 2. Reserve inventory\n        # 3. Charge payment\n        # If payment fails, how do I release the reservation?\n        pass\n\n    def cancel_order(self, order_id):\n        # Need to reverse payment AND release inventory\n        # What if one fails?\n        pass\n```\n\nWhich skill should I use to design this coordination correctly?",
+      "expectations": [
+        "Identifies this as a design task, not a code review task",
+        "Recommends microservices-patterns as primary (service coordination, saga pattern)",
+        "Recommends domain-driven-design as secondary (order domain modeling)",
+        "Explains the distinction: microservices-patterns for inter-service coordination, DDD for domain model design",
+        "Does NOT recommend clean-code-reviewer (no code to review yet)",
+        "Does NOT recommend system-design-interview unless scale/estimation is mentioned"
+      ]
+    },
+    {
+      "id": "eval-03-already-routed",
+      "prompt": "Use the effective-java skill to review my enum usage:\n\n```java\npublic class OrderStatus {\n    public static final int PENDING = 0;\n    public static final int APPROVED = 1;\n    public static final int REJECTED = 2;\n    public static final int CANCELLED = 3;\n}\n```",
+      "expectations": [
+        "Confirms effective-java is the correct skill (already specified by user)",
+        "Does NOT override the user's skill choice",
+        "Optionally notes which Effective Java item applies (Item 34: Use enums instead of int constants)",
+        "May note clean-code-reviewer would also flag this (J3: Constants vs Enums) but defers to user's choice",
+        "Does not second-guess or add unnecessary routing complexity"
+      ]
+    }
+  ]
+}

package/skills/skill-router/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 0.938,
+  "passed": 15,
+  "total": 16,
+  "baseline_pass_rate": 0.688,
+  "baseline_passed": 11,
+  "baseline_total": 16,
+  "delta": 0.25,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-28",
+  "non_standard_provider": true
+}

package/skills/skill-router/examples/after.md

@@ -0,0 +1,63 @@
+# After: Routed Code Review Request
+
+## User Message (same as before)
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## Skill Router Output
+
+**Primary skill:** `clean-code-reviewer`
+**Why:** The user wants general code quality improvement for a Java class. The dominant issues are language-agnostic: poor naming (`o`, `isAdmin` flag arg, magic return codes), static mutable state, nested conditionals, and multiple responsibilities — all Clean Code's territory.
+**Secondary (optional):** `effective-java` — after the Clean Code review, apply Effective Java for Java-specific improvements: replace `Map<String, Object>` with a typed class (Item 64: refer to objects by their interfaces), use enums instead of int return codes (Item 34).
+**Don't apply:** `domain-driven-design` — while an Order is a domain concept, applying DDD here would produce advice about Aggregates and Bounded Contexts that is premature. Fix the code quality first.
+
+---
+
+## What the Clean Code Review Produces
+
+With the right skill applied, the review is sharp and specific:
+
+### Issues Found
+
+🔴 **Critical — F3: Flag Arguments**
+`isAdmin` and `sendEmail` are boolean flags — the function does 4 different things depending on their combination. Split into `approveAsAdmin()` and keep email logic separate.
+
+🔴 **Critical — Shared Mutable Static State (Ch. 13)**
+`pendingOrders` is a static mutable list — not thread-safe and makes the class impossible to test in isolation.
+
+🔴 **Critical — Error Codes Instead of Exceptions (Ch. 7)**
+Returning `-1` and `-2` forces callers to check magic numbers. Throw `InvalidOrderException` and `UnauthorizedOperationException` instead.
+
+🟡 **Important — N1: Poor Naming**
+`o`, `process` — names reveal nothing. `o` → `order`, `process` → `approveOrder`.
+
+🟡 **Important — G30: Function Does Multiple Things**
+`process()` validates, approves, removes from list, and sends email. Each is a separate responsibility.
+
+🟢 **Suggestion — G25: Magic Numbers**
+Return codes `-1`, `-2` should be named constants at minimum, or better: exceptions.
+
+### Result
+
+The user gets a **focused, actionable review** from one authoritative source — not a scattered survey of four books.

package/skills/skill-router/examples/before.md

@@ -0,0 +1,39 @@
+# Before: Unrouted Code Review Request
+
+## User Message
+
+> "Can you review my code? I want to make it better."
+>
+> ```java
+> public class OrderProcessor {
+>     private static List<Map<String, Object>> pendingOrders = new ArrayList<>();
+>     
+>     public static int process(Map<String, Object> o, boolean isAdmin, boolean sendEmail) {
+>         if (o == null) return -1;
+>         if (o.get("status").equals("pending")) {
+>             if (isAdmin) {
+>                 o.put("status", "approved");
+>                 pendingOrders.remove(o);
+>                 if (sendEmail) {
+>                     System.out.println("Sending email to: " + o.get("customerEmail"));
+>                 }
+>                 return 0;
+>             }
+>         }
+>         return -2;
+>     }
+> }
+> ```
+
+## What Happens Without Routing
+
+The AI must guess which lens to apply:
+
+- Does the user want **Java-specific** advice (Effective Java)? → Bloch would focus on generics, raw types, and static factory methods
+- Do they want **code quality** advice (Clean Code)? → Martin would focus on naming, flag arguments, static mutable state
+- Do they want **design pattern** advice (Design Patterns)? → Gang of Four would examine whether a Command or Strategy pattern fits
+- Do they want **domain modeling** advice (DDD)? → Evans would ask about Aggregates and Value Objects
+
+**Result:** The AI either picks one arbitrarily, tries to cover all four superficially, or asks a clarifying question that could have been avoided.
+
+The user gets a scattered review that's 40% relevant from four different books instead of a sharp, deep review from the right one.

package/skills/skill-router/references/api_reference.md

@@ -0,0 +1,24 @@
+# API Reference: Skill Quick-Lookup
+
+Quick-lookup table for all 17 skills.
+
+| Skill | Domain | Works Well With | Conflicts With |
+|-------|--------|-----------------|----------------|
+| `animation-at-work` | Web animation, motion | `refactoring-ui` | None |
+| `clean-code-reviewer` | Code quality (any language) | `effective-java`, `effective-python`, `effective-kotlin` | `domain-driven-design` (model design context) |
+| `data-intensive-patterns` | Storage internals, distributed data | `system-design-interview` | `system-design-interview` (different altitude) |
+| `data-pipelines` | ETL, data ingestion, orchestration | `data-intensive-patterns`, `effective-python` | `microservices-patterns` |
+| `design-patterns` | GoF OO patterns | `clean-code-reviewer`, `effective-java` | `domain-driven-design` |
+| `domain-driven-design` | Domain modeling, DDD patterns | `microservices-patterns`, `clean-code-reviewer` | `clean-code-reviewer` (code review context) |
+| `effective-java` | Java idioms and best practices | `clean-code-reviewer`, `design-patterns` | `clean-code-reviewer` (Java-specific vs general) |
+| `effective-kotlin` | Kotlin best practices | `kotlin-in-action`, `clean-code-reviewer` | `kotlin-in-action` |
+| `effective-python` | Python idioms and best practices | `clean-code-reviewer`, `using-asyncio-python` | `using-asyncio-python` (async topics) |
+| `kotlin-in-action` | Kotlin language features | `effective-kotlin` | `effective-kotlin` |
+| `lean-startup` | Startup strategy, MVP, pivots | None (strategy only) | All technical skills |
+| `microservices-patterns` | Service decomposition, sagas, CQRS | `domain-driven-design`, `system-design-interview` | `domain-driven-design` (service vs model) |
+| `refactoring-ui` | UI design, visual hierarchy | `animation-at-work` | None |
+| `skill-router` | Skill selection and routing | All skills | None |
+| `storytelling-with-data` | Data visualization, charts | `data-pipelines` | None |
+| `system-design-interview` | System scalability, high-level design | `microservices-patterns`, `data-intensive-patterns` | `data-intensive-patterns` (altitude) |
+| `using-asyncio-python` | Python asyncio, concurrency | `effective-python` | `effective-python` (async topics) |
+| `web-scraping-python` | Web scraping, crawling | `effective-python`, `data-pipelines` | None |

package/skills/skill-router/references/routing-heuristics.md

@@ -0,0 +1,89 @@
+# Routing Heuristics
+
+Decision rules for the skill-router. Apply these in order.
+
+## Primary Rules (apply first)
+
+### By Language
+
+| Language | Primary Skill | Override Condition |
+|----------|-------------|-------------------|
+| Python (general) | `effective-python` | If async → `using-asyncio-python`; if scraping → `web-scraping-python` |
+| Python (async/concurrent) | `using-asyncio-python` | Always wins over effective-python for async topics |
+| Python (web scraping) | `web-scraping-python` | Always wins for scraping topics |
+| Java | `effective-java` | If code quality focus → `clean-code-reviewer` |
+| Kotlin | `effective-kotlin` | If learning Kotlin → `kotlin-in-action` |
+| Any language (code quality) | `clean-code-reviewer` | Language-agnostic; always applicable for readability |
+| CSS/HTML/Frontend | `refactoring-ui` | If animation → `animation-at-work` |
+| Any (visualization) | `storytelling-with-data` | Must have a visual component |
+
+### By Domain
+
+| Domain | Primary Skill |
+|--------|-------------|
+| Domain modeling, DDD | `domain-driven-design` |
+| Service decomposition, distributed systems | `microservices-patterns` |
+| GoF design patterns | `design-patterns` |
+| System scalability, estimation | `system-design-interview` |
+| Storage internals, distributed data | `data-intensive-patterns` |
+| Data pipelines, ETL | `data-pipelines` |
+| Startup strategy, product | `lean-startup` |
+
+## Conflict Resolution Rules
+
+### clean-code-reviewer vs effective-java
+- **Code-level review with naming/readability focus** → `clean-code-reviewer`
+- **Java-specific items (generics, enums, serialization, lambdas)** → `effective-java`
+- **Both applicable** → primary: `clean-code-reviewer`, secondary: `effective-java`
+
+### effective-kotlin vs kotlin-in-action
+- **User knows Kotlin, wants best practice advice** → `effective-kotlin`
+- **User is learning Kotlin or asking about language features** → `kotlin-in-action`
+- **Ambiguous** → ask whether they want best practices or feature explanation
+
+### domain-driven-design vs microservices-patterns
+- **Designing or reviewing a domain model** → `domain-driven-design`
+- **Designing service decomposition, sagas, inter-service communication** → `microservices-patterns`
+- **Designing a new microservice with rich domain** → apply both: DDD first (model), microservices-patterns second (service design)
+
+### domain-driven-design vs clean-code-reviewer
+- **Model design** → `domain-driven-design` (ignore clean code's "small functions" rule when modeling)
+- **Code review** → `clean-code-reviewer` (DDD model concerns are separate from code readability)
+
+### data-intensive-patterns vs system-design-interview
+- **Internals: storage engines, replication, consistency models** → `data-intensive-patterns`
+- **High-level: system components, scale, estimation** → `system-design-interview`
+- **Full system design** → primary: `system-design-interview`, secondary: `data-intensive-patterns`
+
+### effective-python vs using-asyncio-python
+- **Any async/concurrent Python** → `using-asyncio-python` (always wins)
+- **Non-async Python** → `effective-python`
+
+## Work Type Rules
+
+| Work Type | Routing Preference |
+|-----------|-------------------|
+| Code review | Language-specific skill OR `clean-code-reviewer` |
+| Code generation | Domain-specific skill (DDD, microservices, design-patterns) |
+| Migration planning | Skill with Mode 3 (clean-code-reviewer, domain-driven-design, microservices-patterns) |
+| System design | `system-design-interview` + optional `microservices-patterns` |
+| Learning | Language-specific learning skill (kotlin-in-action) or domain skill |
+
+## Anti-Trigger Rules
+
+Never route to these skills if:
+
+| Skill | Don't route if... |
+|-------|------------------|
+| `domain-driven-design` | Simple CRUD, no complex domain, < 3 entity types |
+| `microservices-patterns` | Single service, no decomposition intent |
+| `lean-startup` | Pure technical code — this is a strategy skill only |
+| `effective-java` | Code is not Java |
+| `effective-kotlin` | Code is not Kotlin |
+| `effective-python` | Code is not Python |
+| `using-asyncio-python` | Code is not async Python |
+| `web-scraping-python` | Not web scraping |
+| `refactoring-ui` | No UI component |
+| `storytelling-with-data` | No visualization |
+| `animation-at-work` | No animation/motion concern |
+| `system-design-interview` | Code-level concern, not system-level |

package/skills/skill-router/references/skill-catalog.md

@@ -0,0 +1,174 @@
+# Skill Catalog
+
+All 19 skills in the `@booklib/skills` library with routing metadata.
+
+## animation-at-work
+- **Source:** *Animation at Work* by Rachel Nabors
+- **Domain:** Web animation, UI motion design
+- **Language:** CSS, JavaScript, any frontend
+- **Trigger keywords:** "animation", "motion", "transition", "keyframe", "easing", "12 principles of animation", "web animation", "CSS animation", "performance of animation"
+- **Anti-triggers:** Backend code, data processing, non-visual concerns
+- **Works well with:** refactoring-ui (visual design context)
+- **Conflicts with:** None (niche domain)
+
+## clean-code-reviewer
+- **Source:** *Clean Code* by Robert C. Martin
+- **Domain:** Code quality, readability, maintainability
+- **Language:** Language-agnostic (Java, Python, Kotlin, JavaScript examples used)
+- **Trigger keywords:** "review my code", "code quality", "readable", "clean up", "refactor", "naming", "functions", "comments", "smells"
+- **Anti-triggers:** Architecture design (too high-level), language-specific idioms (use language-specific skill instead)
+- **Works well with:** effective-java, effective-python, effective-kotlin (clean code first, then language idioms)
+- **Conflicts with:** domain-driven-design (Clean Code's "small functions" vs DDD's "rich models" — clean code wins for code review, DDD wins for model design)
+
+## data-intensive-patterns
+- **Source:** *Designing Data-Intensive Applications* by Martin Kleppmann
+- **Domain:** Storage engines, replication, partitioning, distributed systems, transactions, consistency
+- **Language:** Language-agnostic (systems-level)
+- **Trigger keywords:** "replication", "partitioning", "consistency", "CAP theorem", "event sourcing internals", "storage engine", "LSM tree", "B-tree", "distributed transactions", "ACID", "BASE", "linearizability"
+- **Anti-triggers:** Application-level code quality, UI, domain modeling
+- **Works well with:** system-design-interview (data layer + high-level architecture)
+- **Conflicts with:** system-design-interview (data-intensive-patterns is deeper/lower-level; use it for internals, system-design-interview for high-level)
+
+## data-pipelines
+- **Source:** *Data Pipelines Pocket Reference* by James Densmore
+- **Domain:** Data ingestion, ETL, streaming, pipeline orchestration
+- **Language:** Python, SQL, any data engineering stack
+- **Trigger keywords:** "data pipeline", "ETL", "ELT", "ingestion", "Airflow", "dbt", "Spark", "streaming pipeline", "batch processing", "data warehouse", "orchestration"
+- **Anti-triggers:** Application code unrelated to data movement, real-time microservices
+- **Works well with:** data-intensive-patterns (pipeline + storage), effective-python (Python data code)
+- **Conflicts with:** microservices-patterns (pipeline orchestration ≠ service decomposition)
+
+## design-patterns
+- **Source:** *Head First Design Patterns* by Freeman & Robson (GoF patterns)
+- **Domain:** Object-oriented design patterns (creational, structural, behavioral)
+- **Language:** Java primarily, but pattern-agnostic
+- **Trigger keywords:** "design pattern", "factory", "singleton", "observer", "strategy", "decorator", "facade", "command", "template method", "composite", "adapter", "proxy", "iterator", "state"
+- **Anti-triggers:** Functional programming (patterns don't apply the same way), microservices decomposition
+- **Works well with:** clean-code-reviewer (patterns + readability), effective-java (Java idioms + patterns)
+- **Conflicts with:** domain-driven-design (GoF patterns are structural; DDD patterns are domain-driven — use DDD for domain modeling, GoF for implementation structure)
+
+## domain-driven-design
+- **Source:** *Domain-Driven Design* by Eric Evans
+- **Domain:** Domain modeling, tactical patterns (Entities, Value Objects, Aggregates, Repositories), strategic patterns (Bounded Contexts, Context Maps, ACL)
+- **Language:** Language-agnostic (OO languages)
+- **Trigger keywords:** "DDD", "domain model", "aggregate", "value object", "bounded context", "ubiquitous language", "repository pattern", "domain service", "anticorruption layer", "entity", "anemic domain model", "primitive obsession"
+- **Anti-triggers:** Simple CRUD without domain complexity, microservices infrastructure concerns, code quality review
+- **Works well with:** microservices-patterns (domain model + service boundaries), clean-code-reviewer (model + code quality)
+- **Conflicts with:** clean-code-reviewer (rich models vs small functions — DDD wins for model design; clean code wins for code review)
+
+## effective-java
+- **Source:** *Effective Java* (3rd Edition) by Joshua Bloch
+- **Domain:** Java best practices and idioms
+- **Language:** Java only
+- **Trigger keywords:** "effective java", "java best practices", "generics", "enums", "lambdas", "streams", "builders", "serialization", "java concurrency", "checked exceptions", "java item"
+- **Anti-triggers:** Non-Java code, architecture concerns, domain modeling
+- **Works well with:** clean-code-reviewer (Java idioms + code quality), design-patterns (Java implementation of patterns)
+- **Conflicts with:** clean-code-reviewer (both review Java but from different angles — use effective-java for Java-specific items, clean-code-reviewer for general readability)
+
+## effective-kotlin
+- **Source:** *Effective Kotlin* (2nd Edition) by Marcin Moskała
+- **Domain:** Kotlin best practices, safety, readability
+- **Language:** Kotlin only
+- **Trigger keywords:** "effective kotlin", "kotlin best practices", "kotlin safety", "null safety", "extension functions best practices", "kotlin idioms", "kotlin item"
+- **Anti-triggers:** Non-Kotlin code, architecture concerns
+- **Works well with:** kotlin-in-action (best practices + language features), clean-code-reviewer (Kotlin idioms + readability)
+- **Conflicts with:** kotlin-in-action (effective-kotlin for best practices; kotlin-in-action for language learning — if user knows Kotlin and wants advice, use effective-kotlin)
+
+## effective-typescript
+- **Source:** *Effective TypeScript* by Dan Vanderkam
+- **Domain:** TypeScript best practices, type system, type design, any, migration
+- **Language:** TypeScript only
+- **Trigger keywords:** "effective typescript", "typescript best practices", "type safety", "any type", "type assertions", "type design", "strict mode", "typescript review", "migrate to typescript", "unknown vs any", "type declarations", "tagged union", "branded types", "typescript item"
+- **Anti-triggers:** Non-TypeScript code, plain JavaScript without types, architecture concerns
+- **Works well with:** clean-code-reviewer (TypeScript idioms + readability), design-patterns (type-safe pattern implementations)
+- **Conflicts with:** clean-code-reviewer (effective-typescript wins for TypeScript-specific type system concerns; clean-code-reviewer for general readability)
+
+## programming-with-rust
+- **Source:** *Programming with Rust* by Donis Marshall
+- **Domain:** Rust language, ownership, borrowing, lifetimes, error handling, traits, concurrency
+- **Language:** Rust only
+- **Trigger keywords:** "rust", "ownership", "borrow checker", "lifetimes", "Result", "Option", "traits", "fearless concurrency", "cargo", "crate", "unwrap", "move semantics", "Arc", "Mutex", "pattern matching rust", ".rs"
+- **Anti-triggers:** Non-Rust code, architecture concerns, domain modeling
+- **Works well with:** clean-code-reviewer (Rust idioms + readability), design-patterns (Rust implementation of patterns)
+- **Conflicts with:** clean-code-reviewer (programming-with-rust wins for Rust-specific concerns like ownership, lifetimes, and the borrow checker)
+
+## effective-python
+- **Source:** *Effective Python* (2nd Edition) by Brett Slatkin
+- **Domain:** Python best practices, Pythonic idioms
+- **Language:** Python only
+- **Trigger keywords:** "effective python", "pythonic", "python best practices", "python idioms", "comprehensions", "generators", "decorators", "metaclasses", "python item"
+- **Anti-triggers:** Non-Python code, async Python (use using-asyncio-python instead)
+- **Works well with:** clean-code-reviewer (Pythonic + readable), using-asyncio-python (general Python + async)
+- **Conflicts with:** using-asyncio-python (using-asyncio-python wins for async topics)
+
+## kotlin-in-action
+- **Source:** *Kotlin in Action* (2nd Edition)
+- **Domain:** Kotlin language features, learning Kotlin
+- **Language:** Kotlin only
+- **Trigger keywords:** "kotlin in action", "learn kotlin", "kotlin coroutines", "kotlin lambdas", "kotlin classes", "kotlin functions", "kotlin nullability", "how does kotlin"
+- **Anti-triggers:** Best practices advice (use effective-kotlin), non-Kotlin code
+- **Works well with:** effective-kotlin (learning + best practices)
+- **Conflicts with:** effective-kotlin (kotlin-in-action for learning features; effective-kotlin for best practice advice)
+
+## lean-startup
+- **Source:** *The Lean Startup* by Eric Ries
+- **Domain:** Startup strategy, MVP, validated learning, Build-Measure-Learn
+- **Language:** Not applicable (strategy skill)
+- **Trigger keywords:** "lean startup", "MVP", "validated learning", "pivot", "build-measure-learn", "product market fit", "hypothesis", "experiment", "runway"
+- **Anti-triggers:** Technical code review, architecture, any pure engineering concern
+- **Works well with:** None (strategy domain, not engineering)
+- **Conflicts with:** All technical skills (don't apply to code)
+
+## microservices-patterns
+- **Source:** *Microservices Patterns* by Chris Richardson
+- **Domain:** Microservices architecture, sagas, CQRS, API gateways, event sourcing
+- **Language:** Language-agnostic (Java Spring Boot examples)
+- **Trigger keywords:** "microservice", "saga", "CQRS", "event sourcing", "API gateway", "service mesh", "decompose monolith", "circuit breaker", "distributed transaction", "choreography", "orchestration"
+- **Anti-triggers:** Monolith-only code with no decomposition intent, pure domain modeling without service concerns
+- **Works well with:** domain-driven-design (service boundaries + domain model), system-design-interview (microservices + scale)
+- **Conflicts with:** domain-driven-design (microservices-patterns for service decomposition; DDD for domain model — apply both for new services)
+
+## refactoring-ui
+- **Source:** *Refactoring UI* by Adam Wathan & Steve Schoger
+- **Domain:** UI design, visual hierarchy, typography, color, layout, spacing
+- **Language:** CSS, HTML, any frontend
+- **Trigger keywords:** "UI design", "visual hierarchy", "typography", "color palette", "spacing", "layout", "design system", "refactor UI", "looks bad", "UI review"
+- **Anti-triggers:** Backend code, APIs, data processing, animation (use animation-at-work)
+- **Works well with:** animation-at-work (UI design + motion)
+- **Conflicts with:** animation-at-work (refactoring-ui for static design; animation-at-work for motion — they complement each other)
+
+## storytelling-with-data
+- **Source:** *Storytelling with Data* by Cole Nussbaumer Knaflic
+- **Domain:** Data visualization, charts, narrative structure
+- **Language:** Not applicable (visualization skill)
+- **Trigger keywords:** "data visualization", "chart", "graph", "dashboard", "storytelling", "declutter", "visual", "bar chart", "line chart", "scatter plot", "pie chart"
+- **Anti-triggers:** Code quality, backend processing, no visual component
+- **Works well with:** data-pipelines (pipeline data + visualization)
+- **Conflicts with:** None (niche visual domain)
+
+## system-design-interview
+- **Source:** *System Design Interview* by Alex Xu
+- **Domain:** High-level system architecture, scalability, estimation, real-world system designs
+- **Language:** Language-agnostic
+- **Trigger keywords:** "system design", "scale", "scalability", "back of envelope", "rate limiting", "CDN", "load balancer", "cache", "sharding", "high availability", "design YouTube", "design Twitter", "design a URL shortener"
+- **Anti-triggers:** Code-level review, domain modeling, specific language idioms
+- **Works well with:** data-intensive-patterns (high-level + storage internals), microservices-patterns (system design + service architecture)
+- **Conflicts with:** data-intensive-patterns (system-design-interview for high-level; data-intensive-patterns for storage internals)
+
+## using-asyncio-python
+- **Source:** *Using Asyncio in Python* by Caleb Hattingh
+- **Domain:** Python asyncio, coroutines, event loop, async patterns
+- **Language:** Python only
+- **Trigger keywords:** "asyncio", "async def", "await", "coroutine", "event loop", "aiohttp", "async Python", "concurrent Python", "Python concurrency"
+- **Anti-triggers:** Non-async Python, non-Python code
+- **Works well with:** effective-python (async + general Python best practices)
+- **Conflicts with:** effective-python (using-asyncio-python wins for any async topic)
+
+## web-scraping-python
+- **Source:** *Web Scraping with Python* by Ryan Mitchell
+- **Domain:** Web scraping, BeautifulSoup, Scrapy, data extraction
+- **Language:** Python only
+- **Trigger keywords:** "web scraping", "BeautifulSoup", "Scrapy", "requests", "crawl", "parse HTML", "selenium scraping", "extract data from website"
+- **Anti-triggers:** Non-scraping Python, general Python best practices
+- **Works well with:** effective-python (scraping + Python best practices), data-pipelines (scraping + ingestion)
+- **Conflicts with:** None (niche domain)