qualia-framework 2.6.0 → 3.1.0

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

@@ -1,62 +0,0 @@
----
-name: qualia-resume-work
-description: "Restore context from a previous session and pick up where you left off. Use this skill whenever the user says 'resume', 'continue work', 'pick up where I left off', 'resume work', 'what was I doing', or starts a new session on an existing project. Also trigger when user mentions '.continue-here', 'last session', or needs to restore context from a previous handoff."
----
-
-# Qualia Resume Work — Session Context Restoration
-
-Restore context from a previous session and route to the right next action.
-
-## Usage
-
-`/qualia-resume-work` — Auto-detect and restore context
-
-## Process
-
-### 1. Load State
-
-Reference: `~/.claude/qualia-framework/workflows/resume-project.md`
-
-Check for context sources in priority order:
-
-1. **`.continue-here.md`** at project root — Full handoff from pause-work
-2. **`.planning/STATE.md`** — Project state file
-3. **Reconstruct from git** — `git log --oneline -10` and `git diff --stat`
-
-### 2. Context Restoration
-
-#### If `.continue-here.md` exists:
-Read it fully — it contains everything: what was done, what's in progress, next steps, decisions, blockers. This is the richest context source.
-
-#### If only STATE.md exists:
-Read STATE.md + ROADMAP.md to understand:
-- Current milestone and phase
-- Phase statuses
-- What was last worked on
-
-#### If neither exists:
-Reconstruct from git history and file structure. Present findings and ask user to confirm.
-
-### 3. Detect Incomplete Work
-
-Check for signs of interrupted work:
-- Phase has PLAN.md but no SUMMARY.md (execution started but not completed)
-- Uncommitted changes (`git status --short`)
-- Phase marked `in progress` in STATE.md
-
-### 4. Present Status
-
-Concise summary of:
-- Where the project stands
-- What was happening last session
-- Any incomplete work detected
-
-### 5. Route to Next Action
-
-Based on detected state, suggest the most logical next step:
-- Incomplete execution → "Continue with `/qualia-execute-phase {N}`"
-- Phase done but unverified → "Verify with `/qualia-verify-work {N}`"
-- Clean state → "Next up: `/qualia-plan-phase {N}`"
-- Has blockers from handoff → Surface them for user decision
-
-Clean up `.continue-here.md` after successful context restoration (or offer to keep it).

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

