qualia-framework 2.6.0 → 3.2.0

package/skills/qualia-new/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: qualia-new
+description: "Set up a new project from scratch — interactive wizard with step-by-step questioning. Use when starting any new client project."
+---
+
+# /qualia-new — New Project Wizard
+
+Interactive project setup. Ask one step at a time using AskUserQuestion. Never dump all questions at once.
+
+## Process
+
+### Step 0. Banner
+
+Print this FIRST, before anything else:
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner new
+```
+
+Then say: **"Let's build something. Tell me what you're making."**
+
+Wait for the user's free-text answer. Do NOT use AskUserQuestion here — let them talk naturally.
+
+### Step 1. Project Type
+
+After they describe what they want, use AskUserQuestion:
+
+```
+question: "What type of project is this?"
+header: "Type"
+options:
+  - label: "Website / Web App"
+    description: "Landing page, SaaS, dashboard, marketing site, portal"
+  - label: "AI Agent"
+    description: "Chatbot, AI assistant, tool-calling agent, RAG system"
+  - label: "Voice Agent"
+    description: "Phone agent, VAPI, Retell AI, ElevenLabs call bot"
+  - label: "Mobile App"
+    description: "iOS, Android, React Native, Expo"
+```
+
+### Step 2. Core Features
+
+Based on their description, use AskUserQuestion with multiSelect: true:
+
+```
+question: "Which features do you need?"
+header: "Features"
+multiSelect: true
+options (pick 4 most relevant from):
+  - "Auth & accounts" — Login, signup, user management
+  - "Database & CRUD" — Data storage, tables, admin panel
+  - "Payments" — Stripe, subscriptions, checkout
+  - "AI / LLM" — Chat, completions, embeddings, RAG
+  - "Voice calls" — Inbound/outbound calls, IVR, telephony
+  - "Email / notifications" — Transactional email, SMS, push
+  - "File uploads" — Images, documents, S3/storage
+  - "Admin dashboard" — Internal tools, analytics, reporting
+  - "API / integrations" — Third-party APIs, webhooks, CRM sync
+  - "Real-time" — WebSockets, live updates, presence
+```
+
+Pick the 4 options most relevant to what they described. Always offer the most likely ones.
+
+### Step 3. Design Direction
+
+Use AskUserQuestion with previews:
+
+```
+question: "What's the design vibe?"
+header: "Design"
+options:
+  - label: "Dark & Bold"
+    description: "Dark backgrounds, neon accents, strong contrast"
+    preview: |
+      ┌──────────────────────────────┐
+      │  ██████████████████████████  │
+      │  ██  DARK BG + TEAL GLOW ██  │
+      │  ██████████████████████████  │
+      │                              │
+      │  ░░░░░░░░░░░░░░░░░░░░░░░░  │
+      │  Sharp cards, glass effects  │
+      │  Neon borders, deep shadows  │
+      └──────────────────────────────┘
+
+  - label: "Clean & Minimal"
+    description: "White space, subtle shadows, refined typography"
+    preview: |
+      ┌──────────────────────────────┐
+      │                              │
+      │     Clean & Minimal          │
+      │     ─────────────            │
+      │                              │
+      │  Generous whitespace         │
+      │  Subtle borders              │
+      │  Light, airy feel            │
+      └──────────────────────────────┘
+
+  - label: "Colorful & Playful"
+    description: "Gradients, rounded shapes, vibrant palette"
+    preview: |
+      ┌──────────────────────────────┐
+      │  ⬢ ● ▲ ■  COLORFUL          │
+      │                              │
+      │  ╭──────╮  ╭──────╮         │
+      │  │ Card │  │ Card │         │
+      │  ╰──────╯  ╰──────╯         │
+      │  Rounded, gradient fills     │
+      │  Fun, approachable           │
+      └──────────────────────────────┘
+
+  - label: "Corporate / Professional"
+    description: "Structured layouts, trust signals, enterprise feel"
+    preview: |
+      ┌──────────────────────────────┐
+      │  LOGO    Nav  Nav  [CTA]     │
+      │  ────────────────────────    │
+      │  ┌────┐ ┌────┐ ┌────┐       │
+      │  │Feat│ │Feat│ │Feat│       │
+      │  └────┘ └────┘ └────┘       │
+      │  Structured, trustworthy     │
+      │  Clear hierarchy             │
+      └──────────────────────────────┘
+```
+
+### Step 4. Stack Confirmation
+
+Use AskUserQuestion:
+
+```
+question: "Stack — go with the Qualia default?"
+header: "Stack"
+options:
+  - label: "Qualia Stack (Recommended)"
+    description: "Next.js 16 + React 19 + TypeScript + Supabase + Vercel"
+  - label: "Qualia + extras"
+    description: "Default stack plus additional integrations (Stripe, VAPI, etc.)"
+  - label: "Custom stack"
+    description: "I have specific tech requirements"
+```
+
+If "Custom stack" — ask what they need.
+If "Qualia + extras" — ask which integrations.
+
+### Step 5. Scope & Client
+
+Use AskUserQuestion:
+
+```
+question: "Is this a client project or internal?"
+header: "Client"
+options:
+  - label: "Client project"
+    description: "External client — will need handoff and credentials"
+  - label: "Internal / Qualia"
+    description: "Our own product or tool"
+  - label: "Personal / Side project"
+    description: "No formal client"
+```
+
+If client project, ask: **"What's the client's name?"** (free text, no AskUserQuestion)
+
+After capturing the client name, check for saved preferences:
+
+```bash
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+If there's an entry for this client, show it to the user: *"I have notes on {client} — {preferences summary}. Applying these to the project defaults unless you say otherwise."* Then use those preferences in Step 8a (Design System) and Step 9 (Roadmap).
+
+### Step 6. Confirm & Scaffold
+
+Present a summary:
+
+```
+⬢ QUALIA ▸ PROJECT SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Project    {name}
+  Type       {type}
+  Client     {client}
+  Stack      {stack}
+  Features   {feature list}
+  Design     {design direction}
+```
+
+Use AskUserQuestion:
+
+```
+question: "Ready to scaffold?"
+header: "Confirm"
+options:
+  - label: "Let's go"
+    description: "Create the project now"
+  - label: "Change something"
+    description: "Go back and adjust"
+```
+
+### Step 7. Execute Scaffold
+
+On confirmation, scaffold:
+
+```bash
+mkdir -p .planning
+
+# Initialize git if needed
+git init 2>/dev/null
+
+# Create Next.js project (if website/ai-agent)
+npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir=false --import-alias="@/*" --no-git
+
+# Or Expo project (if mobile-app)
+# npx create-expo-app . --template blank-typescript
+```
+
+Create GitHub repo:
+```bash
+gh repo create {project-name} --private --source=. --push
+```
+
+Link Vercel:
+```bash
+vercel link
+```
+
+Create Supabase project (via MCP or manual).
+
+### Step 8. Create Planning Files
+
+**`.planning/PROJECT.md`** — use template, fill from answers:
+- Client, description, requirements (from features), out of scope, stack, design direction, decisions
+
+### Step 8a. Create Design System
+
+Generate **`.planning/DESIGN.md`** using `~/.claude/qualia-templates/DESIGN.md` as the template.
+
+Fill in based on the design direction chosen in Step 3:
+
+**Dark & Bold:**
+- Palette: dark backgrounds (#0a0a0a, #141414), vibrant accent (teal #00d4aa, amber #f59e0b, etc.)
+- Typography: bold display font + clean body font (e.g., "Plus Jakarta Sans" + "DM Sans")
+- Effects: glass morphism, noise textures, glow effects
+- Motion: expressive — staggered fades, parallax hints
+
+**Clean & Minimal:**
+- Palette: light backgrounds (#fafafa, #ffffff), single muted accent
+- Typography: refined serif or geometric sans (e.g., "Outfit" + "Source Serif 4")
+- Effects: subtle shadows, thin borders
+- Motion: minimal — fades only, no stagger
+
+**Colorful & Playful:**
+- Palette: vibrant multi-color, warm backgrounds
+- Typography: rounded friendly fonts (e.g., "Nunito" + "Quicksand")
+- Effects: gradients, rounded shapes, illustrations
+- Motion: expressive — bouncy spring easing, scale on hover
+
+**Corporate / Professional:**
+- Palette: navy/charcoal base, conservative accent (blue, green)
+- Typography: trustworthy geometric (e.g., "Manrope" + "IBM Plex Sans")
+- Effects: clean borders, subtle shadows, structured grids
+- Motion: subtle — smooth fades, no bounce
+
+**Always include in DESIGN.md:**
+- Concrete CSS variable values (not placeholders)
+- Google Fonts import URL
+- Spacing scale (8px grid)
+- Component patterns (buttons, inputs, cards)
+- Responsive approach
+- Anti-patterns to avoid
+
+### Step 8b. Initialize State
+
+```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
+
+Based on project type and features, create phases in STATE.md:
+
+**Typical website:**
+1. Foundation — Auth, database schema, base layout
+2. Core — Main features
+3. Content — Pages, copy, media
+4. Polish — Design, animations, responsive
+
+**Typical AI agent:**
+1. Foundation — Auth, database, API routes
+2. Agent — AI logic, prompts, tool calling
+3. Interface — Chat UI, streaming, history
+4. Polish — Error handling, rate limiting, monitoring
+
+**Typical voice agent:**
+1. Foundation — Webhook handler, Supabase, auth
+2. Voice — VAPI/Retell config, call flow, prompts
+3. Integration — CRM sync, logging, analytics
+4. Polish — Latency optimization, error handling
+
+Present the roadmap. Use AskUserQuestion:
+
+```
+question: "Does this roadmap look right?"
+header: "Roadmap"
+options:
+  - label: "Looks good"
+    description: "Lock it in and start planning Phase 1"
+  - label: "Adjust phases"
+    description: "I want to change the phase breakdown"
+```
+
+### Step 10. Commit & Output
+
+```bash
+git add .planning/
+git commit -m "init: project setup with planning files"
+git push -u origin main
+```
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PROJECT READY" "/qualia-plan 1"
+```

package/{framework/skills → skills}/qualia-optimize/SKILL.md

@@ -414,4 +414,4 @@ If user wants a fix phase for critical issues:
 3. Map CRITICAL and HIGH findings as success criteria
 4. Update STATE.md
 5. Commit
-6. Suggest: "Fix phase created. Run `/qualia-plan-phase {N}.1`"
+6. Suggest: "Fix phase created. Run `/qualia-plan {N}.1`"

package/skills/qualia-pause/SKILL.md

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

@@ -0,0 +1,101 @@
+---
+name: qualia-plan
+description: "Plan the current phase — spawns planner agent in fresh context. Use when ready to plan a phase."
+---
+
+# /qualia-plan — Plan a Phase
+
+Spawn a planner agent to break the current phase into executable tasks.
+
+## Usage
+`/qualia-plan` — plan the next unplanned phase
+`/qualia-plan {N}` — plan specific phase
+`/qualia-plan {N} --gaps` — plan fixes for verification failures
+
+## Process
+
+### 1. Determine Phase & Load Knowledge
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+If no phase number given, use the current phase from STATE.md.
+If any learned patterns apply to this phase's work, pass them to the planner in the spawn prompt under a `## Relevant Learnings` section.
+If this is a client project and `client-prefs.md` has an entry for the client, include those preferences in the planner context.
+
+### 2. Spawn Planner (Fresh Context)
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from STATE.md}"
+node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
+```
+
+Spawn a subagent with `agents/planner.md` instructions:
+
+```
+Agent(prompt="
+Read your role: @agents/planner.md
+
+Project context:
+@.planning/PROJECT.md
+
+Current state:
+@.planning/STATE.md
+
+Phase {N} goal: {goal from STATE.md roadmap}
+Phase {N} success criteria: {criteria from STATE.md}
+
+{If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix}
+
+Create the plan file at .planning/phase-{N}-plan.md
+", subagent_type="qualia-planner", description="Plan phase {N}")
+```
+
+### 3. Review Plan
+
+Read the generated plan. Present the summary using the UI helpers:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Plan ready: {count} tasks across {count} waves"
+```
+
+Then, for each wave, print:
+
+```bash
+node ~/.claude/bin/qualia-ui.js wave {wave_num} {wave_total} {task_count_in_wave}
+node ~/.claude/bin/qualia-ui.js task 1 "{task title}"
+node ~/.claude/bin/qualia-ui.js task 2 "{task title}"
+```
+
+End with an approval prompt (plain text, no UI helper): *"Approve? (yes / adjust)"*
+
+If "adjust" — get feedback, re-spawn planner with revision context.
+
+### 4. Update State
+
+```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.
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
+```
+
+### Gap Closure Mode (`--gaps`)
+
+When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
+
+1. Read `.planning/phase-{N}-verification.md` — extract ONLY the FAIL items
+2. For each FAIL item, create a targeted fix task:
+   - **Files:** The specific files that failed verification
+   - **Action:** The specific fix needed (not "fix auth" — "add session persistence check in `src/lib/auth.ts` signIn function")
+   - **Done when:** The exact verification criterion that previously failed, restated
+3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
+4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
+5. All gap tasks are Wave 1 (parallel) unless they share files

package/skills/qualia-polish/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: qualia-polish
+description: "Design and UX pass — critique, polish, harden. Run after all phases are verified."
+---
+
+# /qualia-polish — Design Pass
+
+Run after all feature phases are verified. Makes it look production-ready.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner polish
+```
+
+### 0. Load Design Context
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+If DESIGN.md exists → use it as the standard. If not → use Qualia defaults from `rules/frontend.md`.
+
+Read EVERY frontend file before modifying. No blind edits.
+
+### 1. Critique (Structured Audit)
+
+Review the entire UI against this checklist. Check each item, note violations with file:line.
+
+**Typography:**
+- [ ] No generic fonts (Inter, Roboto, Arial, system-ui, Space Grotesk)
+- [ ] Proper type scale with clear hierarchy (display → heading → body → caption)
+- [ ] Body text: 16px+, line-height 1.5–1.7
+- [ ] Headings: tighter line-height (1.1–1.3), negative letter-spacing for large sizes
+- [ ] Prose max-width: 65ch
+- [ ] Font weights used for hierarchy (Regular, Medium, Semibold, Bold)
+
+**Color & Contrast:**
+- [ ] Cohesive palette via CSS variables (not scattered hex values)
+- [ ] All text passes WCAG AA contrast (4.5:1 normal, 3:1 large)
+- [ ] CTA buttons use accent color — stand out from the page
+- [ ] No blue-purple gradients, no rainbow palettes
+- [ ] Dark mode: rethought surfaces (not just inverted)
+- [ ] Semantic colors used consistently (success=green, error=red, warning=amber)
+
+**Layout & Spacing:**
+- [ ] Full-width fluid layouts — no hardcoded max-width caps
+- [ ] 8px spacing grid followed consistently
+- [ ] Tight spacing within groups, generous between sections
+- [ ] Fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
+- [ ] No identical card grids — varied visual hierarchy
+- [ ] No generic heroes — purposeful, distinctive
+
+**Interactive States:**
+- [ ] Every button/link: hover (color shift, 150ms), focus (visible ring), active (press feedback), disabled
+- [ ] Loading: skeleton or spinner on all async operations
+- [ ] Empty: helpful message + action on empty lists/data
+- [ ] Error: user-friendly message + recovery action on failed fetches
+- [ ] Form validation: inline errors with `aria-describedby`
+
+**Motion:**
+- [ ] Hover/focus: 150–200ms transitions
+- [ ] Page load: staggered entrance animations (50–80ms delay)
+- [ ] Expand/collapse: 250ms ease-in-out
+- [ ] `prefers-reduced-motion` respected (no animation for users who opt out)
+- [ ] No jank: transforms and opacity only for animated properties
+
+**Accessibility:**
+- [ ] Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer`
+- [ ] One `h1` per page, sequential heading hierarchy
+- [ ] All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
+- [ ] All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
+- [ ] All interactive elements: keyboard accessible (Tab/Enter/Escape)
+- [ ] Touch targets: 44px minimum
+- [ ] Skip link: `<a href="#main">` as first focusable element
+- [ ] No `outline: none` without focus replacement
+- [ ] `<html lang="en">` set
+- [ ] Color not sole information carrier — icons/text as supplements
+
+**Responsive:**
+- [ ] Mobile-first approach (base styles for mobile, min-width breakpoints for larger)
+- [ ] No horizontal scroll at 320px
+- [ ] Navigation: hamburger on mobile, expanded on desktop
+- [ ] Touch targets adequate on mobile (44px min)
+- [ ] Fluid typography with `clamp()`
+- [ ] Images: `max-width: 100%`, responsive srcset where needed
+- [ ] Tables: card view or horizontal scroll on mobile
+
+**Performance:**
+- [ ] Server Components by default — `'use client'` only when needed
+- [ ] Images via `next/image` with width/height
+- [ ] No barrel file imports — direct imports from source
+- [ ] Heavy components lazy-loaded with `next/dynamic`
+- [ ] Data fetched in parallel, not sequentially
+
+### 2. Fix Everything
+
+Work through violations from the critique. Fix each category:
+
+1. Typography first (sets the visual foundation)
+2. Color & contrast (palette coherence)
+3. Layout & spacing (structural fixes)
+4. Interactive states (loading, empty, error, hover, focus)
+5. Motion (transitions, entrance animations, reduced-motion)
+6. Accessibility (semantic HTML, ARIA, keyboard, labels)
+7. Responsive (mobile breakpoints, fluid sizing)
+8. Performance (quick wins — image optimization, dynamic imports)
+
+### 3. Harden
+
+After polish, stress-test edge cases:
+- Long text content (overflow, truncation, word-break)
+- Extremely long usernames or email addresses
+- Empty data everywhere simultaneously
+- Error state on every fetch simultaneously
+- 320px viewport width
+- Keyboard-only navigation through entire flow
+- Screen reader landmarks check (semantic HTML)
+- Right-to-left text (if i18n is planned)
+- Slow network (loading states visible, no flash of empty content)
+
+### 4. Verify
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors before committing.
+
+### 5. Commit & Transition
+
+```bash
+git add {changed files}
+git commit -m "polish: design and UX pass — typography, accessibility, responsive, states"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to polished
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+### 6. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Files modified: {N}"
+node ~/.claude/bin/qualia-ui.js ok "Typography — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Color — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Layout — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "States — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Motion — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Accessibility — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Responsive — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Performance — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Hardening — {brief}"
+node ~/.claude/bin/qualia-ui.js end "POLISHED" "/qualia-ship"
+```

package/skills/qualia-quick/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: qualia-quick
+description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning."
+---
+
+# /qualia-quick — Quick Task
+
+For tasks under 1 hour that don't need full phase planning. Single file changes, bug fixes, config tweaks, typo fixes.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner quick
+```
+
+1. **Understand:** Ask what needs to be done (or read the instruction)
+2. **Build:** Do it directly — read before write, MVP only
+3. **Verify:** Run `npx tsc --noEmit`, test locally
+4. **Commit:** Atomic commit with clear message
+5. **Update:** Update tracking.json notes field
+
+End with:
+```bash
+node ~/.claude/bin/qualia-ui.js end "QUICK FIX DONE"
+```
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+No plan file. No subagents. Just build and ship.
+
+```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.