qualia-framework 5.9.0 → 5.9.1

package/package.json

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

package/skills/qualia-discuss/SKILL.md

@@ -51,10 +51,12 @@ Hard rule: **never go technical here.** No "Should we use Supabase or Postgres?"
 
 ### 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:
+If `/qualia-new` already asked the Demo vs Full gate (it does this as Step 1, the literal first question), it passes the type in as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full` via env or arg — **skip the gate, do not re-ask.**
+
+Only ask the gate yourself when invoked standalone (not via `/qualia-new`). When you do, use **AskUserQuestion** (interactive UI — never plain text):
 
 - 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)?"
+- question: "Is this a demo (single shippable milestone, sales conversation) 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.

package/skills/qualia-new/SKILL.md

@@ -46,11 +46,33 @@ Initialize a project with the **entire arc mapped from kickoff to handoff**. All
 node ~/.claude/bin/qualia-ui.js banner new
 ```
 
-Then say: **"Let's build something. Tell me what you want to make."**
+Banner only. Do NOT ask anything yet. The next thing the user sees is the project-shape gate — not a free-text "tell me what to build". Shape gate first, content second, because the shape drives the question set.
 
-Wait for free-text answer. Do NOT use AskUserQuestion here — let them talk naturally.
+### Step 1. Project Type Gate (Demo vs Full vs Quick) — FIRST QUESTION
 
-### Step 0.5. Brownfield Check
+The single most important fork. Demo and Full produce different journeys, different research depth, different milestone counts. This is the literal first interaction with the user.
+
+Use **AskUserQuestion** (interactive UI — never a plain-text prompt):
+
+- header: "Project shape"
+- question: "What kind of project is this? Pick one — it drives everything else."
+- options:
+  - "Demo" — one shippable milestone, real backend, no mocks. Built to win a client conversation, extensible via `/qualia-milestone` if they sign. 8-question discovery.
+  - "Full project" — the multi-milestone arc to Handoff. 2-5 milestones planned upfront. 14-question discovery.
+  - "Quick prototype" — landing page, throwaway, ≤1 day. Skips research and journey. (Equivalent to `--quick` flag.)
+
+Store the answer as `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` | `PROJECT_TYPE=quick`. It drives every downstream step.
+
+**Demo design philosophy is non-negotiable (do NOT compromise on these regardless of speed pressure):**
+- **1 milestone only.** No multi-milestone arc, no Handoff phase. The demo IS the artifact.
+- **NO mock data.** Real backend, real database, real auth. Hardcoded JSON in components is a hard-block. If the data needs Supabase, ship Supabase.
+- **Real agent/platform functionality.** The thing actually works end-to-end. A demo with broken flows is not a Qualia demo.
+- **DESIGN.md mandatory.** OKLCH palette, distinctive typography, full token system. Slop-detect runs hard-block.
+- **Focus = design + functionality.** No sales decks, no placeholder copy, no "lorem ipsum" anywhere.
+
+Speed in a demo comes from skipping multi-milestone planning, NEVER from skipping design quality, mocking the backend, or cutting corners on the core flow.
+
+### Step 2. Brownfield Check
 
 ```bash
 test -f package.json && echo "HAS_PACKAGE"
@@ -58,23 +80,27 @@ 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 0.6.
+If existing code is detected AND not already mapped, **AskUserQuestion**:
 
-### Step 0.6. Project Type Gate (Demo vs Full)
+- header: "Existing code detected"
+- question: "Run `/qualia-map` to scan the repo first?"
+- options: ["Yes — map it", "No — proceed without mapping"]
 
-The single most important fork in the workflow. Demo and Full produce different journeys, different research depth, different milestone counts.
+If yes, invoke the `qualia-map` skill inline, wait for completion, then continue. If quick prototype + brownfield, skip the map (quick is for greenfield trivial work; brownfield + quick is contradictory — route to `/qualia-feature` instead).
 
-- 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.
+### Step 3. One-line Pitch (free-text — minimal, no clarification round)
+
+The shape is locked, now capture the content in one sentence:
+
+> **"What are you building? One sentence — a stranger should understand it."**
+
+Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-discuss` will refine it through its 8 or 14 structured questions.
 
