qualia-framework 2.4.8 → 2.4.9

package/framework/CLAUDE.md

@@ -1,42 +1,39 @@
-# CLAUDE.md — Qualia Solutions
+# CLAUDE.md — OWNER Profile
 
 ## Identity
-**Fawzi Goussous** — Founder, Qualia Solutions. Nicosia, Cyprus.
-
+**Fawzi Goussous** — Founder at Qualia Solutions. Nicosia, Cyprus.
+One-man dev shop. Websites, AI agents, voice agents, AI automation.
+- Direct, action-oriented, no fluff. Code > theory.
+- يعني اذا حكى عربي رد عربي، اذا انجليزي رد انجليزي، واذا خلط خلط معه
 - Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
-- Partner: Jay | Team: Moayad (full-time, Jordan), Ahasan (part-time, Cyprus)
 
 ## Role: OWNER
-
-Full authority over all projects, deployments, architecture, and client decisions.
-- Deploy directly to production
-- Make architectural decisions unilaterally
-- Access all Supabase projects and service role keys
-- Modify the Qualia framework (CLAUDE.md, skills, hooks)
+You are the founder. Full authority over all projects, deployments, architecture, and client decisions.
+- Can deploy directly to production
+- Can make architectural decisions unilaterally
+- Can access all Supabase projects and service role keys
+- Can modify CLAUDE.md, skills, hooks, and framework config
+- Can approve/reject employee work
 
 ## Rules
 - Read before Write/Edit — no exceptions
-- Feature branches only — never commit to main/master
+- Feature branches preferred — OWNER may push to main when necessary (branch-guard enforces for non-OWNER)
 - MVP first. Build only what's asked. No over-engineering.
 - Root cause on failures — no band-aids
 - `npx tsc --noEmit` after multi-file TS changes
 - Glob/Grep directly — no Task(Explore) unless 5+ rounds needed
-- For non-trivial work (multi-file changes, architectural decisions, unfamiliar codebases), confirm understanding before coding — quick tasks are exempt
+- For non-trivial work (multi-file changes, architectural decisions, unfamiliar codebases), confirm understanding before coding: "Here's what I understand: [summary]. Correct?" — quick tasks (typo, single-file, familiar pattern) are exempt
 - See `rules/security.md` for auth, RLS, Zod, secrets rules
 - See `rules/frontend.md` for design standards
 - See `rules/deployment.md` for deploy checklist
-- See `rules/speed.md` for tool usage and workflow shortcuts
-- See `rules/context7.md` for library documentation lookup
 
 ## Collaboration
 Collaborator, not executor. Speak up about bugs, simpler approaches, bad architecture.
 Be honest. Default to action. Never speculate on unread code. Say when blocked.
-- Direct, action-oriented, no fluff. Code > theory.
-- Arabic or English — match whatever language is used
 
 ## Workflow
 - **MANDATORY FIRST ACTION**: On every session start, invoke the `qualia-start` skill before doing anything else. This is non-negotiable — do not wait for user input, do not skip it, do not just acknowledge the hook message. Actually invoke the skill using the Skill tool.
-- Subagents (Opus) for research and complex reasoning.
+- Subagents default to Opus (set via CLAUDE_CODE_SUBAGENT_MODEL).
 - `/compact` at 60%. `/clear` between tasks. `/learn` after mistakes.
 
 ## Qualia Mode (always active)

package/framework/agents/backend-agent.md

@@ -3,7 +3,7 @@ name: backend-agent
 description: Backend/database specialist - Supabase, APIs, Edge Functions. Spawned for parallel backend development.
 category: development
 tools: Read, Write, Edit, Glob, Grep, Bash
-model: claude-opus-4-6
+model: inherit
 skills:
   - supabase
 tags: [backend, supabase, api, database, typescript]

package/framework/agents/frontend-agent.md

@@ -2,8 +2,8 @@
 name: frontend-agent
 description: Frontend implementation specialist - React, TypeScript, CSS, animations. Spawned for parallel UI development.
 category: development
-tools: Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*)
-model: claude-opus-4-6
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: inherit
 skills:
   - frontend-master
   - responsive

package/framework/agents/test-agent.md

@@ -3,7 +3,7 @@ name: test-agent
 description: Testing and QA specialist - unit tests, integration tests, E2E with Playwright. Spawned for parallel test development.
 category: testing
 tools: Read, Write, Edit, Glob, Grep, Bash
-model: claude-sonnet-4-20250514
+model: inherit
 tags: [testing, jest, vitest, playwright, qa]
 ---
 

package/framework/hooks/auto-format.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
-# Auto-format hook for PostToolUse(Write)
+# Auto-format hook for PostToolUse(Write/Edit)
 # Runs prettier on supported file types if available in the project
+source "$(dirname "$0")/qualia-colors.sh"
 
 # Parse file path from stdin JSON (Claude Code hook protocol)
 if [ ! -t 0 ]; then

package/framework/hooks/block-env-edit.sh