@@ -1,263 +0,0 @@
----
-name: qualia-review
-description: "Production audit and code review. Use --web for web app audit (security, performance, reliability), --ai for AI/voice agent audit (prompt injection, safety, RAG, voice), or no flag for general code review. Trigger on 'review', 'audit', 'code review', 'security check', 'qualia-review'."
-tags: [review, audit, security, production, ai, voice]
----
-
-# Review & Audit
-
-> **Deep parallel-agent analysis with full severity-scored report.** For a quick checklist scan without agents, run the shipping checklist manually.
-
-Unified review skill. Detects project type, spawns parallel agents, scores everything.
-
-## Usage
-
-- `/review` — General code review: quality, security, architecture, performance, tests
-- `/review --web` — Web app production audit: security hardening, performance, reliability, observability
-- `/review --ai` — AI/voice agent audit: prompt injection, safety rails, RAG quality, voice latency, conversation flow
-
----
-
-## General Code Review (default)
-
-Spawn parallel review agents for:
-
-### 1. Code Quality
-- Clean code principles, SOLID, DRY, naming
-- Code smells, readability, maintainability
-- TypeScript strictness, type safety
-
-### 2. Security
-- OWASP top 10 (injection, XSS, CSRF)
-- Auth/authorization checks server-side
-- Secrets scan, env var handling
-- RLS policies on Supabase tables
-
-### 3. Architecture
-- Component boundaries, coupling/cohesion
-- API contract stability
-- Design pattern consistency
-
-### 4. Performance
-- Database query efficiency (N+1, missing indexes)
-- Bundle size, lazy loading, render performance
-- Caching strategy
-
-### 5. Test Coverage
-- Unit/integration test gaps
-- Edge cases not covered
-- Test quality (not just coverage numbers)
-
-### Output
-Consolidated report with severity levels:
-- **CRITICAL** — Must fix before deploy (security, data loss)
-- **HIGH** — Should fix soon (performance, reliability)
-- **MEDIUM** — Recommended (code quality, maintainability)
-- **LOW** — Nice to have (style, documentation)
-
----
-
-## --web (Web App Production Audit)
-
-Full production-readiness audit for Next.js + Supabase + Vercel web apps.
-
-### Pre-Audit Discovery
-Detect: deployment target, database, auth provider, CI/CD setup.
-
-### Security Audit
-```
-CRITICAL:
-[ ] No secrets in code
-[ ] HTTPS enforced
-[ ] Auth tokens have expiry/refresh
-[ ] CORS properly restricted
-[ ] CSP headers configured
-[ ] SQL injection prevention
-[ ] XSS prevention
-[ ] Rate limiting on auth endpoints
-
-HIGH:
-[ ] npm audit clean
-[ ] Security headers (X-Frame-Options, HSTS)
-[ ] Admin routes protected
-[ ] File upload validation
-```
-
-### Performance Audit
-```
-[ ] Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)
-[ ] Image optimization (next/image, WebP)
-[ ] Bundle analysis (no oversized chunks)
-[ ] Database query performance
-[ ] API response times
-[ ] Caching strategy
-```
-
-### Reliability Audit
-```
-[ ] Error boundaries on all pages
-[ ] API error handling (timeouts, retries)
-[ ] Database connection pooling
-[ ] Graceful degradation
-[ ] Health check endpoint
-```
-
-### Observability Audit
-```
-[ ] Error tracking (Sentry or similar)
-[ ] Structured logging
-[ ] Uptime monitoring
-[ ] Analytics configured
-```
-
-### Deployment Config
-```
-[ ] Environment variables set per environment
-[ ] Build succeeds locally
-[ ] Rollback procedure documented
-[ ] Database backups configured
-```
-
----
-
-## --ai (AI/Voice Agent Production Audit)
-
-Purpose-built for voice agents, chatbots, and multi-channel AI apps.
-
-### Phase 0: Auto-Detection
-Scan package.json for:
-- **Voice**: VAPI, ElevenLabs, Retell, Telnyx
-- **Chat**: AI SDK, OpenAI, Anthropic, Gemini
-- **Channels**: WhatsApp, Telegram, Slack, Twilio
-- **RAG**: pgvector, Pinecone, ChromaDB, LangChain
-
-Skip irrelevant agents based on detection.
-
-### Prompt Safety Audit
-```
-CRITICAL:
-[ ] System prompts not exposed to users
-[ ] Prompt injection defenses (input sanitization)
-[ ] No eval() or dynamic code execution from AI output
-[ ] Output validation before rendering
-[ ] Token limits enforced
-
-HIGH:
-[ ] Prompt template versioning
-[ ] Fallback responses for edge cases
-[ ] Content filtering on AI output
-[ ] User input length limits
-```
-
-### Auth & Data Security
-```
-[ ] User context isolated per session
-[ ] API keys server-side only
-[ ] Conversation data encrypted at rest
-[ ] PII handling compliant
-[ ] Rate limiting per user
-```
-
-### Conversation Flow
-```
-[ ] Graceful handling of off-topic inputs
-[ ] Context window management (not exceeding limits)
-[ ] Conversation history pruning strategy
-[ ] Error recovery mid-conversation
-[ ] Handoff to human when needed
-```
-
-### Voice-Specific (when voice detected)
-```
-[ ] Latency < 500ms first response
-[ ] Interruption handling
-[ ] Silence detection and timeout
-[ ] Audio quality / codec settings
-[ ] VAPI webhook security (signature verification)
-[ ] Fallback TTS if primary fails
-```
-
-### RAG Quality (when embeddings detected)
-```
-[ ] Embedding consistency (same model for index/query)
-[ ] Chunk size appropriate for use case
-[ ] Metadata filtering working
-[ ] Retrieval relevance scoring
-[ ] Index refresh strategy
-```
-
-### Tool/Function Calling
-```
-[ ] Tool descriptions clear and unambiguous
-[ ] Input validation on tool parameters
-[ ] Error handling for tool failures
-[ ] Tool execution timeout
-[ ] Dangerous tools gated behind confirmation
-```
-
-### AI Resilience
-```
-[ ] Provider failover (primary → fallback model)
-[ ] Timeout handling (don't hang on slow API)
-[ ] Cost monitoring and alerts
-[ ] Token budget per request
-[ ] Streaming error recovery
-```
-
-### Output
-Severity-scored findings with exact `file:line` references and fix recommendations.
-
----
-
-## Shipping Checklist Scan
-
-After running all review agents, cross-reference findings against the relevant shipping checklist from `~/.claude/qualia-framework/references/completion-checklists.md`.
-
-Detect project type and load the matching checklist:
-- **website** → "Website-Specific Checklist" + "Universal Checklist"
-- **agent/ai** → "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 each checklist item, run automated verification where possible (grep, file checks, build checks). Include a "Shipping Checklist" section in the review report with PASS/WARN/FAIL per item. FAIL items should be scored as HIGH severity findings.
-
-## Persist Results
-
-After generating the review report, write findings to a persistent file:
-
-**Location:** `.planning/REVIEW.md` if `.planning/` exists, otherwise `.review/REVIEW.md` at project root.
-
-**Format:**
-```markdown
----
-date: YYYY-MM-DD HH:MM
-mode: general|web|ai
-critical_count: N
-high_count: N
-medium_count: N
-low_count: N
-status: clean|has_blockers
----
-
-# Review — YYYY-MM-DD
-
-## Blockers (CRITICAL + HIGH)
-- [file:line] description (CRITICAL)
-- [file:line] description (HIGH)
-
-## Recommendations (MEDIUM + LOW)
-- [file:line] description (MEDIUM)
-```
-
-**Rules:**
-- `status: has_blockers` when critical_count > 0 OR high_count > 0
-- `status: clean` when critical_count == 0 AND high_count == 0
-- If file exists, prepend new review (keep last 3 reviews, delete older)
-- Confirm: "Review saved to {path}. `/ship` will check this before deploying."
-
-## Deploy Gate
-
-Any CRITICAL or HIGH finding from `/review` is a **deploy blocker**. The `/deploy-verify` skill checks for unresolved review findings before running its 8-point verification. If you haven't run `/review` before deploying, `/deploy-verify` will flag it as a warning.
-
-Workflow: `/review` → fix findings → `/ship` (which triggers `/deploy-verify` automatically)

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

