qualia-framework 5.3.0 → 5.4.0

package/rules/speed.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: true
+---
+
+# Speed Rules (MANDATORY)
+
+## Direct tools over subagents
+
+**NEVER use Task(Explore) or Task(general-purpose) for simple file lookups or code searches.** Use direct tools instead:
+- **Glob** for finding files by name/pattern
+- **Grep** for searching code content
+- **Read** for reading specific files
+- Only use Task(Explore) when you genuinely need 5+ rounds of deep codebase archaeology.
+
+**NEVER spawn subagents when direct tools work.** Subagents are slow — a direct Glob or Grep returns in seconds, a fresh agent burns 5-10 seconds of spawn overhead plus its own context budget.
+
+**Bias toward action, not exploration.** If the user asks you to fix something and you know the project structure, just do it.
+
+## CLI-first, MCP only when CLI can't
+
+MCP servers impose a **token tax**: their tool definitions consume context-window space on every turn, even when unused. CLIs that the model already knows from training data (git, gh, supabase, vercel, railway, npx, curl) impose zero token tax — the model recalls them from weights, not from the prompt.
+
+**Default to CLI.** Reach for MCP only when:
+- The CLI doesn't exist or doesn't expose the operation you need.
+- The CLI requires interactive auth that MCP has already brokered (e.g., Stripe Dashboard).
+- The MCP returns structured JSON that would be expensive to parse from CLI text output.
+- The MCP enforces governance (RLS-aware queries, scoped DB credentials) that the CLI doesn't.
+
+If a `/skill-name` exists that wraps a CLI, prefer the skill — it's been hardened. Canonical example: `/supabase` skill replaces 32 supabase MCP tools with `supabase` CLI calls and saves substantial token budget.
+
+### MCP tier-list (when each is justified)
+
+| Server | Always-on? | Justification |
+|---|---|---|
+| `claude-in-chrome` | On-demand | Browser automation has no CLI equivalent; use for QA flows only |
+| `supabase` MCP | **Off** in favor of `/supabase` skill | CLI covers 95% of operations; MCP only if you need branch management interactively |
+| `context7` | On-demand | Library docs at runtime — no CLI alternative for Context7 itself |
+| `notebooklm-mcp` | On-demand | NotebookLM has no CLI; only loaded when researching against existing notebooks |
+| `firecrawl-mcp` | On-demand | Web scraping; only loaded when feature requires it |
+| `next-devtools` | Always-on (dev) | Next.js 16 runtime errors not visible elsewhere |
+| `mux`, `stitch`, `higgsfield` | On-demand | Specialized API surfaces; load only on relevant client work |
+| `ZohoMCP`, `qualia-erp` | On-demand | Business ops only, not engineering-path |
+
+The pattern: **on-demand by default; always-on only when the data is irreducibly remote AND there's no CLI.**
+
+## Use shortcuts (Qualia commands)
+
+When a Qualia command exists for the situation, use it — don't reinvent:
+- `/qualia` — what's my next step?
+- `/qualia-quick` — small inline fix, no plan, no spawn
+- `/qualia-task` — single focused task, fresh builder spawn, atomic commit
+- `/qualia-ship` — full deploy pipeline (quality gates → commit → deploy → verify)
+- `/qualia-review` — production audit
+- `/qualia-pause` — save context before clearing the conversation
+- `/qualia-learn` — save a lesson from a mistake

package/skills/qualia-help/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-help
-description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+description: "Open the BROWSER HTML reference for the Qualia Framework — themed page with all commands, rules, services, and the road. The default when a browser is available. For terminal-only output (SSH, headless), use /qualia-road. Triggers: 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference', 'open the docs'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-map
-description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process."
+description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process. Triggers: 'map this codebase', 'onboard to existing project', 'brownfield setup', 'what's already built here', 'scan the repo', 'inherited a codebase', 'audit this project before planning'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-milestone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-milestone
-description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone."
+description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone. Triggers: 'close milestone', 'next milestone', 'milestone done', 'wrap up milestone', 'M1 done open M2', 'I want to advance to the next milestone', 'finish this milestone'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-new/SKILL.md

