qualia-framework 2.5.1 → 3.1.0

package/skills/qualia-pause/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: qualia-pause
+description: "Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off. Trigger on 'pause', 'stop for now', 'save progress', 'continue later', 'pick up tomorrow'."
+---
+
+# /qualia-pause — Session Handoff
+
+Save context so the next session picks up where you left off.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner pause
+```
+
+### 1. Read State
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+git status --short 2>/dev/null
+git log --oneline -5 2>/dev/null
+```
+
+### 2. Create `.continue-here.md`
+
+```markdown
+# Continue Here
+
+## Session Summary
+{What was accomplished — from conversation context + git log}
+
+## Current Phase
+Phase {N}: {name} — {status}
+
+## In Progress
+- {What's partially done}
+- {Where exactly work stopped}
+
+## Next Steps
+1. {Immediate next action}
+2. {Following action}
+
+## Decisions Made
+- {Decision and rationale}
+
+## Blockers
+- {Any unresolved issues}
+
+## Files Modified
+- {List from git status/diff}
+```
+
+### 3. Commit
+
+```bash
+git add .continue-here.md {any uncommitted work files}
+git commit -m "WIP: {phase name} — session handoff"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "Session paused — see .continue-here.md"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-plan/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: qualia-plan
+description: "Plan the current phase — spawns planner agent in fresh context. Use when ready to plan a phase."
+---
+
+# /qualia-plan — Plan a Phase
+
+Spawn a planner agent to break the current phase into executable tasks.
+
+## Usage
+`/qualia-plan` — plan the next unplanned phase
+`/qualia-plan {N}` — plan specific phase
+`/qualia-plan {N} --gaps` — plan fixes for verification failures
+
+## Process
+
+### 1. Determine Phase & Load Knowledge
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+If no phase number given, use the current phase from STATE.md.
+If any learned patterns apply to this phase's work, pass them to the planner in the spawn prompt under a `## Relevant Learnings` section.
+If this is a client project and `client-prefs.md` has an entry for the client, include those preferences in the planner context.
+
+### 2. Spawn Planner (Fresh Context)
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner plan {N} "{phase name from STATE.md}"
+node ~/.claude/bin/qualia-ui.js spawn planner "Breaking phase into tasks..."
+```
+
+Spawn a subagent with `agents/planner.md` instructions:
+
+```
+Agent(prompt="
+Read your role: @agents/planner.md
+
+Project context:
+@.planning/PROJECT.md
+
+Current state:
+@.planning/STATE.md
+
+Phase {N} goal: {goal from STATE.md roadmap}
+Phase {N} success criteria: {criteria from STATE.md}
+
+{If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix}
+
+Create the plan file at .planning/phase-{N}-plan.md
+", subagent_type="qualia-planner", description="Plan phase {N}")
+```
+
+### 3. Review Plan
+
+Read the generated plan. Present the summary using the UI helpers:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Plan ready: {count} tasks across {count} waves"
+```
+
+Then, for each wave, print:
+
+```bash
+node ~/.claude/bin/qualia-ui.js wave {wave_num} {wave_total} {task_count_in_wave}
+node ~/.claude/bin/qualia-ui.js task 1 "{task title}"
+node ~/.claude/bin/qualia-ui.js task 2 "{task title}"
+```
+
+End with an approval prompt (plain text, no UI helper): *"Approve? (yes / adjust)"*
+
+If "adjust" — get feedback, re-spawn planner with revision context.
+
+### 4. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to planned --phase {N}
+```
+If state.js returns an error, show it to the employee and stop.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
+```
+
+### Gap Closure Mode (`--gaps`)
+
+When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
+
+1. Read `.planning/phase-{N}-verification.md` — extract ONLY the FAIL items
+2. For each FAIL item, create a targeted fix task:
+   - **Files:** The specific files that failed verification
+   - **Action:** The specific fix needed (not "fix auth" — "add session persistence check in `src/lib/auth.ts` signIn function")
+   - **Done when:** The exact verification criterion that previously failed, restated
+3. Do NOT re-plan passing items. Do NOT add new features. Gap plans are surgical.
+4. Write to `.planning/phase-{N}-gaps-plan.md` (separate from original plan)
+5. All gap tasks are Wave 1 (parallel) unless they share files

package/skills/qualia-polish/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: qualia-polish
+description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
+---
+
+# /qualia-polish — Design Pass
+
+Makes it look like a human designer built it. Kills AI slop. Run after all feature phases are verified.
+
+## The Standard
+
+Every site Qualia ships must feel **designed, not generated.** AI-generated sites have tells:
+- Identical card grids with rounded corners and soft shadows
+- Blue-purple gradients on everything
+- Inter/system-ui font with no hierarchy
+- Generic hero with centered text and a stock gradient background
+- Fixed-width containers leaving dead space on wide screens
+- No motion, no personality, no opinion
+- Perfect symmetry everywhere (real design has tension)
+
+**Kill all of these.** A Qualia site should make someone ask "who designed this?" — not "which template is this?"
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner polish
+```
+
+### 0. Load Design Context
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+If DESIGN.md exists → it's the standard. Read ALL 12 sections. Key sections for polish:
+- §1 Visual Theme — the feel and signature details
+- §2 Color Palette — exact hex values, CSS variables, contrast ratios
+- §3 Typography — hierarchy table with exact sizes/weights/spacing
+- §4 Components — exact button/card/input/badge specs
+- §5 Layout — spacing scale, grid strategy
+- §6 Depth & Elevation — shadow levels with exact rgba values
+- §7 Do's/Don'ts — brand-specific guardrails
+- §9 Agent Prompt Guide — quick reference for common patterns
+- §10 Accessibility — WCAG checklist
+- §11 Hardening — stress-test criteria
+- §12 Anti-Slop Detection — grep patterns for automated checks
+
+If no DESIGN.md → use `rules/frontend.md` defaults.
+
+Read EVERY frontend file before modifying. No blind edits.
+
+### 1. AI Slop Detector
+
+Run these checks first. Any hits = mandatory fixes.
+
+```bash
+# Generic fonts (the #1 AI tell)
+grep -rn "Inter\|Roboto\|Arial\|Helvetica\|system-ui\|Space.Grotesk" --include="*.tsx" --include="*.css" --include="*.scss" --include="tailwind*" app/ components/ src/ 2>/dev/null | grep -v node_modules
+
+# Hardcoded max-width containers (screams template)
+grep -rn "max-w-7xl\|max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-width.*1280" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+
+# Blue-purple gradients
+grep -rn "from-blue.*to-purple\|from-purple.*to-blue\|linear-gradient.*blue.*purple\|linear-gradient.*purple.*blue\|from-indigo.*to-violet" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+
+# Card grid monotony (same card component repeated in a grid)
+grep -rn "grid-cols-3\|grid-cols-4" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+
+# Generic hero patterns
+grep -rn "text-center.*mx-auto\|Hero\|hero" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+
+# Scattered hardcoded colors (no design system)
+grep -rn "text-\[#\|bg-\[#\|border-\[#\|color:.*#\|background:.*#" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
+```
+
+**Every hit gets fixed.** Not flagged — fixed.
+
+### 2. Typography Pass
+
+**Goal:** A reader should feel the type was chosen, not defaulted.
+
+- Pick a distinctive display font. Not Inter, not Roboto, not system. Something with character: Clash Display, Cabinet Grotesk, General Sans, Satoshi, Plus Jakarta Sans, Outfit, Sora, Manrope. Pair with a clean body font.
+- Establish clear hierarchy: display (hero text) → h1 → h2 → h3 → body → caption
+- Body: 16px minimum, line-height 1.5-1.7
+- Headings: tighter line-height (1.1-1.3), negative letter-spacing (-0.02em) for display sizes
+- Weight hierarchy: Regular (400) for body, Medium (500) for labels, Semibold (600) for headings, Bold (700) for display
+- Prose content: `max-width: 65ch`. Everything else: fluid full-width.
+- Use `clamp()` for fluid sizing: `clamp(2rem, 1rem + 3vw, 3.75rem)` for h1
+
+### 3. Color & Surfaces
+
+**Goal:** A palette that looks intentional, not random.
+
+- Define all colors as CSS variables or Tailwind config — zero scattered hex values
+- One dominant brand color. One sharp accent for CTAs that pops against the page.
+- Surfaces: layer them. Background → card → elevated card. Use subtle shade differences, not just white-on-white.
+- Dark mode (if present): rethink surfaces, don't just invert. Slightly reduce contrast. Use darker brand colors, not just white→black swap.
+- Semantic colors with non-color indicators: success (green + checkmark), error (red + icon), warning (amber + triangle)
+- Verify WCAG AA: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
+
+### 4. Layout & Spacing
+
+**Goal:** Full-width, fluid, generous. No dead space gutters.
+
+- Full-width layouts with fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
+- 8px spacing grid: 4, 8, 12, 16, 24, 32, 48, 64, 96
+- Tight spacing within groups (related items). Generous spacing between sections.
+- Break symmetry where it serves the design — offset grids, overlapping elements, diagonal flow
+- Varied layouts: not every section should be a centered-text-with-cards-below. Use side-by-side, staggered, asymmetric, full-bleed.
+- Section spacing: `clamp(2rem, 8vw, 6rem)` vertical padding
+
+### 5. Interactive States
+
+**Goal:** Every clickable thing responds. Every async operation shows progress.
+
+- **Hover:** color shift or underline within 150ms ease-out. `cursor: pointer` on ALL clickables.
+- **Focus:** visible ring (2px+ offset, contrasting color). Never `outline: none` without replacement.
+- **Active/pressed:** subtle scale down (`transform: scale(0.98)`) or color shift.
+- **Disabled:** opacity 0.5 + `cursor: not-allowed` + `aria-disabled="true"`
+- **Loading:** skeleton shimmer or spinner on every async operation. Never a blank void.
+- **Empty:** helpful message + CTA on empty lists/tables. Not just "No results."
+- **Error:** user-friendly message + recovery action. Not raw error text. Use `aria-live="assertive"`.
+
+### 6. Motion & Personality
+
+**Goal:** The site feels alive, not static. But tasteful — not a circus.
+
+- Page load: stagger children entrance (50-80ms delay between items, `fadeUp` animation, 300ms)
+- Hover transitions: 150-200ms ease-out
+- Section transitions: 300-500ms with `cubic-bezier(0.4, 0, 0.2, 1)`
+- One signature motion that gives the site personality (parallax, scroll-triggered reveal, magnetic buttons, morphing shapes)
+- **Always** `prefers-reduced-motion: reduce` — disable non-essential animation
+- CSS-only for static sites, `motion/react` (formerly Framer Motion) for React
+
+### 7. Accessibility (Non-Negotiable)
+
+- Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer` — not div soup
+- One `h1` per page, sequential heading order (no h1 → h3 skip)
+- All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
+- All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
+- All interactive elements: keyboard accessible (Tab, Enter, Escape, Arrow keys)
+- Touch targets: 44x44px minimum
+- Skip link: `<a href="#main" class="sr-only focus:not-sr-only">` as first focusable element
+- `<html lang="en">` set
+- Color never the sole information carrier — icons, text, patterns as supplements
+- `aria-live="polite"` for toast notifications and dynamic content updates
+
+### 8. Responsive (Mobile-First)
+
+- Base styles for mobile (320px), scale up with `min-width` breakpoints
+- Test at: 320px (small phone), 375px (iPhone), 768px (iPad), 1024px (laptop), 1440px (desktop)
+- No horizontal scroll at any viewport
+- Navigation: hamburger/drawer on mobile, full horizontal on desktop
+- Stack on mobile, expand on desktop
+- Fluid typography with `clamp()`
+- Images: `max-width: 100%`, responsive `srcset`, `next/image` with width/height
+- Tables: card layout or horizontal scroll on mobile
+
+### 9. Harden (Edge Cases)
+
+After all visual work, stress-test:
+- Long text: does a 200-character username break the layout?
+- Empty everywhere: all lists empty, all data missing — does it still make sense?
+- Error everywhere: every fetch fails — are error states visible and helpful?
+- 320px viewport: nothing overflows, nothing clips, nothing overlaps
+- Keyboard only: Tab through the entire app — can you reach everything? Is focus visible?
+- Slow network: are loading states visible? Does content stream in or flash?
+
+### 10. Verify & Ship
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors.
+
+```bash
+git add {changed files}
+git commit -m "polish: design pass — typography, color, states, motion, responsive, a11y"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to polished
+```
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "AI slop: killed"
+node ~/.claude/bin/qualia-ui.js ok "Typography: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Color: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Layout: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "States: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Motion: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Accessibility: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Responsive: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Hardened: {brief}"
+node ~/.claude/bin/qualia-ui.js end "POLISHED" "/qualia-ship"
+```
+
+## Rules
+
+1. **Read before write.** Understand every file before changing it.
+2. **DESIGN.md is law.** If it exists, follow it. Don't override client decisions.
+3. **Don't break functionality.** Only change styling, never logic.
+4. **AI slop is a bug.** Generic fonts, card grids, blue-purple gradients, centered-everything — treat these as defects, not preferences.
+5. **TypeScript must pass** after every change.
+6. **One commit** at the end — not per category.

package/skills/qualia-quick/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: qualia-quick
+description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning."
+---
+
+# /qualia-quick — Quick Task
+
+For tasks under 1 hour that don't need full phase planning. Single file changes, bug fixes, config tweaks, typo fixes.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner quick
+```
+
+1. **Understand:** Ask what needs to be done (or read the instruction)
+2. **Build:** Do it directly — read before write, MVP only
+3. **Verify:** Run `npx tsc --noEmit`, test locally
+4. **Commit:** Atomic commit with clear message
+5. **Update:** Update tracking.json notes field
+
+End with:
+```bash
+node ~/.claude/bin/qualia-ui.js end "QUICK FIX DONE"
+```
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+No plan file. No subagents. Just build and ship.
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-report/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: qualia-report
+description: "Generate session report and commit to repo. Mandatory before clock-out."
+---
+
+# /qualia-report — Session Report
+
+Generate a concise report of what was done. Committed to git and uploaded to the ERP for clock-out.
+
+## Process
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner report
+```
+
+### 1. Gather Data
+
+```bash
+SINCE="8 hours ago"
+echo "---COMMITS---"
+git log --oneline --since="$SINCE" 2>/dev/null | head -20
+echo "---STATS---"
+echo "COUNT:$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)"
+echo "---PROJECT---"
+echo "DIR:$(basename $(pwd))"
+echo "BRANCH:$(git branch --show-current 2>/dev/null)"
+echo "---STATE---"
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+### 2. Synthesize
+
+Build a concise summary:
+- **What was done:** 3-6 bullet points. Start with verbs (Built, Fixed, Added). Group related commits.
+- **Blockers:** Only if something is actually blocked.
+- **Next:** 1-3 clear next actions.
+
+### 3. Generate Report
+
+Write to `.planning/reports/report-{YYYY-MM-DD}.md`:
+
+```markdown
+# Session Report — {YYYY-MM-DD}
+
+**Project:** {name}
+**Employee:** {git user.name}
+**Branch:** {branch}
+**Phase:** {N} — {name} ({status})
+**Date:** {YYYY-MM-DD}
+
+## What Was Done
+- {accomplishment 1}
+- {accomplishment 2}
+- {accomplishment 3}
+
+## Blockers
+None. / - {blocker}
+
+## Next Steps
+1. {next action}
+2. {next action}
+
+## Commits
+{list from git log}
+```
+
+### 4. Commit and Push
+
+```bash
+mkdir -p .planning/reports
+git add .planning/reports/report-{date}.md
+git commit -m "report: session {YYYY-MM-DD}"
+git push
+```
+
+### 5. Upload to ERP (if enabled)
+
+Read `~/.claude/.qualia-config.json` and check the `erp` object:
+- If `erp.enabled` is `false`, skip this step and print: "ERP upload skipped (disabled in config)."
+- If `erp.enabled` is `true` (default) or the `erp` field is missing (backward compatibility), proceed with the upload.
+
+```bash
+# Read ERP config
+ERP_URL=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.url||'https://portal.qualiasolutions.net')}catch{console.log('https://portal.qualiasolutions.net')}")
+ERP_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.enabled!==false)}catch{console.log('true')}")
+
+API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
+REPORT_FILE=".planning/reports/report-{date}.md"
+EMAIL=$(git config user.email)
+PROJECT=$(basename $(pwd))
+
+# Only upload if ERP is enabled
+if [ "$ERP_ENABLED" = "true" ]; then
+  curl -s -X POST "$ERP_URL/api/claude/report-upload" \
+    -H "X-API-Key: $API_KEY" \
+    -F "file=@$REPORT_FILE" \
+    -F "employee_email=$EMAIL" \
+    -F "project_name=$PROJECT"
+fi
+```
+
+If the upload succeeds, print: "Report uploaded to ERP. You can now clock out."
+If it fails (no API key, network error), print the error and tell the employee to ask Fawzi.
+If ERP is disabled, print: "ERP upload skipped (disabled in config)."
+
+### 6. Update State
+
+```bash
+node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"
+```
+
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
+
+Employee cannot skip this. Run `/qualia-report` before clock-out.

package/skills/qualia-resume/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: qualia-resume
+description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+---
+
+# /qualia-resume — Resume Work
+
+Restore context and route to the right next action.
+
+## Process
+
+### 1. Find Context (priority order)
+
+1. `.continue-here.md` — richest source, from `/qualia-pause`
+2. `.planning/STATE.md` — project state
+3. Git history — `git log --oneline -10` + `git diff --stat`
+
+### 2. Restore
+
+**If `.continue-here.md` exists:** Read fully. Summarize: what was done, what's in progress, next steps, blockers.
+
+**If only STATE.md:** Read STATE.md + tracking.json. Show current phase and status.
+
+**If neither:** Reconstruct from git. Present findings, ask user to confirm.
+
+### 3. Detect Incomplete Work
+
+- Phase has plan but no verification → execution may be incomplete
+- Uncommitted changes → `git status --short`
+- Phase marked in-progress in STATE.md
+
+### 4. Present and Route
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner resume
+node ~/.claude/bin/qualia-ui.js info "Last session: {summary}"
+```
+
+If uncommitted changes:
+```bash
+node ~/.claude/bin/qualia-ui.js warn "{N} uncommitted files"
+```
+
+End with the next command:
+```bash
+node ~/.claude/bin/qualia-ui.js next "{next command}"
+```
+
+Clean up `.continue-here.md` after restoration (or offer to keep it).