qualia-framework 2.1.0

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

@@ -0,0 +1,203 @@
+---
+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:
+```bash
+git add -A
+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

@@ -0,0 +1,72 @@
+---
+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-engine/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-engine/templates/context.md`
+
+### 5. Handoff
+
+> "Context captured. These decisions will feed into `/qualia-plan-phase {N}`."

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

@@ -0,0 +1,86 @@
+---
+name: qualia-execute-phase
+description: "Wave-based parallel execution of phase plans with subagent orchestration. Use this skill whenever the user says 'execute phase', 'run phase', 'build phase', 'start building', 'execute', or wants to implement a planned phase. Also trigger when user mentions 'start implementation', 'begin coding', or has a planned phase ready to execute. Supports gap-closure mode for fixing issues found during verification."
+---
+
+# Qualia Execute Phase — Phase Execution
+
+Execute all plans in a phase using wave-based parallel subagent orchestration.
+
+## Usage
+
+`/qualia-execute-phase 3` — Execute phase 3
+`/qualia-execute-phase` — Auto-detect next phase ready for execution
+`/qualia-execute-phase 3 --gaps-only` — Execute only gap closure plans (after verify-work found issues)
+
+## Process
+
+### 1. Load Plans
+
+Read all PLAN.md files for the target phase from `.planning/phases/{phase}-{slug}/`.
+
+For `--gaps-only`, read only the gap-closure plans created by `plan-phase --gaps`.
+
+Reference: `~/.claude/qualia-engine/workflows/execute-phase.md`
+UI/brand reference: `~/.claude/qualia-engine/references/ui-brand.md`
+
+### 2. Organize into Waves
+
+Group plan steps into execution waves based on dependencies:
+- **Wave 1**: Steps with no dependencies (can run in parallel)
+- **Wave 2**: Steps that depend on Wave 1 outputs
+- **Wave 3**: Steps that depend on Wave 2 outputs
+- etc.
+
+### 3. Execute Waves
+
+For each wave, spawn subagents in parallel. The orchestrator uses ~15% of context for coordination; each subagent gets 100% fresh context with:
+- The specific plan step(s) to execute
+- Project context (PROJECT.md, relevant files)
+- UI/brand guidelines
+- Clear acceptance criteria
+
+### 4. Collect Results
+
+As subagents complete:
+- Verify each step's acceptance criteria are met
+- Resolve any conflicts between parallel changes
+- Handle failures (retry or escalate to user)
+
+### 5. Create Phase Summary
+
+Write `{phase}-SUMMARY.md`:
+```markdown
+# Phase {N}: {Name} — Execution Summary
+
+## Completed Steps
+- Step 1: [what was done]
+- Step 2: [what was done]
+
+## Files Created/Modified
+- file1.tsx — [description]
+- file2.ts — [description]
+
+## Notes
+- Any deviations from plan
+- Tech debt incurred
+- Things to watch for in verification
+```
+
+### 6. Update State
+
+Update `.planning/STATE.md` phase status to `executed`.
+
+### 7. Next Step
+
+> "Phase {N} executed. Run `/qualia-verify-work {N}` to test the results."
+
+### Agents Used
+| Agent | File | Role |
+|-------|------|------|
+| `qualia-executor` | `~/.claude/agents/qualia-executor.md` | Executes each plan's tasks atomically |
+| `qualia-verifier` | `~/.claude/agents/qualia-verifier.md` | Verifies phase goal achievement |
+| `qualia-planner` | `~/.claude/agents/qualia-planner.md` | Creates gap closure plans (if verify fails) |
+| `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates gap closure plans |
+
+Domain skill context from PLAN.md `@skill` references is automatically resolved and inlined into each executor subagent prompt. Plans referencing skills like `frontend-design`, `supabase`, `financial-ledger`, etc. will have those patterns available to executors.

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

@@ -0,0 +1,67 @@
+---
+name: qualia-help
+description: "Display the complete Qualia command reference — all available skills and their usage. Use this skill whenever the user says 'help', 'qualia help', 'what commands', 'what can you do', 'show commands', or wants to see all available Qualia workflow commands. Also trigger when user seems lost or unsure which command to use next."
+---
+
+# Qualia Help — Command Reference
+
+Display the complete reference of all available Qualia workflow skills.
+
+## Usage
+
+`/qualia-help` — Show all commands
+
+## Output
+
+Reference: `~/.claude/qualia-engine/workflows/help.md`
+
+Display the command reference. Output only — no analysis, no suggestions, just the reference.
+
+### Project Lifecycle
+| Skill | Description |
+|-------|-------------|
+| `qualia-new-project` | Initialize a new project (questioning → research → requirements → roadmap) |
+| `qualia-new-milestone` | Start a new milestone on existing project |
+| `qualia-complete-milestone` | Archive milestone, tag release, prepare for next |
+
+### Phase Workflow
+| Skill | Description |
+|-------|-------------|
+| `qualia-discuss-phase` | Clarify phase decisions before planning |
+| `qualia-list-phase-assumptions` | Surface assumptions before planning |
+| `qualia-research-phase` | Conduct technical research for a phase |
+| `qualia-plan-phase` | Create detailed execution plans |
+| `qualia-execute-phase` | Wave-based parallel execution of plans |
+| `qualia-verify-work` | Conversational UAT testing |
+
+### Navigation & Status
+| Skill | Description |
+|-------|-------------|
+| `qualia-progress | Quick project status + routing |
+| `qualia-progress` | Progress summary with routing |
+| `qualia-resume-work` | Restore context from previous session |
+| `qualia-pause-work` | Save session context for handoff |
+
+### Quick Actions
+| Skill | Description |
+|-------|-------------|
+| `qualia-quick` | Quick tasks with quality guarantees |
+| `qualia-debug` | Structured debugging |
+| `qualia-add-todo` | Capture ideas and tasks |
+| `qualia-check-todos` | Review and act on todos |
+
+### Intelligence
+| Skill | Description |
+|-------|-------------|
+| `qualia-idk` | "What should I do next?" — smart advisor, reads planning + codebase |
+| `qualia-optimize` | Deep optimization pass — perf, design, UI, backend, alignment |
+| `qualia-design` | One-shot design transformation — critique + fix + responsive + polish + harden |
+
+### Quality & Deployment
+| Skill | Description |
+|-------|-------------|
+| `qualia-audit-milestone` | Verify milestone definition of done |
+| `qualia-plan-milestone-gaps` | Create fix phases from audit gaps |
+| `qualia-review` | Production audit and code review |
+| `ship` | Full production deployment pipeline |
+| `team` | Agent team orchestration |