qualia-framework 2.1.0

package/framework/skills/qualia/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: qualia
+description: Smart Qualia router - reads project state and auto-routes to the right command
+tags: [qualia, workflow, auto-route]
+---
+
+# Qualia Smart Router
+
+Single entry point that reads project state and routes to the appropriate Qualia action.
+
+## How It Works
+
+1. Detect if we're in a Qualia project (has .planning/)
+2. Read STATE.md to find current position
+3. Analyze what's needed next
+4. Route to the correct /qualia: command OR execute directly
+
+## Execution
+
+### Step 1: Detect Project State
+
+```bash
+# Check if .planning exists
+if [ ! -d ".planning" ]; then
+  echo "NO_PROJECT"
+  exit 0
+fi
+
+# Check for STATE.md
+if [ -f ".planning/STATE.md" ]; then
+  cat .planning/STATE.md
+fi
+
+# Check for ROADMAP.md
+if [ -f ".planning/ROADMAP.md" ]; then
+  cat .planning/ROADMAP.md
+fi
+
+# List phase directories
+ls -la .planning/phases/ 2>/dev/null || echo "NO_PHASES"
+```
+
+### Step 2: Parse Current Position
+
+From STATE.md, extract:
+- `current_phase`: Which phase number we're on
+- `phase_status`: planning | executing | verifying | complete
+- `blockers`: Any blockers or decisions needed
+
+From ROADMAP.md, extract:
+- Total phases
+- Which phases are complete
+- Next phase info
+
+### Step 3: Route Decision Tree
+
+```
+NO .planning/ directory?
+  → "No Qualia project. Run /qualia-new-project to initialize."
+
+Has .planning/ but no STATE.md?
+  → "Project initialized but no state. Run /qualia-progress to diagnose."
+
+STATE.md exists:
+
+  phase_status = "needs_discussion"?
+    → Route to: /qualia-discuss-phase {current_phase}
+
+  phase_status = "discussed" or "needs_planning"?
+    → Route to: /qualia-plan-phase {current_phase}
+
+  phase_status = "planned" or "needs_execution"?
+    → Route to: /qualia-execute-phase {current_phase}
+
+  phase_status = "executed" or "needs_verification"?
+    → Route to: /qualia-verify-work {current_phase}
+
+  phase_status = "verified" or "complete"?
+    → Check if more phases exist
+    → If yes: increment phase, route to discuss
+    → If no: "Milestone complete! Run /qualia-complete-milestone"
+
+  blockers exist?
+    → Show blockers, ask user how to proceed
+```
+
+### Step 4: Execute or Prompt
+
+**If clear next action:**
+Invoke the appropriate skill directly using:
+```
+Skill(skill="qualia-{action}", args="{phase_number}")
+```
+
+**If ambiguous:**
+Present options to user:
+```
+Current: Phase {N} - {status}
+
+Options:
+1. Continue with {recommended_action}
+2. Check progress (/qualia-progress)
+3. Quick task (/qualia-quick)
+```
+
+## Output Format
+
+```
+## Qualia Status
+
+**Project:** {project_name from PROJECT.md or directory name}
+**Phase:** {N} of {total} - {phase_name}
+**Status:** {status_emoji} {status_description}
+
+---
+
+**Next:** /qualia:{action} {phase}
+
+{If blockers: show them}
+{If decision needed: present options}
+```
+
+## Status Emojis
+
+- `planning` - Planning phase
+- `executing` - Building
+- `verifying` - Testing
+- `complete` - Done
+- `blocked` - Needs input
+
+## Quick Actions
+
+If user provides argument:
+
+- `/qualia plan` → Route to /qualia-plan-phase for current phase
+- `/qualia exec` → Route to /qualia-execute-phase for current phase
+- `/qualia verify` → Route to /qualia-verify-work for current phase
+- `/qualia next` → Move to next phase
+- `/qualia quick {description}` → Pass to /qualia-quick
+- `/qualia optimize` → Route to /qualia-optimize (full optimization pass)
+- `/qualia idk` → Route to /qualia-idk (what should I do next?)
+
+## No Project Fallback
+
+If no .planning/ exists:
+
+```
+No Qualia project detected in current directory.
+
+Options:
+1. /qualia-new-project - Initialize new project with full workflow
+2. /qualia-quick - Run a quick task without project setup
+```

