qualia-framework 2.6.0 → 3.2.0

package/skills/qualia/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: qualia
+description: "Smart router — reads project state, classifies your situation, tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', 'idk', 'what now', 'what should I do', 'I'm stuck', 'help me decide', 'lost', 'confused', or are unsure about your next step."
+---
+
+# /qualia — What's Next?
+
+Read project state. Classify your situation. Tell you the exact next command.
+
+## Process
+
+### 1. Get State
+
+```bash
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Also gather context:
+```bash
+test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"
+git status --short 2>/dev/null | head -10
+git log --oneline -3 2>/dev/null
+ls .planning/phase-*-plan.md 2>/dev/null || echo "NO_PLANS"
+ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
+```
+
+Read conversation context — what has the user been doing, what errors occurred.
+
+### 2. Classify and Route
+
+Use the state.js JSON output plus gathered context:
+
+| Situation | Detection | Route |
+|-----------|-----------|-------|
+| `no-project` | state.js returns NO_PROJECT | → `/qualia-new` |
+| `handoff` | `.continue-here.md` exists | → Read it, summarize, route to next step |
+| `mid-work` | Uncommitted changes + phase in progress | → Continue or `/qualia-pause` |
+| `ready-to-plan` | status == "setup" | → `/qualia-plan {N}` |
+| `ready-to-build` | status == "planned" | → `/qualia-build {N}` |
+| `ready-to-verify` | status == "built" | → `/qualia-verify {N}` |
+| `gaps-found` | status == "verified", verification == "fail", gap_cycles < 2 | → `/qualia-plan {N} --gaps` |
+| `gap-limit` | status == "verified", verification == "fail", gap_cycles >= 2 | → Escalate to Fawzi or re-plan from scratch |
+| `phase-complete` | state.js auto-advanced (status == "setup", phase > 1) | → `/qualia-plan {N}` |
+| `all-verified` | last phase verified pass, status == "verified" | → `/qualia-polish` |
+| `polished` | status == "polished" | → `/qualia-ship` |
+| `shipped` | status == "shipped" | → `/qualia-handoff` |
+| `handed-off` | status == "handed_off" | → `/qualia-report` then done |
+| `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
+| `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+
+**Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
+
+### 3. Display
+
+**Clear next step** (use the UI helper — it reads state.js itself):
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
+```
+
+**Ambiguous situation (multiple options):**
+Print the banner first, then use plain markdown for the options:
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+```
+```
+## Where You Are
+{1-2 sentences}
+
+## I Recommend
+**{action}** — {why}
+{command}
+
+## Other Options
+1. **{option}** — {what}
+2. **{option}** — {what}
+3. **{option}** — {what}
+```
+
+**Blocker detected** (gap-limit, bug-loop, employee escalation):
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js fail "{blocker description}"
+node ~/.claude/bin/qualia-ui.js warn "Escalate to Fawzi or re-plan from scratch"
+```
+
+User can respond with a number, "just do it", or natural language.

package/skills/qualia-build/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: qualia-build
+description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+---
+
+# /qualia-build — Build a Phase
+
+Execute the phase plan. Each task runs in a fresh subagent context. Independent tasks run in parallel.
+
+## Usage
+`/qualia-build` — build the current planned phase
+`/qualia-build {N}` — build specific phase
+
+## Process
+
+### 1. Load Plan
+
+```bash
+cat .planning/phase-{N}-plan.md
+```
+
+Parse: tasks, waves, file references.
+
+### 2. Execute Waves
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
+```
+
+**For each wave (sequential):**
+
+```bash
+node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
+```
+
+**For each task in the wave (parallel if multiple):**
+
+```bash
+node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
+```
+
+Spawn a fresh builder subagent:
+
+```
+Agent(prompt="
+Read your role: @agents/builder.md
+
+Project context:
+@.planning/PROJECT.md
+
+YOUR TASK:
+{paste the single task block from the plan — title, files, action, context refs, done-when}
+
+Execute this task. Read all @file references before writing. Commit when done.
+", subagent_type="qualia-builder", description="Task {N}: {title}")
+```
+
+**After each task completes:**
+- Verify the commit exists: `git log --oneline -1`
+- Show result:
+```bash
+node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
+```
+
+**After each wave completes:**
+- Move to next wave
+- Show wave summary
+
+### 3. Wave Completion
+
+After all waves complete:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Tasks: {done}/{total}"
+node ~/.claude/bin/qualia-ui.js ok "Commits: {count}"
+node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
+```
+
+### 4. Handle Failures
+
+If a builder subagent returns a deviation or blocker:
+- **Minor deviation:** Log it, continue
+- **Major deviation:** Show to employee, ask how to proceed
+- **Blocker:** Show the blocker, suggest fix or escalation
+
+### 5. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
+```
+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.
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
+```

package/skills/qualia-debug/SKILL.md

@@ -0,0 +1,87 @@
+---
+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)
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner debug
+```
+
+### 0. Check Known Fixes First
+
+Before gathering symptoms, check if we've seen this before:
+
+```bash
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+```
+
+If the user's description matches a known fix, suggest it first: *"I've seen this before — check {fix title}. Want to try that before we dig deeper?"* Only proceed to full investigation if the known fix doesn't apply.
+
+### 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,93 @@
+---
+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
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner design
+```
+
+### 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

@@ -0,0 +1,66 @@
+---
+name: qualia-handoff
+description: "Client delivery — credentials, handover doc, final update. Use after shipping."
+---
+
+# /qualia-handoff — Client Delivery
+
+Prepare and deliver the finished project to the client.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner handoff
+```
+
+### 1. Generate Handover Doc
+
+Create `.planning/HANDOFF.md`:
+
+```markdown
+# {Project Name} — Handover
+
+## What Was Built
+{3-5 bullet summary of delivered features}
+
+## Access
+- **URL:** {production URL}
+- **Admin login:** {credentials or where to find them}
+- **Supabase:** {project ref}
+- **GitHub:** {repo URL}
+- **Vercel:** {project URL}
+
+## How to Use
+{Brief walkthrough of the main user flows}
+
+## Known Limitations
+{Anything not in scope or deferred}
+
+## Maintenance
+- Hosting: Vercel (auto-deploys from main branch)
+- Database: Supabase ({region})
+- Domain: {domain provider if applicable}
+
+## Support
+Contact: Fawzi Goussous — fawzi@qualiasolutions.net
+```
+
+### 2. Commit
+
+```bash
+git add .planning/HANDOFF.md
+git commit -m "docs: client handoff document"
+git push
+```
+
+### 3. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to handed_off
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+```bash
+node ~/.claude/bin/qualia-ui.js ok "{Project Name} handed off to {client}"
+node ~/.claude/bin/qualia-ui.js end "DELIVERED" "/qualia-report"
+```

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,88 @@
+---
+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
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner learn
+```
+
+### 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.