qualia-framework 2.2.1 → 2.4.0

package/framework/skills/qualia/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia
-description: Smart Qualia router - reads project state and auto-routes to the right command
+description: "Mechanical state router — reads STATE.md and tells you the exact next command to run. No analysis, no advice, just routing. Use this skill whenever the user says 'qualia', 'next', 'route me', or wants to know the immediate next command without context. For advice when stuck, use /qualia-idk instead. For progress overview, use /qualia-progress."
 tags: [qualia, workflow, auto-route]
 ---
 
@@ -76,9 +76,15 @@ STATE.md exists:
     → Route to: /qualia-verify-work {current_phase}
 
   phase_status = "verified" or "complete"?
-    → Check if more phases exist
-    → If yes: increment phase, route to discuss
-    → If no: "Milestone complete! Run /qualia-complete-milestone"
+    → Check if more phases exist in ROADMAP.md
+    → If yes: increment phase, route to plan
+      "Phase {N} done! Next: Phase {N+1} — {name}. Run /qualia-plan-phase {N+1}"
+    → If no phases remain AND no milestone audit exists:
+      "All phases complete! Run /qualia-audit-milestone to verify the milestone."
+    → If no phases remain AND audit exists AND passed:
+      "Milestone audit passed! Run /qualia-complete-milestone to archive and tag."
+    → If milestone is completed:
+      "Milestone complete! Run /client-handoff to prepare the client delivery document."
 
   blockers exist?
     → Show blockers, ask user how to proceed
@@ -114,7 +120,7 @@ Options:
 
 ---
 
-**Next:** /qualia:{action} {phase}
+**Next:** /qualia-{action} {phase}
 
 {If blockers: show them}
 {If decision needed: present options}

package/framework/skills/qualia-audit-milestone/SKILL.md

@@ -21,7 +21,7 @@ Read all project files:
 - `.planning/ROADMAP.md` — All phases
 - `.planning/config.json`
 
-Reference: `~/.claude/qualia-engine/workflows/audit-milestone.md`
+Reference: `~/.claude/qualia-framework/workflows/audit-milestone.md`
 
 ### 2. Read Verification Results
 
@@ -43,7 +43,7 @@ Scan phase summaries and verification files for noted tech debt, workarounds, or
 
 ### 5. Shipping Checklist Audit
 
-Run the full shipping checklist from `~/.claude/qualia-engine/references/completion-checklists.md` as part of the audit.
+Run the full shipping checklist from `~/.claude/qualia-framework/references/completion-checklists.md` as part of the audit.
 
 Detect project type from `.planning/PROJECT.md` and load the matching checklist:
 - **website** → "Website-Specific Checklist" + "Universal Checklist"
@@ -90,3 +90,6 @@ Write `v{version}-MILESTONE-AUDIT.md`:
 **If PASS**: "Milestone audit passed. Run `/qualia-complete-milestone` to archive and tag."
 
 **If FAIL**: "Audit found gaps. Run `/qualia-plan-milestone-gaps` to create fix phases."
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-complete-milestone/SKILL.md

@@ -17,7 +17,7 @@ Must have a passing milestone audit (`v*-MILESTONE-AUDIT.md` with PASS status).
 
 ## Process (8 Steps)
 
-Reference: `~/.claude/qualia-engine/workflows/complete-milestone.md`
+Reference: `~/.claude/qualia-framework/workflows/complete-milestone.md`
 
 ### 1. Pre-flight Audit Check
 
@@ -26,7 +26,7 @@ Verify the most recent `v*-MILESTONE-AUDIT.md` shows PASS. If not:
 
 ### 2. Shipping Checklist Final Gate
 
-Before archiving, run the full shipping checklist from `~/.claude/qualia-engine/references/completion-checklists.md`.
+Before archiving, run the full shipping checklist from `~/.claude/qualia-framework/references/completion-checklists.md`.
 
 Detect project type from `.planning/PROJECT.md` and load the matching checklist:
 - **website** → "Website-Specific Checklist" + "Universal Checklist"