@@ -183,7 +183,7 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 If frontend work is involved, generate `.planning/DESIGN.md` from `templates/DESIGN.md`. The generation MUST commit to four things upfront (these go in §1 of DESIGN.md):
 
 1. **Aesthetic direction** — pick ONE: `editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...`. Don't hedge ("modern minimal" is hedging — pick one extreme).
-2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `rules/design-laws.md` §2.
+2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `qualia-design/design-laws.md` §2.
 3. **Scene sentence** — one concrete sentence: who uses this, where, ambient light, mood. NOT "observability dashboard" — "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room." Run the sentence, not the category.
 4. **Differentiation** — one sentence: what someone remembers 24 hours later.
 
@@ -198,7 +198,7 @@ Then fill the rest of DESIGN.md:
 - §9 Responsive: mobile-first
 - §10 Anti-pattern checklist (the auto-runnable one)
 
-Cross-check the result against `rules/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
+Cross-check the result against `qualia-design/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
 ```bash
 git add .planning/DESIGN.md .planning/config.json

package/skills/qualia-optimize/REFERENCE.md

@@ -15,7 +15,7 @@ Agent(
 </planning>
 
 <rules>
-{rules/frontend.md content}
+{qualia-design/frontend.md content}
 </rules>
 
 <task>
@@ -30,7 +30,7 @@ Analyze frontend:
 
 2. **Design Alignment**
    - Components vs DESIGN.md (colors, typography, spacing)
-   - rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
+   - qualia-design/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
    - Consistency across app (buttons, spacing, colors)
 
 3. **Frontend Perf**

package/skills/qualia-optimize/SKILL.md

@@ -73,7 +73,7 @@ ls .planning/decisions/ 2>/dev/null && cat .planning/decisions/*.md 2>/dev/null
 
 Also read rules:
 ```bash
-cat ~/.claude/rules/frontend.md 2>/dev/null
+cat ~/.claude/qualia-design/frontend.md 2>/dev/null
 cat ~/.claude/rules/security.md 2>/dev/null
 ```
 

package/skills/qualia-polish/SKILL.md

@@ -37,7 +37,7 @@ Before any work — design or otherwise — pass these gates. Skipping them prod
 
 | Gate | Required check | If fail |
 |---|---|---|
-| Substrate | `rules/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
+| Substrate | `qualia-design/design-laws.md`, `design-brand.md`, `design-product.md`, `design-rubric.md` exist and have been read | Read them. |
 | PRODUCT | `PRODUCT.md` exists at project root, has `register:` field, and is not placeholder (`[TODO]` markers, < 200 chars) | Run setup: ask 5 questions and generate it. Never synthesize from prompt alone. |
 | DESIGN | `DESIGN.md` exists. If missing on App / Redesign scope, BLOCK and run setup. If missing on Component / Section / Critique / Quick scope, NUDGE and proceed. | Generate from PRODUCT.md + 3 questions. |
 | Slop-detect | `bin/slop-detect.mjs` is callable | Install or pull from framework. |
@@ -100,7 +100,7 @@ For App / Redesign / Section scope on multi-file work:
 - If the conversation already contains design-taste discussion (font/color/motion preferences threaded across multiple turns), prefer **forked subagents** (`--fork-session`) so they inherit the taste context. Otherwise, blank-context fan-out is fine for mechanical fixes.
 
 Each agent receives:
-- `rules/design-laws.md` + the matching register file
+- `qualia-design/design-laws.md` + the matching register file
 - `PRODUCT.md` + `DESIGN.md` (inlined)
 - Its 5 files (paths + contents)
 - Instruction: apply the Design Quality Rubric per file. Fix every dimension scoring < 3. Make literal edits. Do NOT change logic — only styling.
