qualia-framework 4.4.0 → 5.1.0

package/skills/qualia-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process."
 allowed-tools:
   - Bash
   - Read
@@ -12,13 +12,13 @@ allowed-tools:
 
 # /qualia-map — Codebase Mapping (Brownfield)
 
-Scans an existing repo and produces `.planning/codebase/` — architecture, stack, conventions, concerns. Used by `/qualia-new` to infer what's already built and seed Validated requirements.
+Scans existing repo → `.planning/codebase/` (architecture, stack, conventions, concerns). `/qualia-new` uses this to infer capabilities and seed Validated reqs.
 
 ## When to Use
 
-- Taking over an existing client project
-- Adding features to a repo you didn't build
-- Before `/qualia-new` on any directory that already has code
+- Taking over existing client project
+- Adding features to repo you didn't build
+- Before `/qualia-new` on any directory with existing code
 
 ## Usage
 
@@ -48,48 +48,72 @@ If `ALREADY_MAPPED`, ask:
 node ~/.claude/bin/qualia-ui.js banner map
 ```
 
-### 3. Spawn Parallel Mapper Agents
+### 3. Spawn 5 Mapper Agents (parallel)
 
-Map 4 dimensions in parallel for speed. Each writes one file in `.planning/codebase/`:
+Each writes one file in `.planning/codebase/`:
 
 ```
