qualia-framework 2.1.0

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

@@ -0,0 +1,53 @@
+---
+name: qualia-progress
+description: "Check project progress and get routed to the right next action. Use this skill whenever the user says 'progress', 'how far along', 'what happened', 'show progress', or wants a summary of what's been done and what comes next. Also trigger when user seems to need situational awareness about their project state before deciding what to do. Routes to the most logical next step based on current state."
+---
+
+# Qualia Progress — Progress Check & Routing
+
+Check current progress, summarize state, and route to the most logical next action.
+
+## Usage
+
+`/qualia-progress` — Check progress and get next-step recommendation
+
+## Process
+
+### 1. Load State
+
+Read `.planning/STATE.md`, `.planning/ROADMAP.md`, and check `git status --short`.
+
+Reference: `~/.claude/qualia-engine/workflows/progress.md`
+
+### 2. Summarize Progress
+
+Present a concise summary:
+- Current milestone and phase
+- Phases completed vs total
+- Current phase status
+- Any uncommitted changes
+- Recent activity
+
+### 3. Route to Next Action
+
+Based on current state, recommend one of these routes:
+
+**Route A** — Phase needs planning:
+> "Phase {N} is next and unplanned. Run `/qualia-plan-phase {N}`."
+
+**Route B** — Phase is planned, needs execution:
+> "Phase {N} is planned and ready. Run `/qualia-execute-phase {N}`."
+
+**Route C** — Phase is executed, needs verification:
+> "Phase {N} is done but unverified. Run `/qualia-verify-work {N}`."
+
+**Route D** — Verification found gaps:
+> "Phase {N} has gaps from verification. Run `/qualia-plan-phase {N} --gaps`."
+
+**Route E** — All phases complete:
+> "All phases done! Run `/qualia-audit-milestone` to verify the milestone."
+
+**Route F** — Milestone audit complete:
+> "Milestone audit passed. Run `/qualia-complete-milestone` to archive and tag."
+
+Keep the output concise — this is a quick status check with routing, not a detailed report.

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

@@ -0,0 +1,89 @@
+---
+name: qualia-quick
+description: "Execute quick tasks with Qualia quality guarantees — atomic commits, STATE.md tracking, minimal overhead. Use this skill whenever the user says 'quick task', 'quick fix', 'just do this quickly', 'small change', 'hotfix', or wants to make a small change outside the normal phase workflow. Also trigger when user mentions 'quick bug fix', '--fix', or needs a fast targeted change with proper tracking. Supports no-plan mode and bug-fix mode with minimal-change discipline."
+---
+
+# Qualia Quick — Quick Tasks with Guarantees
+
+Execute small tasks outside the normal phase workflow while maintaining Qualia quality standards: atomic commits, state tracking, and verification.
+
+## Usage
+
+`/qualia-quick "Add loading spinner to dashboard"` — Quick task with planning
+`/qualia-quick --no-plan "Update footer copyright year"` — Skip planner, just do it
+`/qualia-quick --fix "Login button not responding on mobile"` — Bug fix mode (implies --no-plan)
+
+## Process
+
+### 1. Load Context
+
+Read `.planning/STATE.md` for current project state.
+
+Reference: `~/.claude/qualia-engine/workflows/quick.md`
+
+### 2. Complexity Check
+
+Before planning or executing, classify the task:
+
+| Signal | Classification | Action |
+|--------|---------------|--------|
+| Single file change, familiar codebase | **Quick** | Proceed directly (no confirmation) |
+| `--no-plan` or `--fix` flag | **Quick** | Proceed directly (no confirmation) |
+| Typo, config, or copy change | **Quick** | Proceed directly (no confirmation) |
+| Multi-file change | **Non-trivial** | Present understanding, wait for confirmation |
+| Architectural impact (new table, new service, new API) | **Non-trivial** | Present understanding, wait for confirmation |
+| Unfamiliar codebase (first time working in this project) | **Non-trivial** | Present understanding, wait for confirmation |
+
+**If Non-trivial:** Before making changes, present:
+> "Here's what I understand: [1-2 sentence summary]. I'll modify [file list]. Correct?"
+
+Wait for user confirmation. Capture any corrections for the session.
+
+**If Quick:** Skip confirmation and proceed to Step 3.
+
+### 3. Plan (unless --no-plan or --fix)
+
+Quick-plan the task:
+- What files need changing
+- What the change looks like
+- How to verify it works
+
+Quick tasks do NOT create PLAN.md files — planning is lightweight and inline.
+
+### 4. Execute
+
+Implement the change. Quick tasks live in `.planning/quick/` — they're separate from planned phases.
+
+#### Fix Mode (`--fix`)
+Bug fix mode enforces minimal-change discipline:
+1. **Locate** — Find the exact source of the bug
+2. **Root Cause** — Understand why it's happening
+3. **Smallest Fix** — Make the minimum change that fixes it
+4. **Verify** — Confirm the fix works and nothing else broke
+
+Fix mode skips planning entirely (implies `--no-plan`).
+
+### 5. Verify
+
+Run the change and verify it works:
+- Does the feature/fix work as expected?
+- No console errors?
+- No regressions in related functionality?
+
+### 6. Track
+
+Update `.planning/STATE.md` — add entry to the "Quick Tasks Completed" table:
+
+| Date | Task | Status |
+|------|------|--------|
+| YYYY-MM-DD | Description | ✅ Done |
+
+**Important**: Quick tasks update STATE.md only, NOT ROADMAP.md. They're tracked separately from planned phases.
+
+### 7. Commit
+
+Atomic commit with descriptive message:
+```bash
+git add [specific files]
+git commit -m "quick: [description of change]"
+```

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