@@ -158,7 +158,7 @@ viewports: [
 For each iteration:
 
 1. Capture all 3 viewports
-2. Pass to a vision-model agent with `rules/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
+2. Pass to a vision-model agent with `qualia-design/design-rubric.md` as the prompt anchor + DESIGN.md as the spec
 3. The agent scores 8 dimensions, anchored 1-5, with evidence per dimension
 4. Apply fixes ONLY to dimensions scored 1 or 2 (don't nitpick 3s; prevents oscillation)
 5. STOP if: all dimensions ≥ 3 (success), OR any dimension regressed from previous iteration (regression-stop), OR 2 iterations reached (hard cap)

package/skills/qualia-polish-loop/REFERENCE.md

@@ -58,7 +58,7 @@ Agent({
 Role: @~/.claude/agents/visual-evaluator.md
 
 <rubric>
-{INLINE rules/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
+{INLINE qualia-design/design-rubric.md §"The 8 dimensions" through §"Aggregate score"}
 </rubric>
 
 <brief>

package/skills/qualia-polish-loop/SKILL.md

@@ -18,7 +18,7 @@ See its own work. Fix its own work. Stop only when correct.
 
 ## What it does
 
-Takes a URL + design brief. Screenshots at 3 viewports (mobile / tablet / desktop). Spawns a vision evaluator that scores 8 dimensions of `rules/design-rubric.md` against the brief with cited evidence. Spawns up to 3 fix-builders in parallel for the top issues. Re-screenshots. Loops until all dimensions ≥ 3 or the kill-switch trips (regression, budget, or max iterations).
+Takes a URL + design brief. Screenshots at 3 viewports (mobile / tablet / desktop). Spawns a vision evaluator that scores 8 dimensions of `qualia-design/design-rubric.md` against the brief with cited evidence. Spawns up to 3 fix-builders in parallel for the top issues. Re-screenshots. Loops until all dimensions ≥ 3 or the kill-switch trips (regression, budget, or max iterations).
 
 Different from `/qualia-polish`: that one is read+edit+slop-detect, single pass. This one is **see+edit+verify+repeat** with a real loop and real screenshots.
 
@@ -39,7 +39,7 @@ Run these in order. Halt on the first failure.
 
 | Gate | Check | If fail |
 |---|---|---|
-| Substrate | `rules/design-rubric.md`, `rules/design-laws.md` exist | Run `npx qualia install` |
+| Substrate | `qualia-design/design-rubric.md`, `qualia-design/design-laws.md` exist | Run `npx qualia install` |
 | Brief | `--brief` PATH if provided, else `.planning/DESIGN.md`, else PRODUCT.md | If none, HALT: "No design brief found. Pass --brief or run /qualia-new." |
 | Browser | `node ~/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs --url about:blank --out /tmp/qpl-preflight` exits 0 | HALT with the script's setup hint |
 | URL reachable | `curl -fsS -o /dev/null -w '%{http_code}' "$URL"` returns 2xx/3xx | HALT — start the dev server first |
@@ -91,7 +91,7 @@ node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs record \
 
 Exit codes: `0` = SUCCESS (all dims ≥ 3), `1` = CONTINUE (more iterations), `3` = KILLED (regression / budget / max).
 
-The orchestrator computes the verdict per `rules/design-rubric.md`:
+The orchestrator computes the verdict per `qualia-design/design-rubric.md`:
 
 - **all aggregate scores ≥ 3 AND no critical issues remain** → SUCCESS, exit loop
 - **same issue fingerprint recurred 3 consecutive iterations** → KILL, `LOOP_REGRESSION_DETECTED`

package/skills/qualia-polish-loop/fixtures/broken.html

@@ -1,8 +1,8 @@
 <!doctype html>
 <!--
   Deliberately broken page used by /qualia-polish-loop self-test Scenario 2.
-  Hits multiple absolute-ban patterns from rules/design-laws.md and
-  rules/design-brand.md so the vision evaluator has to identify them all.
+  Hits multiple absolute-ban patterns from qualia-design/design-laws.md and
+  qualia-design/design-brand.md so the vision evaluator has to identify them all.
   Banned font (Inter), pure white + pure black, blue-purple gradient,
   gradient text, identical 3-column card grid, "Get Started" / "Learn More"
   generic CTAs, side-stripe border-left:4px decorative, max-width:1280

package/skills/qualia-polish-loop/scripts/score.mjs

@@ -3,7 +3,7 @@
  * score.mjs -- Qualia visual-polish loop scoring utility.
  *
  * Takes a JSON object with 8 dimension scores and computes pass/fail
- * per the design rubric formula from rules/design-rubric.md.
+ * per the design rubric formula from qualia-design/design-rubric.md.
  *
  * Usage:
  *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs

package/skills/qualia-postmortem/SKILL.md

@@ -95,7 +95,7 @@ matches the failure. Use this lookup:
 | Wave 2 task ran before wave 1 committed | `agents/planner.md` (dependency graph) |
 | Build passed locally, broke in CI | `rules/deployment.md` or a missing pre-deploy-gate scan |
 | RLS missing on new table | `rules/security.md` + `agents/builder.md` (security persona handling) |
-| Design regression — fonts off, contrast fail | `rules/frontend.md` + `skills/qualia-design/SKILL.md` |
+| Design regression — fonts off, contrast fail | `qualia-design/frontend.md` + `skills/qualia-design/SKILL.md` |
 | Migration unsafe (DROP without IF EXISTS, etc.) | `hooks/migration-guard.js` |
 | Verifier missed it | `agents/verifier.md` — most embarrassing case, address with extra care |
 

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-quick
-description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
+description: "Fast inline path for trivial fixes — ≤1 hour, typically 1 file, no plan, NO subagent spawn. The current Claude does the work directly. For a 1-5 file change that justifies a fresh builder context, use /qualia-task instead. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak'."
 allowed-tools:
   - Bash
   - Read

package/skills/qualia-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-research
-description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md."
+description: "Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md. Triggers: 'research X library', 'research the domain before planning', 'study Stripe webhooks', 'how do others do RAG', 'best practices for X', 'compare libraries', 'I need depth before planning phase N'. Distinct from /qualia-recall (which queries the local Obsidian vault) and /qualia-discuss (which interviews the user)."
 allowed-tools:
   - Bash
   - Read
@@ -75,7 +75,8 @@ Reqs: {REQ-IDs for this phase}
 
 <output_path>.planning/phase-{N}-research.md</output_path>
 
-Priority: Context7 → WebFetch → WebSearch.
+Priority: NotebookLM (cross-notebook query) → local knowledge layer (knowledge.js search + qualia-recall) → Context7 → WebFetch → WebSearch.
+Skip web round when local sources cover the question with confidence ≥ MEDIUM (per agents/researcher.md §1b).
 Include: recommendation, rationale, versions, code examples, alternatives, pitfalls, sources.
 ", subagent_type="qualia-researcher", description="Phase {N} research")
 ```
@@ -123,4 +124,5 @@ node ~/.claude/bin/qualia-ui.js end "PHASE {N} RESEARCH DONE" "/qualia-plan {N}"
 1. **One session per run.** Don't research phases 1-5 in one call.
 2. **Must produce a file.** Research in conversation only is worthless.
 3. **Honor locked decisions.** Don't research alternatives to locked choices.
-4. **Context7 first.** Try Context7 MCP before WebFetch.
+4. **Local-first.** Drain NotebookLM and `~/qualia-memory` before any external call. The team has already researched most domains we touch — querying existing notebooks is near-zero token cost AND higher-quality than fresh WebSearch.
+5. **Context7 before WebFetch.** When you do go external, Context7 first for libraries; only WebFetch for non-library content (blog posts, case studies, post-mortems).

package/skills/qualia-road/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-road
-description: "Show the Qualia workflow map in the terminal — Project → Journey → Milestones → Phases → Tasks. Lists every command, when to use it, and how phases chain. Use when user asks 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', or is new to the framework. (For an interactive HTML reference instead, use /qualia-help.)"
+description: "TERMINAL workflow map — Project → Journey → Milestones → Phases → Tasks. Use this in headless/SSH/no-browser sessions or when the user asks for the road in chat. For the HTML reference (default when a browser is available), use /qualia-help. Triggers: 'how does Qualia work', 'what's the workflow', 'show me the road', 'what command does X', 'how do projects flow', 'in terminal please', SSH context."
 disable-model-invocation: true
 allowed-tools:
   - Read
@@ -45,14 +45,24 @@ Every road agent loads `PRODUCT.md + DESIGN.md + design-laws.md` substrate. Buil
 /qualia-polish --quick                       ~1m  gates only
 ```
 
-## /qualia-polish-loop -- autonomous visual QA (v5.1+)
+## /qualia-polish-loop -- autonomous visual QA (v5.1+, hardened in v5.2)
 ```
-/qualia-polish-loop http://localhost:3000     screenshot + eval + fix loop
-/qualia-polish-loop {url} --max 4            cap iterations
-/qualia-polish-loop {url} --ref design.png   anchor to reference image
+/qualia-polish-loop http://localhost:3000                screenshot + eval + fix loop
+/qualia-polish-loop {url} --max 4                       cap iterations
+/qualia-polish-loop {url} --ref design.png              anchor to reference image
+/qualia-polish-loop {url} --reduced-motion              force prefers-reduced-motion (v5.2+)
+/qualia-polish-loop --routes /a,/b,/c                   multi-route sweep (v5.2+)
 ```
 Screenshots at 3 viewports (375/768/1440), scores 8 design dimensions using vision, fixes issues, re-screenshots, loops until all dims >= 3 or kill-switch triggers. Per-iteration git commits for clean revert.
 
+## v5.3+ skills (Matt Pocock gaps closed)
+```
+/qualia-prd            synthesize current conversation → .planning/PRD-{slug}.md (durable feature spec)
+/qualia-hook-gen       convert a CLAUDE.md/rules instruction into a deterministic pre-tool-use hook
+/qualia-optimize --deepen   now spawns 3 parallel interface-design variants per candidate (Step 5b)
+```
+`/qualia-prd` pairs with `/qualia-issues` to form the PRD → vertical-slice → execute loop. `/qualia-hook-gen` reduces lifetime token cost (each migrated rule frees ~50-200 tokens per request). `/qualia-optimize --deepen` produces dramatically better refactor RFCs because 3 radically-different interfaces are surfaced and the human picks/hybridizes.
+
 ## Alignment substrate (v5.0+)
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 

package/skills/qualia-task/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-task
-description: "Builds a single focused task in a fresh builder context with atomic commit and validation. More structured than /qualia-quick, lighter than /qualia-build (no phase plan needed). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file change outside a full phase."
+description: "Single focused task with a FRESH builder subagent spawn — 1-3 hours, 1-5 files, atomic commit, validation contract. Heavier than /qualia-quick (which runs inline with no spawn) but lighter than /qualia-build (which needs a phase plan). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file feature outside a full phase."
 allowed-tools:
   - Bash
   - Read

package/templates/PRODUCT.md

@@ -49,7 +49,7 @@ Sites the project should NOT look like. Anti-references pin down what the design
 - {URL or descriptor} — ...
 ```
 
-For Brand register, these are usually saturated aesthetic lanes (see `rules/design-brand.md`).
+For Brand register, these are usually saturated aesthetic lanes (see `qualia-design/design-brand.md`).
 For Product register, these are usually patterns we don't want to inherit (e.g., "Salesforce Lightning — too dense, too many panels").
 
 ## Positive references (optional, ≤3)

package/tests/bin.test.sh

@@ -1201,7 +1201,7 @@ else
 fi
 
 # 108. package.json version is 5.x (5.1+ accepted; v5.1 / v5.2 share the v5 line)
-if grep -qE '"5\.[123]\.' "$FRAMEWORK_DIR/package.json"; then
+if grep -qE '"5\.[1234]\.' "$FRAMEWORK_DIR/package.json"; then
   pass "package.json version is 5.x"
 else
   fail_case "package.json version not 5.x"
@@ -1430,7 +1430,7 @@ fi
 
 # 128. package.json bumped to 5.x (5.1+ accepted; 5.2 is the v5.2 release)
 PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
-if echo "$PKG_V" | grep -qE "^5\.[123]\."; then
+if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
   pass "package.json version bumped to 5.x ($PKG_V)"
 else
   fail_case "package.json version not 5.x" "got=$PKG_V"
@@ -1577,7 +1577,7 @@ fi
 
 # 143. package.json version is 5.x (5.1+ accepted; v5.3 is the v5.3 release)
 PKG_V=$($NODE -e 'console.log(require("'"$FRAMEWORK_DIR"'/package.json").version)')
-if echo "$PKG_V" | grep -qE "^5\.[123]\."; then
+if echo "$PKG_V" | grep -qE "^5\.[1234]\."; then
   pass "package.json version is 5.x ($PKG_V) — v5.3 accepted"
 else
   fail_case "package.json version not 5.x" "got=$PKG_V"

package/tests/skills.test.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# Qualia Framework — skill smoke tests
+# Verifies every skills/*/SKILL.md is well-formed:
+#   - YAML frontmatter present and parseable
+#   - name field matches folder name
+#   - description present and substantive
+#   - description has trigger phrases (or skill is disable-model-invocation)
+#   - body has at least one h1 heading and 2+ sections
+#
+# Run: bash tests/skills.test.sh
+
+PASS=0
+FAIL=0
+SKILLS_DIR="$(cd "$(dirname "$0")/../skills" && pwd)"
+
+# Skills allowed to ship without trigger phrases — disable-model-invocation
+# skills only fire on explicit slash command, so triggers are optional.
+SKIP_TRIGGER_CHECK=("qualia-road" "qualia-handoff")
+
+pass() {
+  echo "  ✓ $1"
+  PASS=$((PASS + 1))
+}
+
+fail_case() {
+  echo "  ✗ $1"
+  echo "    $2"
+  FAIL=$((FAIL + 1))
+}
+
+is_in_skip_list() {
+  local needle="$1"
+  for x in "${SKIP_TRIGGER_CHECK[@]}"; do
+    [ "$x" = "$needle" ] && return 0
+  done
+  return 1
+}
+
+echo "skills.test.sh — smoke tests for every skills/*/SKILL.md"
+echo ""
+
+for skill_dir in "$SKILLS_DIR"/*/; do
+  name=$(basename "$skill_dir")
+  skill_md="$skill_dir/SKILL.md"
+
+  # Existence
+  if [ ! -f "$skill_md" ]; then
+    fail_case "$name" "SKILL.md not found at $skill_md"
+    continue
+  fi
+
+  # Frontmatter present
+  if ! head -1 "$skill_md" | grep -q "^---$"; then
+    fail_case "$name: frontmatter" "first line is not '---'"
+    continue
+  fi
+  if ! sed -n '2,30p' "$skill_md" | grep -q "^---$"; then
+    fail_case "$name: frontmatter" "no closing --- within first 30 lines"
+    continue
+  fi
+
+  # name field matches folder
+  fm_name=$(grep "^name:" "$skill_md" | head -1 | sed 's/^name:[[:space:]]*//' | tr -d '"')
+  if [ "$fm_name" != "$name" ]; then
+    fail_case "$name: name field" "frontmatter says name=\"$fm_name\", folder is \"$name\""
+    continue
+  fi
+  pass "$name: frontmatter name matches folder"
+
+  # description field present + substantive
+  fm_desc=$(grep "^description:" "$skill_md" | head -1 | sed 's/^description:[[:space:]]*//')
+  desc_len=${#fm_desc}
+  if [ "$desc_len" -lt 50 ]; then
+    fail_case "$name: description" "description is $desc_len chars, expected >= 50"
+    continue
+  fi
+  pass "$name: description present (${desc_len} chars)"
+
+  # Trigger phrases (unless disable-model-invocation or in transitional skip list)
+  if ! is_in_skip_list "$name"; then
+    has_disable=$(grep -c "disable-model-invocation:[[:space:]]*true" "$skill_md")
+    if [ "$has_disable" = "0" ]; then
+      if echo "$fm_desc" | grep -qiE "trigger|when user|use when|invoke|says|use this|fire on|user types"; then
+        pass "$name: description has trigger guidance"
+      else
+        fail_case "$name: triggers" "description lacks trigger phrases (Trigger:/Use when:/'says'/etc.) and skill is not disable-model-invocation"
+      fi
+    fi
+  fi
+
+  # Body has an h1 heading
+  h1_count=$(grep -cE "^# " "$skill_md")
+  if [ "$h1_count" -ge 1 ]; then
+    pass "$name: body has h1 heading"
+  else
+    fail_case "$name: body" "no h1 heading (^# ) in body"
+  fi
+
+  # Body has at least one section (any ## heading)
+  h2_count=$(grep -cE "^## " "$skill_md")
+  if [ "$h2_count" -ge 1 ]; then
+    pass "$name: body has section heading (${h2_count} found)"
+  else
+    fail_case "$name: body" "no '## ' section heading; every skill needs at least one"
+  fi
+
+  # Cache-aware spawn audit (per rules/grounding.md):
+  # Every spawn to a CUSTOM (qualia-*) agent must anchor the prompt with
+  # `@~/.claude/agents/{name}.md` (either `Role: @...` or `Read your role:
+  # @...` — both forms accepted). The role file is session-stable; placing
+  # it first lets Anthropic's prompt cache reuse the prefix across spawns
+  # (documented 81-90% cost reduction). If task-specific content lands
+  # before the role anchor, the entire prefix recomputes on every spawn.
+  #
+  # Built-in subagent types (Explore, general-purpose, Plan, etc.) have
+  # stable system-prompt baselines on Anthropic's side; no Role anchor
+  # required. We count only `subagent_type="qualia-*"` spawns.
+  #
+  # Some skills follow progressive-disclosure discipline (e.g.
+  # qualia-polish-loop) and put the literal spawn template in REFERENCE.md
+  # while SKILL.md mentions the spawn in prose. We scan both.
+  custom_spawn_count=$(grep -c 'subagent_type="qualia-' "$skill_md")
+  ref_md="$skill_dir/REFERENCE.md"
+  if [ -f "$ref_md" ]; then
+    custom_spawn_count=$((custom_spawn_count + $(grep -c 'subagent_type="qualia-' "$ref_md")))
+  fi
+  if [ "${custom_spawn_count:-0}" -gt 0 ]; then
+    role_count=$(grep -cE '@~/\.claude/agents/' "$skill_md")
+    if [ -f "$ref_md" ]; then
+      role_count=$((role_count + $(grep -cE '@~/\.claude/agents/' "$ref_md")))
+    fi
+    if [ "${role_count:-0}" -ge "$custom_spawn_count" ]; then
+      pass "$name: spawn audit ($custom_spawn_count custom spawn(s), all role-anchored for cache)"
+    else
+      fail_case "$name: spawn audit" "$custom_spawn_count custom spawn(s) but only ${role_count:-0} '@~/.claude/agents/' anchors — prompt cache will miss"
+    fi
+  fi
+done
+
+echo ""
+echo "=== Results: $PASS passed, $FAIL failed ==="
+
+[ "$FAIL" = "0" ]