qualia-framework 2.1.0

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

@@ -0,0 +1,182 @@
+---
+name: qualia-start
+description: "Activate Qualia mode for the entire session. Auto-invoked on SessionStart. Detects project type, gathers cross-session context, runs system health checks, loads relevant skills and patterns, enables all quality gates. Use when starting any work session to get full framework intelligence on every interaction."
+user-invocable: true
+args: []
+---
+
+# Qualia Mode — Teal Activation Dashboard
+
+Activate all framework intelligence. Gather session context, run diagnostics, render branded teal dashboard.
+
+**Auto-invoked on SessionStart and /clear.** Also callable manually with `/qualia-start`.
+
+## How This Works
+
+You will:
+1. Run bash commands to gather project data + session context
+2. Format everything into a teal-branded dashboard yourself (not raw bash output)
+3. Activate behavioral rules for the session
+
+**CRITICAL**: Do NOT dump raw bash output. YOU format the dashboard as styled text output.
+
+## Step 1: Gather Project Data
+
+Run these bash commands to collect info (combine where possible):
+
+```bash
+pwd
+```
+
+```bash
+node -e "try{const p=require('./package.json');console.log(p.name||'')}catch(e){console.log('')}" 2>/dev/null
+```
+
+```bash
+git branch --show-current 2>/dev/null || echo ""
+```
+
+```bash
+git status --porcelain 2>/dev/null | wc -l
+```
+
+```bash
+node -v 2>/dev/null || echo "none"
+```
+
+```bash
+test -f tsconfig.json && echo "yes" || echo "no"
+```
+
+```bash
+test -d supabase && echo "supabase:yes" || echo "supabase:no"; test -d .planning && echo "planning:yes" || echo "planning:no"; ls next.config.* 2>/dev/null | head -1; ls app.json expo.json 2>/dev/null | head -1; ls app.py main.py 2>/dev/null | head -1
+```
+
+```bash
+HOOKS_OK=0; HOOKS_TOTAL=0; for h in branch-guard pre-commit confirm-delete migration-validate pre-deploy-gate block-env-edit auto-format session-context-loader retention-cleanup pre-compact save-session-state session-learn notification-speak qualia-colors; do HOOKS_TOTAL=$((HOOKS_TOTAL+1)); test -f "$HOME/.claude/hooks/${h}.sh" && HOOKS_OK=$((HOOKS_OK+1)); done; echo "${HOOKS_OK}/${HOOKS_TOTAL}"
+```
+
+If `.planning/STATE.md` exists, read it. If `.planning/ROADMAP.md` exists, read it.
+
+Classify project type from signals: `web` | `voice` | `mobile` | `python-agent` | `edge-functions` | `framework` | `unknown`
+
+## Step 2: Gather Session Context
+
+This replaces the old session-context-loader. Run these:
+
+```bash
+# Cross-project session digest (last 5 sessions)
+tail -n +4 ~/.claude/knowledge/session-digest.md 2>/dev/null | head -5
+```
+
+```bash
+# Stale knowledge detection (>30 days) — only top-level .md files
+NOW=$(date +%s); find ~/.claude/knowledge -maxdepth 1 -name "*.md" -type f | while read f; do B=$(basename "$f"); [ "$B" = "session-digest.md" ] && continue; AGE=$(( (NOW - $(stat -c %Y "$f" 2>/dev/null || echo $NOW)) / 86400 )); [ "$AGE" -gt 30 ] && echo "STALE: ${B} (${AGE}d)"; done
+```
+
+```bash
+# Project pulse (git activity in last 7 days)
+for DIR in ~/Projects/*/; do [ -d "$DIR/.git" ] || continue; LAST=$(git -C "$DIR" log --oneline -1 --since="7 days ago" --format="%ar" 2>/dev/null); [ -n "$LAST" ] && echo "$(basename "$DIR")(${LAST})"; done | head -10
+```
+
+```bash
+# Check for .continue-here.md (auto-handoff from previous session)
+test -f .continue-here.md && echo "HANDOFF: .continue-here.md exists" || echo ""
+```
+
+## Step 3: Render the Dashboard
+
+**CRITICAL RENDERING RULE**: Output the dashboard as plain text directly from your response — do NOT use Bash, printf, or echo to render it. Write it as regular markdown text output. ANSI escape codes do NOT work in Claude Code text output — they show as raw garbage. Use markdown formatting instead.
+
+**Use this format** (plain text with unicode symbols, no ANSI codes):
+
+**Dashboard example** (adapt with real data, output as plain markdown text):
+
+```
+◆ Q U A L I A   M O D E
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Project    underdogsales
+  Type       web
+  Branch     fix/header-nav
+  Git        clean (0 changes)
+
+── SYSTEM ──────────────────────────────
+  ✓ Hooks       14/14
+  ✓ Node        v22.x     TS: yes
+  ✓ Supabase    linked
+
+── SESSION ─────────────────────────────
+  Recent   under(3h) giulio-agent(5h)
+  Pulse    qualia-erp underdogsales vero
+  ▲ Stale: employees.md (5d)
+
+── PROJECT ─────────────────────────────
+  Phase     3/6 — Auth Integration
+  Status    executed
+  DESIGN.md ✓   REVIEW.md ▲ stale
+
+── GATES ───────────────────────────────
+  ✓ Frontend guard    ✓ Deploy guard
+  ✓ Intent verify     ✓ Security rules
+  ✓ TypeScript        ✓ .env protection
+
+── PATTERNS ────────────────────────────
+  frontend-master  responsive  seo-master  ship
+
+── NEXT ────────────────────────────────
+  → /qualia-verify-work 3
+
+Session armed. All quality gates active.
+```
+
+### Rules:
+- Output this as **plain text** in your response, NOT via Bash/printf
+- Use `✓` for pass, `✗` for fail, `▲` for warning, `·` for skipped
+- If no `.planning/` → show "ad-hoc mode" in PROJECT section
+- If no git → show "no git"
+- If no package.json → use directory name as project
+- If .continue-here.md exists → show "▲ Handoff: read .continue-here.md" in SESSION
+- Omit sections that have no data (e.g., no SESSION section if no digest/pulse)
+
+## Step 4: Route to Next Action
+
+The NEXT section shows one routing suggestion:
+- Phase needs planning → `Run /qualia-plan-phase N`
+- Phase planned → `Run /qualia-execute-phase N`
+- Phase executed → `Run /qualia-verify-work N`
+- Gaps found → `Run /qualia-plan-phase N --gaps`
+- All phases done → `Run /qualia-audit-milestone`
+- No .planning → `Start with /qualia-new-project or work ad-hoc`
+- .continue-here.md exists → `Read .continue-here.md and resume`
+
+## Step 5: Activate Behavioral Rules
+
+After rendering the dashboard, activate these for the rest of the session:
+
+1. **Frontend guard**: Before writing *.tsx, *.jsx, *.css — read DESIGN.md first
+2. **Deploy guard**: Before vercel --prod — check REVIEW.md freshness
+3. **Intent verification**: When 3+ files will change — list and confirm
+4. **Quality defaults**: Security rules, tsc checks, RLS consideration
+
+## Step 6: Load Patterns
+
+Note relevant skills for the session (do NOT read them now):
+
+| Project Type | Active Patterns |
+|-------------|-----------------|
+| web | frontend-master, responsive, seo-master, qualia-review, ship, deploy-verify |
+| voice | voice-agent, ship, deploy-verify |
+| mobile | mobile-expo, i18n-rtl, fcm-notifications |
+| python-agent | test-runner |
+| edge-functions | supabase, ship |
+| framework | test-runner |
+
+If Sakani detected: also load sakani-conventions, i18n-rtl, nestjs-backend, financial-ledger, subscription-payments.
+
+## Persistence
+
+Qualia mode persists through the session via:
+1. CLAUDE.md "Qualia Mode" section describes always-on behaviors
+2. Compaction rules preserve "Qualia mode: active" state
+3. If `/compact` is needed, compacted context includes "Qualia mode is active"

