qualia-framework 2.6.0 → 3.2.0

package/skills/qualia-report/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: qualia-report
+description: "Generate session report and commit to repo. Mandatory before clock-out."
+---
+
+# /qualia-report — Session Report
+
+Generate a concise report of what was done. Committed to git and uploaded to the ERP for clock-out.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner report
+```
+
+### 1. Gather Data
+
+```bash
+SINCE="8 hours ago"
+echo "---COMMITS---"
+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---"
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+### 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 Report
+
+Write to `.planning/reports/report-{YYYY-MM-DD}.md`:
+
+```markdown
+# Session Report — {YYYY-MM-DD}
+
+**Project:** {name}
+**Employee:** {git user.name}
+**Branch:** {branch}
+**Phase:** {N} — {name} ({status})
+**Date:** {YYYY-MM-DD}
+
+## What Was Done
+- {accomplishment 1}
+- {accomplishment 2}
+- {accomplishment 3}
+
+## Blockers
+None. / - {blocker}
+
+## Next Steps
+1. {next action}
+2. {next action}
+
+## Commits
+{list from git log}
+```
+
+### 4. Commit and Push
+
+```bash
+mkdir -p .planning/reports
+git add .planning/reports/report-{date}.md
+git commit -m "report: session {YYYY-MM-DD}"
+git push
+```
+
+### 5. Upload to ERP
+
+**This step is MANDATORY** — the clock-out modal requires the report to be uploaded.
+
+```bash
+ERP_URL="https://portal.qualiasolutions.net"
+API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
+REPORT_FILE=".planning/reports/report-{date}.md"
+EMAIL=$(git config user.email)
+PROJECT=$(basename $(pwd))
+
+curl -s -X POST "$ERP_URL/api/claude/report-upload" \
+  -H "X-API-Key: $API_KEY" \
+  -F "file=@$REPORT_FILE" \
+  -F "employee_email=$EMAIL" \
+  -F "project_name=$PROJECT"
+```
+
+If the upload succeeds, print: "Report uploaded to ERP. You can now clock out."
+If it fails (no API key, network error), print the error and tell the employee to ask Fawzi.
+
+### 6. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"
+```
+
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+Employee cannot skip this. Run `/qualia-report` before clock-out.

package/skills/qualia-resume/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: qualia-resume
+description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+---
+
+# /qualia-resume — Resume Work
+
+Restore context and route to the right next action.
+
+## Process
+
+### 1. Find Context (priority order)
+
+1. `.continue-here.md` — richest source, from `/qualia-pause`
+2. `.planning/STATE.md` — project state
+3. Git history — `git log --oneline -10` + `git diff --stat`
+
+### 2. Restore
+
+**If `.continue-here.md` exists:** Read fully. Summarize: what was done, what's in progress, next steps, blockers.
+
+**If only STATE.md:** Read STATE.md + tracking.json. Show current phase and status.
+
+**If neither:** Reconstruct from git. Present findings, ask user to confirm.
+
+### 3. Detect Incomplete Work
+
+- Phase has plan but no verification → execution may be incomplete
+- Uncommitted changes → `git status --short`
+- Phase marked in-progress in STATE.md
+
+### 4. Present and Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner resume
+node ~/.claude/bin/qualia-ui.js info "Last session: {summary}"
+```
+
+If uncommitted changes:
+```bash
+node ~/.claude/bin/qualia-ui.js warn "{N} uncommitted files"
+```
+
+End with the next command:
+```bash
+node ~/.claude/bin/qualia-ui.js next "{next command}"
+```
+
+Clean up `.continue-here.md` after restoration (or offer to keep it).

