qualia-framework 2.5.1 → 3.1.0

package/skills/qualia-design/SKILL.md

@@ -0,0 +1,99 @@
+---
+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 → it is law. Use exact values from sections 1-9 (Visual Theme, Color Palette, Typography, Components, Layout, Depth, Do's/Don'ts, Responsive, Agent Prompt Guide). If not → use Qualia defaults from `rules/frontend.md`: 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
+
+Use exact values from DESIGN.md when available. Sections map to fixes:
+
+**Typography (§3):** Apply fonts from hierarchy table. Replace any generic fonts (Inter, Arial) with project fonts. Use exact weights, sizes, letter-spacing from the table. Body line-height 1.5-1.7.
+
+**Color (§2):** Apply palette from CSS variables. Replace scattered hex values with `var(--color-*)`. Verify contrast ratios listed in DESIGN.md.
+
+**Components (§4):** Match button, card, input, badge specs exactly — padding, radius, shadow, hover states.
+
+**Layout (§5):** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. Apply spacing scale. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+
+**Depth (§6):** Apply shadow levels from elevation table. Use brand-tinted shadows, not neutral gray.
+
+**Motion (§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 every interactive element.
+
+**Responsive (§8):** Apply collapsing strategy from table. Mobile-first. Touch targets 44x44px min. No horizontal scroll.
+
+**Anti-Slop (§12):** Run grep patterns from the detection table. Every match = mandatory fix.
+
+**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-help/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: qualia-help
+description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+---
+
+# /qualia-help — Framework Reference
+
+Opens a Qualia-themed HTML reference guide in your default browser.
+
+## Process
+
+### 1. Generate the HTML
+
+```bash
+# Read the template and inject the current version
+VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+TEMPLATE="$HOME/.claude/qualia-templates/help.html"
+OUTPUT="/tmp/qualia-help.html"
+
+# If template doesn't exist, check the framework install
+if [ ! -f "$TEMPLATE" ]; then
+  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+fi
+```
+
+### 2. Inject version and open
+
+```bash
+# Replace {{VERSION}} placeholder with actual version
+sed "s/{{VERSION}}/$VERSION/g" "$TEMPLATE" > "$OUTPUT"
+
+# Open in default browser (cross-platform)
+if command -v xdg-open &>/dev/null; then
+  xdg-open "$OUTPUT"          # Linux
+elif command -v open &>/dev/null; then
+  open "$OUTPUT"               # macOS
+elif command -v start &>/dev/null; then
+  start "$OUTPUT"              # Windows (Git Bash)
+else
+  echo "Open this file in your browser: $OUTPUT"
+fi
+```
+
+### 3. Confirm
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js ok "Reference guide opened in browser"
+node ~/.claude/bin/qualia-ui.js info "File: /tmp/qualia-help.html"
+```
+
+If the browser does not open automatically, tell the user the file path so they can open it manually.
+
+## Notes
+
+- The HTML file is self-contained — no external dependencies except Google Fonts
+- Works offline after first load (fonts cache)
+- Qualia-themed: dark background, teal accents, Outfit + Inter fonts
+- Shows: The Road, all commands grouped, verification scoring, rules, stack, GitHub orgs
+- Version is injected dynamically from .qualia-config.json

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,111 @@
+---
+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. Check for Duplicates
+
+Before saving, check if a similar entry already exists:
+
+```bash
+# Search for the title (case-insensitive substring match)
+grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+```
+
+If a near-match exists (title is similar to an existing entry):
+- Show the existing entry to the user
+- Ask: "A similar entry exists. Update it, create a new one, or skip?"
+- If update: replace the existing entry. If new: append. If skip: done.
+
+### 3. Format Entry
+
+Each entry gets a unique ID and ISO timestamp for dedup and ordering:
+
+```markdown
+
+---
+
+### {Title}
+**ID:** {random 8-char hex, e.g. a3f7c1e9}
+**Date:** {ISO 8601, e.g. 2026-04-11}
+**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}
+```
+
+### 4. Append to Knowledge File
+
+Append-only — never overwrite the file, always add at the end:
+
+```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`
+
+### 5. 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

@@ -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"
+```