qualia-framework-v2 2.1.2 → 2.4.0

package/skills/qualia-debug/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: qualia-debug
+description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+---
+
+# /qualia-debug — Structured Debugging
+
+Systematic debugging. Don't guess — gather symptoms, confirm diagnosis, then fix.
+
+## Usage
+
+- `/qualia-debug` — Interactive (gather symptoms, diagnose, fix)
+- `/qualia-debug --frontend` — CSS/layout/visual issues
+- `/qualia-debug --perf` — Performance issues
+
+## Interactive Mode (Default)
+
+### 1. Gather Symptoms
+
+Ask:
+- What's happening? (exact error or behavior)
+- What should happen instead?
+- When did it start? (after what change?)
+- What have you tried?
+
+### 2. Confirm Diagnosis
+
+Before ANY code changes, present your diagnosis:
+
+> "Based on the symptoms, I think: [diagnosis]. I'll investigate [specific area]. Does that match what you're seeing?"
+
+Wait for confirmation. If user corrects → adjust. Never proceed on a wrong diagnosis.
+
+### 3. Investigate and Fix
+
+1. Reproduce the issue
+2. Isolate the cause (binary search: which file, which function, which line)
+3. Identify root cause (not symptoms)
+4. Implement minimal fix
+5. Verify fix works
+6. Check for related issues
+
+### 4. Commit
+
+```bash
+git add {specific files}
+git commit -m "fix: {what was broken and why}"
+```
+
+## Frontend Mode (`--frontend`)
+
+For layout breaks, z-index issues, overflow, animation glitches.
+
+**Quick diagnostics:**
+- Z-index not working → element needs `position: relative/absolute/fixed`, check parent stacking contexts
+- Horizontal scroll → use `width: 100%` not `100vw`, find overflowing element
+- Flex overflow → add `min-width: 0`
+- Grid blowout → use `minmax(0, 1fr)`
+- Janky animations → only animate `transform` and `opacity`
+- Safari → `-webkit-backdrop-filter`, `100dvh` not `100vh`
+
+## Performance Mode (`--perf`)
+
+### Investigate
+1. Profile the bottleneck (network, render, compute, database)
+2. Measure baseline
+3. Identify the hot path
+
+### Common fixes
+- Slow queries → check indexes, `EXPLAIN ANALYZE`, optimize joins
+- Large bundles → code split, lazy load, tree shake
+- Slow renders → memoize, virtualize long lists
+- API latency → cache, reduce payload, parallelize requests

package/skills/qualia-design/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: qualia-design
+description: "One-shot design transformation — critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional. Trigger on 'fix the design', 'make it look better', 'redesign', 'design pass', 'make it modern', 'it looks ugly', 'fix the UI'."
+---
+
+# /qualia-design — One-Shot Design Transformation
+
+Read the code, understand what's wrong, fix everything, move on. No reports, no choices.
+
+## Usage
+
+- `/qualia-design` — Full transformation on all frontend files
+- `/qualia-design app/page.tsx` — Specific file(s)
+- `/qualia-design --scope=dashboard` — Transform a section
+
+## Process
+
+### 1. Read Brand Context
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+If DESIGN.md exists → use it. If not → use Qualia defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
+
+### 2. Find Target Files
+
+- If specific files given: use those
+- If `--scope`: grep for matching files in `app/` and `components/`
+- If none: find all `page.tsx`, `layout.tsx`, and component files
+
+Read EVERY target file before modifying.
+
+### 3. Critique (internal — don't output)
+
+Evaluate each file on: AI slop detection, visual hierarchy, typography, color, states (loading/error/empty), motion, spacing, responsiveness, microcopy.
+
+### 4. Fix Everything
+
+**Typography:** Replace generic fonts (Inter, Arial) with distinctive ones. Proper type scale, line-height 1.5-1.7 body.
+
+**Color:** Cohesive palette from DESIGN.md or brand. Sharp accent for CTAs. WCAG AA contrast.
+
+**Layout:** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+
+**Spacing:** Consistent scale (8px grid). Generous whitespace between sections, tight within groups.
+
+**Motion:** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+
+**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on interactive elements.
+
+**Responsive:** Mobile-first. Touch targets 44x44px min. Stack on mobile, expand on desktop. No horizontal scroll.
+
+**Kill:** Card grids → varied layouts. Generic heroes → distinctive. Blue-purple gradients → brand colors. Static pages → purposeful motion. Fixed widths → fluid.
+
+### 5. Verify
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors before committing.
+
+### 6. Commit
+
+```bash
+git add {modified files}
+git commit -m "style: design transformation"
+```
+
+```
+◆ Design Transformation Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Files: {N}
+  Changes:
+  - {key change 1}
+  - {key change 2}
+  - {key change 3}
+
+  Fine-tune: /bolder, /design-quieter, /colorize, /animate
+```
+
+## Rules
+
+- Read before write — understand every file before changing it
+- Don't ask — just fix
+- Respect DESIGN.md decisions
+- Don't break functionality — only change styling, never logic
+- TypeScript must pass after changes

