qualia-framework 3.6.0 → 4.0.3

package/skills/qualia-new/SKILL.md

@@ -1,15 +1,35 @@
 ---
 name: qualia-new
-description: "Set up a new project from scratch — deep questioning, parallel research, REQUIREMENTS.md, ROADMAP.md, approval gate. Use when starting any new client project."
+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
+# /qualia-new — New Project (Full Journey)
 
-Comprehensive project initialization. Deep questioning → 4 parallel research agents → REQUIREMENTS.md with REQ-IDs → ROADMAP.md with phases → approval → scaffold → ready to plan Phase 1.
+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:**
-- `/qualia-new` — full flow (default)
-- `/qualia-new --quick` — 4-phase flat wizard (faster, less rigorous, for trivial projects)
+## Flags
+
+- `/qualia-new` — full-journey flow, stops after approval (default, backward-compatible)
+- `/qualia-new --auto` — full-journey flow, then auto-chains into `/qualia-plan 1 → /qualia-build → /qualia-verify` for Milestone 1
+- `/qualia-new --quick` — 4-phase flat wizard for trivial projects (landing pages, prototypes). Skips research and journey mapping.
+
+## The Shift From Previous Versions
+
+**Before:** `/qualia-new` produced a v1 ROADMAP and stopped. Team improvised subsequent milestones ad hoc.
+
+**Now:** `/qualia-new` produces **JOURNEY.md** (all milestones → Handoff) + REQUIREMENTS.md (multi-milestone, REQ-IDs) + ROADMAP.md (Milestone 1's phase detail). **One approval gate** on the whole journey. Research always runs — no permission ask.
 
 ## Process
 
@@ -25,157 +45,61 @@ Wait for free-text answer. Do NOT use AskUserQuestion here — let them talk nat
 
 ### Step 0.5. Brownfield Check
 
-Before questioning, detect if we're in an existing codebase:
-
 ```bash
 test -f package.json && echo "HAS_PACKAGE"
 test -d .git && echo "HAS_GIT"
-ls *.ts *.tsx *.js *.jsx *.py 2>/dev/null | head -5
 test -f .planning/codebase/README.md && echo "ALREADY_MAPPED"
 ```
 
-**If existing code detected AND not already mapped:**
-
-- header: "Existing Code"
-- question: "I see existing code here. Map the codebase first so I understand what's already built?"
-- options:
-  - "Map codebase first" — Run /qualia-map, then continue (recommended for brownfield)
-  - "Skip mapping" — Treat as greenfield anyway
-
-If "Map codebase first": 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 1.
 
 ### Step 1. Deep Questioning
 
-**Load the questioning methodology as your guide:**
+Load the questioning methodology:
 
 ```bash
 cat ~/.claude/qualia-references/questioning.md 2>/dev/null
 ```
 
-Follow that methodology:
-- Start with their free-text answer from Step 0
-- Follow energy — dig into what excited them
-- Challenge vagueness — never accept fuzzy answers
-- Make abstract concrete — "walk me through using this"
-- Surface motivation — "what prompted this?"
-- Check the 4-item context checklist mentally (what, why, who, done)
+Follow the thread. Challenge vagueness. Make abstract concrete. Check the 4-item mental checklist (what, why, who, done).
 
-**Use AskUserQuestion for forks with 2-4 concrete interpretations.** Use free text when you want them to think freely.
+Use `AskUserQuestion` for forks with 2-4 concrete interpretations. Use free text when you want them to think freely.
 
 **Decision gate** — when you could write a clear PROJECT.md:
 
 - header: "Ready?"
-- question: "I think I understand what you're building. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more
+- question: "I understand what you're building. Create PROJECT.md and move forward?"
+- options: ["Create PROJECT.md", "Keep exploring"]
 
 Loop until "Create PROJECT.md".
 
-### Step 2. Detect Project Type + Load Template
-
-From the questioning answers, infer project type:
-
-- "website", "landing page", "marketing site", "SaaS", "dashboard", "portal" → `website`
-- "chatbot", "AI assistant", "chat agent", "RAG", "agent" → `ai-agent`
-- "voice agent", "phone agent", "call bot", "VAPI", "Retell" → `voice-agent`
-- "mobile app", "iOS", "Android", "React Native", "Expo" → `mobile-app`
-
-**If a type matches:**
-
-```bash
-cat ~/.claude/qualia-templates/projects/{type}.md
-```
-
-This template gives suggested phase structure and category names the roadmapper will use.
-
-**If no type matches:** continue without a template — the roadmapper will derive structure from requirements.
+### Step 2. Detect Project Type
 
-Store `template_type` (or `null`) for use in Step 6.
+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.
 
 ### Step 3. Design Direction (frontend only)
 
-If the project involves frontend work (most do), capture design direction:
-
 - header: "Design"
 - question: "What's the design vibe?"
-- options:
-  - "Dark & Bold" — Dark backgrounds, neon accents, strong contrast
-  - "Clean & Minimal" — White space, subtle shadows, refined typography
-  - "Colorful & Playful" — Gradients, rounded shapes, vibrant palette
-  - "Corporate / Professional" — Structured, trust signals, enterprise feel
+- options: ["Dark & Bold", "Clean & Minimal", "Colorful & Playful", "Corporate / Professional"]
 
-Also ask (free text): "Any brand colors or reference sites I should look at?"
-
-Store these for Step 7 (DESIGN.md generation).
+Plus free-text: "Any brand colors or reference sites I should look at?"
 
 ### Step 4. Client Context
 
 - header: "Client"
 - question: "Client project or internal?"
-- options:
-  - "Client project" — External client, needs handoff
-  - "Internal / Qualia" — Our own product
-  - "Personal / Side project" — No formal client
+- options: ["Client project", "Internal / Qualia", "Personal / Side project"]
 
-If client, ask their name (free text) and check for saved prefs:
+If client, ask name. Check saved prefs:
 ```bash
 cat ~/.claude/knowledge/client-prefs.md 2>/dev/null | grep -A 10 "{client name}"
 ```
 
-If prefs found, mention: *"I have notes on {client} — {summary}. Applying these to defaults unless you say otherwise."*
-
 ### Step 5. Write PROJECT.md
 
-Create `.planning/PROJECT.md` from the template:
+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.
 
-```bash
-mkdir -p .planning
-cat ~/.claude/qualia-templates/project.md
-```
-
-Fill in with questioning answers. Include:
-
-```markdown
-# {Project Name}
-
-## Client
-{name or "Internal" or "Personal"}
-
-## What We're Building
-{one-paragraph description from questioning}
-
-## Core Value
-{the ONE thing that must work}
-
-## Requirements
-### Validated
-{if brownfield, inferred from codebase map; else "(none yet)"}
-
-### Active (hypotheses)
-- [ ] {requirement 1 — from questioning}
-- [ ] {requirement 2}
-- [ ] {requirement 3}
-
-### Out of Scope
-- {exclusion 1}
-
-## Stack
-{from questioning — default: Next.js 16 + React 19 + TypeScript + Supabase + Vercel}
-
-## Design Direction
-{from Step 3}
-
-## Decisions
-| Decision | Rationale |
-|----------|-----------|
-| {choice from questioning} | {why} |
-
----
-*Created: {date}*
-```
-
-Commit:
 ```bash
 git init 2>/dev/null
 git add .planning/PROJECT.md
@@ -184,8 +108,6 @@ git commit -m "docs: initialize project"
 
 ### Step 6. Create config.json
 
-Write `.planning/config.json`:
-
 ```json
 {
   "mode": "interactive",
@@ -199,40 +121,31 @@ Write `.planning/config.json`:
 }
 ```
 
-**If the user says "quick" or the project is clearly trivial (landing page with 2 sections, 1 form):** set `depth: "quick"` and `workflow.research: false`.
+**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)
 
-If frontend work is involved, generate `.planning/DESIGN.md` from `~/.claude/qualia-templates/DESIGN.md` using the design direction from Step 3. Fill in:
-- Palette (concrete hex values, not placeholders)
-- Typography (distinctive fonts, NOT Inter/Roboto/system-ui)
-- Spacing (8px grid)
-- Motion approach
-- Component patterns
+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.
 
-Commit:
 ```bash
 git add .planning/DESIGN.md .planning/config.json
 git commit -m "docs: design direction + config"
 ```
 
-### Step 8. Run Research (if enabled)
+### Step 8. 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.
 
-Check `.planning/config.json` → `workflow.research`. If `true`, proceed. If `false`, skip to Step 9.
+Only `/qualia-new --quick` skips this step.
 
-**Banner:**
 ```bash
 node ~/.claude/bin/qualia-ui.js banner research
+mkdir -p .planning/research
 ```
 
 Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
 
-**Create research dir:**
-```bash
-mkdir -p .planning/research
-```
-
-**Spawn 4 researchers in parallel** (single message, 4 Agent tool calls):
+Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope:
 
 ```
 Agent(prompt="
@@ -241,7 +154,7 @@ 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>greenfield</milestone_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")
 
@@ -251,7 +164,7 @@ Read your role: @~/.claude/agents/researcher.md
 <dimension>features</dimension>
 <domain>{inferred domain}</domain>
 <project_context>{PROJECT.md summary}</project_context>
-<milestone_context>greenfield</milestone_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")
 
@@ -261,7 +174,7 @@ Read your role: @~/.claude/agents/researcher.md
 <dimension>architecture</dimension>
 <domain>{inferred domain}</domain>
 <project_context>{PROJECT.md summary}</project_context>
-<milestone_context>greenfield</milestone_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")
 
@@ -271,7 +184,7 @@ Read your role: @~/.claude/agents/researcher.md
 <dimension>pitfalls</dimension>
 <domain>{inferred domain}</domain>
 <project_context>{PROJECT.md summary}</project_context>
-<milestone_context>greenfield</milestone_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")
 ```
@@ -283,145 +196,170 @@ Agent(prompt="
 Read your role: @~/.claude/agents/research-synthesizer.md
 
 Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
-Include roadmap implications.
+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")
 ```
 
-**Commit research:**
+**Commit:**
 ```bash
 git add .planning/research/
-git commit -m "docs: research synthesis (4 dimensions)"
+git commit -m "docs: research synthesis (4 dimensions, multi-milestone scope)"
 ```
 
-**Show key findings:**
+Show key findings:
 ```bash
 node ~/.claude/bin/qualia-ui.js ok "Research complete"
 ```
-Display top 3 findings from SUMMARY.md (stack recommendation, table stakes, top pitfall).
+Display top 3 from SUMMARY.md (stack recommendation, table stakes, top pitfall).
 
-### Step 9. Feature Scoping
+### Step 9. Feature Scoping (Multi-Milestone)
 
-Read `.planning/research/FEATURES.md` (if exists) and present the feature landscape:
+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:
 
 - header: "{Category name}"
-- question: "Which {category} features are in v1?"
+- question: "Which {category} features belong to v1 (Milestones 1..N-1 excluding Handoff)?"
 - multiSelect: true
-- options:
-  - Each feature from FEATURES.md with brief description
-  - "None for v1" — defer entire category
+- options: each feature from FEATURES.md + "None for v1"
 
-Track:
-- Selected → v1 requirements
-- Unselected table stakes → v2 (users expect these)
-- Unselected differentiators → out of scope
-
-**If research was skipped:** Ask free text: "What are the main things users need to be able to do?" — then probe for specifics on each capability mentioned.
+Track selections:
+- Selected → v1 scope (roadmapper assigns to specific milestones based on dependency order)
+- Unselected table stakes → Post-Handoff v2 (users expect these)
+- Unselected differentiators → Out of Scope
 
 Gather any additional requirements the user wants that research missed.
 
 ### Step 10. Run Roadmapper
 
-**Banner:**
 ```bash
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper agent:
+Spawn the roadmapper with full-journey mandate:
 
 ```
 Agent(prompt="
 Read your role: @~/.claude/agents/roadmapper.md
 
 <task>
-Create REQUIREMENTS.md and ROADMAP.md for this project.
+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)
 
 User-scoped v1 features:
 {list of features selected in Step 9, grouped by category}
 
 Template type: {template_type from config.json}
-If template type is set, use ~/.claude/qualia-templates/projects/{type}.md as the phase structure starting point.
+If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
+
+The final milestone MUST be named 'Handoff' with the fixed 4 phases
+(Polish, Content + SEO, Final QA, Handoff). Do not omit it.
 
-Write files immediately:
-- .planning/REQUIREMENTS.md
-- .planning/ROADMAP.md
-- Update STATE.md via: node ~/.claude/bin/state.js init --project '{name}' --client '{client}' --type '{type}' --phases '<JSON>' --total_phases <N>
+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 roadmap")
+", subagent_type="qualia-roadmapper", description="Create full journey")
 ```
 
-### Step 11. Review Roadmap
+### Step 11. Present the Journey (single view)
 
-Read the generated `ROADMAP.md`. Present it inline:
+Render the branded journey ladder:
+
+```bash
+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 Roadmap
-
-**{N} phases** | **{X} requirements mapped** | All v1 requirements covered ✓
-
-| # | Phase | Goal | Requirements | Success Criteria |
-|---|-------|------|--------------|------------------|
-| 1 | {name} | {goal} | {REQ-IDs} | {count} |
-| 2 | {name} | {goal} | {REQ-IDs} | {count} |
-...
-
-### Phase 1: {Name}
-Goal: {goal}
-Requirements: {REQ-IDs}
-Success criteria:
-1. {criterion}
-2. {criterion}
-3. {criterion}
-
-### Phase 2: {Name}
-...
+## 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.
 ```
 
-### Step 12. Approval Gate
+### Step 12. Approval Gate (single — for the whole journey)
 
-- header: "Roadmap"
-- question: "Does this roadmap work for you?"
+- header: "Journey"
+- question: "Does this journey work for you?"
 - options:
-  - "Approve" — Commit and continue
-  - "Adjust phases" — Tell me what to change
-  - "Review full file" — Show raw ROADMAP.md
+  - "Approve" — commit the full journey and continue
+  - "Adjust" — tell me what to change (milestones, phases, exit criteria, scope)
+  - "Review full JOURNEY.md" — show the raw file
 
-**If "Adjust":**
-- Get the user's feedback
-- Re-spawn the roadmapper with revision context
-- Show revised roadmap
-- Loop until approved
+**If "Adjust":** capture feedback, re-spawn roadmapper with revision context, re-present. Loop until approved.
 
-**If "Review full file":** `cat .planning/ROADMAP.md`, then re-ask.
+**If "Review full JOURNEY.md":** `cat .planning/JOURNEY.md`, then re-ask.
 
 **If "Approve":**
 
 ```bash
-git add .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
-git commit -m "docs: requirements + roadmap ({N} phases)"
+git add .planning/JOURNEY.md .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
+git commit -m "docs: journey + requirements + milestone 1 roadmap ({N} milestones)"
 ```
 
 ### Step 13. Environment Setup
 
-Check what the project needs (from PROJECT.md stack + research):
-
-- Supabase project? Guide through `supabase link` or create new
-- Vercel project? Guide through `vercel link`
-- Env vars? Create `.env.local` with placeholders
+Supabase project? `supabase link` or create. Vercel project? `vercel link`. Env vars? `.env.local` with placeholders from PROJECT.md stack.
 
-Only walk through what's needed. Skip if the user says "I'll handle env myself."
+Skip if user says "I'll handle env myself."
 
-Commit:
 ```bash
 git add .gitignore
 git commit -m "chore: environment setup" 2>/dev/null
 ```
 
-### Step 14. Done
+### Step 14. Auto-Apply Gate (or stop here)
+
+If invoked with `--auto`, skip straight into building Milestone 1:
+
+```bash
+node ~/.claude/bin/qualia-ui.js info "Auto mode — chaining into /qualia-plan 1"
+```
+
+Then inline-invoke `/qualia-plan 1`. That skill will chain into `/qualia-build 1 → /qualia-verify 1 → /qualia-plan 2 → ...` until Milestone 1's last phase verifies, at which point the chain pauses at the milestone boundary and asks:
+
+- header: "Milestone 1 shipped"
+- question: "Continue to Milestone 2 ({next milestone name})?"
+- options: ["Continue", "Pause here"]
+
+**Without `--auto`**, end with a clear pointer:
 
 ```bash
-node ~/.claude/bin/qualia-ui.js end "PROJECT READY" "/qualia-plan 1"
+node ~/.claude/bin/qualia-ui.js end "JOURNEY READY" "/qualia-plan 1"
 ```
 
 Show summary:
@@ -432,37 +370,32 @@ Show summary:
 | Artifact       | Location                    |
 |----------------|-----------------------------|
 | Project        | .planning/PROJECT.md        |
-| Config         | .planning/config.json       |
+| Journey        | .planning/JOURNEY.md        |
 | Requirements   | .planning/REQUIREMENTS.md   |
-| Roadmap        | .planning/ROADMAP.md        |
+| Roadmap (M1)   | .planning/ROADMAP.md        |
 | Design         | .planning/DESIGN.md         |
 | Research       | .planning/research/         |
 | State          | .planning/STATE.md          |
+| Config         | .planning/config.json       |
 
-{N} phases | {X} requirements | Ready to build
+{N} milestones | {X} requirements | Ready to build Milestone 1: {name}
 
-▶ Next: /qualia-plan 1 — plan Phase 1: {phase 1 name}
+▶ Next: /qualia-plan 1
+(or rerun with /qualia-new --auto to chain through automatically)
 ```
 
-## --quick Flag (Fast Path)
-
-If invoked as `/qualia-new --quick`, run a 4-phase flat flow instead of the full comprehensive flow:
+## --quick Flag (Fast Path, Unchanged)
 
-1. Banner + "What do you want to make?"
-2. 4-step wizard (type / features / design / client)
-3. Fixed 4 phases based on project type (Foundation / Core / Content / Polish)
-4. Skip: research, REQUIREMENTS.md, plan-check
-5. Still creates: PROJECT.md, ROADMAP.md (simplified), STATE.md, DESIGN.md
-6. Route to `/qualia-plan 1`
+`/qualia-new --quick` still runs the 4-phase flat wizard for trivial projects (landing pages with 1-2 sections, throwaway prototypes). Creates PROJECT.md + a simplified ROADMAP.md + DESIGN.md + STATE.md. No JOURNEY.md, no research, no multi-milestone. Routes to `/qualia-plan 1`.
 
-Use `--quick` for: landing pages with 1-2 sections, throwaway prototypes, personal experiments.
-Do NOT use `--quick` for: client projects, anything with compliance/regulatory stakes, anything longer than 1 week.
+Do NOT use `--quick` for: client projects, anything with compliance stakes, anything longer than one week.
 
 ## Rules
 
-1. **Questioning is not a checklist.** Follow the thread, don't follow a script.
-2. **Research runs automatically** unless `depth: quick` in config. Don't ask the user every time.
-3. **Approval gate is mandatory.** Never commit a roadmap the user hasn't seen.
-4. **STATE.md updates go through state.js init.** Never edit STATE.md by hand — the statusline reads tracking.json which state.js writes atomically.
-5. **Don't skip the research synthesizer.** Four research files without a synthesis = unread bloat.
-6. **Inline skill invocation.** When Step 0.5 offers `/qualia-map`, INVOKE it inline — don't exit and tell the user to re-run.
+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.

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