qualia-framework 4.0.0 → 4.0.5

package/hooks/session-start.js

@@ -52,6 +52,14 @@ function getNextCommand() {
   }
 }
 
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
 function fallbackText() {
   // If qualia-ui.js is missing, emit plain text. Keeps the session informative
   // even on a broken install.
@@ -121,14 +129,6 @@ try {
   // Deliberately silent — hook must never fail
 }
 
-function readConfig() {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(HOME, ".claude", ".qualia-config.json"), "utf8"));
-  } catch {
-    return {};
-  }
-}
-
 function _trace(hookName, result, extra) {
   try {
     const traceDir = path.join(os.homedir(), ".claude", ".qualia-traces");

package/package.json

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

package/rules/frontend.md

@@ -109,18 +109,10 @@ These are Qualia brand standards — mandatory for every frontend component. Not
 If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
 Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
 
-## Impeccable Design Skills (global)
-- `/polish` — Final detail pass before shipping
-- `/bolder` — Amplify safe/boring designs
-- `/design-quieter` — Tone down overly aggressive designs
-- `/animate` — Add purposeful micro-interactions
-- `/colorize` — Inject strategic color into monochrome UIs
-- `/clarify` — Fix unclear UX copy, labels, error messages
-- `/critique` — Design director-level review
-- `/distill` — Strip unnecessary complexity
-- `/delight` — Add memorable touches and personality
-- `/harden` — Edge cases, overflow, i18n robustness
-- `/responsive` — Cross-device responsive adaptation
+## Qualia design commands
+- `/qualia-design` — One-shot design transformation (critique + fix + polish + responsive + harden)
+- `/qualia-polish` — Final detail pass before shipping (run after all phases verified)
+- `/qualia-review` — Scored production audit
 
 ### Recommended workflow
-1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship
+1. Build feature → 2. `/qualia-design` → 3. `/qualia-polish` → ship

package/skills/qualia/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia
 description: "Smart router — reads project state (state.js), classifies the situation mechanically, returns the exact next command. Use whenever you type /qualia, 'what next', 'next', 'what now', 'what should I do next', 'what command now'. For deeper 'I don't understand what's going on' / 'something feels off' situations, use /qualia-idk instead — that one actually scans the planning folder and codebase to diagnose the confusion."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
 ---
 
 # /qualia — What's Next?

package/skills/qualia-build/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-build
 description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-build — Build a Phase

package/skills/qualia-debug/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-debug
 description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-debug — Structured Debugging

package/skills/qualia-design/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-design
 description: "One-shot design transformation — critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional. Trigger on 'fix the design', 'make it look better', 'redesign', 'design pass', 'make it modern', 'it looks ugly', 'fix the UI'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-design — One-Shot Design Transformation
@@ -87,7 +95,7 @@ git commit -m "style: design transformation"
   - {key change 2}
   - {key change 3}
 
-  Fine-tune: /bolder, /design-quieter, /colorize, /animate
+  Next: /qualia-polish (final pass) · /qualia-review (scored audit)
 ```
 
 ## Rules

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-discuss
 description: "Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
 ---
 
 # /qualia-discuss — Phase Context Capture

package/skills/qualia-handoff/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: qualia-handoff
 description: "Client delivery — produces the 4 mandatory Handoff deliverables (production URL, documentation, client assets archive, ERP finalization). Triggered at the end of the Handoff milestone."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-handoff — Client Delivery

package/skills/qualia-help/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: qualia-help
 description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+allowed-tools:
+  - Bash
+  - Read
 ---
 
 # /qualia-help — Framework Reference
@@ -12,14 +15,25 @@ Opens a Qualia-themed HTML reference guide in your default browser.
 ### 1. Generate the HTML
 
 ```bash
-# Read the template and inject the current version
-VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+# Read the template and inject the current version.
+# Prefer .qualia-config.json; fall back to the framework package.json; last resort is the
+# literal string "latest" so the UI never lies about a specific version.
+VERSION=$(node -e "
+  const fs = require('fs'), path = require('path'), os = require('os');
+  const cfg = path.join(os.homedir(), '.claude', '.qualia-config.json');
+  const pkg = path.join(os.homedir(), '.claude', 'qualia-framework', 'package.json');
+  try { const v = JSON.parse(fs.readFileSync(cfg,'utf8')).version; if (v) { console.log(v); process.exit(0); } } catch {}
+  try { const v = JSON.parse(fs.readFileSync(pkg,'utf8')).version; if (v) { console.log('v'+v); process.exit(0); } } catch {}
+  console.log('latest');
+" 2>/dev/null || echo "latest")
 TEMPLATE="$HOME/.claude/qualia-templates/help.html"
 OUTPUT="/tmp/qualia-help.html"
 
-# If template doesn't exist, check the framework install
+# If template doesn't exist in the user home, check the installed framework copy.
 if [ ! -f "$TEMPLATE" ]; then
-  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+  for CANDIDATE in "$HOME/.claude/qualia-framework/templates/help.html"; do
+    if [ -f "$CANDIDATE" ]; then TEMPLATE="$CANDIDATE"; break; fi
+  done
 fi
 ```
 

package/skills/qualia-idk/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-idk
 description: "Diagnostic intelligence for 'I don't know what's going on.' Runs two isolated scans (.planning/ vs codebase), cross-references against the user's confusion, then explains the situation in plain language with a concrete recommended next step. Use whenever the user says 'I don't know', 'something feels off', 'not sure what to do', 'am I doing this right', 'what's happening', 'help me understand'."
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-idk — "I Don't Know What's Going On"

package/skills/qualia-learn/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-learn
 description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions. Trigger on 'remember this', 'save this pattern', 'learned something', 'note for future', 'client prefers', 'qualia-learn'."
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
 ---
 
 # /qualia-learn — Save Knowledge

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-map
 description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-map — Codebase Mapping (Brownfield)

package/skills/qualia-milestone/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: qualia-milestone
 description: "Close the current milestone and open the next one — loads the next milestone's scope from JOURNEY.md (no ad-hoc naming). Archives artifacts, marks requirements Complete, regenerates ROADMAP.md for the next milestone."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Agent
 ---
 
 # /qualia-milestone — Milestone Closeout

package/skills/qualia-new/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: qualia-new
 description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, JOURNEY.md with all milestones to handoff, single approval gate, optional auto-chain into building. Use when starting any new client project."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
 ---
 
 # /qualia-new — New Project (Full Journey)
@@ -9,8 +21,9 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 
 ## Flags
 
-- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible)
+- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible). **Progressive detail**: Milestone 1 gets full phase detail; M2..M{N-1} get sketched (names + one-line goals). Full detail for later milestones is filled in by `/qualia-milestone` when each one opens. This matches how real projects unfold — M1's discoveries reshape M3's plan, so deep-planning M3 now tends to waste effort.
 - `/qualia-new --auto` — full-journey flow, then auto-chains into `/qualia-plan 1 → /qualia-build → /qualia-verify` for Milestone 1
+- `/qualia-new --full-detail` — ALL milestones get full phase-level detail upfront (success criteria per phase for every milestone, not just M1). Use when the client wants a fully-committed plan at kickoff. Trade-off: later milestones often need revision as M1 ships. Combinable with `--auto`.
 - `/qualia-new --quick` — 4-phase flat wizard for trivial projects (landing pages, prototypes). Skips research and journey mapping.
 
 ## The Shift From Previous Versions
@@ -204,7 +217,7 @@ Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
 ### Step 9. Feature Scoping (Multi-Milestone)
 
-Read `.planning/research/FEATURES.md` and present the feature landscape. Unlike v3, features are scoped **to milestones**, not just to v1/v2.
+Read `.planning/research/FEATURES.md` and present the feature landscape. Features are scoped **to milestones** — you'll decide per-feature which milestone owns it.
 
 For each category, use AskUserQuestion:
 
@@ -226,7 +239,7 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate:
+Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones.
 
 ```
 Agent(prompt="
@@ -236,7 +249,7 @@ Read your role: @~/.claude/agents/roadmapper.md
 Create the FULL JOURNEY for this project:
   - .planning/JOURNEY.md — all milestones (2-5 including Handoff) with exit criteria
   - .planning/REQUIREMENTS.md — requirements grouped by milestone
-  - .planning/ROADMAP.md — Milestone 1's phase detail only (ready for /qualia-plan 1)
+  - .planning/ROADMAP.md — Milestone 1's phase detail (and ALL milestones if full_detail=true)
 
 User-scoped v1 features:
 {list of features selected in Step 9, grouped by category}
@@ -244,6 +257,10 @@ User-scoped v1 features:
 Template type: {template_type from config.json}
 If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
 
+<full_detail>{true if --full-detail, else false}</full_detail>
+  - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
+  - true: every milestone (M1..Handoff) gets full phase-level detail in ROADMAP.md upfront. Useful when the client wants a fully-committed plan at kickoff.
+
 The final milestone MUST be named 'Handoff' with the fixed 4 phases
 (Polish, Content + SEO, Final QA, Handoff). Do not omit it.
 
@@ -319,6 +336,16 @@ git add .planning/JOURNEY.md .planning/REQUIREMENTS.md .planning/ROADMAP.md .pla
 git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestones)"
 ```
 
+**After approval, show the progressive-detail reminder explicitly:**
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Milestone 1 is fully planned now."
+node ~/.claude/bin/qualia-ui.js info "Milestones 2..{N-1} are sketched (names + one-line goals)."
+node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone gets written when /qualia-milestone opens it."
+```
+
+(Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
+
 ### Step 13. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.

package/skills/qualia-optimize/SKILL.md

@@ -1,6 +1,14 @@
 ---
 name: qualia-optimize
 description: "Deep optimization pass — reads .planning/ AND codebase to find performance, design, UI, backend, and frontend issues. Spawns parallel specialist agents. Use this skill whenever the user says 'optimize', 'optimization pass', 'find issues', 'qualia-optimize', 'deep optimize', 'performance audit', 'design alignment check', 'speed up', 'slow', 'bundle size', or wants a comprehensive quality sweep. Supports --perf, --ui, --backend, --alignment, --fix flags."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # Qualia Optimize — Deep Codebase + Planning Optimization

package/skills/qualia-pause/SKILL.md

@@ -1,6 +1,11 @@
 ---
 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'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
 ---
 
 # /qualia-pause — Session Handoff

package/skills/qualia-plan/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: qualia-plan
 description: "Plan the current phase — spawns planner, validates with plan-checker in a revision loop (max 3), optionally runs discuss/research first. Use when ready to plan a phase."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - TaskCreate
+  - TaskUpdate
 ---
 
 # /qualia-plan — Plan a Phase
@@ -196,7 +206,7 @@ When invoked as `/qualia-plan {N} --gaps`, the planner is in gap-closure mode:
 2. For each FAIL item, create a targeted fix task:
    - **Files:** specific files that failed verification
    - **Action:** specific fix (not "fix auth" — "add session persistence check in src/lib/auth.ts signIn function")
-   - **Done when:** the exact verification criterion that previously failed, restated
+   - **Acceptance Criteria:** the exact verification criterion that previously failed, restated as an observable behavior
 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

@@ -1,6 +1,14 @@
 ---
 name: qualia-polish
 description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
 ---
 
 # /qualia-polish — Design Pass

package/skills/qualia-quick/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: qualia-quick
 description: "Fast path for small tasks — bug fixes, tweaks, hot fixes. Skips full phase planning. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'quick edit', 'small bug'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
 ---
 
 # /qualia-quick — Quick Task