@@ -1,161 +0,0 @@
----
-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 ALL Data (2 bash calls max)
-
-**CRITICAL: Run exactly 2 bash calls in parallel.** Do NOT split these into separate calls.
-
-### Call 1 — Project & System Health
-
-Run this single combined command:
-
-```bash
-echo "---PROJECT---"
-echo "DIR:$(pwd)"
-echo "NAME:$(node -e "try{const p=require('./package.json');console.log(p.name||'')}catch(e){console.log('')}" 2>/dev/null)"
-echo "BRANCH:$(git branch --show-current 2>/dev/null || echo '')"
-echo "CHANGES:$(git status --porcelain 2>/dev/null | wc -l)"
-echo "NODE:$(node -v 2>/dev/null || echo 'none')"
-echo "TS:$(test -f tsconfig.json && echo 'yes' || echo 'no')"
-echo "SUPABASE:$(test -d supabase && echo 'yes' || echo 'no')"
-echo "PLANNING:$(test -d .planning && echo 'yes' || echo 'no')"
-echo "NEXTCONF:$(ls next.config.* 2>/dev/null | head -1)"
-echo "EXPO:$(ls app.json expo.json 2>/dev/null | head -1)"
-echo "PYTHON:$(ls app.py main.py 2>/dev/null | head -1)"
-echo "HANDOFF:$(test -f .continue-here.md && echo 'yes' || echo 'no')"
-echo "---SYSTEM---"
-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 skill-announce tool-error-announce; do HOOKS_TOTAL=$((HOOKS_TOTAL+1)); test -f "$HOME/.claude/hooks/${h}.sh" && HOOKS_OK=$((HOOKS_OK+1)); done; echo "HOOKS:${HOOKS_OK}/${HOOKS_TOTAL}"
-echo "ENGINE:$(test -f "$HOME/.claude/qualia-framework/bin/qualia-tools.js" && echo 'ok' || echo 'MISSING')"
-echo "VERSION:$(cat "$HOME/.claude/qualia-framework/VERSION" 2>/dev/null || echo 'unknown')"
-```
-
-### Call 2 — Session Context
-
-Run this single combined command:
-
-```bash
-echo "---DIGEST---"
-tail -n +4 ~/.claude/knowledge/session-digest.md 2>/dev/null | head -5
-echo "---STALE---"
-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 "${B} (${AGE}d)"; done
-echo "---PULSE---"
-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
-```
-
-### After bash calls
-
-If PLANNING is "yes", read `.planning/STATE.md` and `.planning/ROADMAP.md` (use the Read tool, not bash).
-
-Classify project type from signals: `web` | `voice` | `mobile` | `python-agent` | `edge-functions` | `framework` | `unknown`
-
-## 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
-  ✓ Engine      v1.14.0
-
-── 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
-
-── 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

