qualia-framework 2.6.0 → 3.1.0

package/skills/qualia-review/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: qualia-review
+description: "Production audit with scored diagnostics. Runs real commands, scores findings by severity. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+---
+
+# /qualia-review — Production Audit
+
+Runs real diagnostic commands and scores every finding. Not a checklist — an executable audit.
+
+## Usage
+
+- `/qualia-review` — Full audit (security + quality + performance)
+- `/qualia-review --web` — Adds web-specific checks (headers, CORS, vitals)
+- `/qualia-review --ai` — Adds AI/voice agent checks (prompt safety, latency)
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner review
+```
+
+### 0. Load Context
+
+```bash
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+```
+
+Detect project shape:
+```bash
+ls package.json next.config.* tsconfig.json supabase/ app/ src/ 2>/dev/null
+```
+
+### 1. Security Scan
+
+Run every command. Record each finding with severity.
+
+```bash
+# CRITICAL: service_role in client code
+grep -rn "service_role" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.server\.\|[\\/]server[\\/]\|[\\/]app[\\/]api[\\/]\|route\.\|middleware\."
+
+# CRITICAL: hardcoded secrets
+grep -rn "sk_live\|sk_test\|SUPABASE_SERVICE_ROLE\|eyJhbGciOi" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | grep -v "\.env"
+
+# CRITICAL: dangerous patterns
+grep -rn "dangerouslySetInnerHTML\|eval(" --include="*.ts" --include="*.tsx" --include="*.js" app/ components/ src/ 2>/dev/null | grep -v node_modules
+
+# CRITICAL: .env files tracked in git
+git ls-files | grep -i "\.env" | grep -v "\.example\|\.template\|\.sample"
+
+# HIGH: API routes without auth
+for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
+  grep -qL "getUser\|getSession\|auth()\|createClient" "$f" && echo "UNPROTECTED: $f"
+done
+
+# HIGH: API routes without input validation
+for f in $(find app/api -name "route.ts" -o -name "route.js" 2>/dev/null); do
+  grep -L "z\.\|zod\|Zod\|parse\|safeParse" "$f" 2>/dev/null
+done
+
+# HIGH: client-side database mutations
+grep -rn "\.insert\|\.update\|\.delete\|\.upsert" --include="*.tsx" --include="*.jsx" app/ components/ 2>/dev/null | grep -v "use server" | grep -v "\.server\."
+
+# MEDIUM: npm vulnerabilities
+npm audit --json 2>/dev/null | node -e "try{const d=JSON.parse(require('fs').readFileSync(0,'utf8'));const v=d.metadata?.vulnerabilities||{};console.log('critical:',v.critical||0,'high:',v.high||0,'moderate:',v.moderate||0)}catch{console.log('audit unavailable')}"
+```
+
+### 2. Code Quality Scan
+
+```bash
+# TypeScript errors (HIGH if >0)
+npx tsc --noEmit 2>&1 | grep -c "error TS"
+
+# 'any' type usage (MEDIUM — count)
+grep -rn ": any\| as any" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | wc -l
+
+# Empty catch blocks (HIGH)
+grep -rn "catch\s*{}\|catch\s*(.*)\s*{\s*}" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | head -10
+
+# TODO/FIXME left in code (LOW — count)
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" app/ components/ src/ lib/ 2>/dev/null | grep -v node_modules | wc -l
+
+# console.log in production code (LOW — count)
+grep -rn "console\.log" --include="*.ts" --include="*.tsx" app/ components/ src/ 2>/dev/null | grep -v node_modules | wc -l
+```
+
+### 3. Performance Scan
+
+```bash
+# Build output — route sizes and first load JS
+npx next build 2>&1 | grep -E "Route|First Load|shared by all|○|●|ƒ|λ" | tail -25
+
+# Heavy files (>300 lines often means split needed)
+find app/ components/ src/ -name "*.tsx" -o -name "*.ts" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -10
+
+# Missing next/image (MEDIUM)
+grep -rn "<img " --include="*.tsx" --include="*.jsx" app/ components/ src/ 2>/dev/null | grep -v "next/image" | wc -l
+
+# Client component ratio
+echo "use client: $(grep -rl "'use client'" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l)"
+echo "total tsx: $(find app/ components/ src/ -name '*.tsx' 2>/dev/null | wc -l)"
+
+# Sequential data fetching (HIGH)
+grep -rn "const.*=.*await" --include="*.tsx" --include="*.ts" app/ src/ 2>/dev/null | grep -v "Promise.all\|Promise.allSettled" | head -10
+```
+
+### 4. Score and Report
+
+Write to `.planning/REVIEW.md`:
+
+```markdown
+# Production Review — {YYYY-MM-DD}
+
+## Summary
+| Category | Critical | High | Medium | Low | Score |
+|----------|----------|------|--------|-----|-------|
+| Security | {n} | {n} | {n} | {n} | {1-5} |
+| Quality  | {n} | {n} | {n} | {n} | {1-5} |
+| Perf     | {n} | {n} | {n} | {n} | {1-5} |
+| **Total** | {n} | {n} | {n} | {n} | **{avg}/5** |
+
+## Findings
+
+### CRITICAL
+- **{title}** — `{file}:{line}` — {what's wrong} — Fix: {how}
+
+### HIGH
+- ...
+
+### MEDIUM
+- ...
+
+### LOW
+- ...
+
+## Verdict
+{PASS: no critical/high | FAIL: N blockers — fix before /qualia-ship}
+```
+
+**Scoring:**
+- 5 = zero high/critical, fewer than 3 medium
+- 4 = zero critical, 1 high or fewer than 5 medium
+- 3 = zero critical, 2-3 high
+- 2 = 1 critical or 4+ high
+- 1 = multiple critical
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Security: {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js info "Quality:  {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js info "Perf:     {score}/5 ({n} findings)"
+node ~/.claude/bin/qualia-ui.js end "REVIEW: {PASS|FAIL}" "{next command}"
+```
+
+## Rules
+
+1. **Run every command.** Don't skip scans because "the code looks clean."
+2. **Every finding gets a severity.** No prose — CRITICAL/HIGH/MEDIUM/LOW.
+3. **Every finding gets a fix suggestion.** Not just "this is bad" — say what to do.
+4. **Review detects. It does NOT fix.** This is an audit, not a refactor. Tell the user what to fix.
+5. **CRITICAL or HIGH = deploy blocker.** `/qualia-ship` checks for these.

package/skills/qualia-ship/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: qualia-ship
+description: "Deploy to production — quality gates, commit, push, deploy, verify. Use when ready to go live."
+---
+
+# /qualia-ship — Deploy
+
+Full deployment pipeline with quality gates.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner ship
+```
+
+### 1. Quality Gates
+
+Run in sequence. Auto-fix failures (up to 2 attempts).
+
+```bash
+npx tsc --noEmit          # TypeScript — must pass
+npx eslint . --max-warnings 0   # Lint — auto-fix first
+npm run build             # Build — must succeed
+```
+
+On failure:
+1. Summarize what failed in plain language
+2. Auto-fix
+3. Re-run the gate
+4. If still failing after 2 attempts: tell the employee, suggest `/qualia-debug`
+
+### 2. Security Check
+
+```bash
+# service_role in client code?
+grep -r "service_role" app/ components/ src/ 2>/dev/null | grep -v node_modules | grep -v ".server."
+# Should be ZERO matches
+```
+
+### 3. Git
+
+```bash
+git add {specific changed files}
+git commit -m "ship: {project name} production deploy"
+git push
+```
+
+Employee stays on feature branch. Never push to main.
+
+### 4. Deploy
+
+```bash
+vercel --prod              # Website/AI agent
+# OR
+supabase functions deploy  # Edge functions
+# OR
+wrangler deploy            # Cloudflare Workers
+```
+
+### 5. Post-Deploy Verification
+
+```bash
+# HTTP 200
+curl -s -o /dev/null -w "%{http_code}" {domain}
+
+# Latency under 500ms
+curl -s -o /dev/null -w "%{time_total}" {domain}
+
+# Auth endpoint responds
+curl -s -o /dev/null -w "%{http_code}" {domain}/api/auth/callback
+```
+
+### 6. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "URL: {production url}"
+node ~/.claude/bin/qualia-ui.js ok "Status: HTTP 200"
+node ~/.claude/bin/qualia-ui.js ok "Latency: {time}ms"
+node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to shipped --deployed-url {production url}
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "SHIPPED" "/qualia-handoff"
+```

package/skills/qualia-skill-new/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: qualia-skill-new
+description: "Author a new Qualia skill or agent. Use when the user says 'create a new skill', 'add a skill', 'I want to build a skill', 'make this a reusable command', 'turn this into a skill'. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo."
+---
+
+# /qualia-skill-new — Author a New Skill
+
+You are about to create a reusable slash command. Skills are the leverage of the Qualia framework — if the team does something twice, it probably belongs here.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner skill-new
+```
+
+### 1. Scope Decision
+
+Ask the user with AskUserQuestion:
+
+```
+question: "Where should this skill live?"
+header: "Scope"
+options:
+  - label: "Framework skill (ships to the team)"
+    description: "Edit qualia-framework repo. Everyone gets it on next update."
+  - label: "Local skill (just me)"
+    description: "Lives only in ~/.claude/skills/. Not shared."
+  - label: "Agent instead of a skill"
+    description: "This is a subagent role, not a slash command. Creates agents/{name}.md."
+```
+
+### 1a. Resolve framework directory
+
+If the user chose **Framework skill** or a framework-scoped **Agent**, resolve `${FRAMEWORK_DIR}` — the checkout path of this user's qualia-framework repo — BEFORE computing any target paths. Never hardcode `/home/<user>/...`; different teammates and operating systems have different paths.
+
+```bash
+# Priority order: env var → git detection → ask user
+FRAMEWORK_DIR="${QUALIA_FRAMEWORK_DIR:-}"
+if [ -z "$FRAMEWORK_DIR" ] && git -C . rev-parse --show-toplevel >/dev/null 2>&1; then
+  ORIGIN=$(git -C . config --get remote.origin.url 2>/dev/null)
+  case "$ORIGIN" in
+    *qualia-framework*) FRAMEWORK_DIR=$(git -C . rev-parse --show-toplevel) ;;
+  esac
+fi
+echo "${FRAMEWORK_DIR:-UNRESOLVED}"
+```
+
+If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework checkout? (absolute path, or type 'local' to save only to ~/.claude/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
+
+**Framework** → target: `${FRAMEWORK_DIR}/skills/{name}/SKILL.md`
+**Local** → target: `~/.claude/skills/{name}/SKILL.md`
+**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `~/.claude/agents/{name}.md` (local)
+
+### 2. Gather Requirements
+
+Ask the user — one question at a time, natural conversation:
+
+1. **"What's the name?"** — kebab-case, prefix with `qualia-` for framework skills. E.g., `qualia-seed-db`.
+2. **"What does it do?"** — one sentence, used as the description.
+3. **"How does the user invoke it?"** — trigger phrases they'd naturally say. E.g., "seed the database", "load test data", "populate dev db".
+4. **"Does it need planning / building / verification?"** — if yes, it probably should spawn an agent. If no, it's a direct-action skill.
+5. **"What files does it read or write?"** — tells you what tools to restrict to.
+
+### 3. Read Reference Skills
+
+Before writing, read two existing skills that are structurally similar:
+
+```bash
+# Short direct-action skill reference:
+cat ~/.claude/skills/qualia-learn/SKILL.md
+
+# Skill-that-spawns-an-agent reference:
+cat ~/.claude/skills/qualia-plan/SKILL.md
+
+# Interactive wizard reference:
+cat ~/.claude/skills/qualia-new/SKILL.md
+```
+
+Pick the closest pattern and copy its structure.
+
+### 4. Write the SKILL.md
+
+Every SKILL.md MUST have:
+
+```markdown
+---
+name: {kebab-case-name}
+description: "{one sentence}. {trigger phrases}"
+---
+
+# /{name} — {Human Title}
+
+{one-paragraph explanation}
+
+## Usage
+
+`/{name}` — {default behavior}
+`/{name} {arg}` — {with argument}
+
+## Process
+
+### 1. {First Step}
+{specifics}
+
+### 2. {Second Step}
+{specifics}
+
+### N. Update State (only if this skill changes project state)
+
+```bash
+node ~/.claude/bin/state.js transition --to {status} ...
+```
+Do NOT manually edit STATE.md or tracking.json.
+```
+
+**Description field rules:**
+- MUST include trigger phrases the user would naturally say
+- The Claude Code router matches user messages against descriptions — if you don't list triggers, the skill never fires
+- Bad: `"Manages database seeding."` (no triggers)
+- Good: `"Seed the database with test data. Trigger on 'seed db', 'load test data', 'populate dev'."`
+
+### 5. Test the Skill
+
+Spawn a fresh subagent to simulate running the skill — does it make sense without the context you have right now?
+
+```
+Agent(prompt="
+Read this skill: @~/.claude/skills/{name}/SKILL.md
+
+Pretend the user just said '{one of the trigger phrases}'. Walk through what you would do, step by step. Flag anything ambiguous or missing.
+", subagent_type="general-purpose", description="Test skill {name}")
+```
+
+Fix any ambiguity the test agent found.
+
+### 6. Install (if framework skill)
+
+```bash
+# Framework skill — copy to local .claude for immediate testing
+mkdir -p ~/.claude/skills/{name}
+cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ~/.claude/skills/{name}/SKILL.md
+
+# Verify it parses
+node -e "const fs=require('fs');const os=require('os');const path=require('path');const c=fs.readFileSync(path.join(os.homedir(),'.claude/skills/{name}/SKILL.md'),'utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
+```
+
+### 7. Commit (framework skills only)
+
+Do NOT commit unless the user explicitly says "commit" or "ship it".
+
+When they do:
+```bash
+cd "${FRAMEWORK_DIR}"
+git add skills/{name}/
+git commit -m "feat: add /{name} skill"
+```
+
+Remind the user to run `npx qualia-framework update` on their other machines, or bump the version and `npm publish`.
+
+## Anti-Patterns
+
+- ❌ **Description without triggers** — the skill won't fire
+- ❌ **Multiple commands in one skill** — split into two skills
+- ❌ **Direct file writes instead of state.js** — always use state.js for STATE.md/tracking.json
+- ❌ **Hardcoded project paths** — use `.planning/` relative or `~/.claude/` absolute, never `/home/specific-user/`
+- ❌ **Skills that spawn agents without passing PROJECT.md and STATE.md context** — agents are blind by default
+- ❌ **Skills longer than ~150 lines** — split or move logic to an agent

package/skills/qualia-task/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: qualia-task
+description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+---
+
+# /qualia-task — Single Task Builder
+
+Build one thing properly. Fresh builder context, atomic commit, but no phase plan needed.
+
+## Usage
+`/qualia-task` — describe what to build interactively
+`/qualia-task {description}` — build it directly
+
+## When to Use
+- One feature, 1-5 files, clear scope, 1-3 hours of work
+- Adding a single feature, component, API route, or integration
+- Refactoring one module
+- Building something specific someone asked for
+
+## Process
+
+### 1. Clarify
+
+If no description provided, ask: **"What do you want to build?"**
+
+Then use AskUserQuestion:
+
+```
+question: "How complex is this task?"
+header: "Scope"
+options:
+  - label: "Small (1-2hrs)"
+    description: "Single file or component, straightforward implementation"
+  - label: "Medium (2-3hrs)"
+    description: "Multiple files, some integration work, needs testing"
+  - label: "Large (3hrs+)"
+    description: "Significant feature, multiple components — use /qualia-plan instead"
+```
+
+If "Large" — suggest `/qualia-plan` instead. Ask if they want to proceed anyway.
+
+### 2. Task Spec
+
+Write a quick task spec (don't save to file, just confirm with user):
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner task
+node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
+node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify}"
+node ~/.claude/bin/qualia-ui.js info "Done: {what done looks like}"
+```
+
+Ask: **"Good to build?"**
+
+### 3. Build
+
+Spawn a builder agent with the task:
+
+```
+Agent(subagent_type: "qualia-builder")
+
+Task: {task description}
+Files: {files to create/modify}
+Done when: {completion criteria}
+
+Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
+```
+
+The builder runs in fresh context — reads before writing, follows rules, commits atomically.
+
+### 4. Verify
+
+After the builder finishes:
+- Run `npx tsc --noEmit` if TypeScript
+- Quick smoke test if applicable
+- Review what was built
+
+### 5. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Task: {description}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
+node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
+node ~/.claude/bin/qualia-ui.js end "TASK COMPLETE"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{task description}"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-test/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: qualia-test
+description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
+---
+
+# /qualia-test — Test Generator
+
+Generate tests for client project code. Detect framework, classify targets, write tests, run them.
+
+## Usage
+
+- `/qualia-test` — Generate tests for recently changed files
+- `/qualia-test {file}` — Generate tests for a specific file
+- `/qualia-test --run` — Run existing tests and report
+- `/qualia-test --coverage` — Run with coverage report
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner test
+```
+
+### 1. Detect Test Framework
+
+```bash
+node -e "
+const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));
+const d={...p.dependencies,...p.devDependencies};
+console.log(JSON.stringify({
+  vitest: !!d.vitest,
+  jest: !!d.jest,
+  playwright: !!d['@playwright/test'],
+  testing_library: !!d['@testing-library/react']
+}))
+"
+```
+
+If no test framework found, install vitest (lighter than jest for Next.js/Vite):
+
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
+```
+
+Add to `vitest.config.ts` if it doesn't exist:
+```typescript
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+  },
+})
+```
+
+### 2. Find Targets
+
+If specific file given → use that.
+If `--run` → skip to step 4.
+Otherwise find recently changed untested files:
+
+```bash
+# Files changed in last 5 commits that don't have tests
+git diff --name-only HEAD~5 --diff-filter=AM -- '*.ts' '*.tsx' 2>/dev/null | grep -v "test\|spec\|__test__\|\.d\.ts" | head -10
+```
+
+### 3. Generate Tests
+
+For each target file, classify it and generate the appropriate test:
+
+**API route** (`app/api/**/route.ts`):
+- Test each exported handler (GET, POST, PUT, DELETE)
+- Test with valid input → expected response
+- Test with invalid input → 400 error
+- Test without auth → 401 (if auth is required)
+
+**Server action** (has `"use server"`):
+- Test each exported function
+- Test with valid args → expected result
+- Test with invalid args → error handling
+
+**React component** (`*.tsx` with JSX):
+- Test rendering without crashing
+- Test interactive elements (clicks, form submissions)
+- Test loading, error, and empty states if they exist
+- Test accessibility (role, aria-label presence)
+
+**Utility function** (`lib/*.ts`, `utils/*.ts`):
+- Test each exported function with normal input
+- Test edge cases: empty, null, undefined, boundary values
+- Test error cases: invalid input, missing data
+
+Write test file next to the source: `{file}.test.ts` or `{file}.test.tsx`.
+
+### 4. Run Tests
+
+```bash
+# Vitest
+npx vitest run --reporter=verbose 2>&1 | tail -30
+
+# Or Jest
+npx jest --verbose 2>&1 | tail -30
+
+# Coverage (if --coverage flag)
+npx vitest run --coverage 2>&1 | tail -30
+```
+
+### 5. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
+node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
+node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
+```
+
+If any tests fail, show the failures and offer to fix them.
+
+### 6. Commit
+
+```bash
+git add {test files}
+git commit -m "test: add tests for {files}"
+```
+
+## Rules
+
+1. **Test behavior, not implementation.** Don't test internal state — test what the user/caller sees.
+2. **No snapshot tests.** They're brittle and meaningless.
+3. **No mocking unless necessary.** Test real behavior. Mock only external services (APIs, databases).
+4. **Each test file is self-contained.** No shared mutable state between tests.
+5. **Name tests as sentences.** `it("returns 401 when user is not authenticated")` not `it("test auth")`.