@@ -76,7 +76,7 @@ cp .planning/ROADMAP.md .planning/milestones/v{version}-ROADMAP.md
 cp .planning/REQUIREMENTS.md .planning/milestones/v{version}-REQUIREMENTS.md
 ```
 
-Template: `~/.claude/qualia-engine/templates/milestone-archive.md`
+Template: `~/.claude/qualia-framework/templates/milestone-archive.md`
 
 ### 6. Archive Requirements
 
@@ -103,6 +103,10 @@ git tag v{version}
 ### 9. Offer Next Steps
 
 > "Milestone v{version} complete and tagged! Options:"
-> - "Start next milestone: `/qualia-new-milestone`"
+> - "Prepare client handoff: `/client-handoff`" — generates client-facing deliverable document
 > - "Ship to production: `/ship`"
-> - "Take a break — you earned it"
+> - "Start next milestone: `/qualia-new-milestone`"
+> - "Run final production audit: `/qualia-production-check`"
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-execute-phase/SKILL.md

@@ -21,8 +21,8 @@ Read all PLAN.md files for the target phase from `.planning/phases/{phase}-{slug
 
 For `--gaps-only`, read only the gap-closure plans created by `plan-phase --gaps`.
 
-Reference: `~/.claude/qualia-engine/workflows/execute-phase.md`
-UI/brand reference: `~/.claude/qualia-engine/references/ui-brand.md`
+Reference: `~/.claude/qualia-framework/workflows/execute-phase.md`
+UI/brand reference: `~/.claude/qualia-framework/references/ui-brand.md`
 
 ### 2. Organize into Waves
 
@@ -84,3 +84,6 @@ Update `.planning/STATE.md` phase status to `executed`.
 | `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates gap closure plans |
 
 Domain skill context from PLAN.md `@skill` references is automatically resolved and inlined into each executor subagent prompt. Plans referencing skills like `frontend-design`, `supabase`, `financial-ledger`, etc. will have those patterns available to executors.
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-help/SKILL.md

@@ -5,7 +5,7 @@ description: "Display the complete Qualia command reference — all available sk
 
 # Qualia Help — Command Reference
 
-Display the complete reference of all available Qualia workflow skills.
+Display the complete reference of all available Qualia workflow skills, organized by situation.
 
 ## Usage
 
@@ -13,66 +13,100 @@ Display the complete reference of all available Qualia workflow skills.
 
 ## Output
 
-Reference: `~/.claude/qualia-engine/workflows/help.md`
-
-Display the command reference. Output only — no analysis, no suggestions, just the reference.
-
-### Project Lifecycle
-| Skill | Description |
-|-------|-------------|
-| `qualia-new-project` | Initialize a new project (questioning → research → requirements → roadmap) |
-| `qualia-new-milestone` | Start a new milestone on existing project |
-| `qualia-complete-milestone` | Archive milestone, tag release, prepare for next |
-
-### Phase Workflow
-| Skill | Description |
-|-------|-------------|
-| `qualia-discuss-phase` | Clarify phase decisions before planning |
-| `qualia-list-phase-assumptions` | Surface assumptions before planning |
-| `qualia-research-phase` | Conduct technical research for a phase |
-| `qualia-plan-phase` | Create detailed execution plans |
-| `qualia-execute-phase` | Wave-based parallel execution of plans |
-| `qualia-verify-work` | Conversational UAT testing |
-
-### Navigation & Status
-| Skill | Description |
-|-------|-------------|
-| `qualia-progress` | Progress summary with routing |
-| `qualia-resume-work` | Restore context from previous session |
-| `qualia-pause-work` | Save session context for handoff |
-
-### Quick Actions
-| Skill | Description |
-|-------|-------------|
-| `qualia-quick` | Quick tasks with quality guarantees |
-| `qualia-debug` | Structured debugging |
-| `qualia-add-todo` | Capture ideas and tasks |
-| `qualia-check-todos` | Review and act on todos |
-
-### Intelligence
-| Skill | Description |
-|-------|-------------|
-| `qualia-idk` | "What should I do next?" — smart advisor, reads planning + codebase |
-| `qualia-optimize` | Deep optimization pass — perf, design, UI, backend, alignment |
-| `qualia-design` | One-shot design transformation — critique + fix + responsive + polish + harden |
-
-### Quality & Deployment
-| Skill | Description |
-|-------|-------------|
-| `qualia-production-check` | Final client-handoff audit — 5 agents check UX, auth, backend, perf, completeness |
-| `qualia-audit-milestone` | Verify milestone definition of done |
-| `qualia-plan-milestone-gaps` | Create fix phases from audit gaps |
-| `qualia-review` | Code review (security, quality, architecture) |
-| `qualia-framework-audit` | Audit the Qualia framework itself (agents, skills, hooks, knowledge) |
-| `ship` | Full production deployment pipeline |
-| `team` | Agent team orchestration |
-
-### Which Review/Audit Skill?
-| When | Use |
-|------|-----|
-| Before deploying (code quality check) | `/qualia-review` or `/qualia-review --web` |
+Reference: `~/.claude/qualia-framework/workflows/help.md`
+
+Display the command reference below. Output only — no analysis, no suggestions, just the reference.
+
+---
+
+### "I'm starting a new project"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-new-project` | Full project setup: questioning → research → requirements → roadmap → environment |
+| `/qualia-new-milestone` | Start a new milestone on an existing project |
+
+### "I need to plan and build"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-plan-phase` | Create detailed execution plans for the next phase |
+| `/qualia-execute-phase` | Build the phase (spawns subagents, runs in waves) |
+| `/qualia-discuss-phase` | Clarify decisions before planning |
+| `/qualia-list-phase-assumptions` | Surface hidden assumptions before planning |
+| `/qualia-research-phase` | Research a topic before planning |
+| `/qualia-quick` | Quick one-off tasks without full phase workflow |
+
+### "I finished building — what now?"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-verify-work` | Test that what was built matches the plan (UAT) |
+| `/qualia-progress` | See how far along the project is + what's next |
+| `/qualia` | Quick router — tells you the exact next command to run |
+
+### "I need to review and fix quality"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-review` | Code review — security, quality, architecture. Use `--web` for web apps, `--ai` for AI agents |
+| `/qualia-optimize` | Find and fix performance, design, and code issues |
+| `/qualia-design` | One-shot design fix — critique + polish + harden + responsive |
+| `/qualia-production-check` | Final audit before handing to client (5 specialist agents) |
+
+### "I need to deploy"
+| Command | What it does |
+|---------|-------------|
+| `/ship` | **The standard deploy command.** Quality gates → git → deploy → verify. Use this. |
+| `/deploy` | Quick deploy without quality gates (advanced) |
+| `/deploy-verify` | Post-deploy verification only (usually called by /ship) |
+
+### "I'm done — time to deliver to client"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-audit-milestone` | Verify all requirements are met before wrapping up |
+| `/qualia-complete-milestone` | Archive milestone, tag release, generate changelog |
+| `/client-handoff` | Generate the client delivery document (features, credentials, maintenance notes) |
+| `/qualia-plan-milestone-gaps` | Create fix phases if the audit found gaps |
+
+### "I'm stuck or confused"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-idk` | **Use this when you don't know what to do.** Analyzes your situation and suggests next steps. |
+| `/qualia-help` | This reference (you're looking at it) |
+| `/qualia-debug` | Structured debugging when something is broken |
+| `/qualia-progress` | See where the project stands |
+
+### "I need to pause or resume"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-pause-work` | Save session context before stopping |
+| `/qualia-resume-work` | Restore context and pick up where you left off |
+
+### "I need to track tasks and notes"
+| Command | What it does |
+|---------|-------------|
+| `/qualia-add-todo` | Capture an idea or task for later |
+| `/qualia-check-todos` | Review pending todos |
+| `/learn` | Save a lesson from a mistake |
+| `/memory` | See what Claude remembers |
+
+### "I'm building a specific type of thing"
+| Command | What it does |
+|---------|-------------|
+| `/frontend-master` | Premium, distinctive UI components |
+| `/voice-agent` | Retell AI + ElevenLabs voice agent |
+| `/openrouter-agent` | AI chatbot with OpenRouter |
+| `/mobile-expo` | React Native / Expo mobile app |
+| `/supabase` | Database, auth, edge functions, RLS |
+| `/seo-master` | SEO audit and optimization |
+| `/rag` | RAG system (embeddings + retrieval) |
+
+### Which review/audit skill should I use?
+| Situation | Use |
+|-----------|-----|
+| Before deploying (code quality) | `/qualia-review` |
 | Before client handoff (is it ready?) | `/qualia-production-check` |
-| Finding perf/design/code issues to fix | `/qualia-optimize` |
-| Best practices research (no fixes) | `/deep-research` |
+| Finding issues to fix (perf, design) | `/qualia-optimize` |
+| AI/voice agent safety check | `/qualia-review --ai` |
 | Auditing the framework itself | `/qualia-framework-audit` |
-| AI/voice agent safety audit | `/qualia-review --ai` |
+
+---
+
+**Tip:** Most of the time, just describe what you want in plain language. The framework will route to the right skill automatically. Say "and ship" when you want it deployed.

package/framework/skills/qualia-new-project/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: qualia-new-project
-description: "Initialize a new Qualia workflow project from scratch — questioning, research, requirements, roadmap. Use this skill whenever the user says 'new project', 'start project', 'init project', 'qualia new', or wants to begin a brand new project with the Qualia qualia-engine workflow. Also trigger when user mentions setting up .planning directory, creating a roadmap, or starting fresh on a new client project."
+description: "Initialize a new Qualia workflow project from scratch — questioning, research, requirements, roadmap, environment setup, design context. Use this skill whenever the user says 'new project', 'start project', 'init project', 'qualia new', or wants to begin a brand new project with the Qualia workflow. Also trigger when user mentions setting up .planning directory, creating a roadmap, or starting fresh on a new client project."
 ---
 
-# Qualia New Project — Project Initialization
+# Qualia New Project — Full Project Initialization
 
-Initialize a new project with the full Qualia qualia-engine workflow: questioning → research → requirements → roadmap.
+Initialize a new project with the complete Qualia workflow: questioning → research → requirements → roadmap → environment → design context. Produces everything needed for an employee to start building and carry through to client handoff.
 
 ## Usage
 
@@ -14,95 +14,217 @@ Initialize a new project with the full Qualia qualia-engine workflow: questionin
 
 ## Process
 
-### 0. Scan for Uploaded Files
+Reference: `~/.claude/qualia-framework/workflows/new-project.md` (the full 1000+ line workflow — follow it exactly)
 
-Before asking any questions, check if the user uploaded or placed files in the project directory:
+### 0. Pre-flight
 
+**Initialize context:**
 ```bash
-ls *.pdf *.docx *.doc *.txt *.md *.png *.jpg *.jpeg 2>/dev/null | head -10
+INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-project)
 ```
 
-If files are found, read them. If ANY file mentions a tech stack (WordPress, Firebase, PHP, Laravel, React Native, Flutter, etc.) that differs from the Qualia standard stack (Next.js + Supabase + Vercel), you MUST ask:
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `project_exists`, `has_existing_code`, `needs_codebase_map`, `has_git`.
 
-> "The document mentions {tech stack from doc}. Do you want to:
-> 1. **Use the Qualia stack** (Next.js + React + TypeScript + Supabase + Vercel) — recommended, this is what we build with
-> 2. **Use the stack from the document** ({tech stack}) — I'll adapt the workflow accordingly"
+- If `project_exists` is true → Error: "Project already initialized. Run `/qualia-progress` to see status."
+- If `has_git` is false → `git init`
 
-Never silently adopt a non-Qualia stack from uploaded documents. Always confirm.
+**Scan for uploaded files** (PDFs, docs, images). If they mention a non-Qualia stack, ask:
+> "The document mentions {stack}. Use the Qualia stack (Next.js + Supabase + Vercel) or the document's stack?"
 
-### 1. Questioning Phase
+**Brownfield detection:** If existing code found without a codebase map, offer `/qualia-map-codebase` first.
 
-Run the questioning workflow to understand the project deeply before any planning.
+### 1. Deep Questioning
 
-Reference: `~/.claude/qualia-engine/references/questioning.md`
+Reference: `~/.claude/qualia-framework/references/questioning.md`
 
-Ask targeted questions covering:
-- What is the project? Who is it for?
+**Start open:** "What do you want to build?"
+
+Then follow threads — dig into what they said. This is dream extraction, not an interview. Ask about:
+- What is it? Who is it for?
 - What problem does it solve?
-- What are the key features?
-- What tech stack preferences exist?
+- What does "done" look like?
 - What are the constraints (timeline, budget, existing systems)?
-- What does success look like?
 
-### 2. Research Phase
+Use AskUserQuestion with concrete options to help them think. Challenge vagueness. Make abstract things concrete ("walk me through using this").
 
-Based on answers, conduct research on:
-- Similar solutions and competitors
-- Best tech stack choices for the requirements
-- Potential challenges and pitfalls
-- UI/brand considerations per `~/.claude/qualia-engine/references/ui-brand.md`
+**Decision gate:** When you have enough to write PROJECT.md, ask:
+> "I think I understand. Ready to create PROJECT.md, or want to explore more?"
 
-### 3. Create Project Structure
+### 2. Detect Project Type & Load Template
 
-Create the `.planning/` directory with all required files:
+Based on questioning answers, detect the project type:
 
-```bash
-mkdir -p .planning/research .planning/phases .planning/quick .planning/debug
-```
+| Signal | Type | Template |
+|--------|------|----------|
+| website, landing page, marketing, SaaS | `website` | `templates/projects/website.md` |
+| chatbot, AI assistant, chat agent | `ai-agent` | `templates/projects/ai-agent.md` |
+| voice agent, phone agent, call bot, Retell | `voice-agent` | `templates/projects/voice-agent.md` |
+| mobile app, iOS, Android, Expo | `mobile-app` | `templates/projects/mobile-app.md` |
+
+**Always load the matching template.** Read it from `~/.claude/qualia-framework/templates/projects/{type}.md`. This gives you the standard phase structure for this project type — the roadmap will use it as a scaffold.
+
+Ask the employee to confirm:
+> "This looks like a {type} project. I'll use the {type} template for the phase structure. Sound right?"
+
+If no type detected, build the roadmap from scratch.
+
+### 3. Write PROJECT.md
+
+Template: `~/.claude/qualia-framework/templates/project.md`
 
-#### PROJECT.md
-Template from `~/.claude/qualia-engine/templates/project.md`:
+Synthesize all context into `.planning/PROJECT.md`:
 - Project name, description, client
+- Core Value (the ONE thing that must work)
+- Requirements (Active = hypotheses until shipped)
+- Context, Constraints, Key Decisions
 - Tech stack decisions
 - Deploy target
-- Key URLs and credentials references
-
-#### config.json
-```json
-{
-  "project": "<name>",
-  "version": "1.0",
-  "deploy": { "platform": "vercel", "domain": "" },
-  "stack": { "framework": "next", "db": "", "auth": "" }
-}
+
+**Commit immediately:**
+```bash
+mkdir -p .planning
+node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
+```
+
+### 4. Workflow Preferences
+
+Ask the employee about how they want to work:
+
+**Core settings:**
+- **Mode:** YOLO (auto-approve) or Interactive (confirm each step)?
+- **Depth:** Quick (3-5 phases) / Standard (5-8 phases) / Comprehensive (8-12 phases)?
+- **Execution:** Parallel (independent plans run simultaneously) or Sequential?
+
+**Quality agents (all recommended for client projects):**
+- **Researcher:** Investigate domain before planning each phase?
+- **Plan Checker:** Verify plans will achieve their goals?
+- **Verifier:** Confirm deliverables match phase goals after execution?
+- **Model Profile:** Quality (Opus) / Balanced (Sonnet) / Budget (Haiku)?
+
+Write `.planning/config.json` with all settings.
+
+**Commit:**
+```bash
+node ~/.claude/qualia-framework/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
+```
+
+### 5. Research Phase (if selected)
+
+Spawn 4 parallel research agents:
+1. **Stack research** → `.planning/research/STACK.md`
+2. **Features research** → `.planning/research/FEATURES.md`
+3. **Architecture research** → `.planning/research/ARCHITECTURE.md`
+4. **Pitfalls research** → `.planning/research/PITFALLS.md`
+
+Then spawn synthesizer → `.planning/research/SUMMARY.md`
+
+Present key findings to employee before moving on.
+
+### 6. Define Requirements
+
+Load context from PROJECT.md and research (if exists).
+
+**If research exists:** Present features by category (table stakes vs differentiators). Let employee scope each category for v1 using AskUserQuestion with multiSelect.
+
+**If no research:** Gather requirements conversationally.
+
+Generate `.planning/REQUIREMENTS.md` with:
+- v1 Requirements grouped by category (with REQ-IDs like AUTH-01, CONT-02)
+- v2 Requirements (deferred)
+- Out of Scope (with reasons)
+- Traceability section (filled by roadmap)
+
+**Show full requirements list for approval.** Loop until employee confirms.
+
+**Commit:**
+```bash
+node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
 ```
 
-#### REQUIREMENTS.md
-Template from `~/.claude/qualia-engine/templates/requirements.md`:
-- Milestone definition (v1.0)
-- Functional requirements (categorized)
-- Non-functional requirements
-- Definition of Done checklist
+### 7. Create Roadmap
+
+Spawn qualia-roadmapper agent with PROJECT.md, REQUIREMENTS.md, research, config, and the project type template.
+
+**CRITICAL — The roadmap MUST include these mandatory final phases:**
+
+After all feature phases, the roadmap must always end with:
+
+| Phase | Name | Purpose |
+|-------|------|---------|
+| N-2 | **Quality Review & Polish** | Run `/qualia-review`, fix issues, run design polish (`/critique` → `/polish` → `/harden`). No new features. |
+| N-1 | **Deploy & Verify** | Run `/ship` to production. Post-deploy verification (HTTP 200, auth, console, latency, UptimeRobot). |
+| N | **Client Handoff** | Run `/client-handoff` to generate delivery document. Final production check (`/qualia-production-check`). Hand credentials, docs, and access to client. |
+
+These are NOT optional. Every client project needs review, deploy, and handoff. The employee should never have to discover these steps on their own.
+
+**If using a project type template:** Use its phases as the feature scaffold, then append the 3 mandatory final phases.
+
+**Present roadmap to employee for approval.** Show phase table with goals, requirements mapped, and success criteria. Loop until approved.
+
+**Commit:**
+```bash
+node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+### 8. Environment Setup
+
+Detect what's needed from PROJECT.md and stack:
+
+- **Supabase** → Link or create project, init schema
+- **Vercel** → Link project
+- **Environment variables** → Create `.env.local` with placeholders
+- **External services** → Note which API keys are needed (Stripe, Retell, OpenRouter, etc.)
 
-#### ROADMAP.md
-- Break requirements into sequential phases
-- Each phase: number, name, description, status, dependencies
-- Phases should be small enough to complete in 1-2 sessions
+Walk the employee through setup. If they want to skip: note `env_setup: pending` in STATE.md.
 
-#### STATE.md
-- Current milestone, current phase
-- Phase status table
-- Quick tasks completed table
-- Session log
+**Starter template:** If a matching starter exists at `~/Projects/qualia-erp/templates/{type}-starter/`, offer to scaffold from it.
 
-### 4. Next Step
+### 9. Design Context (frontend projects)
 
-After initialization, tell the user:
-> "Project initialized. Next: run `/qualia-plan-phase 1` to plan the first phase."
+If the project involves frontend work (detected from roadmap or project type):
+
+Run `/critique` to gather design context — brand colors, typography preferences, layout style, reference sites. This runs ONCE and persists to the project's `.planning/DESIGN.md` so all future phases have design context.
+
+### 10. Done — Present Summary
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Qualia ► PROJECT INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**[Project Name]** — [type] project for [client]
+
+| Artifact       | Location                    |
+|----------------|-----------------------------|
+| Project        | .planning/PROJECT.md        |
+| Config         | .planning/config.json       |
+| Research       | .planning/research/         |
+| Requirements   | .planning/REQUIREMENTS.md   |
+| Roadmap        | .planning/ROADMAP.md        |
+| State          | .planning/STATE.md          |
+| Design         | .planning/DESIGN.md         |
+
+**[N] phases** | **[X] requirements** | Ready to build ✓
+
+## The Full Journey
+
+Phase 1-{N-3}: Feature phases (build the product)
+Phase {N-2}: Quality Review & Polish
+Phase {N-1}: Deploy & Verify
+Phase {N}: Client Handoff
+
+## ▶ Next
+
+Run `/qualia-plan-phase 1` to plan the first phase.
+(Or `/qualia-discuss-phase 1` to discuss approach first.)
+```
 
 ### Agents Used
 | Agent | File | Role |
 |-------|------|------|
-| `qualia-project-researcher` | `~/.claude/agents/qualia-project-researcher.md` | Domain ecosystem research |
+| `qualia-project-researcher` | `~/.claude/agents/qualia-project-researcher.md` | Domain ecosystem research (4 parallel) |
 | `qualia-research-synthesizer` | `~/.claude/agents/qualia-research-synthesizer.md` | Synthesizes parallel research |
-| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md |
+| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md with mandatory final phases |
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-plan-phase/SKILL.md

@@ -22,7 +22,7 @@ Create detailed PLAN.md files for a project phase, with optional research and ve
 
 If phase number provided, use it. Otherwise, scan ROADMAP.md for the first phase with status `not started` or `planned` without a PLAN.md.
 
-Reference: `~/.claude/qualia-engine/workflows/plan-phase.md`
+Reference: `~/.claude/qualia-framework/workflows/plan-phase.md`
 
 ### 2. Research (if needed)
 
@@ -85,7 +85,7 @@ If checker finds issues, revise the plan and re-verify.
 
 Update `.planning/STATE.md` to reflect the phase is now `planned`.
 
-Reference UI/brand guidelines: `~/.claude/qualia-engine/references/ui-brand.md`
+Reference UI/brand guidelines: `~/.claude/qualia-framework/references/ui-brand.md`
 
 For complex phases touching multiple subsystems, consider `/deep-research` before phase research to establish architectural direction.
 
@@ -99,3 +99,6 @@ For complex phases touching multiple subsystems, consider `/deep-research` befor
 | `qualia-planner` | `~/.claude/agents/qualia-planner.md` | Creates PLAN.md with goal-backward methodology |
 | `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates plan completeness |
 | `qualia-phase-researcher` | `~/.claude/agents/qualia-phase-researcher.md` | Phase research (when --research) |
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`