package/skills/qualia-review/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: qualia-review
+description: "Production audit and code review. General review, --web for web app audit, --ai for AI/voice agent audit. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+---
+
+# /qualia-review — Production Audit
+
+Deep review with severity-scored findings. Different from `/qualia-verify` (which checks phase goals). This checks production readiness.
+
+## Usage
+
+- `/qualia-review` — General code review
+- `/qualia-review --web` — Web app production audit
+- `/qualia-review --ai` — AI/voice agent audit
+
+## General Review (default)
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner review
+```
+
+Spawn parallel agents analyzing:
+
+1. **Code Quality** — Clean code, TypeScript strictness, naming, readability
+2. **Security** — OWASP top 10, auth server-side, RLS policies, secrets scan
+3. **Architecture** — Component boundaries, coupling, API contracts
+4. **Performance** — N+1 queries, bundle size, caching, render performance
+5. **Test Coverage** — Gaps, edge cases, test quality
+
+## --web (Web App Audit)
+
+Full production readiness for Next.js + Supabase + Vercel:
+
+**Security:** No secrets in code, HTTPS, CORS restricted, CSP headers, rate limiting, npm audit clean.
+
+**Performance:** Core Web Vitals (LCP < 2.5s, CLS < 0.1), image optimization, bundle analysis, query performance.
+
+**Reliability:** Error boundaries, API error handling, graceful degradation, health check endpoint.
+
+**Observability:** Error tracking (Sentry), structured logging, uptime monitoring, analytics.
+
+## --ai (AI/Voice Agent Audit)
+
+Auto-detect stack (VAPI, ElevenLabs, Retell, OpenAI, Anthropic, pgvector).
+
+**Prompt Safety:** System prompts not exposed, injection defenses, no eval() on AI output, token limits.
+
+**Conversation Flow:** Off-topic handling, context window management, error recovery, human handoff.
+
+**Voice (if detected):** Latency < 500ms, interruption handling, silence timeout, webhook security.
+
+**RAG (if detected):** Embedding consistency, chunk size, retrieval relevance, index refresh.
+
+**Resilience:** Provider failover, timeout handling, cost monitoring, streaming error recovery.
+
+## Output
+
+Every finding:
+- **What** — description
+- **Where** — `file:line`
+- **Fix** — concrete suggestion
+- **Severity** — CRITICAL / HIGH / MEDIUM / LOW
+
+Write to `.planning/REVIEW.md`. CRITICAL or HIGH findings are deploy blockers — `/qualia-ship` checks for them.
+
+```
+⬢ Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Critical:  {N}
+  High:      {N}
+  Medium:    {N}
+  Low:       {N}
+
+  {If blockers: Fix CRITICAL/HIGH before /qualia-ship}
+  {If clean: Ready to ship}
+```

package/skills/qualia-ship/SKILL.md

@@ -0,0 +1,90 @@
+---
+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
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner ship
+```
+
+### 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
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "URL: {production url}"
+node ~/.claude/bin/qualia-ui.js ok "Status: HTTP 200"
+node ~/.claude/bin/qualia-ui.js ok "Latency: {time}ms"
+node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to shipped --deployed-url {production url}
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "SHIPPED" "/qualia-handoff"
+```

package/skills/qualia-skill-new/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: qualia-skill-new
+description: "Author a new Qualia skill or agent. Use when the user says 'create a new skill', 'add a skill', 'I want to build a skill', 'make this a reusable command', 'turn this into a skill'. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo."
+---
+
+# /qualia-skill-new — Author a New Skill
+
+You are about to create a reusable slash command. Skills are the leverage of the Qualia framework — if the team does something twice, it probably belongs here.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner skill-new
+```
+
+### 1. Scope Decision
+
+Ask the user with AskUserQuestion:
+
+```
+question: "Where should this skill live?"
+header: "Scope"
+options:
+  - label: "Framework skill (ships to the team)"
+    description: "Edit qualia-framework repo. Everyone gets it on next update."
+  - label: "Local skill (just me)"
+    description: "Lives only in ~/.claude/skills/. Not shared."
+  - label: "Agent instead of a skill"
+    description: "This is a subagent role, not a slash command. Creates agents/{name}.md."
+```
+
+### 1a. Resolve framework directory
+
+If the user chose **Framework skill** or a framework-scoped **Agent**, resolve `${FRAMEWORK_DIR}` — the checkout path of this user's qualia-framework repo — BEFORE computing any target paths. Never hardcode `/home/<user>/...`; different teammates and operating systems have different paths.
+
+```bash
+# Priority order: env var → git detection → ask user
+FRAMEWORK_DIR="${QUALIA_FRAMEWORK_DIR:-}"
+if [ -z "$FRAMEWORK_DIR" ] && git -C . rev-parse --show-toplevel >/dev/null 2>&1; then
+  ORIGIN=$(git -C . config --get remote.origin.url 2>/dev/null)
+  case "$ORIGIN" in
+    *qualia-framework*) FRAMEWORK_DIR=$(git -C . rev-parse --show-toplevel) ;;
+  esac
+fi
+echo "${FRAMEWORK_DIR:-UNRESOLVED}"
+```
+
+If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework checkout? (absolute path, or type 'local' to save only to ~/.claude/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
+
+**Framework** → target: `${FRAMEWORK_DIR}/skills/{name}/SKILL.md`
+**Local** → target: `~/.claude/skills/{name}/SKILL.md`
+**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `~/.claude/agents/{name}.md` (local)
+
+### 2. Gather Requirements
+
+Ask the user — one question at a time, natural conversation:
+
+1. **"What's the name?"** — kebab-case, prefix with `qualia-` for framework skills. E.g., `qualia-seed-db`.
+2. **"What does it do?"** — one sentence, used as the description.
+3. **"How does the user invoke it?"** — trigger phrases they'd naturally say. E.g., "seed the database", "load test data", "populate dev db".
+4. **"Does it need planning / building / verification?"** — if yes, it probably should spawn an agent. If no, it's a direct-action skill.
+5. **"What files does it read or write?"** — tells you what tools to restrict to.
+
+### 3. Read Reference Skills
+
+Before writing, read two existing skills that are structurally similar:
+
+```bash
+# Short direct-action skill reference:
+cat ~/.claude/skills/qualia-learn/SKILL.md
+
+# Skill-that-spawns-an-agent reference:
+cat ~/.claude/skills/qualia-plan/SKILL.md
+
+# Interactive wizard reference:
+cat ~/.claude/skills/qualia-new/SKILL.md
+```
+
+Pick the closest pattern and copy its structure.
+
+### 4. Write the SKILL.md
+
+Every SKILL.md MUST have:
+
+```markdown
+---
+name: {kebab-case-name}
+description: "{one sentence}. {trigger phrases}"
+---
+
+# /{name} — {Human Title}
+
+{one-paragraph explanation}
+
+## Usage
+
+`/{name}` — {default behavior}
+`/{name} {arg}` — {with argument}
+
+## Process
+
+### 1. {First Step}
+{specifics}
+
+### 2. {Second Step}
+{specifics}
+
+### N. Update State (only if this skill changes project state)
+
+```bash
+node ~/.claude/bin/state.js transition --to {status} ...
+```
+Do NOT manually edit STATE.md or tracking.json.
+```
+
+**Description field rules:**
+- MUST include trigger phrases the user would naturally say
+- The Claude Code router matches user messages against descriptions — if you don't list triggers, the skill never fires
+- Bad: `"Manages database seeding."` (no triggers)
+- Good: `"Seed the database with test data. Trigger on 'seed db', 'load test data', 'populate dev'."`
+
+### 5. Test the Skill
+
+Spawn a fresh subagent to simulate running the skill — does it make sense without the context you have right now?
+
+```
+Agent(prompt="
+Read this skill: @~/.claude/skills/{name}/SKILL.md
+
+Pretend the user just said '{one of the trigger phrases}'. Walk through what you would do, step by step. Flag anything ambiguous or missing.
+", subagent_type="general-purpose", description="Test skill {name}")
+```
+
+Fix any ambiguity the test agent found.
+
+### 6. Install (if framework skill)
+
+```bash
+# Framework skill — copy to local .claude for immediate testing
+mkdir -p ~/.claude/skills/{name}
+cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ~/.claude/skills/{name}/SKILL.md
+
+# Verify it parses
+node -e "const fs=require('fs');const os=require('os');const path=require('path');const c=fs.readFileSync(path.join(os.homedir(),'.claude/skills/{name}/SKILL.md'),'utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
+```
+
+### 7. Commit (framework skills only)
+
+Do NOT commit unless the user explicitly says "commit" or "ship it".
+
+When they do:
+```bash
+cd "${FRAMEWORK_DIR}"
+git add skills/{name}/
+git commit -m "feat: add /{name} skill"
+```
+
+Remind the user to run `npx qualia-framework update` on their other machines, or bump the version and `npm publish`.
+
+## Anti-Patterns
+
+- ❌ **Description without triggers** — the skill won't fire
+- ❌ **Multiple commands in one skill** — split into two skills
+- ❌ **Direct file writes instead of state.js** — always use state.js for STATE.md/tracking.json
+- ❌ **Hardcoded project paths** — use `.planning/` relative or `~/.claude/` absolute, never `/home/specific-user/`
+- ❌ **Skills that spawn agents without passing PROJECT.md and STATE.md context** — agents are blind by default
+- ❌ **Skills longer than ~150 lines** — split or move logic to an agent

package/skills/qualia-task/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: qualia-task
+description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+---
+
+# /qualia-task — Single Task Builder
+
+Build one thing properly. Fresh builder context, atomic commit, but no phase plan needed.
+
+## Usage
+`/qualia-task` — describe what to build interactively
+`/qualia-task {description}` — build it directly
+
+## When to Use
+- One feature, 1-5 files, clear scope, 1-3 hours of work
+- Adding a single feature, component, API route, or integration
+- Refactoring one module
+- Building something specific someone asked for
+
+## Process
+
+### 1. Clarify
+
+If no description provided, ask: **"What do you want to build?"**
+
+Then use AskUserQuestion:
+
+```
+question: "How complex is this task?"
+header: "Scope"
+options:
+  - label: "Small (1-2hrs)"
+    description: "Single file or component, straightforward implementation"
+  - label: "Medium (2-3hrs)"
+    description: "Multiple files, some integration work, needs testing"
+  - label: "Large (3hrs+)"
+    description: "Significant feature, multiple components — use /qualia-plan instead"
+```
+
+If "Large" — suggest `/qualia-plan` instead. Ask if they want to proceed anyway.
+
+### 2. Task Spec
+
+Write a quick task spec (don't save to file, just confirm with user):
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner task
+node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
+node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify}"
+node ~/.claude/bin/qualia-ui.js info "Done: {what done looks like}"
+```
+
+Ask: **"Good to build?"**
+
+### 3. Build
+
+Spawn a builder agent with the task:
+
+```
+Agent(subagent_type: "qualia-builder")
+
+Task: {task description}
+Files: {files to create/modify}
+Done when: {completion criteria}
+
+Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
+```
+
+The builder runs in fresh context — reads before writing, follows rules, commits atomically.
+
+### 4. Verify
+
+After the builder finishes:
+- Run `npx tsc --noEmit` if TypeScript
+- Quick smoke test if applicable
+- Review what was built
+
+### 5. Report
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Task: {description}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
+node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
+node ~/.claude/bin/qualia-ui.js end "TASK COMPLETE"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{task description}"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-verify/SKILL.md

@@ -0,0 +1,113 @@
+---
+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)
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner verify {N} "{phase name}"
+node ~/.claude/bin/qualia-ui.js spawn verifier "Goal-backward check..."
+```
+
+```
+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="qualia-verifier", description="Verify phase {N}")
+```
+
+### 2b. Browser QA (if phase touched frontend)
+
+If the phase plan's Files section includes any `.tsx`, `.jsx`, `.css`, `.scss`, or `app/`/`pages/`/`components/` paths, ALSO spawn the browser QA agent in parallel:
+
+```bash
+# Detect frontend touch
+grep -l "\.tsx\|\.jsx\|\.css\|app/\|components/\|pages/" .planning/phase-{N}-plan.md && FRONTEND=true
+```
+
+If frontend:
+
+```
+Agent(prompt="
+Read your role: @agents/qa-browser.md
+
+Phase plan: @.planning/phase-{N}-plan.md
+Existing verification: @.planning/phase-{N}-verification.md
+
+Drive the running dev server and test the routes this phase touched. Append a '## Browser QA' section to the verification file.
+", subagent_type="qualia-qa-browser", description="Browser QA phase {N}")
+```
+
+Wait for both the main verifier and the QA browser agent before moving to step 3. If Playwright MCP is unavailable, the QA browser agent returns BLOCKED — that's not a phase failure, just a note in the report.
+
+### 3. Present Results
+
+Read the verification report. Present:
+
+**If PASS:**
+```bash
+node ~/.claude/bin/qualia-ui.js ok "All {count} criteria passed"
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} VERIFIED" "/qualia-plan {N+1}"
+```
+(If phase == total phases, use `/qualia-polish` as the next command.)
+
+**If FAIL:**
+```bash
+node ~/.claude/bin/qualia-ui.js ok "Passed: {pass_count}"
+node ~/.claude/bin/qualia-ui.js fail "Failed: {fail_count}"
+```
+
+Then for each gap:
+```bash
+node ~/.claude/bin/qualia-ui.js fail "{gap description}"
+```
+
+End:
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} GAPS FOUND" "/qualia-plan {N} --gaps"
+```
+
+### 4. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to verified --phase {N} --verification {pass|fail}
+```
+If PASS and more phases: state.js auto-advances to the next phase.
+If FAIL and gap_cycles >= 2: state.js returns GAP_CYCLE_LIMIT — tell the employee to escalate.
+If FAIL and gap_cycles < 2: proceed to `/qualia-plan {N} --gaps`.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+### 5. Passive Knowledge Capture (on FAIL)
+
+When verification fails, after showing the gaps, ask the user:
+
+> *"Was any of this a recurring issue worth saving to common-fixes.md? (yes / no / which ones)"*
+
+If yes, for each flagged gap spawn a brief `/qualia-learn` flow with type=`fix` — the gap title and fix direction from the verification report become the entry. Do NOT save every failure automatically — only the ones the user flags. The point is to build a real knowledge base, not a log of every mistake.