package/framework/skills/qualia-add-todo/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: qualia-add-todo
+description: "Capture ideas and tasks as structured todos in the .planning system. Use this skill whenever the user says 'add todo', 'remember this', 'note this down', 'add task', 'todo', or wants to capture an idea or task for later without acting on it now. Also trigger when user mentions 'backlog item', 'future task', or needs to save something for later in a structured way."
+---
+
+# Qualia Add Todo — Structured Task Capture
+
+Capture ideas and tasks as structured todo files in the `.planning/todos/` directory.
+
+## Usage
+
+`/qualia-add-todo "Add dark mode support"` — Capture a new todo
+`/qualia-add-todo "Optimize image loading" --area=performance` — With explicit area
+
+## Process
+
+### 1. Setup
+
+Ensure the todos directory exists:
+```bash
+mkdir -p .planning/todos
+```
+
+Reference: `~/.claude/qualia-engine/workflows/add-todo.md`
+
+### 2. Extract Content
+
+Parse the user's input to determine:
+- **Title** — Short description of the task
+- **Details** — Any additional context provided
+- **Area** — Infer from content if not specified (e.g., "dark mode" → `ui`, "API rate limiting" → `backend`, "fix typo" → `content`)
+
+### 3. Check for Duplicates
+
+Scan existing todos in `.planning/todos/` for similar items. If a near-duplicate exists, tell the user and ask if they want to update the existing one or create a new one.
+
+### 4. Create Todo File
+
+Write to `.planning/todos/{slug}.md`:
+
+```markdown
+---
+title: "{title}"
+area: "{area}"
+priority: normal
+status: pending
+created: {YYYY-MM-DD}
+---
+
+# {title}
+
+{details and context}
+```
+
+### 5. Update STATE.md
+
+Add entry to the todos section of `.planning/STATE.md` (create section if it doesn't exist).
+
+### 6. Commit
+
+```bash
+git add .planning/todos/{slug}.md .planning/STATE.md
+git commit -m "todo: add {title}"
+```
+
+### 7. Confirm
+
+> "Todo captured: {title}. Run `/qualia-check-todos` to review your backlog."

package/framework/skills/qualia-audit-milestone/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: qualia-audit-milestone
+description: "Verify milestone definition of done — aggregate verification results, check tech debt, run integration tests. Use this skill whenever the user says 'audit milestone', 'check milestone', 'milestone review', 'are we done', or wants to verify that all phases of a milestone meet the definition of done before completing it. Also trigger when user mentions 'milestone audit', 'definition of done check', or needs to validate overall milestone readiness."
+---
+
+# Qualia Audit Milestone — Milestone Verification
+
+Orchestrate a full audit of the current milestone to verify all requirements are met before completion.
+
+## Usage
+
+`/qualia-audit-milestone` — Audit current milestone
+
+## Process
+
+### 1. Load Context
+
+Read all project files:
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md` — Definition of Done
+- `.planning/ROADMAP.md` — All phases
+- `.planning/config.json`
+
+Reference: `~/.claude/qualia-engine/workflows/audit-milestone.md`
+
+### 2. Read Verification Results
+
+For each completed phase, read its VERIFICATION.md or UAT.md files. Aggregate results:
+- How many phases verified passing
+- How many have outstanding issues
+- What gaps remain
+
+### 3. Check Requirements
+
+Walk through every item in REQUIREMENTS.md Definition of Done:
+- Is each requirement addressed by a completed phase?
+- Is each requirement verified as working?
+- Flag any unmet requirements
+
+### 4. Tech Debt Aggregation
+
+Scan phase summaries and verification files for noted tech debt, workarounds, or deferred items. Compile a tech debt list.
+
+### 5. Shipping Checklist Audit
+
+Run the full shipping checklist from `~/Projects/qualia-erp/docs/completion-checklists.md` as part of the audit.
+
+Detect project type from `.planning/PROJECT.md` and load the matching checklist:
+- **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 every checklist item, run automated verification where possible. Include a "Shipping Checklist" section in the audit report with PASS/WARN/FAIL per item. FAIL items contribute to the overall PASS/FAIL decision.
+
+### 6. Integration Check
+
+Spawn an integration checker to verify cross-phase functionality:
+- Do features from different phases work together?
+- Are there any conflicts or regressions?
+- End-to-end user flows work?
+
+### 7. Produce Audit Report
+
+Write `v{version}-MILESTONE-AUDIT.md`:
+
+```markdown
+# Milestone v{version} Audit
+
+## Requirements Status
+| Requirement | Phase | Verified | Status |
+|------------|-------|----------|--------|
+| ... | ... | ... | ✅/❌ |
+
+## Gaps
+- List of unmet requirements or failing tests
+
+## Tech Debt
+- Items deferred during implementation
+
+## Integration Results
+- Cross-phase test outcomes
+
+## Overall: PASS / FAIL
+```
+
+### 8. Route
+
+**If PASS**: "Milestone audit passed. Run `/qualia-complete-milestone` to archive and tag."
+
+**If FAIL**: "Audit found gaps. Run `/qualia-plan-milestone-gaps` to create fix phases."

package/framework/skills/qualia-check-todos/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: qualia-check-todos
+description: "List and manage pending todos with filtering and interactive routing. Use this skill whenever the user says 'check todos', 'show todos', 'what todos', 'backlog', 'pending tasks', or wants to review their captured todo items. Also trigger when user mentions 'todo list', 'what's in the backlog', or needs to pick a todo to work on."
+---
+
+# Qualia Check Todos — Todo Review & Routing
+
+List pending todos with area filtering, interactive selection, and action routing.
+
+## Usage
+
+`/qualia-check-todos` — Show all pending todos
+`/qualia-check-todos --area=ui` — Filter by area
+`/qualia-check-todos --priority=high` — Filter by priority
+
+## Process
+
+### 1. Load Todos
+
+Read all files in `.planning/todos/`. Parse frontmatter for status, area, priority, created date.
+
+Also read `.planning/STATE.md` and `.planning/ROADMAP.md` for project context.
+
+Reference: `~/.claude/qualia-engine/workflows/check-todos.md`
+
+### 2. Display List
+
+Show todos grouped by area, sorted by priority then date:
+
+```
+## UI (3 pending)
+1. Add dark mode support [normal] — 2026-03-10
+2. Improve mobile nav [high] — 2026-03-08
+3. Loading skeleton screens [low] — 2026-03-12
+
+## Backend (1 pending)
+4. API rate limiting [high] — 2026-03-09
+```
+
+Apply filters if specified.
+
+### 3. Interactive Selection
+
+Ask the user which todo they want to act on (by number).
+
+### 4. Route to Action
+
+For the selected todo, offer actions:
+
+- **Work now** — Execute the todo as a quick task: `/qualia-quick "{todo title}"`
+- **Add to phase** — Incorporate into an upcoming phase in the roadmap
+- **Brainstorm** — Discuss the todo further to flesh out details
+- **Create phase** — If the todo is big enough, create a new roadmap phase for it
+
+Load the full todo file content to provide context for whichever action is chosen.

package/framework/skills/qualia-complete-milestone/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: qualia-complete-milestone
+description: "Archive a completed milestone — gather stats, archive files, tag release, prepare for next milestone. Use this skill whenever the user says 'complete milestone', 'finish milestone', 'archive milestone', 'milestone done', 'close milestone', or wants to wrap up a verified milestone and prepare for the next one. Also trigger when user mentions 'tag release', 'v1 done', or needs to finalize and archive milestone work."
+---
+
+# Qualia Complete Milestone — Milestone Archive & Release
+
+Complete a verified milestone: gather stats, archive, tag release, and prepare for the next milestone.
+
+## Usage
+
+`/qualia-complete-milestone` — Complete current milestone
+
+## Prerequisites
+
+Must have a passing milestone audit (`v*-MILESTONE-AUDIT.md` with PASS status). If no audit exists or it failed, direct user to run `/qualia-audit-milestone` first.
+
+## Process (8 Steps)
+
+Reference: `~/.claude/qualia-engine/workflows/complete-milestone.md`
+
+### 1. Pre-flight Audit Check
+
+Verify the most recent `v*-MILESTONE-AUDIT.md` shows PASS. If not:
+> "Milestone audit hasn't passed yet. Run `/qualia-audit-milestone` first."
+
+### 2. Shipping Checklist Final Gate
+
+Before archiving, run the full shipping checklist from `~/Projects/qualia-erp/docs/completion-checklists.md`.
+
+Detect project type from `.planning/PROJECT.md` and load the matching checklist:
+- **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"
+
+Run automated checks for every item possible (grep, file existence, build checks). Report:
+- PASS / WARN / FAIL per item
+- Total: "Shipping checklist: X/Y items verified"
+
+Any FAIL items block milestone completion. Ask user: "Fix these first, or accept risk and continue?"
+Include checklist results in the milestone archive.
+
+### 3. Verify Readiness
+
+Confirm with user:
+- All phases complete and verified
+- Shipping checklist passed (or risks accepted)
+- No critical tech debt blocking release
+- Ready to archive and tag
+
+### 4. Gather Stats
+
+Collect from STATE.md and git history:
+- Total phases completed
+- Total commits
+- Duration (first commit to now)
+- Quick tasks completed
+- Lines of code changed
+
+### 4. Extract Accomplishments
+
+From phase summaries and audit report, compile a list of what was achieved in this milestone.
+
+### 5. Generate Changelog
+
+After archiving, generate/update CHANGELOG.md at project root with milestone accomplishments and phase summaries. Prepend to existing file or create new.
+
+### 6. Archive Milestone
+
+Create milestone archive:
+```bash
+mkdir -p .planning/milestones
+cp .planning/ROADMAP.md .planning/milestones/v{version}-ROADMAP.md
+cp .planning/REQUIREMENTS.md .planning/milestones/v{version}-REQUIREMENTS.md
+```
+
+Template: `~/.claude/qualia-engine/templates/milestone-archive.md`
+
+### 6. Archive Requirements
+
+Delete current requirements (fresh start for next milestone):
+```bash
+rm .planning/REQUIREMENTS.md
+```
+
+### 7. Update PROJECT.md
+
+Update PROJECT.md to reflect:
+- Milestone v{version} completed on {date}
+- Stats summary
+- Key accomplishments
+
+### 8. Commit & Tag
+
+```bash
+git add -A
+git commit -m "milestone: complete v{version}"
+git tag v{version}
+```
+
+### 9. Offer Next Steps
+
+> "Milestone v{version} complete and tagged! Options:"
+> - "Start next milestone: `/qualia-new-milestone`"
+> - "Ship to production: `/ship`"
+> - "Take a break — you earned it"

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

@@ -0,0 +1,149 @@
+---
+name: qualia-debug
+description: "Structured debugging with symptom gathering, deep error analysis, frontend/CSS fixing, and performance profiling. Use this skill whenever the user says 'debug', 'find bug', 'fix error', 'something is broken', 'error analysis', or needs help diagnosing and fixing a bug. Also trigger when user mentions 'stack trace', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'z-index', 'slow page', 'performance', 'latency', or wants systematic debugging rather than quick guessing. Supports interactive, error-analysis, frontend, and perf modes."
+---
+
+# Qualia Debug — Structured Debugging
+
+Systematic debugging with four modes: interactive symptom-based debugging, deep error analysis, frontend/CSS fixes, and performance profiling.
+
+## Usage
+
+`/qualia-debug` — Interactive debugging (gather symptoms, diagnose, fix)
+`/qualia-debug --frontend` — CSS/layout/visual issues
+`/qualia-debug --perf` — Performance issues
+`/qualia-debug --error-analysis` — Deep 7-phase error analysis
+
+## Interactive Mode (Default)
+
+### 1. Initialize
+
+Load state with `qualia-tools.js`:
+```bash
+node ~/.claude/qualia-engine/bin/qualia-tools.js phase-op current
+```
+
+Check for existing debug sessions in `.planning/debug/`.
+
+### 2. Check Active Sessions
+
+If there's an in-progress debug session, offer to continue it or start fresh.
+
+### 3. Gather Symptoms
+
+Ask targeted questions:
+- What's happening? (exact error message or behavior)
+- What should happen instead?
+- When did it start? (after what change?)
+- Is it consistent or intermittent?
+- What have you already tried?
+
+### 3.5. Confirm Diagnosis
+
+Before spawning the debugger or making any code changes, present your diagnosis:
+
+> "Based on the symptoms, here's what I think is happening: [diagnosis]. I plan to investigate [specific area]. Does that match what you're seeing?"
+
+Wait for user confirmation. If the user corrects the diagnosis:
+- Acknowledge the correction
+- Adjust the investigation plan accordingly
+- Do NOT proceed with the original (incorrect) diagnosis
+
+This prevents the #1 debugging anti-pattern: jumping to a wrong root cause and "fixing" the wrong thing.
+
+### 4. Spawn Debugger
+
+Spawn the `qualia-debugger` agent with symptoms and project context.
+
+Reference: `~/.claude/agents/qualia-debugger.md`
+
+Model resolution:
+```bash
+node ~/.claude/qualia-engine/bin/qualia-tools.js resolve-model qualia-debugger
+```
+
+The debugger follows a systematic approach:
+1. Reproduce the issue
+2. Isolate the cause
+3. Identify root cause
+4. Implement minimal fix
+5. Verify fix
+6. Check for related issues
+
+### 5. Save Debug Record
+
+Write findings to `.planning/debug/{slug}.md`:
+- Symptoms
+- Root cause
+- Fix applied
+- Lessons learned
+
+## Error Analysis Mode (`--error-analysis`)
+
+Deep 7-phase analysis for complex or recurring error patterns:
+
+### Phase 1: Error Pattern Analysis
+Categorize all errors by type, frequency, and trigger conditions.
+
+### Phase 2: Debugging Strategy
+Design a systematic investigation plan based on patterns found.
+
+### Phase 3: Error Handling Improvements
+Identify where error handling is missing or inadequate.
+
+### Phase 4: Logging Enhancement
+Recommend logging improvements to make future debugging easier.
+
+### Phase 5: Monitoring Integration
+Suggest monitoring and alerting for error conditions.
+
+### Phase 6: Recovery Mechanisms
+Design graceful degradation and recovery patterns.
+
+### Phase 7: Prevention Strategies
+Identify systemic changes to prevent error classes from recurring.
+
+Output saved to `.planning/debug/error-analysis-{timestamp}.md`.
+
+## Frontend Mode (`--frontend`)
+
+For layout breaks, z-index wars, animation glitches, overflow problems, CSS conflicts, rendering bugs.
+
+### Debug Toolkit
+```css
+/* Outline everything to find what's too wide */
+* { outline: 1px solid red; }
+/* Show stacking contexts */
+* { transform: translateZ(0); }
+```
+
+### Common Fixes
+
+**Z-index not working:** Element needs `position: relative/absolute/fixed`. Check parent stacking contexts — `transform`, `opacity`, or `filter` on parent creates new context.
+
+**Horizontal scroll:** Use `width: 100%` not `100vw`. Find the overflowing element with outline trick.
+
+**Flex child overflow:** Add `min-width: 0` to allow shrinking.
+
+**Grid blowout:** Use `minmax(0, 1fr)` or `min-width: 0` on grid items.
+
+**Janky animations:** Only animate `transform` and `opacity`. Use `translateX()` not `left`.
+
+**Safari issues:** `-webkit-backdrop-filter` for blur, `100dvh` not `100vh`, explicit width/height on SVGs.
+
+**Layout shift:** Set `aspect-ratio` + `object-fit: cover` on images. Use `font-display: swap`.
+
+## Performance Mode (`--perf`)
+
+For slow queries, high memory, slow renders, large bundles, API latency.
+
+### Investigation
+1. Profile the bottleneck (network, render, compute, database)
+2. Measure current performance baseline
+3. Identify the hot path
+
+### Common Fixes
+- **Slow queries:** Check indexes, add `EXPLAIN ANALYZE`, optimize joins
+- **Large bundles:** Code split, lazy load, tree shake
+- **Slow renders:** Memoize expensive components, virtualize long lists
+- **API latency:** Add caching, reduce payload, parallelize requests