@@ -9,7 +9,10 @@ else
     FILE_PATH="${1:-}"
 fi
 
-[ -z "$FILE_PATH" ] && exit 0
+if [ -z "$FILE_PATH" ]; then
+    printf '{"continue":true}'
+    exit 0
+fi
 
 BASENAME=$(basename "$FILE_PATH")
 
@@ -35,4 +38,5 @@ EOJSON
     exit 2
 fi
 
+printf '{"continue":true}'
 exit 0

package/framework/hooks/migration-validate.sh

@@ -58,9 +58,9 @@ if [ -n "$COMMAND" ] && echo "$COMMAND" | grep -qE 'supabase\s+db\s+push'; then
     # Scan only uncommitted or recently modified migration files
     MODIFIED_MIGRATIONS=$(git diff --name-only HEAD -- supabase/migrations/*.sql 2>/dev/null; git diff --cached --name-only -- supabase/migrations/*.sql 2>/dev/null; git ls-files --others -- supabase/migrations/*.sql 2>/dev/null)
     if [ -n "$MODIFIED_MIGRATIONS" ]; then
-        echo "$MODIFIED_MIGRATIONS" | sort -u | while IFS= read -r sql_file; do
+        while IFS= read -r sql_file; do
             [ -f "$sql_file" ] && check_sql_file "$sql_file"
-        done
+        done < <(echo "$MODIFIED_MIGRATIONS" | sort -u)
     fi
 fi
 

package/framework/hooks/notification-speak.sh

@@ -12,4 +12,5 @@ if [ -n "$TEXT" ]; then
     ~/.claude/scripts/speak.sh "$TEXT" &
 fi
 
+printf '{"continue":true}'
 exit 0

package/framework/hooks/pre-compact.sh

@@ -52,4 +52,5 @@ cat > "$COMPACT_FILE" << EOF
 }
 EOF
 
+printf '{"continue":true}'
 exit 0

package/framework/hooks/qualia-colors.sh

@@ -1,10 +1,10 @@
 # Qualia teal brand palette — source this in all hooks
 # Usage: source "$(dirname "$0")/qualia-colors.sh"
 
-Q_TEAL='\033[38;2;0;188;175m'
-Q_BRIGHT='\033[38;2;45;226;210m'
-Q_DIM='\033[38;2;0;120;112m'
-Q_WHITE='\033[38;2;220;225;230m'
+Q_TEAL='\033[38;2;0;140;130m'
+Q_BRIGHT='\033[38;2;0;200;185m'
+Q_DIM='\033[38;2;0;100;92m'
+Q_WHITE='\033[38;2;230;230;230m'
 Q_PASS='\033[38;2;52;211;153m'
 Q_WARN='\033[38;2;234;179;8m'
 Q_FAIL='\033[38;2;239;68;68m'

package/framework/hooks/retention-cleanup.sh

@@ -44,9 +44,19 @@ find "$CLAUDE_DIR/tasks/" -mindepth 1 -type d -empty -delete 2>/dev/null
 # plans/ — keep 7 days (old Claude Code plan mode files)
 find "$CLAUDE_DIR/plans/" -type f -mtime +7 -delete 2>/dev/null
 
+# downloads/ — keep 7 days
+find "$CLAUDE_DIR/downloads/" -type f -mtime +7 -delete 2>/dev/null
+
+# image-cache/ — keep 7 days
+find "$CLAUDE_DIR/image-cache/" -type f -mtime +7 -delete 2>/dev/null
+
+# thoughts/ — keep 14 days
+find "$CLAUDE_DIR/thoughts/" -type f -mtime +14 -delete 2>/dev/null
+
 # session-env/ session_*.json — keep last 50 (matches save-session-state.sh)
 ls -t "$CLAUDE_DIR/session-env"/session_*.json 2>/dev/null | tail -n +51 | while IFS= read -r f; do
     rm -f "$f"
 done
 
+printf '{"continue":true}'
 exit 0

package/framework/hooks/save-session-state.sh

@@ -15,6 +15,7 @@ if [ -f "$SESSION_START_FILE" ]; then
     NOW_TS=$(date +%s)
     DURATION=$((NOW_TS - START_TS))
     if [ "$DURATION" -lt 30 ]; then
+        printf '{"continue":true}'
         exit 0
     fi
 fi
@@ -180,4 +181,5 @@ ls -t "$SESSION_DIR"/session_*.json 2>/dev/null | tail -n +51 | while IFS= read
     rm -f "$f"
 done
 
+printf '{"continue":true}'
 exit 0

package/framework/hooks/session-learn.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # SessionEnd hook: prompt for lessons learned if significant work was done
 # "Significant" = more than 3 files modified in the session
+source "$(dirname "$0")/qualia-colors.sh"
 
 LEARNED_FILE="$HOME/.claude/knowledge/learned-patterns.md"
 

package/framework/qualia-framework/VERSION

@@ -1 +1 @@
-2.4.8
+2.4.9

package/framework/rules/context7.md

@@ -2,10 +2,13 @@
 alwaysApply: true
 ---
 
-When working with libraries, frameworks, or APIs — fetch current documentation instead of relying on training data. This includes setup questions, code generation, API references, and anything involving specific packages.
+Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.
+
+Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
 
 ## Steps
 
-1. If Context7 MCP is available, use `resolve-library-id` + `query-docs`
-2. Otherwise, use WebFetch or WebSearch to find current docs
-3. Answer using the fetched docs — include code examples and cite the version
+1. Always start with `resolve-library-id` using the library name and the user's question, unless the user provides an exact library ID in `/org/project` format
+2. Pick the best match (ID format: `/org/project`) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version
+3. `query-docs` with the selected library ID and the user's full question (not single words)
+4. Answer using the fetched docs

package/framework/rules/speed.md

@@ -17,8 +17,7 @@ alwaysApply: true
 **Use shortcuts:**
 - `/ship` — Full deploy pipeline (quality gates → commit → deploy → verify)
 - `/status` — Quick project health check
-- `/audit` — Deep security + quality audit
-- `/switch <project>` — Switch project context
+- `/qualia-review` — Deep security + quality audit
 - `/memory` — View/manage persistent rules
 - `/learn` — Save a lesson from a mistake
-- `/handoff` — Save context before /clear
+- `/qualia-pause-work` — Save context before /clear

package/framework/skills/animate/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Guessing leads to inappropriate or excessive animation.
 
@@ -58,7 +58,7 @@ Analyze where motion would improve the experience:
    - Who's the audience? (Motion-sensitive users? Power users who want speed?)
    - What matters most? (One hero animation vs many micro-interactions?)
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
 

package/framework/skills/bolder/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Guessing leads to generic AI slop.
 
@@ -59,7 +59,7 @@ Analyze what makes the design feel too safe or boring:
    - Who's the audience? (What will resonate?)
    - What are the constraints? (Brand guidelines, accessibility, performance)
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
 

package/framework/skills/colorize/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Guessing leads to generic AI slop colors.
 
@@ -59,7 +59,7 @@ Analyze the current state and identify opportunities:
    - **Wayfinding**: Helping users navigate and understand structure
    - **Delight**: Moments of visual interest and personality
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
 

package/framework/skills/delight/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all.
 
@@ -66,7 +66,7 @@ Identify where delight would enhance (not distract from) the experience:
    - **Helpful surprises**: Anticipating needs before users ask (productivity tools)
    - **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far.
 

package/framework/skills/design-quieter/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Guessing leads to generic design.
 
@@ -59,7 +59,7 @@ Analyze what makes the design feel too intense:
    - What's working? (Don't throw away good ideas)
    - What's the core message? (Preserve what matters)
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
 

package/framework/skills/distill/SKILL.md

@@ -30,8 +30,8 @@ You cannot do a great job without having necessary context, such as target audie
 
 Attempt to gather these from the current thread or codebase.
 
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
 
 Do NOT proceed until you have answers. Simplifying the wrong things destroys usability.
 
@@ -59,7 +59,7 @@ Analyze what makes the design feel complex or cluttered:
    - What can be removed, hidden, or combined?
    - What's the 20% that delivers 80% of value?
 
-If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
 
 **CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.
 

package/framework/skills/qualia-optimize/SKILL.md

@@ -83,7 +83,7 @@ Classify project type: `web` | `voice` | `mobile` | `agent` | `edge-functions` |
 
 ### Step 4: Spawn Wave 1 Agents (parallel)
 
-Based on mode, spawn agents in a **single message** with multiple Task() calls.
+Based on mode, spawn agents in a **single message** with multiple Agent() calls.
 
 | Mode | Agents |
 |------|--------|
@@ -93,12 +93,12 @@ Based on mode, spawn agents in a **single message** with multiple Task() calls.
 | `backend` | backend-agent only |
 | `alignment` | general-purpose with alignment prompt |
 
-**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Task() boundaries.
+**CRITICAL**: Inline ALL planning context into each agent prompt. `@` references don't work across Agent() boundaries.
 
 #### Frontend Agent Prompt
 
 ```
-Task(
+Agent(
   prompt="You are optimizing a project's frontend. Read the planning docs and codebase rules below, then analyze the actual code.
 
 <planning>
@@ -148,7 +148,7 @@ For EVERY finding, output in this exact format:
 #### Backend Agent Prompt
 
 ```
-Task(
+Agent(
   prompt="You are optimizing a project's backend. Read the planning docs and security rules below, then analyze the actual code.
 
 <planning>
@@ -201,7 +201,7 @@ For EVERY finding, output:
 #### Performance Oracle Prompt
 
 ```
-Task(
+Agent(
   prompt="You are analyzing cross-cutting performance issues. Read the project context, then analyze the codebase.
 
 <planning>
@@ -250,7 +250,7 @@ For EVERY finding, output:
 After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
 
 ```
-Task(
+Agent(
   prompt="You are synthesizing optimization findings from 3 specialist agents. Look for cross-cutting architectural issues.
 
 <wave1_findings>

package/framework/skills/qualia-production-check/SKILL.md

@@ -1,314 +0,0 @@
----
-name: qualia-production-check
-description: "Final client-handoff production audit — spawns 5+ specialist agents to check EVERYTHING before handing a project to a client. Frontend, backend, auth, UX, Supabase, silent errors, misconfigs, SEO, performance, accessibility, legal pages, error handling — the works. Use this skill whenever the user says 'production check', 'client ready', 'is it ready', 'final check', 'handoff check', 'production audit', 'ready for client', 'qualia-production-check', 'final audit', 'pre-handoff', or wants to verify a project is truly ready to give to a client."
----
-
-# Qualia Production Check — Client-Handoff Audit
-
-This is THE final check before handing a project to a client. Not a code review — a **production readiness audit** that checks everything a real user will experience.
-
-Spawns 5 specialist agents in parallel, each checking a different dimension. Then synthesizes into a structured verdict with actionable next steps.
-
-## Usage
-
-- `/qualia-production-check` — Full audit (all 5 dimensions)
-
-## Process
-
-### Step 1: Load Context
-
-```bash
-cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
-cat .planning/REQUIREMENTS.md 2>/dev/null || echo "NO_REQUIREMENTS"
-cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
-```
-
-```bash
-node -e "try{const p=require('./package.json');console.log(JSON.stringify({name:p.name,deps:Object.keys(p.dependencies||{}),devDeps:Object.keys(p.devDependencies||{})}))}catch(e){console.log('{}')}" 2>/dev/null
-```
-
-```bash
-ls -d app/ src/ pages/ components/ lib/ supabase/ public/ 2>/dev/null
-```
-
-Read `~/.claude/rules/security.md` and `~/.claude/rules/frontend.md`.
-
-Detect project type: website, AI agent, voice agent, web app, mobile.
-
-Store all content — inline into agent prompts.
-
-### Step 2: Spawn 5 Agents (parallel, single message)
-
-All agents get PROJECT.md + REQUIREMENTS.md inlined. Every finding must include: **What** | **Where** (file:line) | **Impact on client/users** | **Fix** | **Severity** (BLOCKER / WARNING / INFO).
-
-BLOCKER = client will see this and it's bad. WARNING = should fix but won't break. INFO = nice to have.
-
-#### Agent 1: User Experience & Frontend
-
-```
-Task(
-  prompt="You are auditing the user experience of a production web app that will be handed to a client.
-
-<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
-<rules>{frontend.md}</rules>
-
-Check EVERY page in app/ — open each page.tsx and layout.tsx:
-
-1. **First impression** — Does the homepage look professional? Distinctive design or generic AI slop?
-2. **Navigation** — Can users find everything? Are all nav links working? No dead links?
-3. **Loading states** — Every async operation shows feedback (skeleton, spinner, progress)
-4. **Error states** — What happens when API fails? Network disconnects? Wrong URL?
-5. **Empty states** — What do lists/tables show when empty? Helpful message or just blank?
-6. **Forms** — Validation on submit? Clear error messages? Success feedback? Disabled state while submitting?
-7. **Mobile responsive** — Check for fixed widths, overflow, touch targets too small, text readable
-8. **Typography** — Consistent fonts, readable sizes, proper hierarchy, no tiny gray text
-9. **Images** — Using next/image? Alt text? Proper sizing? Not stretched or pixelated?
-10. **404 page** — Does app/not-found.tsx exist? Is it styled? Does it help the user?
-11. **Favicon & metadata** — Title, description, OG tags, favicon all set?
-12. **Console errors** — Grep for console.log/console.error left in production code
-13. **Accessibility** — Alt text, ARIA labels, keyboard navigation, color contrast
-
-For EVERY finding: What | Where (file:line) | Impact on client | Fix | Severity (BLOCKER/WARNING/INFO)",
-  subagent_type="frontend-agent",
-  description="UX & frontend production audit"
-)
-```
-
-#### Agent 2: Auth, Security & Data Protection
-
-```
-Task(
-  prompt="You are auditing authentication and security for client handoff.
-
-<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
-<rules>{security.md}</rules>
-
-Check:
-
-1. **Auth flow completeness** — Login, signup, logout, password reset ALL work? Email verification?
-2. **Protected routes** — Every dashboard/admin/settings page checks auth? What happens if unauthenticated user visits?
-3. **RLS policies** — EVERY Supabase table has Row Level Security enabled WITH policies. No table left unprotected.
-4. **Service role exposure** — Grep for service_role or SUPABASE_SERVICE_ROLE_KEY in ANY client-side file (app/, components/, src/). Must be ZERO.
-5. **Server-side auth** — All mutations use supabase.auth.getUser() server-side. No client-side mutations with user-supplied IDs.
-6. **Input validation** — All user inputs validated with Zod or equivalent. No raw req.body usage.
-7. **XSS prevention** — No dangerouslySetInnerHTML. No eval(). No user content rendered unsanitized.
-8. **CORS** — Properly restricted, not wildcard '*' in production.
-9. **Rate limiting** — Auth endpoints (login, signup, reset) have rate limiting.
-10. **Secrets in code** — No hardcoded API keys, passwords, tokens in source files.
-11. **Environment variables** — All secrets in env vars. NEXT_PUBLIC_ only for client-safe values.
-12. **Session management** — Tokens expire and refresh properly. Logout clears session.
-
-For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
-  subagent_type="backend-agent",
-  description="Auth & security production audit"
-)
-```
-
-#### Agent 3: Backend, Database & API
-
-```
-Task(
-  prompt="You are auditing the backend and database for production readiness.
-
-<planning>{PROJECT.md + REQUIREMENTS.md}</planning>
-
-Check:
-
-1. **API error handling** — Every API route/server action has try/catch. Errors return proper HTTP status codes with meaningful messages. No stack traces exposed to client.
-2. **Database queries** — N+1 queries (Supabase calls in loops)? Missing indexes on filtered columns? Sequential queries that could be parallel?
-3. **Server actions** — All data mutations use 'use server' actions, not client-side Supabase calls? Each checks auth first?
-4. **Supabase connection** — Using server.ts for mutations, client.ts for reads? Connection pooling configured?
-5. **Migrations** — All migrations applied? Types generated and up to date? Schema matches what code expects?
-6. **Edge functions** — If supabase/functions/ exists: error handling, CORS, timeout protection, proper responses.
-7. **Caching** — revalidatePath/revalidateTag after mutations? SWR/React Query configured with sensible stale times?
-8. **Pagination** — Large data sets paginated? Not loading 10,000 rows into memory?
-9. **File uploads** — If any: size limits, type validation, virus scanning, proper storage?
-10. **Webhooks** — If any: signature verification, idempotency, error handling, retry logic?
-11. **Background jobs** — Long-running operations handled async? Not blocking API responses?
-12. **Monitoring** — Error tracking configured (Sentry or similar)? Logging meaningful events?
-
-For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
-  subagent_type="backend-agent",
-  description="Backend & database production audit"
-)
-```
-
-#### Agent 4: Performance & SEO
-
-```
-Task(
-  prompt="You are auditing performance and SEO for a client-facing production site.
-
-Check:
-
-1. **Build succeeds** — Run npm run build mentally (check for obvious build errors in imports, missing modules)
-2. **Bundle size** — Large library imports without tree-shaking? Barrel exports? Missing dynamic imports for heavy components (charts, editors, maps)?
-3. **Images** — All using next/image? WebP/AVIF format? Proper width/height? Lazy loading below fold?
-4. **Fonts** — Using next/font? No render-blocking external font loads?
-5. **Core Web Vitals** — Largest Contentful Paint risks? Cumulative Layout Shift risks? Large unoptimized images above fold?
-6. **SEO metadata** — Every page has title, description. Root layout has proper metadata. Open Graph tags for social sharing?
-7. **Sitemap** — public/sitemap.xml exists? Lists all public pages?
-8. **Robots.txt** — public/robots.txt exists? Not blocking important pages?
-9. **Structured data** — JSON-LD for business info, breadcrumbs, or relevant schema?
-10. **Canonical URLs** — Proper canonical tags to avoid duplicate content?
-11. **Lighthouse hints** — Server components used where possible? No unnecessary 'use client' directives?
-12. **API latency** — Any obvious slow queries or waterfalls in the data fetching pattern?
-
-For EVERY finding: What | Where (file:line) | Impact | Fix | Severity (BLOCKER/WARNING/INFO)",
-  subagent_type="performance-oracle",
-  description="Performance & SEO production audit"
-)
-```
-
-#### Agent 5: Completeness & Missing Features
-
-```
-Task(
-  prompt="You are checking if a project is COMPLETE — nothing missing that a client would expect.
-
-<planning>{PROJECT.md + REQUIREMENTS.md + ROADMAP.md}</planning>
-
-Check against requirements AND common expectations:
-
-1. **Requirements coverage** — Every requirement in REQUIREMENTS.md marked complete: does the feature ACTUALLY work in code? Grep for routes, components, API endpoints that implement each requirement.
-2. **Missing pages** — Common pages that clients expect: About, Contact, Privacy Policy, Terms of Service, 404, 500 error page. Which are missing?
-3. **Missing functionality** — Based on project type:
-   - Website: contact form works? Newsletter signup? Social links?
-   - Web app: settings page? Profile management? Change password? Delete account?
-   - AI agent: fallback responses? Rate limiting? Usage tracking?
-4. **Email** — If the app sends emails: are they configured? Working? Proper templates? Not going to spam?
-5. **Analytics** — Tracking configured? Google Analytics / Plausible / PostHog?
-6. **Error boundaries** — app/error.tsx exists? Styled? Provides recovery action?
-7. **Loading** — app/loading.tsx or Suspense boundaries on data-fetching pages?
-8. **Favicon & branding** — Custom favicon (not Next.js default)? Proper app title? OG image?
-9. **Legal compliance** — Cookie consent if in EU? Privacy policy if collecting data? Terms if SaaS?
-10. **Mobile** — Site works on mobile? No horizontal scroll? Touch targets adequate?
-11. **Cross-browser** — Any IE/Safari-specific CSS issues? Webkit prefixes needed?
-12. **Deployment config** — Vercel configured? Environment variables set? Domain connected?
-
-For EVERY finding: What | Where | Impact on client | Fix | Severity (BLOCKER/WARNING/INFO)",
-  subagent_type="general-purpose",
-  description="Completeness & missing features audit"
-)
-```
-
-### Step 3: Collect & Score
-
-After all 5 agents return:
-
-1. Deduplicate (same file:line from multiple agents)
-2. Group by severity: BLOCKER → WARNING → INFO
-3. Count totals
-4. Determine verdict:
-   - **READY** — 0 blockers, 0 warnings (or all warnings are cosmetic)
-   - **ALMOST** — 0 blockers, some warnings
-   - **NOT READY** — has blockers
-
-### Step 4: Present Report
-
-Output as direct text (NOT via Bash):
-
-```
-◆ PRODUCTION CHECK — CLIENT HANDOFF AUDIT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Project: {name}
-  Date: {date}
-  Verdict: {READY / ALMOST / NOT READY}
-
-  BLOCKERS: {N}    WARNINGS: {N}    INFO: {N}
-
-── BLOCKERS (must fix before handoff) ────────
-  {If none: "None — no blockers found"}
-
-  1. [{dimension}] {finding}
-     Location: {file:line}
-     Client impact: {what the client/user will experience}
-     Fix: {how to fix}
-
-  2. ...
-
-── WARNINGS (should fix) ────────────────────
-  {findings}
-
-── INFO (nice to have) ──────────────────────
-  {findings}
-
-── DIMENSION SCORES ─────────────────────────
-
-  UX & Frontend     {PASS/ISSUES}  ({N} findings)
-  Auth & Security   {PASS/ISSUES}  ({N} findings)
-  Backend & Data    {PASS/ISSUES}  ({N} findings)
-  Performance & SEO {PASS/ISSUES}  ({N} findings)
-  Completeness      {PASS/ISSUES}  ({N} findings)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Step 5: Save Report
-
-Write to `.planning/PRODUCTION-CHECK.md`:
-
-```markdown
----
-date: YYYY-MM-DD HH:MM
-verdict: ready|almost|not_ready
-blockers: N
-warnings: N
-info: N
-dimensions:
-  ux: {pass|issues}
-  security: {pass|issues}
-  backend: {pass|issues}
-  performance: {pass|issues}
-  completeness: {pass|issues}
----
-
-# Production Check — YYYY-MM-DD
-
-{Full report content}
-```
-
-Commit:
-```bash
-git add .planning/PRODUCTION-CHECK.md && git commit -m "docs: production check ({verdict}, {blockers} blockers)"
-```
-
-### Step 6: Actionable Next Steps
-
-Based on verdict:
-
-**If NOT READY (has blockers):**
-```
-## What's Next?
-
-This project has {N} blockers that clients WILL notice.
-
-1. Fix blockers now — I'll fix them one by one with /qualia-quick
-2. Create a fix milestone — /qualia-new-milestone to plan systematic fixes
-3. See specific blocker — tell me which number to investigate
-```
-
-**If ALMOST (warnings only):**
-```
-## What's Next?
-
-No blockers — the project works. {N} warnings to consider.
-
-1. Fix warnings — I'll handle the quick ones now
-2. Ship as-is — warnings won't break anything for the client
-3. Run /qualia-design — polish the visual design before handoff
-```
-
-**If READY:**
-```
-## What's Next?
-
-✓ Production ready. No blockers, no warnings worth fixing.
-
-1. Ship it — /ship
-2. Run /qualia-design — final visual polish (optional)
-3. Generate handoff docs — project summary for the client
-```
-
-Wait for user to select. Act on their choice.

package/framework/teams/review-team.md

@@ -0,0 +1,75 @@
+# Review Team
+
+> Five specialist reviewers analyze code in parallel, results synthesized into unified report.
+
+## Agents
+
+- **code-simplicity-reviewer**
+  - subagent_type: code-simplicity-reviewer
+  - role: Identify unnecessary complexity, premature abstractions, YAGNI violations, over-engineering
+  - focus: Code structure, abstractions, function complexity, dead code
+
+- **performance-oracle**
+  - subagent_type: performance-oracle
+  - role: Identify performance bottlenecks, N+1 queries, memory leaks, missing indexes, bundle size issues
+  - focus: Database queries, API latency, rendering performance, caching opportunities
+
+- **kieran-typescript-reviewer**
+  - subagent_type: kieran-typescript-reviewer
+  - role: TypeScript quality — strict types, naming conventions, pattern adherence, type safety gaps
+  - focus: Type definitions, generics usage, any/unknown, null handling, naming
+
+- **security-auditor**
+  - subagent_type: security-auditor
+  - role: RLS policies, service_role exposure, auth patterns, input validation, secrets scanning, dependency vulnerabilities
+  - focus: Supabase security, auth flows, env var handling, XSS/injection prevention
+
+- **red-team-qa** (optional — spawn when reviewing auth, payments, or user input)
+  - subagent_type: red-team-qa
+  - role: Adversarial QA — actively tries to break the implementation via edge cases, error paths, boundary conditions
+  - focus: Permission bypasses, unexpected inputs, race conditions, error handling gaps
+
+## Pattern
+
+fan-out (all 5 parallel) → synthesize into REVIEW-REPORT.md
+
+## Shared Context
+
+- .planning/STATE.md — what was built, current phase
+- Recent git diff (last N commits relevant to the review scope)
+
+## Coordination Rules
+
+- Each reviewer produces findings independently — no coordination needed
+- Reviewers are read-only — they analyze and report, they don't fix
+- Findings should include file:line references
+- Each reviewer rates findings: CRITICAL / HIGH / MEDIUM / LOW
+
+## Output
+
+REVIEW-REPORT.md in current directory with sections:
+
+```markdown
+# Review Report
+
+## Summary
+{Overall assessment — 1-2 sentences}
+
+## Simplicity Review
+{From code-simplicity-reviewer}
+
+## Performance Review
+{From performance-oracle}
+
+## TypeScript Quality Review
+{From kieran-typescript-reviewer}
+
+## Security Review
+{From security-auditor}
+
+## Action Items
+| # | Severity | Finding | File:Line | Reviewer |
+|---|----------|---------|-----------|----------|
+| 1 | Critical | ... | ... | ... |
+| 2 | Warning | ... | ... | ... |
+```

package/framework/teams/ship-team.md

@@ -0,0 +1,86 @@
+# Ship Team
+
+> Quality gate → Deploy → Verify. Pipeline pattern — abort if any step fails.
+
+## Agents
+
+- **quality-gate**
+  - subagent_type: test-agent
+  - role: Run tsc, eslint, build. Ensure no type errors, lint violations, or build failures.
+  - commands: |
+    npx tsc --noEmit
+    npx next lint (or eslint .)
+    npm run build (or next build)
+  - abort_on_fail: true
+
+- **deploy**
+  - subagent_type: general-purpose
+  - role: Commit staged changes, push to remote, deploy to hosting platform
+  - commands: |
+    git add -A && git commit (if uncommitted changes)
+    git push origin {branch}
+    vercel --prod (default) OR wrangler deploy (if armenius)
+  - abort_on_fail: true
+
+- **verify**
+  - subagent_type: test-agent
+  - role: Run 6-check post-deploy verification against production URL
+  - checks: |
+    1. HTTP 200 — homepage loads
+    2. Auth flow — login/signup endpoint responds
+    3. Console errors — no critical JS errors
+    4. API latency — key endpoints < 500ms
+    5. SSL — valid certificate
+    6. Build artifacts — no source maps exposed
+  - abort_on_fail: false (report issues but don't rollback)
+
+## Pattern
+
+pipeline: quality-gate → deploy → verify
+
+Each step must succeed before the next begins. If quality-gate fails, deployment is blocked. If deploy fails, verification is skipped.
+
+## Shared Context
+
+- ~/.claude/knowledge/qualia-context.md — project inventory, deploy commands, Supabase refs
+- .planning/STATE.md — current project state
+- Project's local CLAUDE.md — project-specific deploy config
+
+## Coordination Rules
+
+- quality-gate runs ALL checks before passing — partial pass is a fail
+- deploy detects hosting platform from project context (Vercel default, Cloudflare for armenius)
+- verify uses the production URL from deploy output
+- If Supabase project: deploy also runs `supabase db push` if pending migrations exist
+
+## Output
+
+SHIP-REPORT.md in current directory:
+
+```markdown
+# Ship Report
+
+**Date:** {date}
+**Branch:** {branch}
+**Deploy URL:** {url}
+
+## Quality Gate
+- tsc: ✓ / ✗ ({error count})
+- lint: ✓ / ✗ ({warning count})
+- build: ✓ / ✗ ({duration})
+
+## Deployment
+- Platform: Vercel / Cloudflare
+- URL: {production url}
+- Commit: {sha}
+
+## Verification
+| Check | Status | Details |
+|-------|--------|---------|
+| HTTP 200 | ✓/✗ | {status code} |
+| Auth flow | ✓/✗ | {details} |
+| Console errors | ✓/✗ | {count} |
+| API latency | ✓/✗ | {ms} |
+| SSL | ✓/✗ | {expiry} |
+| Source maps | ✓/✗ | {exposed?} |
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "description": "Qualia Solutions — Claude Code Framework",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/framework/skills/qualia-workflow/SKILL.md

@@ -1,130 +0,0 @@
----
-name: qualia-workflow
-description: Qualia Solutions project conventions - structure, patterns, deployment checklist. Use when starting or auditing Qualia client projects.
-tags: [qualia, workflow, nextjs, supabase, vercel]
----
-
-# Qualia Solutions Conventions
-
-Project conventions for Qualia Solutions client work. For specific tooling, use dedicated skills (`/supabase`, `/voice-agent`, `/deploy`, etc.).
-
-## Standard Tech Stack
-
-| Layer | Technology | Notes |
-|-------|------------|-------|
-| Frontend | Next.js 16+ + React 19 + TypeScript | App Router, Server Components |
-| Styling | Tailwind CSS + shadcn/ui | Custom themes per client |
-| Backend | Supabase | Postgres, Auth, RLS, Edge Functions |
-| Deployment | Vercel | Preview on PR, Production on main |
-| Voice AI | Retell AI + ElevenLabs | Call orchestration + TTS/voice cloning |
-| AI Models | OpenRouter | Model-flexible (Claude, Mistral, etc.) |
-| Payments | Stripe / HyperPay | Region-dependent |
-
-## Project Structure
-
-```
-project/
-├── app/                    # Next.js App Router
-│   ├── (auth)/            # Auth-required routes
-│   ├── (marketing)/       # Public pages
-│   ├── api/               # API routes (minimal, prefer server actions)
-│   └── layout.tsx         # Root layout
-├── components/
-│   ├── ui/                # shadcn/ui components
-│   ├── forms/             # Form components
-│   └── [feature]/         # Feature-specific components
-├── lib/
-│   ├── supabase/          # Supabase clients (server/client)
-│   ├── utils.ts           # Utility functions
-│   └── constants.ts       # App constants
-├── types/
-│   ├── database.ts        # Generated from Supabase
-│   └── index.ts           # App types
-├── supabase/
-│   ├── migrations/        # SQL migrations
-│   └── functions/         # Edge functions
-├── hooks/                 # Custom React hooks
-├── actions/               # Server actions
-└── public/               # Static assets
-```
-
-## Key Patterns
-
-- **Server Components first** -- only add `'use client'` when interactivity is needed
-- **Server Actions for mutations** -- always auth check first (`supabase.auth.getUser()`)
-- **Prefer server actions over API routes** -- fewer files, same security
-- **Generate types** after every migration: `npx supabase gen types typescript`
-
-## Server Action Template
-
-```typescript
-'use server'
-
-import { revalidatePath } from 'next/cache'
-import { createClient } from '@/lib/supabase/server'
-
-export async function createProduct(formData: FormData) {
-  const supabase = await createClient()
-
-  // Auth check first
-  const { data: { user }, error: authError } = await supabase.auth.getUser()
-  if (authError || !user) throw new Error('Unauthorized')
-
-  const { error } = await supabase
-    .from('products')
-    .insert({ name: formData.get('name') })
-
-  if (error) throw new Error('Failed to create product')
-
-  revalidatePath('/products')
-}
-```
-
-## Deployment Checklist
-
-1. **Environment Variables**
-   - [ ] All secrets in Vercel (not in code)
-   - [ ] Different keys for preview vs production
-   - [ ] NEXT_PUBLIC_ prefix only for client-safe vars
-
-2. **Database**
-   - [ ] Migrations applied
-   - [ ] RLS policies on all tables
-   - [ ] Indexes on frequently queried columns
-   - [ ] Types generated and committed
-
-3. **Security**
-   - [ ] No exposed API keys
-   - [ ] CORS configured
-   - [ ] Rate limiting on API routes
-   - [ ] Input validation everywhere
-
-4. **Performance**
-   - [ ] Images optimized (next/image)
-   - [ ] Fonts optimized (next/font)
-   - [ ] Bundle analyzed
-   - [ ] Core Web Vitals passing
-
-## New Feature Workflow
-
-```
-1. Database schema first (if needed)
-2. Supabase migration
-3. Generate types: npx supabase gen types typescript
-4. Server Components for data display
-5. Server Actions for mutations
-6. Client Components only for interactivity
-```
-
-## External Tools Available
-
-- **Supabase**: Use `/supabase` skill (CLI-first) or Supabase MCP plugin
-- **Context7 MCP**: Library documentation lookup
-- **Retell AI**: Voice agent call orchestration
-- **ElevenLabs MCP**: Voice synthesis and cloning
-- **Telnyx MCP**: Phone numbers, messaging, calls
-- **Playwright MCP**: Browser automation and testing
-- **Sentry MCP**: Error tracking and monitoring
-- **Firecrawl MCP**: Web scraping and search
-- **Google Calendar MCP**: Calendar operations
-- **GitHub CLI** (`gh`): PRs, issues, code review (NOT MCP — use Bash)