-Store the answer as `PROJECT_TYPE=demo` or `PROJECT_TYPE=full`. It drives Steps 1, 8, and 10.
+This is the ONLY free-text question in the kickoff flow. Everything else is `AskUserQuestion`.
 
-**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.
+### Step 4. Mandatory Discovery Interview (PROJECT MODE)
 
-### Step 1. Mandatory Discovery Interview (PROJECT MODE)
+**Hard rule:** This is the next tool call after Step 3. No ad-hoc clarification, no free-form follow-up, no "let me ask a few quick things first." If the one-line pitch was "a SaaS platform", you invoke `/qualia-discuss` NOW — that skill's structured questions are how breadth gets refined into depth.
 
 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.
 
@@ -94,11 +120,11 @@ After the interview returns, `.planning/project-discovery.md` exists with the us
 
 If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
 
-### Step 2. Detect Project Type
+### Step 5. Detect Project Type
 
-From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ~/.claude/qualia-templates/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 10.
+From questioning answers, infer type → `website` | `ai-agent` | `voice-agent` | `mobile-app` | `null`. If matched, `cat ~/.claude/qualia-templates/projects/{type}.md` gives suggested milestone arc. Store `template_type` for Step 13.
 
-### Step 3. Design Direction (frontend only)
+### Step 6. Design Direction (frontend only)
 
 - header: "Design"
 - question: "What's the design vibe?"
@@ -106,7 +132,7 @@ From questioning answers, infer type → `website` | `ai-agent` | `voice-agent`
 
 Plus free-text: "Any brand colors or reference sites I should look at?"
 
-### Step 4. Client Context
+### Step 7. Client Context
 
 - header: "Client"
 - question: "Client project or internal?"
@@ -117,7 +143,7 @@ If client, ask name. Check saved prefs:
 node ~/.claude/bin/knowledge.js search "{client name}"
 ```
 
-### Step 5. Write PROJECT.md
+### Step 8. Write PROJECT.md
 
 Create `.planning/PROJECT.md` from the template. Include: client, what we're building, core value, validated + active requirements (empty for greenfield), out of scope, stack, design direction, decisions table.
 
@@ -127,7 +153,7 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
-### Step 5a. Seed CONTEXT.md and decisions/ (v5.0 — REQUIRED)
+### Step 8a. Seed CONTEXT.md and decisions/ (v5.0 — REQUIRED)
 
 The domain glossary is the single highest-leverage piece of substrate — every road agent loads it BEFORE PROJECT.md/DESIGN.md. Misalignment is the #1 failure mode in AI coding; CONTEXT.md kills it.
 
@@ -156,7 +182,7 @@ git commit -m "docs: seed CONTEXT.md domain glossary + decisions/ folder"
 
 The glossary stays terse — one sentence per entry. It's loaded into every agent spawn; bloat costs tokens. `/qualia-discuss` will grow it inline as decisions crystallize during phase planning.
 
-### Step 5b. Write PRODUCT.md (v4.5.0 — REQUIRED)
+### Step 8b. Write PRODUCT.md (v4.5.0 — REQUIRED)
 
 `PRODUCT.md` is the "who and why" every road agent reads before designing or building. It is **required** — the planner, builder, and verifier all load it as substrate.
 
@@ -175,7 +201,7 @@ git add .planning/PRODUCT.md
 git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 ```
 
-### Step 6. Create config.json
+### Step 9. Create config.json
 
 ```json
 {
@@ -192,7 +218,7 @@ git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
 
 **Note:** `workflow.research` is ALWAYS `true` for v4. It exists for telemetry but is no longer read as a gate.
 
-### Step 7. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
+### Step 10. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
 
 If frontend work is involved, generate `.planning/DESIGN.md` from `templates/DESIGN.md`. The generation MUST commit to four things upfront (these go in §1 of DESIGN.md):
 
@@ -219,7 +245,7 @@ git add .planning/DESIGN.md .planning/config.json
 git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 ```
 