@@ -0,0 +1,88 @@
+---
+name: qualia-research-phase
+description: "Conduct standalone research for a project phase — ecosystem analysis, feasibility studies, implementation patterns, comparisons. Use this skill whenever the user says 'research', 'research phase', 'investigate options', 'tech research', or wants to explore technical options before planning a phase. Also trigger when user mentions 'feasibility study', 'compare frameworks', 'what stack should we use', or needs structured research output that feeds into phase planning."
+---
+
+# Qualia Research Phase — Phase Research
+
+Conduct structured research for a project phase, producing a RESEARCH.md that feeds directly into phase planning.
+
+## Usage
+
+`/qualia-research-phase 3` — Research for phase 3 (default: ecosystem mode)
+`/qualia-research-phase 3 --mode=feasibility` — Feasibility study
+`/qualia-research-phase 3 --mode=implementation` — Implementation patterns
+`/qualia-research-phase 3 --mode=comparison` — Compare alternatives
+
+## Research Modes
+
+- **ecosystem** (default) — Survey the landscape: what libraries, APIs, patterns exist for this problem
+- **feasibility** — Can we do this? What are the blockers? What's the effort?
+- **implementation** — How should we build this? Concrete patterns and examples
+- **comparison** — Compare 2-3 approaches side by side with tradeoffs
+
+## Process
+
+### 1. Initialize
+
+Use `qualia-tools.js` for state management:
+```bash
+node ~/.claude/qualia-engine/bin/qualia-tools.js phase-op <phase>
+```
+
+Validate the phase exists in ROADMAP.md. Check if research already exists at `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md`.
+
+### 2. Gather Context
+
+Read project context:
+- `.planning/PROJECT.md` — tech stack, constraints
+- `.planning/ROADMAP.md` — phase description and dependencies
+- Phase CONTEXT.md if it exists (from discuss-phase)
+
+### 3. Spawn Researcher
+
+Spawn the `qualia-phase-researcher` agent with full context.
+
+Reference: `~/.claude/agents/qualia-phase-researcher.md`
+
+Model resolution:
+```bash
+node ~/.claude/qualia-engine/bin/qualia-tools.js resolve-model qualia-phase-researcher
+```
+
+### 4. Research Output
+
+The researcher produces `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md` with sections designed for downstream consumption by plan-phase:
+
+- **Standard Stack** — Recommended libraries and tools
+- **Architecture Patterns** — How to structure the implementation
+- **Don't Hand-Roll** — Things to use existing solutions for
+- **Common Pitfalls** — What to watch out for
+- **Code Examples** — Concrete snippets showing key patterns
+
+### 5. Handle Return
+
+The researcher returns one of:
+- **COMPLETE** — Research done, ready for planning
+- **CHECKPOINT** — Partial results, needs more investigation (spawn continuation)
+- **INCONCLUSIVE** — Couldn't determine best approach, present options to user
+
+### When to Use /deep-research Instead
+
+| Use `/qualia-research-phase` | Use `/deep-research` |
+|------------------------------|----------------------|
+| Phase-specific technical research | Whole-project architectural analysis |
+| Output feeds into `/qualia-plan-phase` | Output is a standalone report |
+| 1 researcher agent, fast | 6 parallel Opus agents, thorough |
+| "How should we build phase 3?" | "Is this codebase production-ready?" |
+
+Both can be combined: `/deep-research` for architectural context, then `/qualia-research-phase` for the specific phase.
+
+### 6. Next Step
+
+> "Research complete for phase {N}. Run `/qualia-plan-phase {N}` to create the execution plan."
+
+### Agents Used
+| Agent | File | Role |
+|-------|------|------|
+| `qualia-phase-researcher` | `~/.claude/agents/qualia-phase-researcher.md` | Conducts phase-specific research |

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

@@ -0,0 +1,62 @@
+---
+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-engine/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

@@ -0,0 +1,263 @@
+---
+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 `~/Projects/qualia-erp/docs/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)