-Agent 1: Architecture scanner
+Agent 1: Architecture
   Agent(prompt="
-  Scan the current codebase and produce .planning/codebase/architecture.md.
+  Scan codebase → .planning/codebase/architecture.md.
   Identify: entry points, folder structure, module boundaries, data flow.
-  Focus on WHAT the codebase does, not HOW to fix it.
+  Focus on WHAT, not HOW to fix.
   ", subagent_type="general-purpose", description="Architecture scan")
 
-Agent 2: Stack detector
+Agent 2: Stack
   Agent(prompt="
-  Detect the tech stack. Read package.json, requirements.txt, Gemfile, etc.
-  Produce .planning/codebase/stack.md listing: runtime, framework, key libraries,
-  database, hosting, CI. Include version numbers.
+  Detect stack from package.json, requirements.txt, Gemfile, etc.
+  Output: .planning/codebase/stack.md (runtime, framework, key libs, DB, hosting, CI + versions).
   ", subagent_type="general-purpose", description="Stack detection")
 
-Agent 3: Conventions analyzer
+Agent 3: Conventions
   Agent(prompt="
-  Analyze code style and conventions. Sample 10-15 files across the codebase.
-  Produce .planning/codebase/conventions.md listing: naming, component patterns,
-  file organization, import style, test style, commit message format.
+  Analyze code style/conventions. Sample 10-15 files.
+  Output: .planning/codebase/conventions.md (naming, component patterns, file org, import style, test style, commit format).
   ", subagent_type="general-purpose", description="Conventions analysis")
 
-Agent 4: Concerns scanner
+Agent 4: Concerns
   Agent(prompt="
-  Scan for code quality concerns — NOT to fix, just to document.
-  Look for: TODO/FIXME, deprecated APIs, outdated dependencies, missing tests,
-  security smells (hardcoded secrets, no input validation).
-  Produce .planning/codebase/concerns.md.
+  Scan quality concerns (document, NOT fix).
+  Look for: TODO/FIXME, deprecated APIs, outdated deps, missing tests, security smells.
+  Output: .planning/codebase/concerns.md.
   ", subagent_type="general-purpose", description="Concerns scan")
+
+Agent 5: Onboarding adapter
+  Agent(prompt="
+  Detect existing process so Qualia honors it.
+  Output: .planning/codebase/onboarding.md with sections:
+
+  ## Issue tracker
+  - gh repo view --json url 2>/dev/null (GitHub?)
+  - Check: gitlab-ci.yml, .gitlab/ (GitLab?)
+  - Check: .scratch/, docs/issues/, ISSUES.md (local?)
+  - Else: 'none; Qualia uses .planning/decisions/ + tracking.json only'
+
+  ## Existing labels (only if GH/GL detected)
+  - gh label list --json name,description,color 2>/dev/null
+  - Map to canonical: bug, enhancement, needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix
+  - Output mapping table. Note missing canonical roles.
+
+  ## Domain docs
+  - Check: CONTEXT.md, GLOSSARY.md, docs/glossary.md, docs/domain.md, docs/adr/, doc/architecture/, .architecture/
+  - Output: location (or 'none; Qualia creates .planning/CONTEXT.md')
+
+  ## Existing agent files
+  - Check: CLAUDE.md, AGENTS.md, .cursor/, .cursorrules, .aider.conf.yml, .continue/
+  - List found. Qualia APPENDs substrate, never overwrites.
+
+  Terse. Each section < 10 lines. Programmatically parsed.
+  ", subagent_type="general-purpose", description="Onboarding adapter")
 ```
 
-### 4. Wait for All 4
+### 4. Wait for All 5
 
-After all 4 agents complete, read the 4 output files.
+All done → read 5 outputs.
 
 ### 5. Synthesize
 
-Create `.planning/codebase/README.md` — one-page summary linking to the 4 dimension files.
+Create `.planning/codebase/README.md` (one-page summary linking dimensions):
 
 ```markdown
 # Codebase Map
@@ -112,7 +136,7 @@ Based on existing code, this project already does:
 - {capability 2} (evidence: {file path})
 - {capability 3} (evidence: {file path})
 
-These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
+These become **Validated reqs** in PROJECT.md when `/qualia-new` runs.
 
 ## Dimension Details
 
@@ -120,8 +144,26 @@ These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
 - [Stack](./stack.md)
 - [Conventions](./conventions.md)
 - [Concerns](./concerns.md)
+- [Onboarding adapter](./onboarding.md)
+
+## Onboarding adapter snapshot
+
+- **Issue tracker:** {from onboarding.md}
+- **Domain docs:** {from onboarding.md}
+- **Existing agent files:** {from onboarding.md}
 ```
 
+### 5.5 Write adapter config (only if onboarding detected something)
+
+Read `.planning/codebase/onboarding.md`. Per detected dimension:
+
+- Issue tracker → `.planning/agents/tracker.md`
+- Labels → `.planning/agents/labels.md` (canonical mapping)
+- Domain docs at non-default path → `.planning/agents/domain.md`
+- CLAUDE.md/AGENTS.md found → APPEND `## Qualia substrate` (never overwrite)
+
+"none" → skip silently, defaults apply.
+
 ### 6. Commit
 
 ```bash
@@ -137,16 +179,17 @@ node ~/.claude/bin/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
 
 ## What `/qualia-new` Does With This
 
-When `/qualia-new` runs AFTER `/qualia-map`, it:
+After `/qualia-map`:
 1. Reads `.planning/codebase/README.md`
 2. Extracts Validated capabilities
-3. Pre-populates PROJECT.md with Validated requirements section
-4. Skips questions about things already built
-5. Focuses questioning on NEW capabilities being added
+3. Pre-populates PROJECT.md Validated reqs
+4. Skips questions about existing capabilities
+5. Focuses on NEW capabilities
 
 ## Rules
 
-1. **Non-destructive.** This skill only READS code, never modifies it.
-2. **Four parallel agents.** Don't sequential-scan — parallel is ~4x faster.
-3. **Dimension files are structured.** The orchestrator downstream (`/qualia-new`) reads them programmatically.
-4. **Concerns ≠ fixes.** This skill documents concerns. It does NOT fix them. Use `/qualia-optimize` for that.
+1. **Non-destructive.** Only READS code. Writes to `.planning/codebase/`, `.planning/agents/`, and APPENDs to CLAUDE.md/AGENTS.md.
+2. **Five parallel agents.** No sequential scan.
+3. **Dimension files structured.** `/qualia-new` reads programmatically.
+4. **Concerns not fixes.** Document only. `/qualia-optimize` to fix.
+5. **Onboarding respects existing process.** GH issues → Qualia uses them. Never overwrite; only append.

package/skills/qualia-new/REFERENCE.md

@@ -0,0 +1,139 @@
+# /qualia-new Reference Templates
+
+Detailed agent-prompt templates and rendering formats referenced by SKILL.md.
+Each section is a verbatim template -- copy it, fill the `{placeholders}`, and spawn.
+
+## Researcher prompts (4 dimensions)
+
+Spawn all 4 as parallel `Agent()` calls in a single message. Each uses the same structure with a different `<dimension>`.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>stack</dimension>
+<domain>{inferred domain from PROJECT.md}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- research must cover scalability through Milestone 3+</milestone_context>
+<output_path>.planning/research/STACK.md</output_path>
+", subagent_type="qualia-researcher", description="Stack research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>features</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- distinguish v1 table stakes from v2 differentiators</milestone_context>
+<output_path>.planning/research/FEATURES.md</output_path>
+", subagent_type="qualia-researcher", description="Features research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>architecture</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- Phase 1 foundations must support final-milestone requirements</milestone_context>
+<output_path>.planning/research/ARCHITECTURE.md</output_path>
+", subagent_type="qualia-researcher", description="Architecture research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>pitfalls</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- flag risks that stall LATER milestones, not just v1</milestone_context>
+<output_path>.planning/research/PITFALLS.md</output_path>
+", subagent_type="qualia-researcher", description="Pitfalls research")
+```
+
+## Synthesizer prompt
+
+Spawn after all 4 researchers complete.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/research-synthesizer.md
+
+Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
+This is a multi-milestone project -- the SUMMARY must suggest a FULL milestone arc
+(2-5 milestones including Handoff), not just a v1 phase list. Include roadmap
+implications AND handoff implications (what client takeover requires).
+", subagent_type="qualia-research-synthesizer", description="Synthesize research")
+```
+
+## Roadmapper prompt
+
+Spawn with full-journey mandate. If the user passed `--full-detail`, set `<full_detail>true</full_detail>`.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<task>
+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 (and ALL milestones if full_detail=true)
+
+User-scoped v1 features:
+{list of features selected in Step 9, grouped by category}
+
+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.
+
+After writing, update STATE.md via:
+  node ~/.claude/bin/state.js init \
+    --project '{name}' --client '{client}' --type '{type}' \
+    --milestone_name '{Milestone 1 name}' \
+    --phases '<JSON: Milestone 1 phases only>' \
+    --total_phases <count>
+</task>
+", subagent_type="qualia-roadmapper", description="Create full journey")
+```
+
+## Journey ladder format
+
+The branded journey ladder rendered in Step 11. Use `node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md` for the programmatic version. The manual ASCII fallback format is below.
+
+```
+## Proposed Journey
+
+**{N} milestones to handoff** | **{X} requirements mapped** | All v1 requirements covered
+
+  +-- Milestone 1 . {Name}               [CURRENT]
+  |  Why now: {one line}
+  |  Exit: {outcome 1}, {outcome 2}
+  |  Phases: 1. {name} -> 2. {name} -> 3. {name}
+  |  Requirements: {REQ-IDs}
+  +--
+         |
+         v
+  +-- Milestone 2 . {Name}
+  |  Why now: {one line}
+  |  Exit: {outcome 1}, {outcome 2}
+  |  Phases: 1. {name} -> 2. {name}
+  |  Requirements: {REQ-IDs}
+  +--
+         |
+         v
+  ...
+         |
+         v
+  +-- Milestone {N} . Handoff           [FINAL]
+  |  Exit: Deployed, docs, credentials, walkthrough
+  |  Phases: 1. Polish -> 2. Content + SEO -> 3. Final QA -> 4. Handoff
+  +--
+
+Milestone 1 is fully planned. Milestones 2..{N-1} are sketched and will be detailed
+when they open. Milestone {N} (Handoff) uses the standard 4-phase template.
+```

package/skills/qualia-new/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, CONTEXT.md domain glossary seed, decisions/ ADR folder initialized, 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
@@ -17,6 +17,12 @@ allowed-tools:
 
 # /qualia-new — New Project (Full Journey)
 
+## Reference templates
+
+Detailed agent-prompt templates and rendering formats live in `REFERENCE.md` (in this same skill folder). When a step below says "see REFERENCE.md section X", read that section before generating the spawn.
+
+---
+
 Initialize a project with the **entire arc mapped from kickoff to handoff**. All milestones defined upfront so the team follows a clear path, not improvising after each ship.
 
 ## Flags
@@ -107,6 +113,54 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
+### Step 5a. 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.
+
+```bash
+# Copy template
+cp ~/.claude/qualia-templates/CONTEXT.md .planning/CONTEXT.md
+
+# Initialize ADR folder with the template available for reference
+mkdir -p .planning/decisions
+cp ~/.claude/qualia-templates/decisions/ADR-template.md .planning/decisions/_template.md
+```
+
+Then **seed the glossary from the questioning answers**. For each domain term that came up during Step 1 (Deep Questioning) — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
+- the term
+- a one-sentence definition
+- an `Avoid:` line listing rejected synonyms (terms the team should NOT use for this concept)
+
+If the user used multiple terms for the same thing during questioning, capture the disambiguation under `## Flagged ambiguities` (e.g. "User → AuthUser vs Customer").
+
+Replace `{{PROJECT_NAME}}` in CONTEXT.md with the project name.
+
+```bash
+git add .planning/CONTEXT.md .planning/decisions/
+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)
+
+`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.
+
+Ask the user 5 short questions (one at a time, each with a sensible default they can `[Enter]` past):
+
+1. **Register** — "Is this design IS the product (marketing/landing/portfolio → `brand`) or design SERVES the product (app/admin/dashboard → `product`)?" Default: infer from project type.
+2. **Three users** — "Name 3 specific humans who will use this. Not personas — real names + their workflow scenario." Default: project type defaults.
+3. **Brand voice** — "Three adjectives, then one paragraph showing the voice in motion (an error message, a confirmation, an empty state)." Default: derive from PROJECT.md.
+4. **Anti-references** — "Three sites this should NOT look like, with why." Required, no defaults — anti-references are more useful than positive references.
+5. **One-sentence differentiation** — "What does someone remember 24 hours after first using this?" Required.
+
+Write `.planning/PRODUCT.md` from `templates/PRODUCT.md`, filling the user's answers.
+
+```bash
+git add .planning/PRODUCT.md
+git commit -m "docs: PRODUCT.md — register, users, voice, anti-references"
+```
+
 ### Step 6. Create config.json
 
 ```json
@@ -124,13 +178,31 @@ git commit -m "docs: initialize project"
 
 **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)
+### Step 7. Create DESIGN.md (frontend projects — v4.5.0 OKLCH-first)
 
-If frontend work is involved, generate `.planning/DESIGN.md` from the template with concrete palette, distinctive typography (NEVER Inter/Roboto/system-ui), 8px spacing grid, motion approach, component patterns.
+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):
+
+1. **Aesthetic direction** — pick ONE: `editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...`. Don't hedge ("modern minimal" is hedging — pick one extreme).
+2. **Color strategy** — pick ONE: `Restrained · Committed · Full palette · Drenched`. See `rules/design-laws.md` §2.
+3. **Scene sentence** — one concrete sentence: who uses this, where, ambient light, mood. NOT "observability dashboard" — "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room." Run the sentence, not the category.
+4. **Differentiation** — one sentence: what someone remembers 24 hours later.
+
+Then fill the rest of DESIGN.md:
+- §2 Color: OKLCH only, no `#000`/`#fff`, neutrals tinted toward brand hue (chroma 0.005-0.015), accent within the chosen strategy
+- §3 Typography: distinctive display + refined body pair. **NEVER** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk
+- §4 Spacing: 8px grid + fluid `clamp()` for page padding
+- §5 Components: token-driven button/input/card/table specs
+- §6 Depth: 3-level shadow elevation, OKLCH-tinted (not gray)
+- §7 Motion: easing tokens (ease-out-quart/expo), no bounce, `prefers-reduced-motion` respected
+- §8 Iconography: ONE family
+- §9 Responsive: mobile-first
+- §10 Anti-pattern checklist (the auto-runnable one)
+
+Cross-check the result against `rules/design-laws.md` §8 absolute bans BEFORE writing — the design must not propose any banned pattern.
 
 ```bash
 git add .planning/DESIGN.md .planning/config.json
-git commit -m "docs: design direction + config"
+git commit -m "docs: DESIGN.md — direction commit + OKLCH palette + tokens"
 ```
 
 ### Step 8. Run Research (ALWAYS, no permission ask)
@@ -146,62 +218,9 @@ mkdir -p .planning/research
 
 Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
 
-Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope:
-
-```
-Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
-
-<dimension>stack</dimension>
-<domain>{inferred domain from PROJECT.md}</domain>
-<project_context>{PROJECT.md summary}</project_context>
-<milestone_context>multi-milestone — research must cover scalability through Milestone 3+</milestone_context>
-<output_path>.planning/research/STACK.md</output_path>
-", subagent_type="qualia-researcher", description="Stack research")
-
-Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
-
-<dimension>features</dimension>
-<domain>{inferred domain}</domain>
-<project_context>{PROJECT.md summary}</project_context>
-<milestone_context>multi-milestone — distinguish v1 table stakes from v2 differentiators</milestone_context>
-<output_path>.planning/research/FEATURES.md</output_path>
-", subagent_type="qualia-researcher", description="Features research")
-
-Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
-
-<dimension>architecture</dimension>
-<domain>{inferred domain}</domain>
-<project_context>{PROJECT.md summary}</project_context>
-<milestone_context>multi-milestone — Phase 1 foundations must support final-milestone requirements</milestone_context>
-<output_path>.planning/research/ARCHITECTURE.md</output_path>
-", subagent_type="qualia-researcher", description="Architecture research")
-
-Agent(prompt="
-Read your role: @~/.claude/agents/researcher.md
-
-<dimension>pitfalls</dimension>
-<domain>{inferred domain}</domain>
-<project_context>{PROJECT.md summary}</project_context>
-<milestone_context>multi-milestone — flag risks that stall LATER milestones, not just v1</milestone_context>
-<output_path>.planning/research/PITFALLS.md</output_path>
-", subagent_type="qualia-researcher", description="Pitfalls research")
-```
-
-**After all 4 complete, spawn synthesizer:**
+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.
 
-```
-Agent(prompt="
-Read your role: @~/.claude/agents/research-synthesizer.md
-
-Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
-This is a multi-milestone project — the SUMMARY must suggest a FULL milestone arc
-(2-5 milestones including Handoff), not just a v1 phase list. Include roadmap
-implications AND handoff implications (what client takeover requires).
-", subagent_type="qualia-research-synthesizer", description="Synthesize research")
-```
+**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template.
 
 **Commit:**
 ```bash
@@ -239,40 +258,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. 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="
-Read your role: @~/.claude/agents/roadmapper.md
-
-<task>
-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 (and ALL milestones if full_detail=true)
-
-User-scoped v1 features:
-{list of features selected in Step 9, grouped by category}
-
-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.
-
-After writing, update STATE.md via:
-  node ~/.claude/bin/state.js init \\
-    --project '{name}' --client '{client}' --type '{type}' \\
-    --milestone_name '{Milestone 1 name}' \\
-    --phases '<JSON: Milestone 1 phases only>' \\
-    --total_phases <count>
-</task>
-", subagent_type="qualia-roadmapper", description="Create full journey")
-```
+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.
 
 ### Step 11. Present the Journey (single view)
 
@@ -284,37 +270,7 @@ node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
 
 This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, current gets a teal diamond with `[CURRENT]` tag, future get dim open circles. Handoff gets `[FINAL]` tag. Why-now + phase sketch render under current and final.
 
-Also narrate the one-glance summary:
-
-```
-## Proposed Journey
-
-**{N} milestones to handoff** | **{X} requirements mapped** | All v1 requirements covered ✓
-
-  ┌─ Milestone 1 · {Name}               [CURRENT]
-  │  Why now: {one line}
-  │  Exit: {outcome 1}, {outcome 2}
-  │  Phases: 1. {name} → 2. {name} → 3. {name}
-  │  Requirements: {REQ-IDs}
-  └─
-         ↓
-  ┌─ Milestone 2 · {Name}
-  │  Why now: {one line}
-  │  Exit: {outcome 1}, {outcome 2}
-  │  Phases: 1. {name} → 2. {name}
-  │  Requirements: {REQ-IDs}
-  └─
-         ↓
-  ...
-         ↓
-  ┌─ Milestone {N} · Handoff           [FINAL]
-  │  Exit: Deployed, docs, credentials, walkthrough
-  │  Phases: 1. Polish → 2. Content + SEO → 3. Final QA → 4. Handoff
-  └─
-
-Milestone 1 is fully planned. Milestones 2..{N-1} are sketched and will be detailed
-when they open. Milestone {N} (Handoff) uses the standard 4-phase template.
-```
+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)
 
@@ -385,6 +341,9 @@ Show summary:
 | Artifact       | Location                    |
 |----------------|-----------------------------|
 | Project        | .planning/PROJECT.md        |
+| Glossary       | .planning/CONTEXT.md        |
+| Decisions      | .planning/decisions/        |
+| Product        | .planning/PRODUCT.md        |
 | Journey        | .planning/JOURNEY.md        |
 | Requirements   | .planning/REQUIREMENTS.md   |
 | Roadmap (M1)   | .planning/ROADMAP.md        |
@@ -414,3 +373,5 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 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.