-### Step 8. Run Research (ALWAYS, no permission ask)
+### Step 11. Run Research (ALWAYS, no permission ask)
 
 **In v4, research runs unconditionally.** The previous `workflow.research` gate is gone. Skipping research leads to generic roadmaps and surprises late in the project — the 4-agent cost is worth it.
 
@@ -253,7 +279,7 @@ node ~/.claude/bin/qualia-ui.js ok "Research complete"
 ```
 Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
-### Step 9. Feature Scoping (Multi-Milestone)
+### Step 12. Feature Scoping (Multi-Milestone)
 
 Read `.planning/research/FEATURES.md` and present the feature landscape. Features are scoped **to milestones** — you'll decide per-feature which milestone owns it.
 
@@ -271,7 +297,7 @@ Track selections:
 
 Gather any additional requirements the user wants that research missed.
 
-### Step 10. Run Roadmapper
+### Step 13. Run Roadmapper
 
 ```bash
 node ~/.claude/bin/qualia-ui.js banner roadmap
@@ -279,12 +305,12 @@ node ~/.claude/bin/qualia-ui.js banner roadmap
 
 **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.
+- **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 14 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)
+### Step 14. Present the Journey (single view)
 
 Render the branded journey ladder:
 
@@ -296,7 +322,7 @@ This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, cu
 
 Also narrate the one-glance summary. See REFERENCE.md section "Journey ladder format" for the ASCII template.
 
-### Step 12. Approval Gate (single — for the whole journey)
+### Step 15. Approval Gate (single — for the whole journey)
 
 - header: "Journey"
 - question: "Does this journey work for you?"
@@ -326,7 +352,7 @@ node ~/.claude/bin/qualia-ui.js info "Full phase detail for each later milestone
 
 (Skip this block when `--full-detail` was used — all milestones are already fully planned in that case.)
 
-### Step 13. Environment Setup
+### Step 16. Environment Setup
 
 Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.
 
@@ -337,7 +363,7 @@ git add .gitignore
 git commit -m "chore: environment setup" 2>/dev/null
 ```
 
-### Step 14. Auto-Apply Gate (or stop here)
+### Step 17. Auto-Apply Gate (or stop here)
 
 If invoked with `--auto`, skip straight into building Milestone 1:
 
@@ -390,15 +416,17 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 ## Rules
 
-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.
+1. **Project type is the first question, period.** Step 1 (Demo / Full / Quick) is the literal first interaction with the user — even before "what are you building". Every downstream step branches on the answer. Don't skip it, don't infer it, don't ask anything before it.
+2. **AskUserQuestion for every discrete-choice question.** Project type, brownfield gate, design vibe, client type, approval gate, auto-chain — all use the interactive UI. The ONLY free-text question in the kickoff flow is the Step 3 one-line pitch. No plain-text prompts for anything that has a closed set of answers.
+3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-discuss`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the discuss skill's job — not yours.
+4. **Discovery interview is mandatory (v5.6).** Step 4 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.
+5. **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.
+6. **Demo design philosophy is non-negotiable.** Real backend always (Supabase, real auth), DESIGN.md mandatory, slop-detect hard-block, 1 milestone, focus on real agent/platform functionality + design quality. No mock data, no lorem ipsum, no broken flows. Speed comes from skipping multi-milestone planning, never from skipping design quality, mocking the backend, or cutting corners on the core flow. A demo that uses mock data is not a Qualia demo.
+7. **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.
+8. **The full-project journey includes Handoff.** Every full project's final milestone is literally named "Handoff" with 4 standard phases. The roadmapper enforces this.
+9. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
+10. **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.
+11. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
+12. **Inline skill invocation.** When Step 2 offers `/qualia-map` or Step 4 invokes `/qualia-discuss`, invoke it inline — don't exit.
+13. **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.
+14. **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.