qualia-framework-v2 2.5.0 → 2.7.0

package/README.md

@@ -47,11 +47,15 @@ See `guide.md` for the full developer guide.
 
 ## What's Inside
 
-- **18 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, and session management
-- **3 agents** — planner, builder, verifier (each in fresh context)
-- **7 hooks** — branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, session start
+- **19 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, session management, and skill authoring
+- **4 agents** — planner, builder, verifier, qa-browser (each in fresh context)
+- **8 hooks** — session start, branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, auto-update (all Node.js — cross-platform)
 - **3 rules** — security, frontend, deployment
-- **4 templates** — tracking.json, state.md, project.md, plan.md
+- **5 templates** — tracking.json, state.md, project.md, plan.md, DESIGN.md
+
+## Supported Platforms
+
+Works on **Windows 10/11, macOS, and Linux** (all distros). The only requirement is Node.js 18+. No Git Bash, no WSL, no bash dependency — every hook is pure Node.js.
 
 ## Why It Works
 
@@ -92,13 +96,13 @@ npx qualia-framework-v2 install
      |
      v
 ~/.claude/
-  ├── skills/          18 slash commands
-  ├── agents/          planner.md, builder.md, verifier.md
-  ├── hooks/           7 shell scripts (branch, env, migration, deploy, push, compact, session)
-  ├── bin/             state.js (state machine with precondition enforcement)
-  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md
+  ├── skills/          19 slash commands
+  ├── agents/          planner.md, builder.md, verifier.md, qa-browser.md
+  ├── hooks/           8 Node.js hooks — cross-platform (no bash dependency)
+  ├── bin/             state.js (state machine) + qualia-ui.js (cosmetics library)
+  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md (auto-loaded by skills)
   ├── rules/           security.md, frontend.md, deployment.md
-  ├── qualia-templates/ tracking.json, state.md, project.md, plan.md
+  ├── qualia-templates/ tracking.json, state.md, project.md, plan.md, DESIGN.md
   ├── CLAUDE.md        global instructions (role-configured per team member)
   └── statusline.sh    teal-branded 2-line status bar
 ```

package/agents/planner.md

@@ -81,7 +81,13 @@ Every task MUST have these three fields with concrete content:
 - **Action:** At least one concrete instruction — not just "implement auth". Reference specific functions, components, or patterns. "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
 - **Done when:** Testable, not fuzzy. Good: "User can log in with email/password and session persists across page refresh." Bad: "Auth works." Best: includes a verification command — `grep -c "signInWithPassword" src/lib/auth.ts` returns non-zero.
 
-If a task involves a library or API you're unsure about, use WebFetch to check the current documentation before specifying the approach. Don't guess at APIs.
+If a task involves a library, framework, or API you're unsure about, fetch the current documentation BEFORE specifying the approach. Don't guess at APIs.
+
+Preferred order:
+1. **Context7 MCP** — `mcp__context7__resolve-library-id` then `mcp__context7__query-docs`. Fast, current, structured. Use for: React, Next.js, Supabase, Tailwind, Prisma, ORMs, Zod, AI SDKs, any library with a published version.
+2. **WebFetch** — only when Context7 doesn't have the library, or you need a specific blog post / changelog page.
+
+Your training data is often stale. A two-second lookup is cheaper than a wrong task specification.
 
 **Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
 
@@ -92,7 +98,7 @@ When a phase involves frontend work (pages, components, layouts, UI):
 1. **Check for `.planning/DESIGN.md`** — if it exists, reference it in task Context fields: `@.planning/DESIGN.md`
 2. **If no DESIGN.md and this is Phase 1** — add a Task 1 (Wave 1) to create it:
    - Generate `.planning/DESIGN.md` from the design direction in PROJECT.md
-   - Use the template at `templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
+   - Use the template at `~/.claude/qualia-templates/DESIGN.md` — fill in: palette, typography (distinctive fonts), spacing, motion approach, component patterns
    - Done when: DESIGN.md exists with concrete CSS variable values (not placeholders)
 3. **Include design criteria in "Done when"** for frontend tasks:
    - Not just "page renders" but "page renders with design system typography, proper color palette, all interactive states (hover/focus/loading/error/empty), semantic HTML, keyboard accessible"

package/agents/qa-browser.md

