qualia-framework 5.5.0 → 5.8.0

package/skills/qualia-discuss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-discuss
-description: "Aggressive alignment interview before planning a phase — asks ONE question at a time, proposes a recommended answer with each, walks every branch of the decision tree until resolved. Updates .planning/CONTEXT.md inline as terms crystallize and writes ADRs for hard-to-reverse decisions. Output: .planning/phase-{N}-context.md (locked input the planner honors). Use BEFORE /qualia-plan for high-stakes phases (regulatory, auth, payments, multi-tenant, architectural forks), or when the user says 'discuss', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
+description: "Alignment interview. Two modes. PROJECT MODE (default, no args) is the non-technical kickoff before /qualia-new — 8 questions for demo projects, 14 for full projects, output is .planning/project-discovery.md. PHASE MODE (with N arg, e.g. /qualia-discuss 2) is the technical aggressive grilling before /qualia-plan N — one question at a time with recommended answer, output is .planning/phase-{N}-context.md. Trigger phrases: 'discuss', 'kickoff interview', 'grill me', 'stress test this plan', 'wait let's think about this one', 'I'm not sure how to approach this'."
 allowed-tools:
   - Bash
   - Read
@@ -11,24 +11,124 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# /qualia-discuss — Alignment Interview Before Planning
+# /qualia-discuss — Alignment Interview
+
+Two modes. The skill picks one based on whether an arg is passed.
+
+| Arg | Mode | When | Output |
+|-----|------|------|--------|
+| (none) | **PROJECT MODE** | Kickoff, before `/qualia-new`. Non-technical, audience-facing. | `.planning/project-discovery.md` |
+| `N` (e.g. `2`) | **PHASE MODE** | Before `/qualia-plan N`. Technical, aggressive grilling. | `.planning/phase-{N}-context.md` |
+
+## Mode routing
+
+```bash
+if [ -z "$1" ] || ! [[ "$1" =~ ^[0-9]+$ ]]; then
+  MODE="project"
+else
+  MODE="phase"
+  PHASE_N="$1"
+fi
+```
+
+If `MODE=project` → jump to **PROJECT MODE** section below.
+If `MODE=phase` → jump to **PHASE MODE** section below.
+
+---
+
+# PROJECT MODE — Kickoff Interview (no args)
+
+The non-technical conversation that runs at the very start of `/qualia-new`, BEFORE any roadmapping or research. Captures what the client wants, who it's for, brand voice, and constraints — in the client's own words.
+
+Hard rule: **never go technical here.** No "Should we use Supabase or Postgres?". The technical decisions happen in PHASE MODE, per phase. This mode is for the human shape of the project.
+
+## When PROJECT MODE runs
+
+- Triggered automatically by `/qualia-new` after Step 0 banner, BEFORE journey generation.
+- Or invoked manually (e.g. on a brownfield project that already has code but no discovery doc).
+
+## Process — PROJECT MODE
+
+### P1. Detect project type (or accept it from `/qualia-new`)
+
+If `/qualia-new` already asked the Demo vs Full gate, it passes the type in as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full` via env or arg. Otherwise ask first:
+
+- header: "Project shape"
+- question: "Is this a demo (single shippable milestone, sales conversation, ~1 to 2 weeks) or a full project (multi-milestone arc to Handoff)?"
+- options: ["Demo", "Full project"]
+
+This is the only fork. Demo runs §1-§8 of the discovery template. Full project runs all 14 questions.
+
+### P2. Banner and open
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner discuss-project
+```
+
+Say: **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast"** depending on type.
+
+### P3. One question at a time, copy from `templates/project-discovery.md`
+
+For each question §1..§8 (demo) or §1..§14 (full), ask in plain language. Format:
+
+```
+**Question {N}/{total}:** {question text from template}
+
+({one-line clarifier showing the kind of answer that helps)
+```
+
+NO "my recommendation" line in PROJECT MODE — this is open discovery, not technical grilling. Wait for the user's answer. Don't paraphrase back; capture verbatim. If the answer is too thin, ask one follow-up max, then move on.
+
+Allowed `[Enter]` defaults exist on §2, §3, §5 only (inferred from project type). All other questions require an answer.
+
+### P4. Write `.planning/project-discovery.md`
+
+Fill the template at `~/.claude/qualia-templates/project-discovery.md` with the user's verbatim answers. Set frontmatter `project_type` and `discovered_at`.
+
+### P5. Hand back to `/qualia-new`
+
+```bash
+git add .planning/project-discovery.md
+git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
+node ~/.claude/bin/qualia-ui.js ok "Discovery captured — back to /qualia-new"
+```
+
+If invoked standalone (not from `/qualia-new`), end with:
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"
+```
+
+If invoked inline by `/qualia-new`, return control silently — `/qualia-new` continues from Step 2.
+
+## Rules — PROJECT MODE
+
+1. **Never technical.** No stack questions, no architecture forks. Those are PHASE MODE.
+2. **Verbatim capture.** Don't translate the client's words into framework-speak. The client's exact phrasing is the input to PRODUCT.md voice and CONTEXT.md glossary.
+3. **One question, one answer, move on.** No batching. No drilling deeper than one follow-up.
+4. **Demo stops at §8.** Don't ask demo clients milestone-arc questions — they don't have an arc yet.
+5. **Anti-references are required.** If the user can't name three sites this should NOT look like, the design will end up generic. Push back once, then capture whatever they give you.
+
+---
+
+# PHASE MODE — Pre-Plan Grilling (`/qualia-discuss N`)
 
 Surface and lock the decisions, trade-offs, and constraints that must inform a phase plan. Output: `.planning/phase-{N}-context.md` (locked input). Side effects: `.planning/CONTEXT.md` gains new terms; `.planning/decisions/` may gain ADRs.
 
-## When to use
+## When PHASE MODE runs
 - Regulated domains (legal, medical, financial) where wrong choices have legal cost
 - Phases with architectural forks ("auth via middleware or RLS?")
 - Phases with external dependencies you want to lock first
 - User says "wait, let's think about this one"
 
-## The four grilling rules
+## The four grilling rules (PHASE MODE)
 
 1. **One question at a time.** Wait for the answer before asking the next. Never batch.
 2. **Propose your recommended answer first.** Format every question as `Question / Recommendation / Trade-offs`. The user accepts, edits, or rejects — way faster than open interview.
 3. **If the codebase can answer, explore instead of asking.** Don't make the user say what `git grep` could tell you.
 4. **Walk every branch.** When the user picks A over B, the next question is the one that A makes load-bearing. Resolve dependencies one-by-one until the tree is fully traversed.
 
-## Process
+## Process — PHASE MODE
 
 ### 1. Load substrate
 
@@ -108,7 +208,7 @@ git commit -m "docs(phase-{N}): lock context, glossary terms, ADRs"
 node ~/.claude/bin/qualia-ui.js end "PHASE {N} CONTEXT LOCKED" "/qualia-plan {N}"
 ```
 
