qualia-framework 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,151 @@
+---
+name: qualia-new
+description: "Set up a new project from scratch — questioning, scaffold, roadmap. Use when starting any new client project."
+---
+
+# /qualia-new — New Project
+
+Set up a project from zero. Creates repo, infrastructure, and planning files.
+
+## Process
+
+### 1. Question
+
+```
+◆ QUALIA ► NEW PROJECT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ask: **"What are you building?"**
+
+Listen. Then follow threads:
+- What problem does this solve?
+- Who uses it?
+- What does it look like?
+- What's already decided (design, features, tech)?
+- What's NOT in scope?
+
+Keep asking until you could write a clear PROJECT.md. Then ask: "Ready to create the project?"
+
+### 2. Detect Project Type
+
+From the answers, classify:
+- **website** — landing page, SaaS, dashboard, marketing site
+- **ai-agent** — chatbot, AI assistant, agent
+- **voice-agent** — phone agent, VAPI, Retell, call bot
+- **mobile-app** — iOS, Android, React Native, Expo
+
+If unclear, ask.
+
+### 3. Stack Confirmation
+
+Default: **Next.js + React + TypeScript + Supabase + Vercel** (the Qualia stack).
+
+If requirements suggest a different stack, ask before proceeding.
+
+### 4. Scaffold
+
+```bash
+# Create project directory if not already in one
+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).
+Configure auth URLs: Vercel domain, `/**` wildcard, `http://localhost:3000`.
+
+### 5. Create Planning Files
+
+**`.planning/PROJECT.md`:**
+```markdown
+# {Project Name}
+
+## Client
+{client name}
+
+## What We're Building
+{clear description from questioning}
+
+## Requirements
+- [ ] {requirement 1}
+- [ ] {requirement 2}
+- [ ] {requirement 3}
+
+## Out of Scope
+- {exclusion 1}
+- {exclusion 2}
+
+## Stack
+{confirmed stack}
+
+## Decisions
+| Decision | Why |
+|----------|-----|
+| {decision from questioning} | {rationale} |
+```
+
+**`.planning/STATE.md`** — use template from `templates/state.md`
+
+**`.planning/tracking.json`** — use template from `templates/tracking.json`, fill in project/client/assigned_to
+
+### 6. Create Roadmap
+
+Based on project type and requirements, 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. Get approval. Adjust if needed.
+
+### 7. 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
+```

package/skills/qualia-verify/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: qualia-verify
+description: "Goal-backward verification — checks if the phase ACTUALLY works, not just if tasks completed. Spawns verifier agent."
+---
+
+# /qualia-verify — Verify a Phase
+
+Spawn a verifier agent to check if the phase goal was achieved. Does NOT trust build summaries — greps the actual codebase.
+
+## Usage
+`/qualia-verify` — verify the current built phase
+`/qualia-verify {N}` — verify specific phase
+
+## Process
+
+### 1. Load Context
+
+```bash
+echo "---PLAN---"
+cat .planning/phase-{N}-plan.md 2>/dev/null
+echo "---PREVIOUS---"
+cat .planning/phase-{N}-verification.md 2>/dev/null || echo "NONE"
+```
+
+### 2. Spawn Verifier (Fresh Context)
+
+```
+◆ QUALIA ► VERIFYING Phase {N}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Spawning verifier...
+```
+
+```
+Agent(prompt="
+Read your role: @agents/verifier.md
+
+Phase plan with success criteria:
+@.planning/phase-{N}-plan.md
+
+{If re-verification: Previous verification with gaps:}
+{@.planning/phase-{N}-verification.md}
+
+Verify this phase. Write report to .planning/phase-{N}-verification.md
+", subagent_type="general-purpose", description="Verify phase {N}")
+```
+
+### 3. Present Results
+
+Read the verification report. Present:
+
+**If PASS:**
+```
+◆ QUALIA ► Phase {N} VERIFIED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  All {count} criteria passed.
+
+  → Run: /qualia-plan {N+1}
+```
+
+**If FAIL:**
+```
+◆ QUALIA ► Phase {N} GAPS FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Passed: {pass_count}
+  Failed: {fail_count}
+
+  Gaps:
+    ✗ {gap 1 — specific description}
+    ✗ {gap 2 — specific description}
+
+  → Run: /qualia-plan {N} --gaps
+```
+
+### 4. Update State
+
+Update STATE.md: verification result
+Update tracking.json: verification → "pass" or "fail"