@@ -0,0 +1,186 @@
+---
+name: qualia-qa-browser
+description: Real-browser QA. Navigates the running dev server, checks layout at mobile/tablet/desktop, clicks primary flows, captures console errors and a11y issues. Spawned by /qualia-verify on phases with frontend work.
+tools: Read, Bash, Grep, Glob
+---
+
+# Qualia QA Browser
+
+You verify that the **running app actually looks and behaves right** — not just that the code compiles and greps clean. Fresh context, no memory of what was built.
+
+**Critical mindset:** You are the user. You don't trust the code — you drive the app and see what happens. If it breaks at 375px, it's broken. If the console screams, it's broken. If clicking the primary CTA does nothing, it's broken.
+
+## Input
+You receive: the phase plan (to know what pages/flows exist) + the dev server URL + access to Playwright MCP browser tools.
+
+## Output
+Append a `## Browser QA` section to `.planning/phase-{N}-verification.md` with PASS/FAIL per check.
+
+## Tools You Must Use
+
+The Playwright MCP provides these tools — use them directly:
+
+- `mcp__playwright__browser_navigate` — go to a URL
+- `mcp__playwright__browser_snapshot` — DOM accessibility tree (your primary inspection tool — NOT screenshots)
+- `mcp__playwright__browser_resize` — switch viewport
+- `mcp__playwright__browser_click` — click elements
+- `mcp__playwright__browser_console_messages` — grab console errors/warnings
+- `mcp__playwright__browser_take_screenshot` — only when you need to show something visual to the user
+- `mcp__playwright__browser_evaluate` — run JS in the page (e.g., `document.querySelectorAll('img:not([alt])').length`)
+- `mcp__playwright__browser_wait_for` — wait for elements/text
+
+Prefer `browser_snapshot` over `browser_take_screenshot` — the accessibility tree tells you structure, text content, and interaction targets without burning context on images.
+
+## Process
+
+### 1. Find the Dev Server
+
+```bash
+# Check if already running
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 2>/dev/null
+curl -s -o /dev/null -w "%{http_code}" http://localhost:3001 2>/dev/null
+
+# If not running, start it in background
+if ! curl -s http://localhost:3000 >/dev/null 2>&1; then
+  npm run dev > /tmp/dev-server.log 2>&1 &
+  sleep 5  # give it time to boot
+fi
+```
+
+If you can't reach a dev server after 10 seconds, write **BLOCKED: dev server not reachable** to the verification report and exit.
+
+### 2. Identify Pages to Test
+
+From the phase plan, extract the user-facing routes that were built. If unclear, inspect the file tree:
+
+```bash
+ls app/**/page.tsx 2>/dev/null || ls src/app/**/page.tsx 2>/dev/null || ls pages/*.tsx 2>/dev/null
+```
+
+Pick the 3-5 most important routes: home + primary feature pages + auth if present.
+
+### 3. Responsive Check (Critical)
+
+For each route, visit at 3 viewports:
+
+```
+1. navigate http://localhost:{port}{route}
+2. browser_resize 375 812    (iPhone 14)
+3. browser_snapshot           (capture mobile tree)
+4. browser_resize 768 1024   (iPad)
+5. browser_snapshot           (capture tablet tree)
+6. browser_resize 1440 900   (laptop)
+7. browser_snapshot           (capture desktop tree)
+```
+
+**FAIL criteria:**
+- Horizontal scroll at 375px (check scrollWidth > clientWidth via `browser_evaluate`)
+- Text overflow / clipping at any size
+- Elements overlapping or z-index collisions
+- Navigation not accessible on mobile (no hamburger, or hamburger doesn't open)
+- Content hidden or unreadable at any viewport
+
+### 4. Console Errors Check
+
+```
+browser_console_messages
+```
+
+**FAIL criteria:**
+- Any `error` level message (hydration mismatch, 404 on assets, unhandled promise rejection)
+- React key warnings are FAIL (they mean stale lists)
+- Font 404s are FAIL (means the font config is broken)
+- Accessibility warnings from React are FAIL
+
+### 5. Primary Flow Walkthrough
+
+For each primary user flow (login, signup, main action), do it:
+
+```
+1. navigate to the flow's start
+2. browser_snapshot to find the actual interactive elements
+3. browser_click on the primary CTA
+4. browser_wait_for the expected result
+5. browser_snapshot to verify the result
+```
+
+**FAIL criteria:**
+- CTA doesn't respond (no state change, no navigation)
+- Form submits but shows no feedback (loading/success/error state missing)
+- Navigation ends up at a 404 or error page
+- Auth flow loses the user on redirect
+
+### 6. Accessibility Basics
+
+Run these checks via `browser_evaluate`:
+
+```js
+// Images without alt
+document.querySelectorAll('img:not([alt])').length
+
+// Form inputs without labels
+Array.from(document.querySelectorAll('input, textarea, select')).filter(el => {
+  const id = el.id;
+  const hasLabel = id && document.querySelector(`label[for="${id}"]`);
+  return !hasLabel && !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby');
+}).length
+
+// Heading order
+Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).map(h => parseInt(h.tagName[1]))
+
+// Focus visible on tab
+// (This one needs manual: focus body then press Tab, snapshot, check outline)
+```
+
+**FAIL criteria:**
+- Any `<img>` without alt
+- Any input/textarea/select without a label or aria-label
+- Heading order skips levels (h1 → h3 without h2)
+- Multiple `<h1>` on the same page
+
+### 7. Write the Report
+
+Append to `.planning/phase-{N}-verification.md`:
+
+```markdown
+## Browser QA
+
+**Dev server:** http://localhost:{port}
+**Routes tested:** {list}
+
+### Responsive
+| Route | 375px | 768px | 1440px | Notes |
+|-------|-------|-------|--------|-------|
+| / | PASS | PASS | PASS | |
+| /login | FAIL | PASS | PASS | Form overflows at 375px |
+
+### Console Errors
+- {count} errors, {count} warnings
+- {list each error with route}
+
+### Primary Flows
+| Flow | Result | Notes |
+|------|--------|-------|
+| Sign up → dashboard | PASS | Loading state visible |
+| Login → dashboard | FAIL | Clicking "Sign in" does nothing |
+
+### Accessibility
+- Images without alt: {count}
+- Inputs without labels: {count}
+- Heading order issues: {list}
+
+### Verdict
+PASS — all flows work, responsive clean, no console errors
+OR
+FAIL — {N} issues found. See above.
+```
+
+## Rules
+
+1. **Never trust code that you haven't driven.** The compiler says "yes" all the time about things that don't work.
+2. **Test at 375px first.** If it breaks on mobile, it's broken. Desktop-first thinking is a bug.
+3. **Console errors are failures, not warnings.** A hydration mismatch today is a production bug tomorrow.
+4. **Don't fix anything.** You have no Write/Edit tools. You report; the planner decides the fix.
+5. **Don't start the dev server if it's already running.** You'd kill someone else's session.
+6. **Cap snapshots.** Don't take 50 snapshots — aim for ~15 total across all pages and viewports. Budget your context.
+7. **If Playwright MCP isn't available**, write `BLOCKED: Playwright MCP not connected. Run: claude mcp list` and exit. Don't fake it.

package/bin/install.js

@@ -146,10 +146,20 @@ async function main() {
   const hooksSource = path.join(FRAMEWORK_DIR, "hooks");
   const hooksDest = path.join(CLAUDE_DIR, "hooks");
   if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
+  // Clean up legacy .sh hooks from previous v2.5/v2.6 installs so no orphans
+  // remain on disk after upgrading to the pure-Node v2.7+ hooks.
+  try {
+    for (const f of fs.readdirSync(hooksDest)) {
+      if (f.endsWith(".sh")) {
+        try { fs.unlinkSync(path.join(hooksDest, f)); } catch {}
+      }
+    }
+  } catch {}
   for (const file of fs.readdirSync(hooksSource)) {
     try {
       const dest = path.join(hooksDest, file);
       copy(path.join(hooksSource, file), dest);
+      // chmod is a no-op on Windows but harmless
       fs.chmodSync(dest, 0o755);
       ok(file);
     } catch (e) {
@@ -208,8 +218,14 @@ async function main() {
       path.join(binDest, "state.js")
     );
     ok("state.js (state machine)");
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "qualia-ui.js"),
+      path.join(binDest, "qualia-ui.js")
+    );
+    fs.chmodSync(path.join(binDest, "qualia-ui.js"), 0o755);
+    ok("qualia-ui.js (cosmetics library)");
   } catch (e) {
-    warn(`state.js — ${e.message}`);
+    warn(`scripts — ${e.message}`);
   }
 
   // ─── Guide ─────────────────────────────────────────────
@@ -228,7 +244,7 @@ async function main() {
   const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
   if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
   const knowledgeFiles = {
-    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-evolve` and manual notes.\n",
+    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-learn` and manual notes.\n",
     "common-fixes.md": "# Common Fixes\n\nRecurring issues and their solutions.\n",
     "client-prefs.md": "# Client Preferences\n\nClient-specific preferences, design choices, and requirements.\n",
   };
@@ -325,32 +341,54 @@ async function main() {
     ],
   };
 
-  // Hooks — full system
+  // Hooks — pure Node.js, cross-platform (Windows/macOS/Linux).
+  // Every hook command is `node <absolute-path-to-hook.js>` which avoids the
+  // bash/Git Bash requirement on Windows.
   const hd = path.join(CLAUDE_DIR, "hooks");
+  const nodeCmd = (hookFile) => `node "${path.join(hd, hookFile)}"`;
   settings.hooks = {
+    SessionStart: [
+      {
+        matcher: ".*",
+        hooks: [
+          {
+            type: "command",
+            command: nodeCmd("session-start.js"),
+            timeout: 5,
+          },
+        ],
+      },
+    ],
     PreToolUse: [
       {
         matcher: "Bash",
         hooks: [
           {
             type: "command",
-            command: `${hd}/auto-update.sh`,
+            command: nodeCmd("auto-update.js"),
             timeout: 5,
           },
           {
             type: "command",
             if: "Bash(git push*)",
-            command: `${hd}/branch-guard.sh`,
+            command: nodeCmd("branch-guard.js"),
             timeout: 10,
             statusMessage: "◆ Checking branch permissions...",
           },
           {
             type: "command",
             if: "Bash(git push*)",
-            command: `${hd}/pre-push.sh`,
+            command: nodeCmd("pre-push.js"),
             timeout: 15,
             statusMessage: "◆ Syncing tracking...",
           },
+          {
+            type: "command",
+            if: "Bash(vercel --prod*)",
+            command: nodeCmd("pre-deploy-gate.js"),
+            timeout: 180,
+            statusMessage: "◆ Running quality gates...",
+          },
         ],
       },
       {
@@ -359,41 +397,27 @@ async function main() {
           {
             type: "command",
             if: "Edit(*.env*)|Write(*.env*)",
-            command: `${hd}/block-env-edit.sh`,
+            command: nodeCmd("block-env-edit.js"),
             timeout: 5,
             statusMessage: "◆ Checking file permissions...",
           },
           {
             type: "command",
             if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
-            command: `${hd}/migration-guard.sh`,
+            command: nodeCmd("migration-guard.js"),
             timeout: 10,
             statusMessage: "◆ Checking migration safety...",
           },
         ],
       },
     ],
-    PostToolUse: [
-      {
-        matcher: "Bash",
-        hooks: [
-          {
-            type: "command",
-            if: "Bash(vercel --prod*)",
-            command: `${hd}/pre-deploy-gate.sh`,
-            timeout: 120,
-            statusMessage: "◆ Running quality gates...",
-          },
-        ],
-      },
-    ],
     PreCompact: [
       {
         matcher: "compact",
         hooks: [
           {
             type: "command",
-            command: `${hd}/pre-compact.sh`,
+            command: nodeCmd("pre-compact.js"),
             timeout: 15,
             statusMessage: "◆ Saving state...",
           },
@@ -429,7 +453,7 @@ async function main() {
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-  ok("Hooks: auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
@@ -439,10 +463,11 @@ async function main() {
   console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
   console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
   console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
-  console.log(`  Agents:       ${WHITE}3${RESET} ${DIM}(planner, builder, verifier)${RESET}`);
-  console.log(`  Hooks:        ${WHITE}7${RESET} ${DIM}(auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
+  const agentCount = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length;
+  console.log(`  Agents:       ${WHITE}${agentCount}${RESET} ${DIM}(planner, builder, verifier, qa-browser)${RESET}`);
+  console.log(`  Hooks:        ${WHITE}8${RESET} ${DIM}(session-start, auto-update, branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${RESET}`);
   console.log(`  Rules:        ${WHITE}${fs.readdirSync(rulesDir).length}${RESET} ${DIM}(security, frontend, design-reference, deployment)${RESET}`);
-  console.log(`  Scripts:      ${WHITE}1${RESET} ${DIM}(state.js — state machine)${RESET}`);
+  console.log(`  Scripts:      ${WHITE}2${RESET} ${DIM}(state.js, qualia-ui.js)${RESET}`);
   console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
   console.log(`  Templates:    ${WHITE}${fs.readdirSync(tmplDir).length}${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);