qualia-framework-v2 2.5.0 → 2.6.0

package/hooks/session-start.sh

@@ -1,17 +1,35 @@
 #!/bin/bash
-# Qualia session start — load project context
-# Triggered on Claude Code session start
+# Qualia session start — show branded context panel on every new session.
+# Delegates to qualia-ui.js so formatting matches the rest of the framework.
 
+UI="$HOME/.claude/bin/qualia-ui.js"
 STATE=".planning/STATE.md"
-TRACKING=".planning/tracking.json"
 
+# Fallback if qualia-ui.js is missing (first install before mirror)
+if [ ! -f "$UI" ]; then
+  if [ -f "$STATE" ]; then
+    PHASE=$(grep "^Phase:" "$STATE" 2>/dev/null | head -1)
+    STATUS=$(grep "^Status:" "$STATE" 2>/dev/null | head -1)
+    echo "QUALIA: Project loaded. $PHASE | $STATUS"
+    echo "QUALIA: Run /qualia for next step."
+  elif [ -f ".continue-here.md" ]; then
+    echo "QUALIA: Handoff file found. Read .continue-here.md to resume."
+  else
+    echo "QUALIA: No project detected. Run /qualia-new to start."
+  fi
+  exit 0
+fi
+
+# Branded banner for every session start
 if [ -f "$STATE" ]; then
-  PHASE=$(grep "^Phase:" "$STATE" 2>/dev/null | head -1)
-  STATUS=$(grep "^Status:" "$STATE" 2>/dev/null | head -1)
-  echo "QUALIA: Project loaded. $PHASE | $STATUS"
-  echo "QUALIA: Run /qualia for next step."
+  node "$UI" banner router
+  # Read next command from state.js and suggest it
+  NEXT=$(node "$HOME/.claude/bin/state.js" check 2>/dev/null | node -e "try{let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const j=JSON.parse(d);process.stdout.write(j.next_command||'')})}" 2>/dev/null)
+  [ -n "$NEXT" ] && node "$UI" info "Run $NEXT to continue"
 elif [ -f ".continue-here.md" ]; then
-  echo "QUALIA: Handoff file found. Read .continue-here.md to resume."
+  node "$UI" banner router
+  node "$UI" warn "Handoff found — read .continue-here.md to resume"
 else
-  echo "QUALIA: No project detected. Run /qualia-new to start."
+  node "$UI" banner router
+  node "$UI" info "No project detected. Run /qualia-new to start."
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"

package/skills/qualia/SKILL.md

@@ -52,20 +52,17 @@ Use the state.js JSON output plus gathered context:
 
 ### 3. Display
 
-**Clear next step:**
-```
-◆ QUALIA
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Project    {name}
-  Phase      {N} of {total} — {name}
-  Status     {status}
-  Progress   {bar} {percent}%
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  → Run: {next_command from state.js}
+**Clear next step** (use the UI helper — it reads state.js itself):
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
 ```
 
 **Ambiguous situation (multiple options):**
+Print the banner first, then use plain markdown for the options:
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+```
 ```
 ## Where You Are
 {1-2 sentences}
@@ -80,4 +77,11 @@ Use the state.js JSON output plus gathered context:
 3. **{option}** — {what}
 ```
 
+**Blocker detected** (gap-limit, bug-loop, employee escalation):
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js fail "{blocker description}"
+node ~/.claude/bin/qualia-ui.js warn "Escalate to Fawzi or re-plan from scratch"
+```
+
 User can respond with a number, "just do it", or natural language.

package/skills/qualia-build/SKILL.md

@@ -23,19 +23,22 @@ Parse: tasks, waves, file references.
 
 ### 2. Execute Waves
 
-```
-◆ QUALIA ► BUILDING Phase {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
 ```
 
 **For each wave (sequential):**
 
-```
-  ◆ Wave {W} ({count} tasks)
+```bash
+node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
 ```
 
 **For each task in the wave (parallel if multiple):**
 
+```bash
+node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
+```
+
 Spawn a fresh builder subagent:
 
 ```
@@ -55,8 +58,8 @@ Execute this task. Read all @file references before writing. Commit when done.
 **After each task completes:**
 - Verify the commit exists: `git log --oneline -1`
 - Show result:
-```
-    ✓ Task {N}: {title}  ({commit hash})
+```bash
+node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
 ```
 
 **After each wave completes:**
@@ -67,13 +70,11 @@ Execute this task. Read all @file references before writing. Commit when done.
 
 After all waves complete:
 
-```
-◆ QUALIA ► Phase {N} Built
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Tasks:  {done}/{total} ✓
-  Commits: {count}
-  Waves:  {count}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Tasks: {done}/{total}"
+node ~/.claude/bin/qualia-ui.js ok "Commits: {count}"
+node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
 ```
 
 ### 4. Handle Failures
@@ -91,6 +92,6 @@ node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done
 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.
 
-```
-  → Run: /qualia-verify {N}
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
 ```

package/skills/qualia-debug/SKILL.md

@@ -15,6 +15,20 @@ Systematic debugging. Don't guess — gather symptoms, confirm diagnosis, then f
 
 ## Interactive Mode (Default)
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner debug
+```
+
+### 0. Check Known Fixes First
+
+Before gathering symptoms, check if we've seen this before:
+
+```bash
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+```
+
+If the user's description matches a known fix, suggest it first: *"I've seen this before — check {fix title}. Want to try that before we dig deeper?"* Only proceed to full investigation if the known fix doesn't apply.
+
 ### 1. Gather Symptoms
 
 Ask:

package/skills/qualia-design/SKILL.md

@@ -15,6 +15,10 @@ Read the code, understand what's wrong, fix everything, move on. No reports, no
 
 ## Process
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner design
+```
+
 ### 1. Read Brand Context
 
 ```bash

package/skills/qualia-handoff/SKILL.md

@@ -9,9 +9,8 @@ Prepare and deliver the finished project to the client.
 
 ## Process
 
-```
-◆ QUALIA ► HANDOFF
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js banner handoff
 ```
 
 ### 1. Generate Handover Doc
@@ -61,10 +60,7 @@ node ~/.claude/bin/state.js transition --to handed_off
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
-```
-◆ QUALIA ► DELIVERED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  {Project Name} handed off to {client}.
-  Don't forget: /qualia-report
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js ok "{Project Name} handed off to {client}"
+node ~/.claude/bin/qualia-ui.js end "DELIVERED" "/qualia-report"
 ```

package/skills/qualia-learn/SKILL.md

@@ -31,6 +31,10 @@ Client-specific preferences, design choices, requirements.
 
 ## Process
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner learn
+```
+
 ### 1. Classify
 
 If description given, classify automatically. Otherwise ask:

package/skills/qualia-new/SKILL.md

@@ -13,9 +13,8 @@ Interactive project setup. Ask one step at a time using AskUserQuestion. Never d
 
 Print this FIRST, before anything else:
 
-```
-◆ QUALIA ► NEW PROJECT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js banner new
 ```
 
 Then say: **"Let's build something. Tell me what you're making."**
@@ -161,6 +160,14 @@ options:
 
 If client project, ask: **"What's the client's name?"** (free text, no AskUserQuestion)
 
+After capturing the client name, check for saved preferences:
+
+```bash
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+If there's an entry for this client, show it to the user: *"I have notes on {client} — {preferences summary}. Applying these to the project defaults unless you say otherwise."* Then use those preferences in Step 8a (Design System) and Step 9 (Roadmap).
+
 ### Step 6. Confirm & Scaffold
 
 Present a summary:
@@ -225,7 +232,7 @@ Create Supabase project (via MCP or manual).
 
 ### Step 8a. Create Design System
 
-Generate **`.planning/DESIGN.md`** using `templates/DESIGN.md` as the template.
+Generate **`.planning/DESIGN.md`** using `~/.claude/qualia-templates/DESIGN.md` as the template.
 
 Fill in based on the design direction chosen in Step 3:
 
@@ -311,14 +318,6 @@ git commit -m "init: project setup with planning files"
 git push -u origin main
 ```
 
-```
-◆ QUALIA ► PROJECT READY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  {Project Name}
-  Type       {type}
-  Phases     {N}
-  Client     {client}
-
-  → Run: /qualia-plan 1
+```bash
+node ~/.claude/bin/qualia-ui.js end "PROJECT READY" "/qualia-plan 1"
 ```

package/skills/qualia-pause/SKILL.md

@@ -9,6 +9,10 @@ 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

package/skills/qualia-plan/SKILL.md

@@ -14,20 +14,23 @@ Spawn a planner agent to break the current phase into executable tasks.
 
 ## Process
 
-### 1. Determine Phase
+### 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)
 
