qualia-framework 2.6.0 → 3.1.0

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

@@ -1,134 +0,0 @@
----
-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-framework/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 `~/.claude/qualia-framework/references/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-framework/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 <list of modified files>
-git commit -m "milestone: complete v{version}"
-git tag v{version}
-```
-
-### 9. Enter Finish Line
-
-Set `finish_line: "needs_polish"` in STATE.md (or `"needs_review"` if the project has no frontend).
-
-Then show the finish line checklist:
-
-```
-◆ Milestone v{version} archived and tagged!
-
-  Features are ~70% of a project. Time for the finish line.
-
-  ── Progress to Client-Ready ──────────
-  ✓ Build phases       complete
-  ✓ Milestone audit    passed
-  ✓ Milestone archived
-  ▶ Design polish      ← you are here
-  · Code review
-  · Pull request
-  · Deploy (Fawzi reviews + deploys)
-  · Client handoff
-
-  Next → /critique
-```
-
-**For projects without frontend** (AI agents, voice agents, edge functions):
-- Skip design polish step
-- Set `finish_line: "needs_review"` and show `▶ Code review` instead
-
-**Do NOT offer `/client-handoff` or `/ship` directly** — the finish line routing in `/qualia` will guide them through each step in order.
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help` · Done for today? Type `/qualia-report`

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

@@ -1,149 +0,0 @@
----
-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-framework/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-framework/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

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

@@ -1,203 +0,0 @@
----
-name: qualia-design
-description: "One-command design transformation — critiques, fixes, polishes, hardens, and makes responsive in one shot. No reports, no choices, just makes it look professional. Use this skill whenever the user says 'fix the design', 'make it look better', 'redesign', 'make it modern', 'make it professional', 'qualia-design', 'design pass', 'it looks ugly', 'fix the UI', 'make it pretty', 'design overhaul', or wants their frontend to look great without running multiple commands."
----
-
-# Qualia Design — One-Shot Design Transformation
-
-Make it look great. No reports, no choices, no back-and-forth. Read the code, understand what's wrong, fix everything, move on.
-
-This orchestrates critique → fix → responsive → polish → harden in one pass.
-
-## Usage
-
-- `/qualia-design` — Full design transformation on all frontend files
-- `/qualia-design app/page.tsx` — Transform specific file(s)
-- `/qualia-design --scope=dashboard` — Transform a section (greps for matching files)
-
-## Process
-
-### Step 1: Understand the Brand
-
-Read design context BEFORE touching anything:
-
-```bash
-cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
-```
-
-```bash
-cat ~/.claude/rules/frontend.md 2>/dev/null
-```
-
-```bash
-# Find all frontend files changed recently or specified
-git diff --name-only HEAD~10..HEAD 2>/dev/null | grep -E '\.(tsx|jsx|css|scss)$' | head -30
-```
-
-If DESIGN.md exists → use it as the source of truth for colors, typography, spacing, brand personality.
-
-If NO DESIGN.md → use `rules/frontend.md` defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
-
-Read the `frontend-master` skill for the full design system:
-```bash
-cat ~/.claude/skills/frontend-master/SKILL.md
-```
-
-### Step 2: Identify Target Files
-
-**If specific files provided** ($ARGUMENTS): use those.
-
-**If --scope provided**: find matching files:
-```bash
-find app components -name "*.tsx" -o -name "*.jsx" | xargs grep -l "$SCOPE" 2>/dev/null
-```
-
-**If no arguments**: find all user-facing frontend files:
-```bash
-find app -name "page.tsx" -o -name "layout.tsx" 2>/dev/null
-find components -name "*.tsx" -type f 2>/dev/null | head -20
-```
-
-Read EVERY target file before modifying. Understand the current state.
-
-### Step 3: Critique (internal — don't output report)
-
-For each file, mentally evaluate using the critique skill's 10 dimensions:
-
-1. **AI slop detection** — Generic patterns? Looks like every other AI-built site?
-2. **Visual hierarchy** — Can users scan and find what matters?
-3. **Information architecture** — Is content grouped logically?
-4. **Typography** — Distinctive font? Proper scale? Good line height?
-5. **Color** — Cohesive palette? Sharp accents? Not bland?
-6. **States** — Loading, error, empty, hover, focus, active, disabled all handled?
-7. **Motion** — Meaningful transitions? Staggered animations? Not static?
-8. **Spacing** — Consistent rhythm? Breathing room? Not cramped?
-9. **Responsiveness** — Full-width? Proper breakpoints? Touch targets?
-10. **Microcopy** — Clear labels? Helpful error messages? Good CTAs?
-
-Don't output this analysis. Use it to guide fixes.
-
-### Step 4: Fix Everything
-
-Apply fixes directly. For each file:
-
-**Typography:**
-- Replace generic fonts (Inter, Arial, system-ui as primary) with distinctive choices
-- Ensure proper type scale (not everything the same size)
-- Set comfortable line-height (1.5-1.7 for body, 1.1-1.3 for headings)
-- Limit line length for readability (max-width: 65ch on prose)
-
-**Color & Contrast:**
-- Apply cohesive palette from DESIGN.md or create one
-- Add sharp accent color for CTAs and interactive elements
-- Ensure WCAG AA contrast on all text
-- Add subtle gradients or layered backgrounds where flat
-
-**Layout:**
-- Full-width containers with fluid padding: `padding-inline: clamp(1rem, 5vw, 4rem)`
-- NO hardcoded max-width caps (no 1200px, no 1280px on main containers)
-- Prose content gets `max-width: 65ch` (readable line length)
-- Break out of card grids — use varied layouts, asymmetry, visual rhythm
-
-**Spacing:**
-- Consistent spacing scale (use Tailwind's scale or 8px grid)
-- Generous whitespace between sections
-- Tight grouping within related elements
-- Varied rhythm — not everything equidistant
-
-**Motion & Interaction:**
-- Add CSS transitions on hover/focus states (200-300ms ease)
-- Stagger entrance animations on lists/grids
-- Smooth page transitions where applicable
-- `prefers-reduced-motion` respected
-
-**States:**
-- Every async operation → loading state (skeleton or spinner)
-- Every data fetch → error state (not just blank)
-- Every list/table → empty state (helpful message, not just "No data")
-- Every interactive element → hover, focus, active, disabled states
-
-**Responsive:**
-- Mobile-first breakpoints
-- Touch targets minimum 44x44px
-- Stack layouts on mobile, expand on desktop
-- Test mental model at: 375px, 768px, 1024px, 1440px, 1920px+
-- No horizontal scroll at any breakpoint
-
-**Anti-patterns to eliminate:**
-- Card grids with identical cards → use varied layouts
-- Generic hero sections → make distinctive
-- Blue-purple gradients → use brand colors
-- Walls of text → break up with visual elements
-- Static pages → add purposeful motion
-- Fixed pixel widths → fluid/responsive
-- Missing focus indicators → add them
-- Placeholder content → write real copy or flag for user
-
-### Step 5: Polish Pass
-
-After all fixes applied, do a final pass on each file:
-
-- Pixel-perfect alignment (are things actually aligned?)
-- Consistent border-radius across components
-- Consistent shadow/elevation system
-- Icon sizing consistent
-- Button hierarchy clear (primary > secondary > ghost)
-- Spacing between siblings consistent
-- No orphaned headings (heading without following content)
-
-### Step 6: Verify
-
-After all changes:
-
-```bash
-npx tsc --noEmit 2>&1 | head -20
-```
-
-If TypeScript errors → fix them before proceeding.
-
-Check that no files were accidentally broken:
-```bash
-npm run build 2>&1 | tail -10
-```
-
-### Step 7: Commit and Report
-
-Commit all design changes (add only the files you modified — never use `git add -A`):
-```bash
-git add <list of modified files>
-git commit -m "style: design transformation — typography, color, spacing, states, responsive"
-```
-
-Then present a brief summary (NOT a full report — just what changed):
-
-```
-◆ Design Transformation Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Files transformed: {N}
-
-  What changed:
-  - {key change 1, e.g. "Replaced Inter with Space Grotesk"}
-  - {key change 2, e.g. "Added loading/error/empty states to 4 components"}
-  - {key change 3, e.g. "Full-width layout, removed 1200px cap"}
-  - {key change 4, e.g. "Added hover transitions and entrance animations"}
-
-  Run the dev server to see the changes.
-
-  Want to fine-tune? Use individual commands:
-  - /bolder — make it more striking
-  - /design-quieter — tone it down
-  - /colorize — adjust colors
-  - /animate — add more motion
-```
-
-## Rules
-
-- **Read before write** — understand every file before changing it
-- **Don't ask** — just fix. This is not a review command, it's a fix command.
-- **Respect DESIGN.md** — if brand decisions exist, follow them
-- **Don't break functionality** — only change styling/presentation, never logic
-- **TypeScript must pass** — run tsc after changes
-- **Commit atomically** — one commit for the whole transformation
-- **No partial work** — transform ALL target files, not just the first one

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

@@ -1,72 +0,0 @@
----
-name: qualia-discuss-phase
-description: "Adaptive questioning to clarify phase scope and decisions before planning begins. Use this skill whenever the user says 'discuss phase', 'let's talk about phase', 'clarify phase', 'phase discussion', or wants to think through a phase's gray areas before creating a plan. Also trigger when user mentions 'what should we decide', 'before we plan', or needs to make design decisions for an upcoming phase."
----
-
-# Qualia Discuss Phase — Pre-Planning Discussion
-
-Adaptive questioning to surface decisions and clarify gray areas before phase planning begins.
-
-## Usage
-
-`/qualia-discuss-phase 3` — Discuss phase 3 before planning
-`/qualia-discuss-phase` — Auto-detect next phase needing discussion
-
-## Key Principle
-
-The phase boundary is FIXED — discussion clarifies HOW to implement, not WHETHER to implement. The scope comes from the roadmap; this skill fills in the design decisions.
-
-## Process
-
-### 1. Load Phase Context
-
-Read the phase description from ROADMAP.md and any existing research.
-
-Reference: `~/.claude/qualia-framework/workflows/discuss-phase.md`
-
-### 2. Identify Domain Gray Areas
-
-Based on the phase's domain, identify the key decision areas:
-
-**SEE (UI/Visual phases)** — Layout, component hierarchy, responsive behavior, animation
-**CALL (API/Integration phases)** — Response formats, error handling, retry logic, auth flow
-**RUN (Processing/Logic phases)** — Output format, edge cases, performance constraints
-**READ (Data/Content phases)** — Data structure, relationships, validation rules
-**ORGANIZE (Architecture phases)** — Organization criteria, naming conventions, migration paths
-
-### 3. Adaptive Questioning
-
-Ask 4 targeted questions per area. Questions should surface:
-- Ambiguities in the requirements
-- Design choices that could go multiple ways
-- User preferences and priorities
-- Constraints not captured in the roadmap
-
-After each set of 4, offer: "Want to go deeper on this area, or move to the next?"
-
-### 4. Create Context Document
-
-Write decisions to `.planning/phases/{phase}-{slug}/{phase}-CONTEXT.md`:
-
-```markdown
-# Phase {N}: {Name} — Context & Decisions
-
-## Decisions Made
-- Decision 1: [choice] — Rationale: [why]
-- Decision 2: [choice] — Rationale: [why]
-
-## Open Questions
-- Questions deferred to implementation
-
-## Constraints Identified
-- Constraints that affect planning
-
-## User Preferences
-- Specific preferences expressed
-```
-
-Template: `~/.claude/qualia-framework/templates/context.md`
-
-### 5. Handoff
-
-> "Context captured. These decisions will feed into `/qualia-plan-phase {N}`."