package/framework/skills/qualia-verify-work/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: qualia-verify-work
+description: "Conversational UAT testing for a completed phase — verify work meets requirements with persistent test tracking. Use this skill whenever the user says 'verify', 'test phase', 'check work', 'UAT', 'verify work', or wants to validate that a completed phase meets its acceptance criteria. Also trigger when user mentions 'quality check', 'does this work', or needs to run through verification of implemented features."
+---
+
+# Qualia Verify Work — Phase UAT Testing
+
+Run conversational UAT (User Acceptance Testing) for a completed phase with persistent state tracking.
+
+## Usage
+
+`/qualia-verify-work 3` — Verify phase 3
+`/qualia-verify-work` — Auto-detect phase needing verification
+
+## Process
+
+### 1. Load Context
+
+Read:
+- `.planning/STATE.md`
+- `.planning/ROADMAP.md`
+- Phase PLAN.md — for acceptance criteria
+- Phase SUMMARY.md — for what was implemented
+
+Reference: `~/.claude/qualia-engine/workflows/verify-work.md`
+
+### 2. Create UAT Tracking
+
+Create `{phase}-UAT.md` using template from `~/.claude/qualia-engine/templates/UAT.md`:
+
+```markdown
+# Phase {N}: {Name} — UAT Results
+
+## Test Results
+
+| # | Test | Status | Notes |
+|---|------|--------|-------|
+| 1 | [from acceptance criteria] | ⏳ | |
+| 2 | ... | ⏳ | |
+
+## Issues Found
+(none yet)
+
+## Overall: ⏳ In Progress
+```
+
+### 3. Conversational Testing
+
+Walk through each acceptance criterion from the PLAN.md:
+- Test the feature/behavior
+- Record pass (✅) or fail (❌) in the UAT table
+- For failures, document what went wrong
+
+This is interactive — discuss findings with the user as you go.
+
+### 4. Handle Results
+
+#### All tests pass:
+Update UAT.md overall status to ✅ PASSED. Update STATE.md phase status to `verified`.
+> "Phase {N} verified! Run `/qualia-progress` for next steps."
+
+#### Issues found:
+Document gaps in UAT.md. For each gap:
+- What's wrong
+- Severity (blocker, major, minor)
+- Suggested fix approach
+
+Then offer:
+> "Found {N} issues. Run `/qualia-plan-phase {phase} --gaps` to create fix plans, then `/qualia-execute-phase {phase} --gaps-only` to fix them."
+
+### 5. Shipping Checklist Cross-Reference
+
+After UAT testing, cross-reference results against the relevant shipping checklist from `~/Projects/qualia-erp/docs/completion-checklists.md`.
+
+Detect project type from `.planning/PROJECT.md` or `package.json` and load:
+- **website** → "Website-Specific Checklist" + "Universal Checklist"
+- **agent** → "AI Agent Checklist" + "Universal Checklist"
+- **voice** → "Voice Agent Checklist" + "Universal Checklist"
+- **mobile** → "Mobile App Checklist" + "Universal Checklist"
+- **platform** → "Platform with LLM Checklist" + "Universal Checklist"
+
+For items relevant to this phase's scope, verify each one:
+- Run automated checks where possible (grep for service_role, check meta tags, etc.)
+- Add unchecked items as additional UAT entries in the phase UAT.md
+- Report: "Shipping checklist: X/Y items verified for this phase"
+
+Do NOT check items outside this phase's scope (e.g., don't check deployment items during a Phase 1 verify).
+
+### 6. Design Quality Check (Frontend Phases)
+
+If the phase involves frontend work (detected from PLAN.md file references or phase description), after UAT passes with zero issues, suggest the design quality workflow:
+
+`/critique` → `/polish` → `/harden` → then proceed to next phase.
+
+This is advisory — user can skip by running the next command directly.
+
+### 7. Update State
+
+Update `.planning/STATE.md` to reflect verification status.
+
+### Agents Used
+| Agent | File | Role |
+|-------|------|------|
+| `qualia-planner` | `~/.claude/agents/qualia-planner.md` | Creates fix plans from diagnosed gaps |
+| `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates fix plans (max 3 iterations) |

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

@@ -0,0 +1,130 @@
+---
+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 | VAPI or Hume EVI | Depending on emotion needs |
+| Automation | n8n | Workflow orchestration |
+| Monitoring | LangSmith | LLM observability |
+
+## 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
+- **VAPI MCP**: Voice agent configuration
+- **Telnyx MCP**: Phone numbers, messaging, calls
+- **ElevenLabs MCP**: Voice synthesis
+- **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)