@@ -1,132 +0,0 @@
----
-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-framework/workflows/verify-work.md`
-
-### 2. Create UAT Tracking
-
-Create `{phase}-UAT.md` using template from `~/.claude/qualia-framework/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`.
-
-Then check ROADMAP.md for remaining phases:
-
-**If more phases exist after this one:**
-> "Phase {N} verified! Next up: Phase {N+1} — {phase name}. Run `/qualia-plan-phase {N+1}`."
-
-**If this was the last phase:**
-> "All phases complete! Run `/qualia-audit-milestone` to verify the full milestone before wrapping up."
-
-#### 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 `~/.claude/qualia-framework/references/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. Red-Team QA (Optional Adversarial Pass)
-
-After cooperative verification passes (all UAT items green), offer an adversarial stress test:
-
-> "UAT passed. Want to run red-team QA? This spawns an adversarial agent that actively tries to break the implementation — edge cases, error paths, permission bypasses. Run it? (recommended for phases with auth, payments, or user input)"
-
-If accepted, spawn the `red-team-qa` agent:
-- Pass ONLY the phase goal text (from ROADMAP.md) — do NOT pass SUMMARY.md or PLAN.md
-- The agent works from the goal + codebase alone (prevents confirmation bias)
-- Agent produces an attack report with BROKEN / WEAK / SOLID verdicts
-
-**On red-team results:**
-- **BROKEN findings**: treat as UAT failures — add to UAT.md, route to gap planning
-- **WEAK findings**: add as advisory notes in UAT.md, user decides whether to fix
-- **All SOLID**: add "Red-team QA: PASSED" to UAT.md, proceed
-
-### 7. 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.
-
-### 8. Update State
-
-Update `.planning/STATE.md` to reflect verification status.
-
-### Agents Used
-| Agent | File | Role |
-|-------|------|------|
-| `red-team-qa` | `~/.claude/agents/red-team-qa.md` | Adversarial QA — tries to break the implementation |
-| `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) |
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help` · Done for today? Type `/qualia-report`