-## Rules
+## Rules — PHASE MODE
 
 1. **One session, one phase.** Don't discuss phases 1 and 2 in the same invocation.
 2. **Locked decisions are NON-NEGOTIABLE.** The planner honors them exactly. Don't lock what you're unsure of — defer it instead.

package/skills/qualia-feature/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: qualia-feature
+description: "Auto-scoped single feature build. Picks inline (≤1 trivial file, no spawn) or fresh builder spawn (1-5 logic files, atomic commit) automatically from the task description. Refuses and routes to /qualia-plan for 5+ files or full phases. Replaces /qualia-quick and /qualia-task. Flags: --force-spawn forces a builder, --force-inline forces inline. Trigger phrases: 'build this one thing', 'add a component', 'implement this feature', 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak', 'qualia-feature'."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+
+# /qualia-feature — Auto-scoped Single Feature
+
+One command for everything between a typo and a phase. Auto-detects scope from the task description and picks the right execution path. No more guessing whether to use `/qualia-quick` or `/qualia-task`.
+
+## Usage
+
+`/qualia-feature` — describe interactively
+`/qualia-feature {description}` — run with description directly
+`/qualia-feature --force-spawn {description}` — force a fresh builder spawn (even if auto would inline)
+`/qualia-feature --force-inline {description}` — force inline path (even if auto would spawn)
+
+## When to use
+
+- One feature outside a planned phase
+- A bug fix, typo, config tweak, or one-line change
+- A 1-5 file feature, component, API route, or integration
+- A refactor of a single module
+
+## When NOT to use
+
+- 5+ files or multiple subsystems touched → `/qualia-plan`
+- Part of a planned phase → `/qualia-build`
+- Investigating a symptom you can't name yet → `/qualia-debug`
+- Optimization or polish pass → `/qualia-optimize` or `/qualia-polish`
+
+## Process
+
+### 1. Capture description
+
+If invoked without args, ask: **"What do you want to build?"**
+
+Wait for free-text answer. Don't paraphrase back. Capture the user's exact phrasing — it feeds both the auto-scope classifier and the eventual commit message.
+
+### 2. Auto-detect scope
+
+Classify the description into one of three buckets:
+
+| Bucket | Heuristic | Path |
+|--------|-----------|------|
+| **inline** | Typo, comment edit, 1-line config change, single-word rename, dead-code removal, copy edit, link fix, version bump, single emoji/icon swap | Direct work, no spawn |
+| **spawn** | Add a component, add an API route, add a small migration + UI, implement a single feature, fix a non-trivial bug, refactor a module under 5 files | Fresh builder spawn |
+| **refuse** | "Build the dashboard", "implement payments", "ship the auth system", "add a checkout flow", any description that names a multi-step workflow or 5+ subsystems | Refuse, route to `/qualia-plan` |
+
+**Inline signals** (any one is sufficient):
+- "fix typo", "fix the comment", "rename X to Y", "remove unused", "update copy", "change the link", "bump version"
+- Description fits in one short sentence and names one specific micro-change
+- The action is reversible by a single `git revert`
+
+**Spawn signals** (any one is sufficient):
+- "add a", "implement", "build", "create" + a single noun (component, route, page, table, form, modal, hook, util, migration)
+- Description names a single feature with multiple touch points (e.g. "add a feedback form" → migration + API + UI = 3-4 files, but still one cohesive thing)
+- The work needs a fresh context to avoid contaminating the current conversation
+
+**Refuse signals** (any one is sufficient):
+- "build the X system", "implement the entire Y", "add complete Z support"
+- Description names a multi-milestone capability (auth, payments, search, admin panel) without a tight slice
+- Estimated touch ≥ 5 files OR ≥ 1 day
+
+### 3. Announce the route + escape hatch
+
+Show the user what was detected. Always offer the escape hatch:
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner feature
+node ~/.claude/bin/qualia-ui.js info "Detected scope: {inline|spawn|refuse}"
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line rationale}"
+```
+
+Then:
+
+- header: "Scope detected"
+- question: "Auto-scope says {bucket}. Proceed, or override?"
+- options:
+  - "Proceed with {bucket}"
+  - "Force inline" (only shown if bucket != inline)
+  - "Force spawn" (only shown if bucket != spawn)
+  - "Route to /qualia-plan" (only shown if bucket != refuse)
+  - "Re-describe"
+
+If `--force-spawn` or `--force-inline` was passed on the command line, skip this gate entirely and execute the forced path.
+
+### 4. Execute the inline path
+
+For inline scope:
+
+1. Read the file(s) that need to change (one read per file, no spawning).
+2. Make the edit directly using Edit/Write.
+3. Run `npx tsc --noEmit` if TypeScript and the change touches typed code; skip otherwise.
+4. Atomic commit with a clear conventional-commit message:
+
+```bash
+git add {specific files}
+git commit -m "fix: {description}"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description}" --tasks-done 1
+```
+
+6. End with:
+
+```bash
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (inline)"
+```
+
+### 5. Execute the spawn path
+
+For spawn scope:
+
+1. Build a quick task spec (don't write to a file, just confirm with user):
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
+node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify, comma list}"
+node ~/.claude/bin/qualia-ui.js info "Done: {observable acceptance criteria, 1-3 bullets}"
+```
+
+Ask: **"Good to build?"** Wait for confirmation.
+
+2. Spawn the builder:
+
+```
+Agent(subagent_type="qualia-builder", description="Feature: {short title}")
+  prompt: |
+    Read your role: @~/.claude/agents/builder.md
+
+    <task>
+    {task description verbatim from user}
+    </task>
+
+    <files>
+    {files to create/modify}
+    </files>
+
+    <acceptance_criteria>
+    {1-3 observable bullets}
+    </acceptance_criteria>
+
+    <context>
+    Read .planning/PROJECT.md if it exists.
+    Read .planning/CONTEXT.md if it exists (domain glossary).
+    Follow rules/security.md, rules/frontend.md, rules/deployment.md as applicable.
+    Atomic commit. Run npx tsc --noEmit before commit.
+    </context>
+```
+
+3. After the builder returns, verify:
+   - `npx tsc --noEmit` exits 0 (rerun the builder up to 2x if it failed self-verify, per the v5.5.0 auto-heal pattern).
+   - Quick smoke test if applicable.
+   - Confirm the commit was made: `git log --oneline -1` shows the feature.
+
+4. Report:
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "Feature: {description}"
+node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
+node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
+node ~/.claude/bin/qualia-ui.js end "FEATURE SHIPPED (spawn)"
+```
+
+5. Record in state:
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{description}" --tasks-done 1
+```
+
+### 6. Execute the refuse path
+
+For refuse scope, do NOT build. Explain why and route:
+
+```bash
+node ~/.claude/bin/qualia-ui.js warn "This is too big for /qualia-feature (5+ files or multi-step workflow)."
+node ~/.claude/bin/qualia-ui.js info "Reason: {one-line — e.g. 'description names the entire auth system, not a slice'}"
+node ~/.claude/bin/qualia-ui.js end "ROUTED" "/qualia-plan"
+```
+
+If the user is sure it's small and the classifier got it wrong, they can re-invoke with `--force-spawn`.
+
+## Auto-scope examples
+
+| Description | Detected | Why |
+|-------------|----------|-----|
+| "fix the typo in the hero copy" | inline | typo + 1 file |
+| "rename `userId` to `user_id` in auth.ts" | inline | rename in 1 file |
+| "bump next from 16.0.3 to 16.0.4" | inline | version bump, 1 file |
+| "add a Feedback button that opens a modal" | spawn | single feature, 2-4 files |
+| "add a GET /api/health route returning ok" | spawn | 1 route, but worth a fresh context for test pass |
+| "implement Stripe subscription checkout" | refuse | multi-file + webhooks + admin = phase |
+| "build the dashboard" | refuse | names a multi-page surface |
+| "add the admin user-management page" | refuse | usually 5+ files (table, modals, API, RLS, types) |
+
+## Rules
+
+1. **Auto-scope is confident by default, with two escape hatches.** Trust the classifier; use `--force-spawn` or `--force-inline` when it guesses wrong. Don't waste a question on "which path?" — propose and let the user override.
+2. **Inline is genuinely fresh-context-free.** No subagent spawn for inline work — the current Claude does it directly. That's the whole speed advantage over `/qualia-task`.
+3. **Spawn means atomic.** One feature, one commit, one acceptance criteria block. No grab-bag commits that touch four unrelated things.
+4. **Refuse means refuse.** When a description is phase-sized, route to `/qualia-plan`, don't try to fit it in. The auto-classifier is the gate that protects the work from sprawling.
+5. **STATE.md via state.js only.** Never edit STATE.md or tracking.json by hand. Both paths record through `state.js transition`.
+6. **Follow rules/* on every path.** Security, frontend, deployment rules apply equally to inline and spawn. Read-before-write is non-negotiable.

package/skills/qualia-milestone/SKILL.md

@@ -38,6 +38,77 @@ node ~/.claude/bin/state.js check
 
 If either fires (without `--force`), stop and show the error. The user must verify remaining phases first (or add `--force` for explicit bypass on a preview/demo milestone).
 
+### 1b. Demo-Extension Branch (v5.6)
+
+Detect if this is a demo project closing its only milestone:
+
+```bash
+PROJECT_TYPE=$(grep -E "^project_type:" .planning/PROJECT.md | head -1 | awk '{print $2}')
+MILESTONE_COUNT=$(grep -cE "^## Milestone " .planning/JOURNEY.md 2>/dev/null || echo 0)
+```
+
+If `PROJECT_TYPE=demo` AND `MILESTONE_COUNT=1`, the demo's one milestone is closing — there is no "next milestone" in the file. Ask the conversion question:
+
+- header: "Demo shipped — what next?"
+- question: "The demo milestone is done. Did the client sign? If yes, extend this into a full project (regenerate JOURNEY.md as a multi-milestone arc to Handoff). If no, this project closes here."
+- options:
+  - "Client signed — extend to full project"
+  - "Demo only — close here, project is done"
+  - "Pause" — don't close yet, decide later
+
+**If "Client signed — extend to full project":**
+
+1. Update `.planning/PROJECT.md` frontmatter: `project_type: full`.
+2. Run a brief discovery top-up — invoke `/qualia-discuss` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
+3. Spawn the roadmapper in `extend-to-full` mode (see prompt below). It reads the existing single milestone (now M1), the updated discovery, and produces a full JOURNEY.md with M2..M{N-1} sketches plus the Handoff milestone.
+4. Then proceed with the standard close-milestone flow (Steps 2-9) — M1 closes, M2 opens, the user is asked to continue.
+
+Roadmapper prompt for the extension:
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<mode>extend-demo-to-full</mode>
+<existing_journey>.planning/JOURNEY.md</existing_journey>
+<discovery>.planning/project-discovery.md</discovery>
+
+<task>
+The existing JOURNEY.md has 1 milestone (the demo, now M1 and shipped). Extend it
+into a 2-5 milestone arc to Handoff:
+
+- Keep M1 exactly as-is (it shipped).
+- Add M2..M{N-1} based on §9 of project-discovery.md (the milestone-arc question
+  the user answered when converting from demo).
+- Append a Handoff milestone (fixed 4 phases: Polish, Content + SEO, Final QA,
+  Handoff).
+- Update REQUIREMENTS.md to add REQ-IDs for the new milestones.
+- Do NOT regenerate ROADMAP.md here — that happens in Step 7 of /qualia-milestone
+  when M2 opens.
+
+Mark M2..M{N-1} as sketched, not fully detailed. The user gets full detail per
+milestone when /qualia-milestone opens each one.
+</task>
+", subagent_type=\"qualia-roadmapper\", description=\"Extend demo to full project\")
+```
+
+**If "Demo only — close here":** treat the demo as a shipped-and-done project. Skip Steps 2-9 of the normal flow. Just run:
+
+```bash
+node ~/.claude/bin/state.js close-milestone --force
+node ~/.claude/bin/qualia-ui.js end "DEMO SHIPPED" "/qualia-report"
+```
+
+In `--auto` mode, inline-invoke `/qualia-report` and stop.
+
+**If "Pause":** stop, show:
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Demo milestone left open. Run /qualia-milestone again when you decide."
+```
+
+If the demo branch did NOT fire (full project, or demo with multiple milestones already after extension), continue to Step 2.
+
 ### 2. Banner + Confirm
 
 ```bash
@@ -206,4 +277,5 @@ node ~/.claude/bin/qualia-ui.js end "M{N} CLOSED · M{N+1} OPEN" "/qualia-plan 1
 3. **Archive, don't delete.** Old phase work stays accessible via `.planning/archive/`.
 4. **New milestone = fresh phase numbering.** First phase of the new milestone is Phase 1, not Phase {N+1}.
 5. **ERP sync aware.** tracking.json milestones[] gets a summary entry on close — the ERP reads this to render the tree.
-6. **Handoff is the final milestone.** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+6. **Handoff is the final milestone (full projects).** If the current milestone IS Handoff, there is no "next" — route to `/qualia-report` and the project is done.
+7. **Demo closes via the demo-extension branch (Step 1b).** A demo's single milestone closing triggers the "client signed?" question. The framework never silently auto-extends a demo without asking — the conversion is a real business decision.

package/skills/qualia-new/SKILL.md

@@ -58,27 +58,41 @@ test -d .git && echo "HAS_GIT"
 test -f .planning/codebase/README.md && echo "ALREADY_MAPPED"
 ```
 
-If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 1.
+If existing code is detected AND not already mapped, ask the user whether to run `/qualia-map` inline first. If yes, invoke the `qualia-map` skill inline, wait for completion, then continue to Step 0.6.
 
-### Step 1. Deep Questioning
+### Step 0.6. Project Type Gate (Demo vs Full)
 
-Load the questioning methodology:
+The single most important fork in the workflow. Demo and Full produce different journeys, different research depth, different milestone counts.
 
-```bash
-cat ~/.claude/qualia-references/questioning.md 2>/dev/null
-```
+- header: "Project shape"
+- question: "Is this a demo (single shippable milestone, sales conversation) or a full project (multi-milestone arc to Handoff)?"
+- options:
+  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign.
+  - "Full project" — the full multi-milestone arc to Handoff. 2-5 milestones planned upfront.
+
+Store the answer as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full`. It drives Steps 1, 8, and 10.
 
-Follow the thread. Challenge vagueness. Make abstract concrete. Check the 4-item mental checklist (what, why, who, done).
+**Demo design philosophy is non-negotiable:** real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, NEVER from skipping design quality or mocking the backend.
 
-Use `AskUserQuestion` for forks with 2-4 concrete interpretations. Use free text when you want them to think freely.
+### Step 1. Mandatory Discovery Interview (PROJECT MODE)
 
-**Decision gate** — when you could write a clear PROJECT.md:
+Invoke `/qualia-discuss` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the discuss skill skips the type question.
+
+This step REPLACES the old free-form "deep questioning" loop. The discuss skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
+
+```bash
+# Inline-invoke qualia-discuss in PROJECT MODE
+# (no phase number arg = PROJECT MODE; PROJECT_TYPE env tells it which question set)
+PROJECT_TYPE=$PROJECT_TYPE qualia-discuss
+```
+
+After the interview returns, `.planning/project-discovery.md` exists with the user's answers. Read it. Confirm understanding:
 
 - header: "Ready?"
-- question: "I understand what you're building. Create PROJECT.md and move forward?"
-- options: ["Create PROJECT.md", "Keep exploring"]
+- question: "I have what I need to write PROJECT.md and move forward. Continue?"
+- options: ["Continue", "More questions"]
 
-Loop until "Create PROJECT.md".
+If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
 
 ### Step 2. Detect Project Type
 
@@ -216,11 +230,16 @@ node ~/.claude/bin/qualia-ui.js banner research
 mkdir -p .planning/research
 ```
 
-Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
+**Research scope branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): pass `<scope>quick</scope>` to all 4 researchers AND the synthesizer. Each researcher gets a 3-call budget instead of 8. The synthesizer produces a single-milestone suggestion (no Handoff, no multi-milestone arc). Total research time drops roughly 3x with no loss of correctness on the demo path — the depth was wasted when there's only one milestone to ship.
+- **Full project** (`PROJECT_TYPE=full`): standard scope, 8-call budget per researcher, full milestone-arc synthesis.
 
-Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope. See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates.
+Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."** (demo: append "— quick scope").
 
-**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template.
+Spawn 4 researchers in parallel (single message, 4 Agent tool calls). See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates. Include `<scope>quick</scope>` in each prompt when `PROJECT_TYPE=demo`.
+
+**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template. Include `<scope>quick</scope>` when `PROJECT_TYPE=demo`.
 
 **Commit:**
 ```bash
@@ -258,7 +277,12 @@ 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. 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. See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
+**Roadmapper output branches on `PROJECT_TYPE`:**
+
+- **Demo** (`PROJECT_TYPE=demo`): roadmapper produces a 1-milestone JOURNEY.md (the demo milestone, 2-4 phases) plus a matching REQUIREMENTS.md and a fully-detailed ROADMAP.md. No "Handoff" milestone is appended — the demo is its own complete artifact. The journey-tree at Step 11 shows a single rung; the "extend to full project" branch is handled later by `/qualia-milestone` if the client signs.
+- **Full project** (`PROJECT_TYPE=full`): roadmapper produces the standard 2-5 milestone arc ending in Handoff. Milestone 1 fully detailed, M2..M{N-1} sketched (unless `--full-detail`).
+
+Spawn the roadmapper with `<project_type>$PROJECT_TYPE</project_type>` in the prompt. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` so the roadmapper writes complete phase detail for ALL milestones (full project only; demo always has full detail because there's only one milestone). See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
 ### Step 11. Present the Journey (single view)
 
@@ -366,12 +390,15 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 ## Rules
 
-1. **Research runs automatically.** No permission ask. Only `--quick` skips it. This is a v4 invariant.
-2. **The journey includes Handoff.** Every project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
-3. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
-4. **Milestone count: 2-5.** Hard floor 2, hard ceiling 5. Bigger projects defer remainder to post-handoff v2.
-5. **Milestone 1 is fully detailed.** M2..M{N-1} are sketched. Detail fills in when each milestone opens.
-6. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
-7. **Inline skill invocation.** When Step 0.5 offers `/qualia-map`, invoke it inline — don't exit.
-8. **CONTEXT.md is mandatory (v5.0).** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from questioning answers. Loaded by every road agent. Kept terse.
-9. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.
+1. **Project type is the first fork.** Step 0.6 asks Demo vs Full Project. Every downstream step branches on this. Don't skip it, don't infer it.
+2. **Discovery interview is mandatory (v5.6).** Step 1 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+3. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
+4. **Demo design philosophy is non-negotiable.** Real backend always, DESIGN.md mandatory, slop-detect hard-block. Speed comes from skipping multi-milestone planning, never from skipping design quality or mocking the backend. A demo that uses mock data is not a Qualia demo.
+5. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
+6. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
+7. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
+8. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
+9. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
+10. **Inline skill invocation.** When Step 0.5 offers `/qualia-map` or Step 1 invokes `/qualia-discuss`, invoke it inline — don't exit.
+11. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
+12. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-optimize/SKILL.md

@@ -146,7 +146,7 @@ Collect all 3 proposals. Present to the user as a side-by-side table:
 | 2 | ... | ... | ... | ... |
 | 3 | ... | ... | ... | ... |
 
-User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue (mirrors `/qualia-prd` flow).
+User picks `1`, `2`, `3`, or `hybrid` (with notes on which elements from which proposals to combine). The synthesizer then writes a "Refactor RFC" to `.planning/REFACTOR-{slug}.md` and optionally opens a GH issue.
 
 **Why parallel + radically different**: a single deepening proposal anchors on the first idea the LLM has. Three parallel proposals with diverse design constraints surface trade-offs the user can see at a glance — and the human's "taste" dominates the choice rather than the agent's first instinct. Empirically (Matt Pocock + Qualia internal testing) this produces dramatically better refactor RFCs than a single-pass proposal.
 

package/skills/{qualia-polish-loop → qualia-polish}/REFERENCE.md

@@ -1,4 +1,4 @@
-# REFERENCE — /qualia-polish-loop
+# REFERENCE — /qualia-polish --loop
 
 Verbatim agent prompts and operational details. Loaded on demand by SKILL.md, not carried in the system prompt. Per progressive-disclosure discipline (Matt Pocock): the agent reads SKILL.md first, then this file when it needs the spawn templates.
 
@@ -104,7 +104,7 @@ Agent({
 Role: @~/.claude/agents/builder.md
 
 <phase_context>
-You are inside /qualia-polish-loop iteration {N}. The vision evaluator scored
+You are inside /qualia-polish --loop iteration {N}. The vision evaluator scored
 the {dim} dimension at {score}. Your single task: fix that one dimension.
 
 <design>
@@ -133,7 +133,7 @@ the {dim} dimension at {score}. Your single task: fix that one dimension.
 2. Make the MINIMUM edit to fix this one dimension. Do not refactor. Do not change logic. Do not touch state management. Do not change copy unless this is a microcopy issue.
 3. Use design tokens from DESIGN.md. Do not invent new color values, font names, or spacing.
 4. After the edit, commit via the orchestrator (slop-detect-gated):
-     node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
+     node ~/.claude/skills/qualia-polish/scripts/loop.mjs commit-fix --state {STATE} --file {file} --slug {dim}-{short-keyword}
    If slop-detect blocks (exit 2), READ the slop output and re-edit. If you cannot fix without violating slop-detect, return BLOCKED with the conflict.
 5. Return DONE with: file modified, lines changed, slop-detect: pass, commit: {sha}.
 </task>
@@ -260,6 +260,6 @@ This is intentional. Most visual regressions Fawzi has documented in `/insights`
 
 - Cross-browser rendering checks (Firefox / WebKit) — Chromium-only, per `qualia-polish` Stage 4 precedent
 - Accessibility audits beyond what the rubric scores — use `/qualia-polish` Stage 3 (Lighthouse + axe) for that
-- Performance regressions — use `/qualia-polish-loop` only after Lighthouse score passes
+- Performance regressions — use `/qualia-polish --loop` only after Lighthouse score passes
 - Reference-image-only mode (compare to a target screenshot without a brief) — currently the brief is required; reference is supplemental
-- Multi-page sweeps — one URL per invocation; chain `/qualia-polish-loop` per route for site-wide passes
+- Multi-page sweeps — one URL per invocation; chain `/qualia-polish --loop` per route for site-wide passes