qualia-framework 2.1.0

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

@@ -0,0 +1,417 @@
+---
+name: qualia-optimize
+description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
+---
+
+# Qualia Optimize — Deep Codebase + Planning Optimization
+
+Comprehensive optimization that reads BOTH `.planning/` docs AND the actual codebase. Never analyze one without the other.
+
+## Usage
+
+- `/qualia-optimize` — Full optimization (all 6 dimensions)
+- `/qualia-optimize --perf` — Performance only (queries, bundle, render, latency)
+- `/qualia-optimize --ui` — Frontend/design/UI only
+- `/qualia-optimize --backend` — Backend only (RLS, auth, queries, edge functions)
+- `/qualia-optimize --alignment` — Planning-code alignment check only
+- `/qualia-optimize --fix` — Auto-fix LOW/MEDIUM findings from existing OPTIMIZE.md
+
+## Process
+
+### Step 1: Parse Arguments
+
+Extract mode from $ARGUMENTS. Default to `full`.
+
+Supported modes: `full`, `perf`, `ui`, `backend`, `alignment`, `fix`.
+
+If `--fix`: skip to Step 9 (requires existing `.planning/OPTIMIZE.md`).
+
+### Step 2: Load Planning Context (MANDATORY — never skip)
+
+Read ALL of these (skip silently if file doesn't exist, but always attempt):
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
+```
+
+```bash
+cat .planning/REQUIREMENTS.md 2>/dev/null || echo "NO_REQUIREMENTS"
+```
+
+```bash
+cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
+```
+
+```bash
+cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
+```
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+Also read the rules:
+```bash
+cat ~/.claude/rules/frontend.md 2>/dev/null
+cat ~/.claude/rules/security.md 2>/dev/null
+```
+
+Store all content — you will inline it into agent prompts.
+
+**If NO planning docs exist at all**: warn the user but proceed. The optimization still works on raw codebase — it just can't check alignment.
+
+### Step 3: Discover Codebase
+
+```bash
+pwd && 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
+git log --oneline -15 2>/dev/null
+```
+
+```bash
+git diff --stat HEAD~10..HEAD 2>/dev/null | tail -5
+```
+
+```bash
+# Project structure
+ls -d app/ src/ pages/ components/ lib/ actions/ hooks/ supabase/ types/ 2>/dev/null
+```
+
+Classify project type: `web` | `voice` | `mobile` | `agent` | `edge-functions` | `unknown`
+
+### Step 4: Spawn Wave 1 Agents (parallel)
+
+Based on mode, spawn agents in a **single message** with multiple Task() calls.
+
+| Mode | Agents |
+|------|--------|
+| `full` | frontend-agent + backend-agent + performance-oracle (3 parallel) |
+| `perf` | performance-oracle only |
+| `ui` | frontend-agent only |
+| `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.
+
+#### Frontend Agent Prompt
+
+```
+Task(
+  prompt="You are optimizing a project's frontend. Read the planning docs and codebase rules below, then analyze the actual code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{DESIGN.md content}
+</planning>
+
+<rules>
+{rules/frontend.md content}
+</rules>
+
+<task>
+Analyze the frontend codebase for issues in these categories:
+
+1. **UI Quality**
+   - Loading states: every async operation should show a loading indicator
+   - Error states: every data-fetching component should handle errors gracefully
+   - Empty states: lists/tables should handle zero items with helpful messaging
+   - Responsive: check for fixed pixel widths on containers, missing breakpoint handling
+   - Accessibility: alt text on images, ARIA labels on interactive elements, keyboard navigation
+
+2. **Design Alignment**
+   - Compare actual components against DESIGN.md decisions (colors, typography, spacing)
+   - Check rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids or blue-purple gradients?
+   - Consistency: are the same patterns used throughout? (button styles, spacing, color usage)
+
+3. **Frontend Performance**
+   - Bundle: large library imports that could be tree-shaken or dynamically imported
+   - Images: using next/image? width/height set? lazy loading below fold?
+   - Fonts: using next/font? No render-blocking font loads?
+   - CSS: unused Tailwind classes? conflicting styles?
+   - Rendering: unnecessary re-renders, missing React.memo on list items, heavy computations in render
+
+For EVERY finding, output in this exact format:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [impact on users/performance]
+- **Fix**: [concrete fix suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="frontend-agent",
+  description="Frontend optimization analysis"
+)
+```
+
+#### Backend Agent Prompt
+
+```
+Task(
+  prompt="You are optimizing a project's backend. Read the planning docs and security rules below, then analyze the actual code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<rules>
+{rules/security.md content}
+</rules>
+
+<task>
+Analyze the backend codebase for issues:
+
+1. **Security**
+   - RLS: every Supabase table must have ROW LEVEL SECURITY enabled with policies
+   - Service role: grep for service_role key usage in client-side code (app/, components/, src/) — should be ZERO
+   - Auth: all mutations use server-side auth check (supabase.auth.getUser())
+   - Validation: input validated with Zod before database operations
+   - No dangerouslySetInnerHTML or eval()
+
+2. **Data Access Patterns**
+   - Server actions vs client mutations: data writes should use 'use server' actions, not direct Supabase client calls
+   - Proper error handling: try/catch with meaningful error messages
+   - Revalidation: revalidatePath/revalidateTag after mutations
+
+3. **Edge Functions** (if supabase/functions/ exists)
+   - Cold start optimization: bundle size, dependency count
+   - Error handling and logging
+   - CORS configuration
+   - Timeout protection (maxDuration)
+
+4. **API Quality**
+   - Rate limiting on public endpoints
+   - Proper HTTP status codes
+   - Consistent error response format
+
+For EVERY finding, output:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [impact]
+- **Fix**: [concrete suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="backend-agent",
+  description="Backend optimization analysis"
+)
+```
+
+#### Performance Oracle Prompt
+
+```
+Task(
+  prompt="You are analyzing cross-cutting performance issues. Read the project context, then analyze the codebase.
+
+<planning>
+{PROJECT.md content}
+</planning>
+
+<task>
+Analyze for performance issues across the full stack:
+
+1. **Database Queries**
+   - N+1 queries: Supabase .from() calls inside loops or .map()
+   - Missing indexes: .eq()/.filter()/.order() columns without corresponding indexes in migrations
+   - Sequential queries that could be parallel (Promise.all)
+   - Over-fetching: SELECT * when only specific columns needed
+
+2. **API Latency**
+   - Sequential API calls from client that could be batched
+   - Missing caching (SWR/React Query stale times, HTTP cache headers)
+   - Large payloads without pagination
+
+3. **Bundle Size**
+   - Barrel exports (index.ts re-exporting everything) preventing tree-shaking
+   - Large libraries imported for single functions (lodash, moment)
+   - Missing dynamic imports for heavy components (charts, editors, maps)
+
+4. **Render Performance**
+   - Expensive computations in render path without useMemo
+   - Event handlers recreated on every render without useCallback
+   - Large lists without virtualization
+   - Context providers causing unnecessary re-renders
+
+For EVERY finding, output:
+- **What**: [description]
+- **Where**: [file:line]
+- **Why**: [performance impact, quantified if possible]
+- **Fix**: [concrete suggestion]
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+</task>",
+  subagent_type="performance-oracle",
+  description="Performance optimization analysis"
+)
+```
+
+### Step 5: Spawn Wave 2 Agent (after Wave 1 completes)
+
+After all Wave 1 agents return, spawn the architecture strategist with their combined findings:
+
+```
+Task(
+  prompt="You are synthesizing optimization findings from 3 specialist agents. Look for cross-cutting architectural issues.
+
+<wave1_findings>
+{All findings from frontend-agent, backend-agent, performance-oracle}
+</wave1_findings>
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<task>
+1. Identify patterns across findings — recurring issues that point to a structural problem
+2. Find coupling issues between frontend and backend
+3. Check for inconsistent patterns (e.g., some routes use server actions, others use API routes)
+4. Identify missing abstractions (same pattern repeated 3+ times)
+5. Check for dead code and unused exports
+
+Output:
+- **Structural findings** (architectural issues, not covered by Wave 1)
+- **Pattern consolidation** (where Wave 1 findings share a root cause)
+- Each finding in the same format: What/Where/Why/Fix/Severity
+</task>",
+  subagent_type="architecture-strategist",
+  description="Architecture synthesis"
+)
+```
+
+**Skip Wave 2 for single-mode runs** (`--perf`, `--ui`, `--backend`). Only run for `full` mode.
+
+### Step 6: Alignment Check (always runs in `full` and `alignment` modes)
+
+For `alignment` mode, this is the sole analysis. For `full` mode, run alongside Wave 1.
+
+Read REQUIREMENTS.md and ROADMAP.md. For each requirement marked "Complete" or mapped to a completed phase:
+
+```bash
+# Find completed requirements
+grep -E "Complete|✓" .planning/REQUIREMENTS.md 2>/dev/null
+```
+
+For each completed requirement:
+- Grep the codebase for evidence it actually exists (routes, components, API endpoints)
+- If not found: flag as "Claimed complete but not implemented"
+
+Then scan for orphan features:
+```bash
+# Find all routes/pages
+find app -name "page.tsx" -o -name "route.ts" 2>/dev/null
+# Find all API routes
+find app/api -name "route.ts" 2>/dev/null
+```
+
+Cross-reference with REQUIREMENTS.md — any route/feature NOT in requirements is flagged as "Undocumented feature".
+
+### Step 7: Collect and Score Findings
+
+After all agents return:
+1. Deduplicate (same file:line from multiple agents → keep the most detailed one)
+2. Sort by severity: CRITICAL first
+3. Group by dimension: Performance, Design Alignment, UI Quality, Backend, Frontend, Planning-Code Alignment, Architecture
+
+Count totals per severity.
+
+### Step 8: Write OPTIMIZE.md and Present Results
+
+Write to `.planning/OPTIMIZE.md`:
+
+```markdown
+---
+date: {YYYY-MM-DD HH:MM}
+mode: {full|perf|ui|backend|alignment}
+critical: {N}
+high: {N}
+medium: {N}
+low: {N}
+status: {clean|needs_attention|critical_issues}
+---
+
+# Optimization Report
+
+**Project:** {name} | **Mode:** {mode} | **Date:** {date}
+
+## Summary
+
+{2-3 sentence overview}
+
+{If status is clean: "No critical issues found. Project is in good shape."}
+
+## Critical Issues
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## High Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## Medium Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+
+## Low Priority
+
+| # | Dimension | Finding | Location | Fix |
+|---|-----------|---------|----------|-----|
+{findings}
+```
+
+Commit:
+```bash
+node ~/.claude/qualia-engine/bin/qualia-tools.js commit "docs: optimization report ({mode} mode, {critical} critical)" --files .planning/OPTIMIZE.md
+```
+
+**Present results:**
+
+If CRITICAL findings exist:
+```
+{critical} critical issues found. Options:
+
+1. Create a fix phase in ROADMAP.md for critical + high findings
+2. Auto-fix LOW/MEDIUM findings: /qualia-optimize --fix
+3. Review full report: cat .planning/OPTIMIZE.md
+```
+
+If no CRITICAL:
+```
+Optimization complete. {total} findings ({high} high, {medium} medium, {low} low).
+Report: .planning/OPTIMIZE.md
+
+Run /qualia-optimize --fix to auto-fix LOW/MEDIUM findings.
+```
+
+### Step 9: --fix Mode
+
+When `--fix` is provided:
+
+1. Read existing `.planning/OPTIMIZE.md` — if not found, error: "Run /qualia-optimize first"
+2. Filter to LOW and MEDIUM findings only
+3. For each finding with a clear, safe fix:
+   - Read the target file
+   - Apply the fix
+   - Verify it doesn't break (npx tsc --noEmit if TypeScript)
+4. Update OPTIMIZE.md: mark fixed findings, recount severities
+5. Commit changes
+6. Report what was fixed and what remains
+
+**Never auto-fix CRITICAL or HIGH** — those require human judgment.
+
+### Step 10: Gap Phase Creation (if user selects option 1 from Step 8)
+
+If user wants a fix phase for critical issues:
+
+1. Read ROADMAP.md, find current phase number
+2. Insert a decimal phase: `Phase {N}.1: Optimization Fixes (INSERTED)`
+3. Map CRITICAL and HIGH findings as success criteria
+4. Update STATE.md
+5. Commit
+6. Suggest: "Fix phase created. Run `/qualia-plan-phase {N}.1`"

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

@@ -0,0 +1,96 @@
+---
+name: qualia-pause-work
+description: "Save session context for seamless handoff between Claude sessions. Use this skill whenever the user says 'pause', 'save progress', 'stop for now', 'pause work', 'handoff', 'save thoughts', or wants to preserve their current working state before ending a session. Also trigger when user mentions 'continue later', 'pick up tomorrow', or needs to create a checkpoint of current work. Supports both full project handoff and lightweight thoughts mode."
+---
+
+# Qualia Pause Work — Session Handoff
+
+Save current session context so the next session can pick up exactly where you left off.
+
+## Usage
+
+`/qualia-pause-work` — Full project-aware handoff (creates `.continue-here.md`)
+`/qualia-pause-work --thoughts` — Lightweight thought dump (saves to `~/.claude/thoughts/`)
+
+## Default Mode (Project Handoff)
+
+### 1. Read Current State
+
+Load `.planning/STATE.md` and check current phase status.
+
+Reference: `~/.claude/qualia-engine/workflows/pause-work.md`
+
+### 2. Create `.continue-here.md`
+
+Write a handoff file at the project root with:
+
+```markdown
+# Continue Here
+
+## Session Summary
+What was accomplished this session.
+
+## Current Phase
+Phase X: [name] — [status]
+
+## In Progress
+- What's partially done
+- Where exactly work stopped
+
+## Next Steps
+1. Immediate next action
+2. Following actions
+
+## Key Decisions Made
+- Decision 1 and rationale
+- Decision 2 and rationale
+
+## Blockers / Open Questions
+- Any unresolved issues
+
+## Files Modified
+- List of changed files with brief description
+```
+
+### 3. Git Commit
+
+Stage and commit with a descriptive message:
+```bash
+git add -A
+git commit -m "WIP: [phase name] - [brief description of state]"
+```
+
+## Thoughts Mode (`--thoughts`)
+
+Lightweight handoff for non-project work or quick brainstorming sessions.
+
+### Save Location
+`~/.claude/thoughts/handoff-{timestamp}.md`
+
+### Structure
+```markdown
+# Handoff — {date}
+
+## Accomplished
+- What got done
+
+## Current State
+- Where things stand
+
+## In Progress
+- Partially complete work
+
+## Next Steps
+1. What to do next
+
+## Key Decisions
+- Important choices made
+
+## Blockers
+- What's stuck
+
+## Commands to Resume
+- Specific commands or files to look at
+```
+
+No git commit in thoughts mode — it's just a text dump for context restoration.

package/framework/skills/qualia-plan-milestone-gaps/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: qualia-plan-milestone-gaps
+description: "Create fix phases from milestone audit gaps — reads the most recent audit report and generates ROADMAP.md entries for all identified gaps. Use this skill whenever the user says 'plan gaps', 'fix gaps', 'plan milestone gaps', 'create fix phases', or wants to turn audit findings into actionable phases. Also trigger after a milestone audit reveals gaps that need addressing."
+---
+
+# Qualia Plan Milestone Gaps — Gap-to-Phase Conversion
+
+Read the most recent milestone audit report and create ROADMAP.md phases to close all identified gaps.
+
+## Usage
+
+`/qualia-plan-milestone-gaps` — Auto-detect latest audit, create fix phases
+
+## Process
+
+### 1. Find Latest Audit
+
+```bash
+ls -t .planning/v*-MILESTONE-AUDIT.md | head -1
+```
+
+Read the most recent `v*-MILESTONE-AUDIT.md` file.
+
+Reference: `~/.claude/qualia-engine/workflows/plan-milestone-gaps.md`
+
+### 2. Load Project Context
+
+Read these files for full context:
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+
+### 3. Extract and Group Gaps
+
+From the audit report, extract all gaps (items marked as failing or incomplete). Group related gaps into logical phases:
+- Group by feature area or component
+- Keep phases small (completable in 1-2 sessions)
+- Order by dependency — fix foundations before features
+
+### 4. Create ROADMAP.md Entries
+
+Append new phases to ROADMAP.md. Each gap-fix phase should include:
+- Phase number (continuing from existing phases)
+- Name: `Fix: [area]`
+- Description of what gaps it closes
+- Status: `not started`
+- Reference to specific audit gaps being addressed
+
+### 5. Update STATE.md
+
+Update the phase table in STATE.md to reflect the new fix phases.
+
+### 6. Report
+
+Tell the user how many gaps were found, how many fix phases were created, and suggest:
+> "Fix phases created. Run `/qualia-plan-phase [next-phase-number]` to plan the first fix."

package/framework/skills/qualia-plan-phase/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: qualia-plan-phase
+description: "Create detailed execution plans for a project phase with optional research and verification. Use this skill whenever the user says 'plan phase', 'plan next phase', 'create plan', or wants to plan out how a specific phase of work should be executed. Also trigger when user mentions 'PLAN.md', 'phase planning', or needs to break a roadmap phase into concrete implementation steps. Supports research integration, gap closure planning, and plan verification."
+---
+
+# Qualia Plan Phase — Phase Planning
+
+Create detailed PLAN.md files for a project phase, with optional research and verification loop.
+
+## Usage
+
+`/qualia-plan-phase 3` — Plan phase 3
+`/qualia-plan-phase` — Auto-detect next unplanned phase
+`/qualia-plan-phase 3 --research` — Force research before planning
+`/qualia-plan-phase 3 --skip-research` — Skip research even if recommended
+`/qualia-plan-phase 3 --gaps` — Plan gap closure (after verify-work found issues)
+`/qualia-plan-phase 3 --skip-verify` — Skip plan verification step
+
+## Process
+
+### 1. Identify Target Phase
+
+If phase number provided, use it. Otherwise, scan ROADMAP.md for the first phase with status `not started` or `planned` without a PLAN.md.
+
+Reference: `~/.claude/qualia-engine/workflows/plan-phase.md`
+
+### 2. Research (if needed)
+
+Research is recommended when:
+- Phase involves unfamiliar tech or APIs
+- Phase has complex architectural decisions
+- User passes `--research` flag
+
+Skip if `--skip-research` is passed or if research already exists at `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md`.
+
+If research is needed, use the qualia-research-phase skill first.
+
+### 3. Create PLAN.md
+
+Write to `.planning/phases/{phase}-{slug}/PLAN.md`:
+
+```markdown
+# Phase {N}: {Name} — Execution Plan
+
+## Objective
+What this phase accomplishes.
+
+## Prerequisites
+- What must be done/ready before starting
+
+## Implementation Steps
+
+### Step 1: {description}
+- Files to create/modify
+- Key implementation details
+- Acceptance criteria
+
+### Step 2: {description}
+...
+
+## Verification Checklist
+- [ ] Each testable outcome
+- [ ] Integration points work
+- [ ] No regressions
+
+## Risks & Mitigations
+- Risk 1 → Mitigation
+```
+
+For `--gaps` mode, the plan focuses specifically on closing gaps identified by verify-work, referencing the UAT.md findings.
+
+### 4. Verify Plan (unless --skip-verify)
+
+Spawn the qualia-plan-checker agent to review the plan for:
+- Completeness against requirements
+- Realistic scope
+- Clear acceptance criteria
+- No missing dependencies
+
+Reference: `~/.claude/agents/qualia-plan-checker.md`
+
+If checker finds issues, revise the plan and re-verify.
+
+### 5. Update State
+
+Update `.planning/STATE.md` to reflect the phase is now `planned`.
+
+Reference UI/brand guidelines: `~/.claude/qualia-engine/references/ui-brand.md`
+
+For complex phases touching multiple subsystems, consider `/deep-research` before phase research to establish architectural direction.
+
+### 6. Next Step
+
+> "Phase {N} planned. Run `/qualia-execute-phase {N}` to begin execution."
+
+### Agents Used
+| Agent | File | Role |
+|-------|------|------|
+| `qualia-planner` | `~/.claude/agents/qualia-planner.md` | Creates PLAN.md with goal-backward methodology |
+| `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates plan completeness |
+| `qualia-phase-researcher` | `~/.claude/agents/qualia-phase-researcher.md` | Phase research (when --research) |