package/skills/qualia-handoff/SKILL.md

@@ -56,8 +56,10 @@ git push
 
 ### 3. Update State
 
-Update STATE.md: "handed off"
-Update tracking.json: status → "handed_off"
+```bash
+node ~/.claude/bin/state.js transition --to handed_off
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
 ◆ QUALIA ► DELIVERED ✓

package/skills/qualia-idk/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: qualia-idk
+description: "Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations."
+---
+
+# /qualia-idk
+
+This is an alias for `/qualia`. Run `/qualia` — it now handles all situation classification and routing.

package/skills/qualia-learn/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: qualia-learn
+description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions. Trigger on 'remember this', 'save this pattern', 'learned something', 'note for future', 'client prefers', 'qualia-learn'."
+---
+
+# /qualia-learn — Save Knowledge
+
+Persist learnings across projects and sessions. Saved to `~/.claude/knowledge/`.
+
+## Usage
+
+- `/qualia-learn` — Interactively save a learning
+- `/qualia-learn {description}` — Save directly
+
+## Knowledge Types
+
+### Patterns (`learned-patterns.md`)
+Recurring approaches that work (or don't). Architecture decisions, library choices, prompt patterns.
+
+**Example:** "Supabase RLS policies need to be added in the same migration as the table — adding them later causes a window where data is unprotected."
+
+### Fixes (`common-fixes.md`)
+Problems you've solved before. Error messages and their solutions.
+
+**Example:** "`next/font` crash on Vercel: caused by importing font in a client component that's also used server-side. Fix: move font import to layout.tsx."
+
+### Client Prefs (`client-prefs.md`)
+Client-specific preferences, design choices, requirements.
+
+**Example:** "Acme Corp: prefers dark mode, hates rounded corners, logo must be SVG not PNG, primary color #FF6B00."
+
+## Process
+
+### 1. Classify
+
+If description given, classify automatically. Otherwise ask:
+
+```
+What did you learn?
+1. Pattern — approach that works (or doesn't)
+2. Fix — problem and its solution
+3. Client preference — client-specific requirement
+```
+
+### 2. Format Entry
+
+```markdown
+### {Title} ({date})
+**Project:** {current project name or "general"}
+**Context:** {brief context — what you were building when you learned this}
+
+{The learning — be specific enough that future-you understands without context}
+```
+
+### 3. Append to Knowledge File
+
+```bash
+# Append to the right file
+echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
+```
+
+- Pattern → `~/.claude/knowledge/learned-patterns.md`
+- Fix → `~/.claude/knowledge/common-fixes.md`
+- Client pref → `~/.claude/knowledge/client-prefs.md`
+
+### 4. Confirm
+
+```
+◆ Saved to {file}
+  "{title}"
+```
+
+## Reading Knowledge
+
+Skills can read knowledge files for context:
+```bash
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+The `/qualia-debug` skill should check `common-fixes.md` before investigating.
+The `/qualia-new` skill should check `client-prefs.md` when setting up client projects.
+The `/qualia-plan` skill should check `learned-patterns.md` when planning phases.

package/skills/qualia-new/SKILL.md

@@ -223,9 +223,13 @@ Create Supabase project (via MCP or manual).
 **`.planning/PROJECT.md`** — use template, fill from answers:
 - Client, description, requirements (from features), out of scope, stack, design direction, decisions
 
-**`.planning/STATE.md`** — use template from `templates/state.md`
+### Step 8b. Initialize State
 
-**`.planning/tracking.json`** — use template, fill in project/client/assigned_to
+```bash
+node ~/.claude/bin/state.js init --project "{name}" --client "{client}" --type "{type}" --assigned-to "{employee}" --phases '[{phases JSON array from roadmap}]'
+```
+This creates both STATE.md and tracking.json with consistent formatting.
+Do NOT manually edit these files — state.js handles both.
 
 ### Step 9. Create Roadmap
 

package/skills/qualia-pause/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: qualia-pause
+description: "Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off. Trigger on 'pause', 'stop for now', 'save progress', 'continue later', 'pick up tomorrow'."
+---
+
+# /qualia-pause — Session Handoff
+
+Save context so the next session picks up where you left off.
+
+## Process
+
+### 1. Read State
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+git status --short 2>/dev/null
+git log --oneline -5 2>/dev/null
+```
+
+### 2. Create `.continue-here.md`
+
+```markdown
+# Continue Here
+
+## Session Summary
+{What was accomplished — from conversation context + git log}
+
+## Current Phase
+Phase {N}: {name} — {status}
+
+## In Progress
+- {What's partially done}
+- {Where exactly work stopped}
+
+## Next Steps
+1. {Immediate next action}
+2. {Following action}
+
+## Decisions Made
+- {Decision and rationale}
+
+## Blockers
+- {Any unresolved issues}
+
+## Files Modified
+- {List from git status/diff}
+```
+
+### 3. Commit
+
+```bash
+git add .continue-here.md {any uncommitted work files}
+git commit -m "WIP: {phase name} — session handoff"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "Session paused — see .continue-here.md"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-plan/SKILL.md

@@ -76,8 +76,11 @@ If "adjust" — get feedback, re-spawn planner with revision context.
 
 ### 4. Update State
 
-Update STATE.md: status → "planned"
-Update tracking.json: status → "planned"
+```bash
+node ~/.claude/bin/state.js transition --to planned --phase {N}
+```
+If state.js returns an error, show it to the employee and stop.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-build {N}

package/skills/qualia-polish/SKILL.md

@@ -49,8 +49,10 @@ git add {changed files}
 git commit -m "polish: design and UX pass"
 ```
 
-Update STATE.md: "polish complete"
-Update tracking.json: status → "polished"
+```bash
+node ~/.claude/bin/state.js transition --to polished
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-ship

package/skills/qualia-quick/SKILL.md

@@ -22,4 +22,7 @@ git commit -m "fix: {description}"
 
 No plan file. No subagents. Just build and ship.
 
-Update STATE.md last activity. Update tracking.json notes.
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-report/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: qualia-report
-description: "Generate session report as DOCX and auto-upload to ERP. Mandatory before clock-out."
+description: "Generate session report and commit to repo. Mandatory before clock-out."
 ---
 
 # /qualia-report — Session Report
 
-Generate a concise DOCX report of what was done. Auto-uploads to the ERP.
+Generate a concise report of what was done. Committed to git for the ERP to read.
 
 ## Process
 
 ### 1. Gather Data
 
 ```bash
-echo "---COMMITS---"
 SINCE="8 hours ago"
+echo "---COMMITS---"
 git log --oneline --since="$SINCE" 2>/dev/null | head -20
 echo "---STATS---"
 echo "COUNT:$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)"
@@ -21,7 +21,7 @@ echo "---PROJECT---"
 echo "DIR:$(basename $(pwd))"
 echo "BRANCH:$(git branch --show-current 2>/dev/null)"
 echo "---STATE---"
-head -20 .planning/STATE.md 2>/dev/null || echo "no-state"
+node ~/.claude/bin/state.js check 2>/dev/null
 ```
 
 ### 2. Synthesize
@@ -31,44 +31,50 @@ Build a concise summary:
 - **Blockers:** Only if something is actually blocked.
 - **Next:** 1-3 clear next actions.
 
-### 3. Generate DOCX
+### 3. Generate Report
 
-```bash
-mkdir -p .planning/reports
+Write to `.planning/reports/report-{YYYY-MM-DD}.md`:
+
+```markdown
+# Session Report — {YYYY-MM-DD}
+
+**Project:** {name}
+**Employee:** {git user.name}
+**Branch:** {branch}
+**Phase:** {N} — {name} ({status})
+**Date:** {YYYY-MM-DD}
 
-cat <<'REPORT_JSON' | python3 ~/.claude/qualia-framework/bin/generate-report-docx.py ".planning/reports/report-$(date +%Y-%m-%d-%H%M).docx"
-{
-    "project": "{project-name}",
-    "user": "{git user.name}",
-    "date": "{YYYY-MM-DD}",
-    "time": "{HH:MM}",
-    "branch": "{branch}",
-    "phase": "{Phase N — name}",
-    "done": ["{accomplishment 1}", "{accomplishment 2}"],
-    "blockers": [],
-    "next": ["{next action 1}"]
-}
-REPORT_JSON
+## What Was Done
+- {accomplishment 1}
+- {accomplishment 2}
+- {accomplishment 3}
+
+## Blockers
+None. / - {blocker}
+
+## Next Steps
+1. {next action}
+2. {next action}
+
+## Commits
+{list from git log}
 ```
 
-### 4. Commit & Upload
+### 4. Commit and Push
 
 ```bash
-REPORT_FILE=$(ls -t .planning/reports/report-*.docx 2>/dev/null | head -1)
-git add "$REPORT_FILE"
-git commit -m "report: session $(date +%Y-%m-%d)"
+mkdir -p .planning/reports
+git add .planning/reports/report-{date}.md
+git commit -m "report: session {YYYY-MM-DD}"
 git push
 ```
 
-Auto-upload to ERP:
+### 5. Update State
+
 ```bash
-curl -s -X POST "https://portal.qualiasolutions.net/api/claude/report-upload" \
-  -H "x-api-key: $CLAUDE_API_KEY" \
-  -F "file=@$REPORT_FILE" \
-  -F "employee_email=$(git config user.email)" \
-  -F "project_name=$(basename $(pwd))"
+node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"
 ```
 
-Employee cannot skip this. Report goes directly to the ERP.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
-Update STATE.md last activity.
+Employee cannot skip this. Run `/qualia-report` before clock-out.

package/skills/qualia-resume/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: qualia-resume
+description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+---
+
+# /qualia-resume — Resume Work
+
+Restore context and route to the right next action.
+
+## Process
+
+### 1. Find Context (priority order)
+
+1. `.continue-here.md` — richest source, from `/qualia-pause`
+2. `.planning/STATE.md` — project state
+3. Git history — `git log --oneline -10` + `git diff --stat`
+
+### 2. Restore
+
+**If `.continue-here.md` exists:** Read fully. Summarize: what was done, what's in progress, next steps, blockers.
+
+**If only STATE.md:** Read STATE.md + tracking.json. Show current phase and status.
+
+**If neither:** Reconstruct from git. Present findings, ask user to confirm.
+
+### 3. Detect Incomplete Work
+
+- Phase has plan but no verification → execution may be incomplete
+- Uncommitted changes → `git status --short`
+- Phase marked in-progress in STATE.md
+
+### 4. Present and Route
+
+```
+◆ QUALIA ► RESUMING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Last session: {summary}
+  Phase: {N} — {status}
+  {Uncommitted changes if any}
+
+  → {next command}
+```
+
+Clean up `.continue-here.md` after restoration (or offer to keep it).

package/skills/qualia-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: qualia-review
+description: "Production audit and code review. General review, --web for web app audit, --ai for AI/voice agent audit. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+---
+
+# /qualia-review — Production Audit
+
+Deep review with severity-scored findings. Different from `/qualia-verify` (which checks phase goals). This checks production readiness.
+
+## Usage
+
+- `/qualia-review` — General code review
+- `/qualia-review --web` — Web app production audit
+- `/qualia-review --ai` — AI/voice agent audit
+
+## General Review (default)
+
+Spawn parallel agents analyzing:
+
+1. **Code Quality** — Clean code, TypeScript strictness, naming, readability
+2. **Security** — OWASP top 10, auth server-side, RLS policies, secrets scan
+3. **Architecture** — Component boundaries, coupling, API contracts
+4. **Performance** — N+1 queries, bundle size, caching, render performance
+5. **Test Coverage** — Gaps, edge cases, test quality
+
+## --web (Web App Audit)
+
+Full production readiness for Next.js + Supabase + Vercel:
+
+**Security:** No secrets in code, HTTPS, CORS restricted, CSP headers, rate limiting, npm audit clean.
+
+**Performance:** Core Web Vitals (LCP < 2.5s, CLS < 0.1), image optimization, bundle analysis, query performance.
+
+**Reliability:** Error boundaries, API error handling, graceful degradation, health check endpoint.
+
+**Observability:** Error tracking (Sentry), structured logging, uptime monitoring, analytics.
+
+## --ai (AI/Voice Agent Audit)
+
+Auto-detect stack (VAPI, ElevenLabs, Retell, OpenAI, Anthropic, pgvector).
+
+**Prompt Safety:** System prompts not exposed, injection defenses, no eval() on AI output, token limits.
+
+**Conversation Flow:** Off-topic handling, context window management, error recovery, human handoff.
+
+**Voice (if detected):** Latency < 500ms, interruption handling, silence timeout, webhook security.
+
+**RAG (if detected):** Embedding consistency, chunk size, retrieval relevance, index refresh.
+
+**Resilience:** Provider failover, timeout handling, cost monitoring, streaming error recovery.
+
+## Output
+
+Every finding:
+- **What** — description
+- **Where** — `file:line`
+- **Fix** — concrete suggestion
+- **Severity** — CRITICAL / HIGH / MEDIUM / LOW
+
+Write to `.planning/REVIEW.md`. CRITICAL or HIGH findings are deploy blockers — `/qualia-ship` checks for them.
+
+```
+◆ Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Critical:  {N}
+  High:      {N}
+  Medium:    {N}
+  Low:       {N}
+
+  {If blockers: Fix CRITICAL/HIGH before /qualia-ship}
+  {If clean: Ready to ship}
+```

package/skills/qualia-ship/SKILL.md

@@ -83,8 +83,10 @@ curl -s -o /dev/null -w "%{http_code}" {domain}/api/auth/callback
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Update STATE.md: "shipped"
-Update tracking.json: status → "shipped", deployed_url
+```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.
 
 ```
   → Run: /qualia-handoff

package/skills/qualia-task/SKILL.md

@@ -89,4 +89,7 @@ After the builder finishes:
   Status    ✓ Done
 ```
 
-Update `.planning/tracking.json` notes field if it exists.
+```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-verify/SKILL.md

@@ -75,5 +75,10 @@ Read the verification report. Present:
 
 ### 4. Update State
 
-Update STATE.md: verification result
-Update tracking.json: verification → "pass" or "fail"
+```bash
+node ~/.claude/bin/state.js transition --to verified --phase {N} --verification {pass|fail}
+```
+If PASS and more phases: state.js auto-advances to the next phase.
+If FAIL and gap_cycles >= 2: state.js returns GAP_CYCLE_LIMIT — tell the employee to escalate.
+If FAIL and gap_cycles < 2: proceed to `/qualia-plan {N} --gaps`.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/templates/tracking.json

@@ -11,6 +11,7 @@
   "tasks_done": 0,
   "tasks_total": 0,
   "verification": "pending",
+  "gap_cycles": {},
   "blockers": [],
   "last_updated": "",
   "last_commit": "",