-```
-◆ QUALIA ► PLANNING Phase {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Spawning planner...
+```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:
@@ -53,25 +56,23 @@ Create the plan file at .planning/phase-{N}-plan.md
 
 ### 3. Review Plan
 
-Read the generated plan. Present to employee:
+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"
 ```
-◆ Phase {N} Plan
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Tasks: {count}
-  Waves: {count}
-
-  Wave 1 (parallel):
-    Task 1: {title}
-    Task 2: {title}
 
-  Wave 2 (after Wave 1):
-    Task 3: {title}
+Then, for each wave, print:
 
-  Approve? (yes / adjust)
+```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
@@ -82,8 +83,8 @@ 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.
 
-```
-  → Run: /qualia-build {N}
+```bash
+node ~/.claude/bin/qualia-ui.js end "PHASE {N} PLANNED" "/qualia-build {N}"
 ```
 
 ### Gap Closure Mode (`--gaps`)

package/skills/qualia-polish/SKILL.md

@@ -9,9 +9,8 @@ Run after all feature phases are verified. Makes it look production-ready.
 
 ## Process
 
-```
-◆ QUALIA ► POLISHING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js banner polish
 ```
 
 ### 0. Load Design Context
@@ -142,20 +141,17 @@ Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ### 6. Report
 
-```
-◆ QUALIA ► POLISHED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Files modified: {N}
-
-  Typography    ✓ {brief}
-  Color         ✓ {brief}
-  Layout        ✓ {brief}
-  States        ✓ {brief}
-  Motion        ✓ {brief}
-  Accessibility ✓ {brief}
-  Responsive    ✓ {brief}
-  Performance   ✓ {brief}
-  Hardening     ✓ {brief}
-
-  → Run: /qualia-ship
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js info "Files modified: {N}"
+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 "Performance — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Hardening — {brief}"
+node ~/.claude/bin/qualia-ui.js end "POLISHED" "/qualia-ship"
 ```

package/skills/qualia-quick/SKILL.md

@@ -9,12 +9,21 @@ For tasks under 1 hour that don't need full phase planning. Single file changes,
 
 ## 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}"

package/skills/qualia-report/SKILL.md

@@ -9,6 +9,10 @@ Generate a concise report of what was done. Committed to git and uploaded to the
 
 ## Process
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner report
+```
+
 ### 1. Gather Data
 
 ```bash

package/skills/qualia-resume/SKILL.md

@@ -31,14 +31,19 @@ Restore context and route to the right next action.
 
 ### 4. Present and Route
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner resume
+node ~/.claude/bin/qualia-ui.js info "Last session: {summary}"
 ```
-◆ QUALIA ► RESUMING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Last session: {summary}
-  Phase: {N} — {status}
-  {Uncommitted changes if any}
 
-  → {next command}
+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).

package/skills/qualia-review/SKILL.md

@@ -15,6 +15,10 @@ Deep review with severity-scored findings. Different from `/qualia-verify` (whic
 
 ## General Review (default)
 
+```bash
+node ~/.claude/bin/qualia-ui.js banner review
+```
+
 Spawn parallel agents analyzing:
 
 1. **Code Quality** — Clean code, TypeScript strictness, naming, readability

package/skills/qualia-ship/SKILL.md

@@ -9,9 +9,8 @@ Full deployment pipeline with quality gates.
 
 ## Process
 
-```
-◆ QUALIA ► SHIPPING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js banner ship
 ```
 
 ### 1. Quality Gates
@@ -73,14 +72,12 @@ curl -s -o /dev/null -w "%{http_code}" {domain}/api/auth/callback
 
 ### 6. Report
 
-```
-◆ QUALIA ► SHIPPED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  URL      {production url}
-  Status   HTTP 200 ✓
-  Latency  {time}ms ✓
-  Auth     ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "URL: {production url}"
+node ~/.claude/bin/qualia-ui.js ok "Status: HTTP 200"
+node ~/.claude/bin/qualia-ui.js ok "Latency: {time}ms"
+node ~/.claude/bin/qualia-ui.js ok "Auth endpoint responds"
 ```
 
 ```bash
@@ -88,6 +85,6 @@ node ~/.claude/bin/state.js transition --to shipped --deployed-url {production u
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
-```
-  → Run: /qualia-handoff
+```bash
+node ~/.claude/bin/qualia-ui.js end "SHIPPED" "/qualia-handoff"
 ```