qualia-framework-v2 2.0.0

package/skills/qualia-handoff/SKILL.md

@@ -0,0 +1,68 @@
+---
+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
+
+```
+◆ QUALIA ► 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
+
+Update STATE.md: "handed off"
+Update tracking.json: status → "handed_off"
+
+```
+◆ QUALIA ► DELIVERED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  {Project Name} handed off to {client}.
+  Don't forget: /qualia-report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/skills/qualia-new/SKILL.md

@@ -0,0 +1,282 @@
+---
+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:
+
+```
+◆ QUALIA ► NEW PROJECT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+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)
+
+### 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
+
+**`.planning/STATE.md`** — use template from `templates/state.md`
+
+**`.planning/tracking.json`** — use template, fill in project/client/assigned_to
+
+### 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
+```
+
+```
+◆ QUALIA ► PROJECT READY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  {Project Name}
+  Type       {type}
+  Phases     {N}
+  Client     {client}
+
+  → Run: /qualia-plan 1
+```

package/skills/qualia-plan/SKILL.md

@@ -0,0 +1,84 @@
+---
+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
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+```
+
+If no phase number given, use the current phase from STATE.md.
+
+### 2. Spawn Planner (Fresh Context)
+
+```
+◆ QUALIA ► PLANNING Phase {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Spawning planner...
+```
+
+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="general-purpose", description="Plan phase {N}")
+```
+
+### 3. Review Plan
+
+Read the generated plan. Present to employee:
+
+```
+◆ Phase {N} Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Tasks: {count}
+  Waves: {count}
+
+  Wave 1 (parallel):
+    Task 1: {title}
+    Task 2: {title}
+
+  Wave 2 (after Wave 1):
+    Task 3: {title}
+
+  Approve? (yes / adjust)
+```
+
+If "adjust" — get feedback, re-spawn planner with revision context.
+
+### 4. Update State
+
+Update STATE.md: status → "planned"
+Update tracking.json: status → "planned"
+
+```
+  → Run: /qualia-build {N}
+```

package/skills/qualia-polish/SKILL.md

@@ -0,0 +1,57 @@
+---
+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
+
+```
+◆ QUALIA ► POLISHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 1. Critique
+Review the entire UI. Check:
+- Visual hierarchy and information architecture
+- Color consistency, contrast, readability
+- Spacing and alignment
+- Component consistency across pages
+
+### 2. Polish
+Fix what critique found:
+- Alignment and spacing issues
+- Font consistency
+- Color palette adherence (Qualia teal brand)
+- Transition and hover state consistency
+
+### 3. Harden
+Edge cases and robustness:
+- Empty states (no data, loading, error)
+- Text overflow, long content
+- Mobile responsive (check all breakpoints)
+- Error messages (user-friendly, not technical)
+
+### 4. Qualia Frontend Rules
+- Distinctive fonts (not Inter/Arial)
+- Cohesive color palette with sharp accents
+- CSS transitions, staggered animations
+- Full-width layouts, no hardcoded max-width caps
+- No card grids, no generic heroes, no blue-purple gradients
+
+### 5. Commit & Update
+
+```bash
+git add {changed files}
+git commit -m "polish: design and UX pass"
+```
+
+Update STATE.md: "polish complete"
+Update tracking.json: status → "polished"
+
+```
+  → Run: /qualia-ship
+```

package/skills/qualia-quick/SKILL.md

@@ -0,0 +1,25 @@
+---
+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 30 minutes that don't need full phase planning. Bug fixes, small features, tweaks.
+
+## Process
+
+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
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+No plan file. No subagents. Just build and ship.
+
+Update STATE.md last activity. Update tracking.json notes.

package/skills/qualia-report/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: qualia-report
+description: "Generate session report as DOCX and auto-upload to ERP. Mandatory before clock-out."
+---
+
+# /qualia-report — Session Report
+
+Generate a concise DOCX report of what was done. Auto-uploads to the ERP.
+
+## Process
+
+### 1. Gather Data
+
+```bash
+echo "---COMMITS---"
+SINCE="8 hours ago"
+git log --oneline --since="$SINCE" 2>/dev/null | head -20
+echo "---STATS---"
+echo "COUNT:$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)"
+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"
+```
+
+### 2. Synthesize
+
+Build a concise summary:
+- **What was done:** 3-6 bullet points. Start with verbs (Built, Fixed, Added). Group related commits.
+- **Blockers:** Only if something is actually blocked.
+- **Next:** 1-3 clear next actions.
+
+### 3. Generate DOCX
+
+```bash
+mkdir -p .planning/reports
+
+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
+```
+
+### 4. Commit & Upload
+
+```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)"
+git push
+```
+
+Auto-upload to ERP:
+```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))"
+```
+
+Employee cannot skip this. Report goes directly to the ERP.
+
+Update STATE.md last activity.

package/skills/qualia-ship/SKILL.md

@@ -0,0 +1,91 @@
+---
+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
+
+```
+◆ QUALIA ► SHIPPING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 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
+
+```
+◆ QUALIA ► SHIPPED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  URL      {production url}
+  Status   HTTP 200 ✓
+  Latency  {time}ms ✓
+  Auth     ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Update STATE.md: "shipped"
+Update tracking.json: status → "shipped", deployed_url
+
+```
+  → Run: /qualia-handoff
+```