@rune-kit/rune 2.2.6 → 2.3.1

package/skills/skill-router/{SKILL.md → skill.md}

@@ -1,365 +1,446 @@
----
-name: skill-router
-description: "Meta-enforcement layer that routes EVERY agent action through the correct skill. MUST check this routing table before ANY response involving code, files, or technical decisions. Default: route to rune:cook for code tasks. Prevents rationalization, enforces check-before-act discipline."
-user-invocable: false
-metadata:
-  author: runedev
-  version: "1.2.0"
-  layer: L0
-  model: haiku
-  group: orchestrator
-  tools: "Read, Glob, Grep"
----
-
-## Live Routing Context
-
-Routing overrides (if available): !`cat .rune/metrics/routing-overrides.json 2>/dev/null || echo "No adaptive routing rules active."`
-
-Recent skill usage: !`cat .rune/metrics/skills.json 2>/dev/null | head -20 || echo "No metrics collected yet."`
-
-# skill-router
-
-## Purpose
-
-The missing enforcement layer for Rune. While individual skills have HARD-GATEs and constraints, nothing forces the agent to *check* for the right skill before acting. `skill-router` fixes this by intercepting every user request and routing it through the correct skill(s) before any code is written, any file is read, or any clarifying question is asked.
-
-This is L0 — it sits above L1 orchestrators. It doesn't do work itself; it ensures the right skill does the work.
-
-## Triggers
-
-- **ALWAYS** — This skill is conceptually active on every user message
-- Loaded via system prompt or plugin description, not invoked manually
-- The agent MUST internalize this routing table and apply it before every response
-
-## Calls (outbound connections)
-
-- Any skill (L1-L3): routes to the correct skill based on intent detection
-
-## Called By (inbound connections)
-
-- None — this is the entry point. Nothing calls skill-router; it IS the first check.
-
-## Workflow
-
-### Step 0 — Check Routing Overrides (H3 Adaptive Routing)
-
-Before standard routing, check if adaptive routing rules exist:
-
-1. Use `Read` on `.rune/metrics/routing-overrides.json`
-2. If the file exists and has active rules, scan each rule's `condition` against the current user intent
-3. If a rule matches:
-   - Apply the override action (e.g., "route to problem-solver before debug")
-   - Log: "Adaptive routing: applying rule [id] — [action]"
-4. If no file exists or no rules match, proceed to standard routing (Step 1)
-
-**Override constraints**:
-- Overrides MUST NOT bypass layer discipline (L3 cannot call L1)
-- Overrides MUST NOT skip quality gates (sentinel, preflight, verification)
-- Overrides MUST NOT route to non-existent skills
-- If an override seems wrong, announce it and let user decide to keep or disable
-
-**Model hint support** (Adaptive Model Re-balancing):
-- Override entries may include `"model_hint": "opus"` — this signals that a skill previously failed at sonnet-level and needed opus reasoning depth
-- When a model_hint is present, announce: "Adaptive routing: this skill previously required opus-level reasoning for [context]. Escalating model."
-- Model hints are written by cook Phase 8 when debug-fix loops hit max retries on the same error pattern
-- Model hints do NOT override explicit user model preferences
-
-### Step 0.25 — Request Classifier (Fast-Path Filter)
-
-Before intent classification, categorize the request into one of 5 types. This determines the **enforcement level** — how strictly routing must be followed.
-
-| Request Type | Keywords / Signals | Enforcement | Action |
-|---|---|---|---|
-| `CODE_CHANGE` | "build", "implement", "add", "create", "fix", "refactor", "update code" | **FULL** | cook mandatory, no exceptions |
-| `QUESTION` | "what is", "how does", "explain", "why" | **LITE** | Check if a skill has domain knowledge first; answer directly if no skill matches |
-| `DEBUG_REQUEST` | "error", "bug", "not working", "broken", "crash", "fails" | **FULL** | debug skill mandatory |
-| `REVIEW_REQUEST` | "review", "check", "audit", "look at this code" | **FULL** | review skill mandatory |
-| `EXPLORE` | "find", "search", "where is", "show me", "list" | **LITE** | scout if codebase-related; answer directly if general |
-
-**Enforcement levels:**
-- **FULL** → MUST route through a skill. Writing code without skill invocation = protocol violation.
-- **LITE** → SHOULD check if a skill applies. Can answer directly if no skill matches and the response involves no code changes.
-
-**Escape hatch**: If request is clearly trivial (< 5 LOC change, single-line fix, user says "just do it"), classify as CODE_CHANGE but cook activates Fast Mode automatically.
-
-### Step 0.5 — STOP before responding
-
-Before generating ANY response (including clarifying questions), the agent MUST:
-
-1. **Check the request type** from Step 0.25 — if FULL enforcement, routing is mandatory
-2. **Classify the user's intent** using the routing table below
-3. **Identify which skill(s) match** — if even 1% chance a skill applies, invoke it
-4. **Invoke the skill** via the Skill tool
-5. **Follow the skill's instructions** — the skill dictates the workflow, not the agent
-
-### Step 1 — Intent Classification (Progressive Disclosure)
-
-Skills are organized into 3 tiers for discoverability. **Tier 1 skills handle 90% of user requests.**
-
-#### Tier 1 — Primary Entry Points (User-Facing)
-
-These 5 skills are the main interface. Most user intents route here first:
-
-| User Intent | Route To | When |
-|---|---|---|
-| Build / implement / add feature / fix bug | `rune:cook` | Any code change request |
-| Large multi-part task / parallel work | `rune:team` | 5+ files or 3+ modules |
-| Deploy + launch + marketing | `rune:launch` | Ship to production |
-| Legacy code / rescue / modernize | `rune:rescue` | Old/messy codebase |
-| Check project health / full audit | `rune:audit` | Quality assessment |
-| New project / bootstrap / scaffold | `rune:scaffold` | Greenfield project creation |
-
-**Default route**: If unclear, route to `rune:cook`. Cook handles 70% of all requests.
-
-#### Tier 2 — Power User Skills (Direct Invocation)
-
-For users who know exactly what they want:
-
-| User Intent | Route To | Priority |
-|---|---|---|
-| Plan / design / architect | `rune:plan` | L2 — requires opus |
-| Brainstorm / explore ideas | `rune:brainstorm` | L2 — before plan |
-| Review code / check quality | `rune:review` | L2 |
-| Write tests | `rune:test` | L2 — TDD |
-| Refactor | `rune:surgeon` | L2 — incremental |
-| Deploy (without marketing) | `rune:deploy` | L2 |
-| Security concern | `rune:sentinel` | L2 — opus for critical |
-| Performance issue | `rune:perf` | L2 |
-| Database change | `rune:db` | L2 |
-| Received code review / PR feedback | `rune:review-intake` | L2 |
-| Protect / audit / document business logic | `rune:logic-guardian` | L2 |
-| Create / edit a Rune skill | `rune:skill-forge` | L2 — requires opus |
-| Incident / outage | `rune:incident` | L2 |
-| UI/UX design | `rune:design` | L2 |
-| Fix bug / debug only (no fix) | `rune:debug` → `rune:fix` | L2 chain |
-| Marketing assets only | `rune:marketing` | L2 |
-| Gather requirements / BA / elicit needs | `rune:ba` | L2 — requires opus |
-| Generate / update docs | `rune:docs` | L2 |
-| Build MCP server | `rune:mcp-builder` | L2 |
-| Red-team / challenge a plan / stress-test | `rune:adversary` | L2 — requires opus |
-
-#### Tier 3 — Internal Skills (Called by Other Skills)
-
-These are rarely invoked directly — they're called by Tier 1/2 skills:
-
-| Skill | Called By | Purpose |
-|---|---|---|
-| `rune:scout` | cook, plan, team | Codebase scanning |
-| `rune:fix` | debug, cook | Apply code changes |
-| `rune:preflight` | cook | Quality gate |
-| `rune:verification` | cook, fix | Run lint/test/build |
-| `rune:hallucination-guard` | cook, fix | Verify imports |
-| `rune:completion-gate` | cook | Validate claims |
-| `rune:sentinel-env` | cook, scaffold, onboard | Environment pre-flight |
-| `rune:research` / `rune:docs-seeker` | any | Look up docs |
-| `rune:session-bridge` | cook, team | Save context (in-session state handoff) |
-| `rune:journal` | cook, team | Persistent work log within a session |
-| `rune:neural-memory` | cook, team, any L1/L2 | Cross-session cognitive persistence via Neural Memory MCP — semantic complement to session-bridge and journal |
-| `rune:git` | cook, scaffold, team, launch | Semantic commits, PRs, branches |
-| `rune:doc-processor` | docs, marketing | PDF/DOCX/XLSX/PPTX generation |
-| "Done" / "ship it" / "xong" | — | `rune:verification` → commit |
-| "recall", "remember", "brain", "nmem", "cross-project memory" | `rune:neural-memory` | Retrieve or persist cross-session context |
-
-#### Tier 4 — Domain Extension Packs (L4)
-
-When user intent matches a domain-specific pattern or user explicitly invokes an L4 trigger command, route to the L4 pack.
-
-**Split pack loading** (context-efficient): First `Read` the pack's PACK.md index. If the index contains `format: split` in its frontmatter metadata, it is a split pack — the index lists skills in a table but skill content lives in separate files under `skills/`. Match user intent to the specific skill name in the table, then `Read` only that skill file (e.g., `extensions/backend/skills/api-design.md`). This loads ~100-200 lines instead of ~1000+.
-
-**Monolith pack loading** (legacy): If no `format: split` marker, the PACK.md contains all skills inline — read it fully and extract the matching `### skill-name` section.
-
-| User Intent / Domain Signal | Route To | Pack File |
-|---|---|---|
-| Frontend UI, design system, a11y, animation | `@rune/ui` | `extensions/ui/PACK.md` |
-| API design, auth, middleware, rate limiting | `@rune/backend` | `extensions/backend/PACK.md` |
-| Docker, CI/CD, monitoring, server setup | `@rune/devops` | `extensions/devops/PACK.md` |
-| React Native, Flutter, mobile app, app store | `@rune/mobile` | `extensions/mobile/PACK.md` |
-| OWASP, pentest, secrets, compliance | `@rune/security` | `extensions/security/PACK.md` |
-| Trading, fintech, charts, market data | `@rune/trading` | `extensions/trading/PACK.md` |
-| Multi-tenant, billing, SaaS subscription | `@rune/saas` | `extensions/saas/PACK.md` |
-| Shopify, payments, cart, inventory | `@rune/ecommerce` | `extensions/ecommerce/PACK.md` |
-| LLM, RAG, embeddings, fine-tuning | `@rune/ai-ml` | `extensions/ai-ml/PACK.md` |
-| Three.js, WebGL, game loop, physics | `@rune/gamedev` | `extensions/gamedev/PACK.md` |
-| Blog, CMS, MDX, i18n, SEO | `@rune/content` | `extensions/content/PACK.md` |
-| Analytics, A/B testing, funnels, dashboards | `@rune/analytics` | `extensions/analytics/PACK.md` |
-| Chrome extension, manifest, service worker | `@rune/chrome-ext` | `extensions/chrome-ext/PACK.md` |
-| PRD, roadmap, KPI, release notes, product spec | `@rune-pro/product` | `extensions/pro-product/PACK.md` |
-| Sales outreach, pipeline, call prep, prospecting | `@rune-pro/sales` | `extensions/pro-sales/PACK.md` |
-| Data science, SQL, dashboards, statistical analysis | `@rune-pro/data-science` | `extensions/pro-data-science/PACK.md` |
-| Support tickets, KB, escalation, SLA tracking | `@rune-pro/support` | `extensions/pro-support/PACK.md` |
-| Budget, expense, revenue forecast, P&L, cash flow | `@rune-pro/finance` | `extensions/pro-finance/PACK.md` |
-| Contract review, NDA, compliance, GDPR, IP audit | `@rune-pro/legal` | `extensions/pro-legal/PACK.md` |
-
-**L4 routing rules:**
-1. If user explicitly invokes an L4 trigger (e.g., `/rune rag-patterns`), read the PACK.md index first, then load only the matching skill file (split packs) or extract the matching section (monolith packs)
-2. If the intent also involves implementation, route to `cook` (L1) first — cook will detect L4 context in Phase 1.5
-3. L4 packs supplement L1/L2 workflows — they are domain knowledge, not standalone orchestrators
-4. L4 packs can call L3 utilities (scout, verification) but CANNOT call L1 or L2 skills
-5. If the L4 pack file is not found on disk, skip silently and proceed with standard routing
-6. **NEVER load an entire split pack** — always load index first, then only the specific skill file needed
-
-### Step 1.5 — File Ownership Matrix (Constraint Inheritance)
-
-When the routed skill produces file changes, the **owner skill's constraints** apply to those files — even if a different skill (e.g., cook) is the orchestrator.
-
-| File Pattern | Owner Skill | Constraints Applied |
-|---|---|---|
-| `*.test.*`, `*.spec.*`, `__tests__/` | `rune:test` | Test patterns, assertions, no `test.skip`, coverage rules |
-| `migrations/`, `schema.*`, `*.prisma` | `rune:db` | Migration safety, rollback script, parameterized queries |
-| `Dockerfile`, `*.yml` (CI/CD), `terraform/` | `rune:deploy` | Deployment checklist, no hardcoded secrets |
-| `docs/*.md`, `README.md`, `CHANGELOG.md` | `rune:docs` | Documentation patterns, no stale references |
-| `SKILL.md`, `PACK.md` | `rune:skill-forge` | Skill template compliance, frontmatter validation |
-| `.env*`, `*secret*`, `*credential*` | `rune:sentinel` | Security scan mandatory, never commit secrets |
-| `*.css`, `*.scss`, `tailwind.config.*` | `@rune/ui` | Design system patterns (if L4 pack installed) |
-
-**Ownership rules:**
-1. Ownership = **constraints apply**, NOT exclusive access. cook can modify test files during Phase 4 as long as test constraints are honored.
-2. If a file matches multiple patterns, ALL matching constraints apply (union, not exclusive).
-3. If no pattern matches, the routed skill's own constraints apply (default behavior).
-4. File ownership is checked DURING implementation, not at routing time — it augments, not replaces, skill routing.
-
-### Step 2 — Compound Intent Resolution
-
-Many requests combine intents. Route to the HIGHEST-PRIORITY skill first:
-
-```
-Priority: L1 > L2 > L3
-Within same layer: process skills > implementation skills
-
-Example: "Add auth and deploy it"
-  → rune:cook (add auth) FIRST
-  → rune:deploy SECOND (after cook completes)
-
-Example: "Fix the login bug and add tests"
-  → rune:debug (diagnose) FIRST
-  → rune:fix (apply fix) SECOND
-  → rune:test (add tests) THIRD
-
-L4 integration: If cook is the primary route AND a domain pack matches,
-cook handles orchestration while the L4 pack provides domain patterns.
-Both are active — cook for workflow, L4 for domain knowledge.
-```
-
-### Step 3 — Anti-Rationalization Gate
-
-The agent MUST NOT bypass routing with these excuses:
-
-| Thought | Reality | Action |
-|---|---|---|
-| "This is too simple for a skill" | Simple tasks still benefit from structure | Route it |
-| "I already know how to do this" | Skills have constraints you'll miss | Route it |
-| "Let me just read the file first" | Skills tell you HOW to read | Route first |
-| "I need more context before routing" | Route first, skill will gather context | Route it |
-| "The user just wants a quick answer" | Quick answers can still be wrong | Check routing table |
-| "No skill matches exactly" | Pick closest match, or use scout + plan | Route it |
-| "I'll apply the skill patterns mentally" | Mental application misses constraints | Actually invoke it |
-| "This is just a follow-up" | Follow-ups can change intent | Re-check routing |
-
-### Step 4 — Execute
-
-Once routed:
-1. Announce: "Using `rune:<skill>` to [purpose]"
-2. Invoke the skill via Skill tool
-3. Follow the skill's workflow exactly
-4. If the skill has a checklist/phases, track via TodoWrite
-
-### Step 5 — Post-Completion Neural Memory Capture
-
-After ANY L1 or L2 workflow completes (cook, team, launch, rescue, scaffold, plan, design, debug, fix, review, deploy, sentinel, perf, db, ba, docs, mcp-builder, etc.):
-
-1. Trigger `rune:neural-memory` in **Capture Mode** automatically
-2. Save 2–5 memories covering: key decisions made, bugs fixed, patterns applied, architectural choices
-3. Use rich cognitive language (causal, temporal, decisional) — NOT flat facts
-4. Tag memories with [project-name, skill-used, topic]
-5. This step is MANDATORY even if the user did not ask for it
-6. Exception: skip if the workflow produced zero technical output (e.g., only a clarifying question was asked)
-
-**Capture Mode trigger phrase**: "Session artifact — capturing to Neural Memory."
-
-## Routing Exceptions
-
-These DO NOT need skill routing:
-- Pure conversational responses ("hello", "thanks")
-- Answering questions about Rune itself (meta-questions)
-- Single-line factual answers with no code impact
-- Resuming an already-active skill workflow
-
-## Output Format
-
-### Routing Proof (Required in Every Code Response)
-
-Every response that involves code changes MUST begin with a routing proof line:
-
-```
-> Routed: rune:<skill> | Type: CODE_CHANGE | Confidence: HIGH
-```
-
-This is NOT optional formatting. It is evidence that routing occurred. If this line is missing from a code response, the response violated skill-router compliance. For LITE enforcement (QUESTION, EXPLORE), the proof line is optional.
-
-### Full Routing Decision (when announcing route)
-
-```
-## Routing Decision
-- **Intent**: [classified user intent]
-- **Type**: CODE_CHANGE | QUESTION | DEBUG_REQUEST | REVIEW_REQUEST | EXPLORE
-- **Skill**: rune:[skill-name]
-- **Confidence**: HIGH | MEDIUM | LOW
-- **Override**: [routing override applied, if any]
-- **Reason**: [one-line justification for skill selection]
-```
-
-For multi-skill chains:
-```
-## Routing Chain
-1. rune:[skill-1] — [purpose]
-2. rune:[skill-2] — [purpose]
-3. rune:[skill-3] — [purpose]
-```
-
-## Constraints
-
-1. MUST check routing table before EVERY response that involves code, files, or technical decisions
-2. MUST invoke skill via Skill tool — "mentally applying" a skill is NOT acceptable
-3. MUST NOT write code without routing through at least one skill first
-4. MUST NOT skip routing because "it's faster" — speed without correctness wastes more time
-5. MUST re-route on intent change — if user shifts from "plan" to "implement", switch skills
-6. MUST announce which skill is being used and why — transparency builds trust
-7. MUST follow skill's internal workflow, not override it with own judgment
-
-## Sharp Edges
-
-| Failure Mode | Severity | Mitigation |
-|---|---|---|
-| Agent writes code without invoking any skill | CRITICAL | Constraint 3: code REQUIRES skill routing. No exceptions. |
-| Agent "mentally applies" skill without invoking | HIGH | Constraint 2: must use Skill tool for full content |
-| Routes to wrong skill, wastes a full workflow | MEDIUM | Step 2 compound resolution + re-route on mismatch |
-| Over-routing trivial tasks (e.g., "what time is it") | LOW | Routing Exceptions section covers non-technical queries |
-| Skill invocation adds latency to simple tasks | LOW | Acceptable trade-off: correctness > speed |
-
-## Done When
-
-- This skill is never "done" — it's a persistent routing layer
-- Success = every agent response passes through routing check
-- Failure = any code written without skill invocation
-
-## Self-Verification Trigger (MANDATORY)
-
-<HARD-GATE>
-Before EVERY response, complete this 3-point self-check:
-
-1. **Did I classify this request?** (Step 0.25 — what type is it?)
-2. **Did I route through a skill?** (Step 1-2 — which skill handles this?)
-3. **Am I about to write code without a skill invocation?** → **STOP. Route first.**
-
-If the request type is `CODE_CHANGE` or `DEBUG_REQUEST` (FULL enforcement) and ANY answer is "no":
-→ DO NOT RESPOND. Complete routing first.
-
-If the request type is `QUESTION` or `EXPLORE` (LITE enforcement):
-→ Check if a skill has relevant domain knowledge. If yes, route. If no, respond directly.
-
-**User override**: If user explicitly says "skip routing", "just write it", "no process" → respect the override. Log: "User override: routing skipped per explicit request."
-</HARD-GATE>
-
-## Cost Profile
-
-~0 tokens (routing logic is internalized from this document). Cost comes from the skills it routes to, not from skill-router itself. The routing table is loaded once and cached in context.
+---
+name: skill-router
+description: "Meta-enforcement layer that routes EVERY agent action through the correct skill. MUST check this routing table before ANY response involving code, files, or technical decisions. Default: route to rune:cook for code tasks. Prevents rationalization, enforces check-before-act discipline."
+user-invocable: false
+metadata:
+  author: runedev
+  version: "1.3.0"
+  layer: L0
+  model: haiku
+  group: orchestrator
+  tools: "Read, Glob, Grep"
+---
+
+## Live Routing Context
+
+Routing overrides (if available): !`cat .rune/metrics/routing-overrides.json 2>/dev/null || echo "No adaptive routing rules active."`
+
+Recent skill usage: !`cat .rune/metrics/skills.json 2>/dev/null | head -20 || echo "No metrics collected yet."`
+
+# skill-router
+
+## Purpose
+
+The missing enforcement layer for Rune. While individual skills have HARD-GATEs and constraints, nothing forces the agent to *check* for the right skill before acting. `skill-router` fixes this by intercepting every user request and routing it through the correct skill(s) before any code is written, any file is read, or any clarifying question is asked.
+
+This is L0 — it sits above L1 orchestrators. It doesn't do work itself; it ensures the right skill does the work.
+
+## Triggers
+
+- **ALWAYS** — This skill is conceptually active on every user message
+- Loaded via system prompt or plugin description, not invoked manually
+- The agent MUST internalize this routing table and apply it before every response
+
+## Calls (outbound connections)
+
+- Any skill (L1-L3): routes to the correct skill based on intent detection
+
+## Called By (inbound connections)
+
+- None — this is the entry point. Nothing calls skill-router; it IS the first check.
+
+## Workflow
+
+### Step 0 — Check Routing Overrides (H3 Adaptive Routing)
+
+Before standard routing, check if adaptive routing rules exist:
+
+1. Use `Read` on `.rune/metrics/routing-overrides.json`
+2. If the file exists and has active rules, scan each rule's `condition` against the current user intent
+3. If a rule matches:
+   - Apply the override action (e.g., "route to problem-solver before debug")
+   - Log: "Adaptive routing: applying rule [id] — [action]"
+4. If no file exists or no rules match, proceed to standard routing (Step 1)
+
+**Override constraints**:
+- Overrides MUST NOT bypass layer discipline (L3 cannot call L1)
+- Overrides MUST NOT skip quality gates (sentinel, preflight, verification)
+- Overrides MUST NOT route to non-existent skills
+- If an override seems wrong, announce it and let user decide to keep or disable
+
+**Model hint support** (Adaptive Model Re-balancing):
+- Override entries may include `"model_hint": "opus"` — this signals that a skill previously failed at sonnet-level and needed opus reasoning depth
+- When a model_hint is present, announce: "Adaptive routing: this skill previously required opus-level reasoning for [context]. Escalating model."
+- Model hints are written by cook Phase 8 when debug-fix loops hit max retries on the same error pattern
+- Model hints do NOT override explicit user model preferences
+
+### Context Efficiency (Trigger-Table Pattern)
+
+Skill-router's routing table above IS the trigger table — it maps keywords to skill paths without loading any skill content. Skills are loaded on-demand via the Skill tool only when routed. This keeps baseline context usage minimal.
+
+**Rules for context efficiency:**
+- NEVER read a SKILL.md to decide routing — use the routing table keywords
+- NEVER load multiple skills speculatively — route to ONE, let it chain if needed
+- Skill content is loaded by the Skill tool, not by skill-router reading files
+
+### Step 0.25 — Request Classifier (Fast-Path Filter)
+
+Before intent classification, categorize the request into one of 5 types. This determines the **enforcement level** — how strictly routing must be followed.
+
+| Request Type | Keywords / Signals | Enforcement | Action |
+|---|---|---|---|
+| `CODE_CHANGE` | "build", "implement", "add", "create", "fix", "refactor", "update code" | **FULL** | cook mandatory, no exceptions |
+| `QUESTION` | "what is", "how does", "explain", "why" | **LITE** | Check if a skill has domain knowledge first; answer directly if no skill matches |
+| `DEBUG_REQUEST` | "error", "bug", "not working", "broken", "crash", "fails" | **FULL** | debug skill mandatory |
+| `REVIEW_REQUEST` | "review", "check", "audit", "look at this code" | **FULL** | review skill mandatory |
+| `EXPLORE` | "find", "search", "where is", "show me", "list" | **LITE** | scout if codebase-related; answer directly if general |
+
+**Enforcement levels:**
+- **FULL** → MUST route through a skill. Writing code without skill invocation = protocol violation.
+- **LITE** → SHOULD check if a skill applies. Can answer directly if no skill matches and the response involves no code changes.
+
+**Escape hatch**: If request is clearly trivial (< 5 LOC change, single-line fix, user says "just do it"), classify as CODE_CHANGE but cook activates Fast Mode automatically.
+
+### Step 0.3 — Skill Discovery (`/rune list`)
+
+If user says `/rune list`, "what skills do I have", "show all skills", "available skills", or "what can rune do":
+
+1. **Scan installed skills**: `Glob` for `skills/*/skill.md` (core L0-L3) and `extensions/*/PACK.md` (L4 packs)
+2. **Scan paid extensions**: `Glob` for `extensions/pro-*/PACK.md` (Pro/Business packs — only present if purchased)
+3. **Output the catalog** grouped by tier:
+
+```
+## Rune Skills Catalog
+
+### Core Skills (L0-L3) — Always Available
+| Skill | Layer | Description |
+|-------|-------|-------------|
+(list each skill from skills/*/skill.md — read name + description from frontmatter)
+
+### Extension Packs (L4) — Domain Knowledge
+| Pack | Skills | Trigger |
+|------|--------|---------|
+(list each pack from extensions/*/PACK.md — read name + skill count + trigger commands)
+
+### Pro/Business Packs (if installed)
+| Pack | Skills | Trigger |
+|------|--------|---------|
+(list each pack from extensions/pro-*/PACK.md)
+```
+
+4. **Tip line at bottom**: "Use `/rune <pack> <skill>` to invoke any skill directly. Use `/rune <pack>` for the full pack workflow."
+
+**Filtering**: `/rune list <query>` filters by name or domain keyword (e.g., `/rune list finance` shows only finance-related skills).
+
+### Step 0.5 — STOP before responding
+
+Before generating ANY response (including clarifying questions), the agent MUST:
+
+1. **Check the request type** from Step 0.25 — if FULL enforcement, routing is mandatory
+2. **Classify the user's intent** using the routing table below
+3. **Identify which skill(s) match** — if even 1% chance a skill applies, invoke it
+4. **Invoke the skill** via the Skill tool
+5. **Follow the skill's instructions** — the skill dictates the workflow, not the agent
+
+### Step 1 — Intent Classification (Progressive Disclosure)
+
+Skills are organized into 3 tiers for discoverability. **Tier 1 skills handle 90% of user requests.**
+
+#### Tier 1 — Primary Entry Points (User-Facing)
+
+These 5 skills are the main interface. Most user intents route here first:
+
+| User Intent | Route To | When |
+|---|---|---|
+| Build / implement / add feature / fix bug | `rune:cook` | Any code change request |
+| Large multi-part task / parallel work | `rune:team` | 5+ files or 3+ modules |
+| Deploy + launch + marketing | `rune:launch` | Ship to production |
+| Legacy code / rescue / modernize | `rune:rescue` | Old/messy codebase |
+| Check project health / full audit | `rune:audit` | Quality assessment |
+| New project / bootstrap / scaffold | `rune:scaffold` | Greenfield project creation |
+
+**Default route**: If unclear, route to `rune:cook`. Cook handles 70% of all requests.
+
+#### Tier 2 — Power User Skills (Direct Invocation)
+
+For users who know exactly what they want:
+
+| User Intent | Route To | Priority |
+|---|---|---|
+| Plan / design / architect | `rune:plan` | L2 — requires opus |
+| Brainstorm / explore ideas | `rune:brainstorm` | L2 — before plan |
+| Review code / check quality | `rune:review` | L2 |
+| Write tests | `rune:test` | L2 — TDD |
+| Refactor | `rune:surgeon` | L2 — incremental |
+| Deploy (without marketing) | `rune:deploy` | L2 |
+| Security concern | `rune:sentinel` | L2 — opus for critical |
+| Performance issue | `rune:perf` | L2 |
+| Database change | `rune:db` | L2 |
+| Received code review / PR feedback | `rune:review-intake` | L2 |
+| Protect / audit / document business logic | `rune:logic-guardian` | L2 |
+| Create / edit a Rune skill | `rune:skill-forge` | L2 — requires opus |
+| Incident / outage | `rune:incident` | L2 |
+| UI/UX design | `rune:design` | L2 |
+| Fix bug / debug only (no fix) | `rune:debug` → `rune:fix` | L2 chain |
+| Marketing assets only | `rune:marketing` | L2 |
+| Gather requirements / BA / elicit needs | `rune:ba` | L2 — requires opus |
+| Generate / update docs | `rune:docs` | L2 |
+| Build MCP server | `rune:mcp-builder` | L2 |
+| Red-team / challenge a plan / stress-test | `rune:adversary` | L2 — requires opus |
+
+#### Tier 3 — Internal Skills (Called by Other Skills)
+
+These are rarely invoked directly — they're called by Tier 1/2 skills:
+
+| Skill | Called By | Purpose |
+|---|---|---|
+| `rune:scout` | cook, plan, team | Codebase scanning |
+| `rune:fix` | debug, cook | Apply code changes |
+| `rune:preflight` | cook | Quality gate |
+| `rune:verification` | cook, fix | Run lint/test/build |
+| `rune:hallucination-guard` | cook, fix | Verify imports |
+| `rune:completion-gate` | cook | Validate claims |
+| `rune:sentinel-env` | cook, scaffold, onboard | Environment pre-flight |
+| `rune:research` / `rune:docs-seeker` | any | Look up docs |
+| `rune:session-bridge` | cook, team | Save context (in-session state handoff) |
+| `rune:journal` | cook, team | Persistent work log within a session |
+| `rune:neural-memory` | cook, team, any L1/L2 | Cross-session cognitive persistence via Neural Memory MCP — semantic complement to session-bridge and journal |
+| `rune:git` | cook, scaffold, team, launch | Semantic commits, PRs, branches |
+| `rune:doc-processor` | docs, marketing | PDF/DOCX/XLSX/PPTX generation |
+| "Done" / "ship it" / "xong" | — | `rune:verification` → commit |
+| "recall", "remember", "brain", "nmem", "cross-project memory" | `rune:neural-memory` | Retrieve or persist cross-session context |
+
+#### Tier 4 — Domain Extension Packs (L4)
+
+When user intent matches a domain-specific pattern or user explicitly invokes an L4 trigger command, route to the L4 pack.
+
+**Split pack loading** (context-efficient): First `Read` the pack's PACK.md index. If the index contains `format: split` in its frontmatter metadata, it is a split pack — the index lists skills in a table but skill content lives in separate files under `skills/`. Match user intent to the specific skill name in the table, then `Read` only that skill file (e.g., `extensions/backend/skills/api-design.md`). This loads ~100-200 lines instead of ~1000+.
+
+**Monolith pack loading** (legacy): If no `format: split` marker, the PACK.md contains all skills inline — read it fully and extract the matching `### skill-name` section.
+
+| User Intent / Domain Signal | Route To | Pack File |
+|---|---|---|
+| Frontend UI, design system, a11y, animation | `@rune/ui` | `extensions/ui/PACK.md` |
+| API design, auth, middleware, rate limiting | `@rune/backend` | `extensions/backend/PACK.md` |
+| Docker, CI/CD, monitoring, server setup | `@rune/devops` | `extensions/devops/PACK.md` |
+| React Native, Flutter, mobile app, app store | `@rune/mobile` | `extensions/mobile/PACK.md` |
+| OWASP, pentest, secrets, compliance | `@rune/security` | `extensions/security/PACK.md` |
+| Trading, fintech, charts, market data | `@rune/trading` | `extensions/trading/PACK.md` |
+| Multi-tenant, billing, SaaS subscription | `@rune/saas` | `extensions/saas/PACK.md` |
+| Shopify, payments, cart, inventory | `@rune/ecommerce` | `extensions/ecommerce/PACK.md` |
+| LLM, RAG, embeddings, fine-tuning | `@rune/ai-ml` | `extensions/ai-ml/PACK.md` |
+| Three.js, WebGL, game loop, physics | `@rune/gamedev` | `extensions/gamedev/PACK.md` |
+| Blog, CMS, MDX, i18n, SEO | `@rune/content` | `extensions/content/PACK.md` |
+| Analytics, A/B testing, funnels, dashboards | `@rune/analytics` | `extensions/analytics/PACK.md` |
+| Chrome extension, manifest, service worker | `@rune/chrome-ext` | `extensions/chrome-ext/PACK.md` |
+| PRD, roadmap, KPI, release notes, product spec | `@rune-pro/product` | `extensions/pro-product/PACK.md` |
+| Sales outreach, pipeline, call prep, prospecting | `@rune-pro/sales` | `extensions/pro-sales/PACK.md` |
+| Data science, SQL, dashboards, statistical analysis | `@rune-pro/data-science` | `extensions/pro-data-science/PACK.md` |
+| Support tickets, KB, escalation, SLA tracking | `@rune-pro/support` | `extensions/pro-support/PACK.md` |
+| Budget, expense, revenue forecast, P&L, cash flow | `@rune-pro/finance` | `extensions/pro-finance/PACK.md` |
+| Contract review, NDA, compliance, GDPR, IP audit | `@rune-pro/legal` | `extensions/pro-legal/PACK.md` |
+
+**L4 routing rules:**
+1. If user explicitly invokes an L4 trigger (e.g., `/rune rag-patterns`), read the PACK.md index first, then load only the matching skill file (split packs) or extract the matching section (monolith packs)
+2. If the intent also involves implementation, route to `cook` (L1) first — cook will detect L4 context in Phase 1.5
+3. L4 packs supplement L1/L2 workflows — they are domain knowledge, not standalone orchestrators
+4. L4 packs can call L3 utilities (scout, verification) but CANNOT call L1 or L2 skills
+5. If the L4 pack file is not found on disk, skip silently and proceed with standard routing
+6. **NEVER load an entire split pack** — always load index first, then only the specific skill file needed
+
+### Step 1.5 — File Ownership Matrix (Constraint Inheritance)
+
+When the routed skill produces file changes, the **owner skill's constraints** apply to those files — even if a different skill (e.g., cook) is the orchestrator.
+
+| File Pattern | Owner Skill | Constraints Applied |
+|---|---|---|
+| `*.test.*`, `*.spec.*`, `__tests__/` | `rune:test` | Test patterns, assertions, no `test.skip`, coverage rules |
+| `migrations/`, `schema.*`, `*.prisma` | `rune:db` | Migration safety, rollback script, parameterized queries |
+| `Dockerfile`, `*.yml` (CI/CD), `terraform/` | `rune:deploy` | Deployment checklist, no hardcoded secrets |
+| `docs/*.md`, `README.md`, `CHANGELOG.md` | `rune:docs` | Documentation patterns, no stale references |
+| `SKILL.md`, `PACK.md` | `rune:skill-forge` | Skill template compliance, frontmatter validation |
+| `.env*`, `*secret*`, `*credential*` | `rune:sentinel` | Security scan mandatory, never commit secrets |
+| `*.css`, `*.scss`, `tailwind.config.*` | `@rune/ui` | Design system patterns (if L4 pack installed) |
+
+**Ownership rules:**
+1. Ownership = **constraints apply**, NOT exclusive access. cook can modify test files during Phase 4 as long as test constraints are honored.
+2. If a file matches multiple patterns, ALL matching constraints apply (union, not exclusive).
+3. If no pattern matches, the routed skill's own constraints apply (default behavior).
+4. File ownership is checked DURING implementation, not at routing time — it augments, not replaces, skill routing.
+
+### Step 2 — Compound Intent Resolution
+
+Many requests combine intents. Route to the HIGHEST-PRIORITY skill first:
+
+```
+Priority: L1 > L2 > L3
+Within same layer: process skills > implementation skills
+
+Example: "Add auth and deploy it"
+  → rune:cook (add auth) FIRST
+  → rune:deploy SECOND (after cook completes)
+
+Example: "Fix the login bug and add tests"
+  → rune:debug (diagnose) FIRST
+  → rune:fix (apply fix) SECOND
+  → rune:test (add tests) THIRD
+
+L4 integration: If cook is the primary route AND a domain pack matches,
+cook handles orchestration while the L4 pack provides domain patterns.
+Both are active — cook for workflow, L4 for domain knowledge.
+```
+
+### Step 3 — Anti-Rationalization Gate
+
+The agent MUST NOT bypass routing with these excuses:
+
+| Thought | Reality | Action |
+|---|---|---|
+| "This is too simple for a skill" | Simple tasks still benefit from structure | Route it |
+| "I already know how to do this" | Skills have constraints you'll miss | Route it |
+| "Let me just read the file first" | Skills tell you HOW to read | Route first |
+| "I need more context before routing" | Route first, skill will gather context | Route it |
+| "The user just wants a quick answer" | Quick answers can still be wrong | Check routing table |
+| "No skill matches exactly" | Pick closest match, or use scout + plan | Route it |
+| "I'll apply the skill patterns mentally" | Mental application misses constraints | Actually invoke it |
+| "This is just a follow-up" | Follow-ups can change intent | Re-check routing |
+
+### Step 4 — Execute
+
+Once routed:
+1. Announce: "Using `rune:<skill>` to [purpose]"
+2. Invoke the skill via Skill tool
+3. Follow the skill's workflow exactly
+4. If the skill has a checklist/phases, track via TodoWrite
+
+### Step 5 — Post-Completion Neural Memory Capture
+
+After ANY L1 or L2 workflow completes (cook, team, launch, rescue, scaffold, plan, design, debug, fix, review, deploy, sentinel, perf, db, ba, docs, mcp-builder, etc.):
+
+1. Trigger `rune:neural-memory` in **Capture Mode** automatically
+2. Save 2–5 memories covering: key decisions made, bugs fixed, patterns applied, architectural choices
+3. Use rich cognitive language (causal, temporal, decisional) — NOT flat facts
+4. Tag memories with [project-name, skill-used, topic]
+5. This step is MANDATORY even if the user did not ask for it
+6. Exception: skip if the workflow produced zero technical output (e.g., only a clarifying question was asked)
+
+**Capture Mode trigger phrase**: "Session artifact — capturing to Neural Memory."
+
+## Routing Exceptions
+
+These DO NOT need skill routing:
+- Pure conversational responses ("hello", "thanks")
+- Answering questions about Rune itself (meta-questions)
+- Single-line factual answers with no code impact
+- Resuming an already-active skill workflow
+
+## Proactive Skill Recommendations (One-Hop Max)
+
+At the end of a skill's workflow, skill-router MAY suggest a **complementary skill** — limited to ONE recommendation to prevent infinite referral chains.
+
+| After This Skill | Suggest | Rationale |
+|-----------------|---------|-----------|
+| `debug` | `review` | Root cause found — review the fix area for broader issues |
+| `fix` | `test` | Code changed — verify with tests |
+| `plan` | `adversary` | Plan created — stress-test before implementation |
+| `test` (GREEN) | `preflight` | Tests pass — check for edge cases and completeness |
+| `review` (issues found) | `fix` | Issues identified — apply fixes |
+| `sentinel` (findings) | `fix` | Security issues — remediate |
+
+#### L4 Extension Auto-Suggest (Domain Context Detection)
+
+When routing a request through L1/L2 skills, skill-router SHOULD detect domain signals and suggest relevant L4 packs the user may not know they have:
+
+| Domain Signal Detected | Suggest Pack | Announcement |
+|----------------------|-------------|--------------|
+| Financial terms (budget, revenue, P&L, runway, cash flow) | `@rune-pro/finance` | "You have `@rune-pro/finance` with 7 specialized skills. Use `/rune finance` to access." |
+| Legal terms (contract, NDA, compliance, GDPR, IP) | `@rune-pro/legal` | "You have `@rune-pro/legal` with 6 specialized skills. Use `/rune legal` to access." |
+| HR terms (hiring, JD, interview, onboarding, comp) | `@rune-pro/hr` | "You have `@rune-pro/hr` with 7 specialized skills. Use `/rune hr` to access." |
+| Product terms (PRD, roadmap, KPI, release notes) | `@rune-pro/product` | "You have `@rune-pro/product` with 6 specialized skills. Use `/rune product` to access." |
+| Sales terms (pipeline, outreach, prospecting) | `@rune-pro/sales` | "You have `@rune-pro/sales` with 6 specialized skills. Use `/rune sales` to access." |
+| Data terms (SQL, dashboard, statistical, ML eval) | `@rune-pro/data-science` | "You have `@rune-pro/data-science` with 7 specialized skills. Use `/rune data` to access." |
+| Support terms (ticket, KB, escalation, SLA) | `@rune-pro/support` | "You have `@rune-pro/support` with 6 specialized skills. Use `/rune support` to access." |
+| Search terms (enterprise search, knowledge graph) | `@rune-pro/enterprise-search` | "You have `@rune-pro/enterprise-search` with 6 specialized skills. Use `/rune search` to access." |
+
+**Auto-suggest rules:**
+1. Only suggest if the pack's PACK.md **exists on disk** — `Glob` for the pack path first. If not installed, skip silently.
+2. Suggest ONCE per session per pack — do not repeat after user has seen the suggestion.
+3. Format: brief inline note, not a blocking prompt. User can ignore and continue.
+4. If user is already inside the pack's workflow, do not re-suggest.
+
+**Rules:**
+- Hard limit: 1 hop. NEVER chain recommendations (fix→test→preflight→...). Suggest ONE, let the user decide.
+- Announcement format: "Suggested next: `rune:<skill>` — [1-line reason]. Run it? (skip to continue)"
+- User can disable with "no suggestions" or "just do what I asked"
+- Inside `cook` orchestration: skip recommendations — cook already manages transitions
+
+
+## Output Format
+
+### Routing Proof (Required in Every Code Response)
+
+Every response that involves code changes MUST begin with a routing proof line:
+
+```
+> Routed: rune:<skill> | Type: CODE_CHANGE | Confidence: HIGH
+```
+
+This is NOT optional formatting. It is evidence that routing occurred. If this line is missing from a code response, the response violated skill-router compliance. For LITE enforcement (QUESTION, EXPLORE), the proof line is optional.
+
+### Full Routing Decision (when announcing route)
+
+```
+## Routing Decision
+- **Intent**: [classified user intent]
+- **Type**: CODE_CHANGE | QUESTION | DEBUG_REQUEST | REVIEW_REQUEST | EXPLORE
+- **Skill**: rune:[skill-name]
+- **Confidence**: HIGH | MEDIUM | LOW
+- **Override**: [routing override applied, if any]
+- **Reason**: [one-line justification for skill selection]
+```
+
+For multi-skill chains:
+```
+## Routing Chain
+1. rune:[skill-1] — [purpose]
+2. rune:[skill-2] — [purpose]
+3. rune:[skill-3] — [purpose]
+```
+
+## Constraints
+
+1. MUST check routing table before EVERY response that involves code, files, or technical decisions
+2. MUST invoke skill via Skill tool — "mentally applying" a skill is NOT acceptable
+3. MUST NOT write code without routing through at least one skill first
+4. MUST NOT skip routing because "it's faster" — speed without correctness wastes more time
+5. MUST re-route on intent change — if user shifts from "plan" to "implement", switch skills
+6. MUST announce which skill is being used and why — transparency builds trust
+7. MUST follow skill's internal workflow, not override it with own judgment
+
+## Sharp Edges
+
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Agent writes code without invoking any skill | CRITICAL | Constraint 3: code REQUIRES skill routing. No exceptions. |
+| Agent "mentally applies" skill without invoking | HIGH | Constraint 2: must use Skill tool for full content |
+| Routes to wrong skill, wastes a full workflow | MEDIUM | Step 2 compound resolution + re-route on mismatch |
+| Over-routing trivial tasks (e.g., "what time is it") | LOW | Routing Exceptions section covers non-technical queries |
+| Skill invocation adds latency to simple tasks | LOW | Acceptable trade-off: correctness > speed |
+
+## Done When
+
+- This skill is never "done" — it's a persistent routing layer
+- Success = every agent response passes through routing check
+- Failure = any code written without skill invocation
+
+## Self-Verification Trigger (MANDATORY)
+
+<HARD-GATE>
+Before EVERY response, complete this 3-point self-check:
+
+1. **Did I classify this request?** (Step 0.25 — what type is it?)
+2. **Did I route through a skill?** (Step 1-2 — which skill handles this?)
+3. **Am I about to write code without a skill invocation?** → **STOP. Route first.**
+
+If the request type is `CODE_CHANGE` or `DEBUG_REQUEST` (FULL enforcement) and ANY answer is "no":
+→ DO NOT RESPOND. Complete routing first.
+
+If the request type is `QUESTION` or `EXPLORE` (LITE enforcement):
+→ Check if a skill has relevant domain knowledge. If yes, route. If no, respond directly.
+
+**User override**: If user explicitly says "skip routing", "just write it", "no process" → respect the override. Log: "User override: routing skipped per explicit request."
+</HARD-GATE>
+
+## Cost Profile
+
+~0 tokens (routing logic is internalized from this document). Cost comes from the skills it routes to, not from skill-router itself. The routing table is loaded once and cached in context.