qualia-framework 2.4.0 → 2.4.2

package/framework/qualia-engine/references/continuation-prompt.md

@@ -0,0 +1,97 @@
+# Checkpoint Continuation Prompt Template
+
+Template for spawning a fresh agent to continue execution after a checkpoint pause.
+
+**Why fresh agent:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
+
+## Template
+
+```markdown
+<objective>
+Continue executing plan {plan_id} from task {resume_task_number}: {resume_task_name}.
+Previous tasks are already committed. Do NOT re-execute them.
+</objective>
+
+<completed_work>
+## Tasks Already Done
+
+{completed_tasks_table}
+
+These tasks have been committed. Verify their commits exist before continuing:
+```bash
+git log --oneline --all --grep="{plan_id}" | head -10
+```
+</completed_work>
+
+<checkpoint_resolution>
+## Checkpoint Resolution
+
+**Checkpoint type:** {checkpoint_type}
+**User response:** {user_response}
+
+{resume_instructions}
+</checkpoint_resolution>
+
+<resume_from>
+## Resume Point
+
+**Task:** {resume_task_number} — {resume_task_name}
+**Plan path:** {plan_path}
+
+Read the full plan for context, but only execute from task {resume_task_number} onward.
+Follow the same execution rules: per-task commits, deviation handling, verification.
+</resume_from>
+
+<context>
+{state_content}
+{config_content}
+</context>
+
+<success_criteria>
+- [ ] Previous commits verified (not re-executed)
+- [ ] Remaining tasks executed from task {resume_task_number}
+- [ ] Each task committed individually
+- [ ] SUMMARY.md created covering ALL tasks (including pre-checkpoint)
+- [ ] STATE.md updated with final position
+</success_criteria>
+```
+
+## Resume Instructions by Checkpoint Type
+
+### checkpoint:human-verify
+```
+The user has verified the previous work.
+- "approved" → Continue to next task normally.
+- Issue description → Fix the reported issue in the current task context before proceeding.
+```
+
+### checkpoint:decision
+```
+The user selected an option for the decision point.
+- Apply the user's choice: {user_response}
+- This may affect how remaining tasks are implemented.
+- Document the decision in SUMMARY.md under "Decisions Made".
+```
+
+### checkpoint:human-action
+```
+The user completed a manual action (e.g., authentication, external config).
+- "done" → Verify the action succeeded (run verification command if specified).
+- If verification fails, inform user and wait for retry.
+- If verification passes, continue to next task.
+```
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{plan_id}` | Plan frontmatter | e.g., "03-02" |
+| `{resume_task_number}` | Checkpoint return | Task number to resume from |
+| `{resume_task_name}` | Checkpoint return | Name of the resume task |
+| `{completed_tasks_table}` | Checkpoint return | Markdown table of done tasks with commit hashes |
+| `{checkpoint_type}` | Plan XML | human-verify, decision, or human-action |
+| `{user_response}` | User input | What the user provided at the checkpoint |
+| `{resume_instructions}` | This template | Type-specific instructions from above |
+| `{plan_path}` | Phase directory | Path to the PLAN.md file |
+| `{state_content}` | STATE.md | Inlined project state |
+| `{config_content}` | config.json | Inlined project config |

package/framework/qualia-engine/references/employee-guide.md

@@ -0,0 +1,167 @@
+# How Qualia Works — Developer Guide
+
+> This is everything you need to know. Follow the flow, type the commands. The framework handles the rest.
+
+---
+
+## The Big Picture
+
+Every project follows one path:
+
+```
+Start → Build → Polish → Review → PR → Deploy → Handoff
+         70%                    100%
+```
+
+The framework tells you what to do at every step. When in doubt, type `/qualia` — it reads your project state and tells you the exact next command.
+
+---
+
+## Starting a Project
+
+You get assigned a project. Here's what you do:
+
+```
+/qualia-new-project          ← answers questions, sets everything up
+```
+
+This creates a `.planning/` folder with your roadmap, requirements, and phases. You don't need to understand the files — the framework reads them for you.
+
+---
+
+## The Build Cycle (repeat for each phase)
+
+Your roadmap has phases (Phase 1, Phase 2, etc.). For each one:
+
+```
+/qualia-plan-phase 1         ← creates the plan
+/qualia-execute-phase 1      ← builds it
+/qualia-verify-work 1        ← tests it
+```
+
+Then move to the next phase. The framework tells you when to move on.
+
+**Don't memorize this.** After each command finishes, it tells you what's next. Or type `/qualia` anytime.
+
+---
+
+## The Finish Line (this is where most people stall)
+
+When all phases are done, you're about 70% done. The framework now guides you through:
+
+```
+  ✓ Build phases       ← you already did this
+  ✓ Milestone audit    ← framework runs this
+  ✓ Milestone archived ← framework does this
+  ▶ Design polish      ← /critique → /polish → /harden
+  · Code review        ← /qualia-review --web
+  · Pull request       ← /pr
+  · Deploy             ← Fawzi handles this
+  · Client handoff     ← /client-handoff
+```
+
+The framework walks you through each step. Just keep typing `/qualia` to see what's next.
+
+---
+
+## The 10 Commands That Matter
+
+| When | Command | What it does |
+|------|---------|-------------|
+| **Starting** | `/qualia-new-project` | Sets up everything from scratch |
+| **Building** | `/qualia-plan-phase N` | Plans a phase |
+| | `/qualia-execute-phase N` | Builds it |
+| | `/qualia-verify-work N` | Tests it |
+| **Polishing** | `/critique` | Reviews the design |
+| | `/polish` | Fixes spacing, alignment, details |
+| | `/harden` | Handles edge cases, errors, overflow |
+| **Shipping** | `/qualia-review --web` | Code quality + security audit |
+| | `/pr` | Creates a pull request |
+| **Anytime** | `/qualia` | "What should I do next?" |
+
+Everything else is optional. These 10 get the job done.
+
+---
+
+## When You're Stuck
+
+```
+/qualia           ← "what's next?" — reads state, tells you the command
+/qualia-idk       ← "I'm lost" — analyzes everything, suggests a path
+/qualia-debug     ← "something is broken" — structured debugging
+/qualia-progress  ← "where am I?" — full progress report
+```
+
+If none of those help, paste the error and ask Claude directly. If Claude can't fix it, escalate to Fawzi.
+
+---
+
+## Session Start / End
+
+**Every session starts the same way.** Claude automatically runs `/qualia-start` which shows you:
+- What project you're in
+- What branch you're on
+- System health
+- What to do next
+
+**When you're done for the day:**
+```
+/qualia-pause-work    ← saves your context for next time
+/qualia-report        ← logs what you did (Fawzi reviews these)
+```
+
+**When you come back:**
+```
+/qualia-resume-work   ← picks up where you left off
+```
+
+---
+
+## Rules (non-negotiable)
+
+1. **Feature branches only** — never push to main. The framework blocks it automatically.
+2. **Read before write** — don't edit files you haven't read.
+3. **MVP first** — build what's asked, nothing extra.
+4. **Push to GitHub** — you push code. Fawzi deploys to production.
+5. **`/qualia` is your friend** — lost? type it. It always knows what's next.
+
+---
+
+## What the Framework Does Behind the Scenes
+
+You don't need to understand this, but if you're curious:
+
+- **Hooks** run automatically on certain actions (commits, deploys, file writes). They enforce rules like "no pushing to main" and "no editing .env files." If a hook blocks you, it tells you why and how to fix it.
+- **Skills** are the `/commands` you type. They're like recipes — each one does a specific thing.
+- **Agents** are AI workers that skills spawn to do heavy lifting (research, verification, code review). You don't interact with them directly.
+- **`.planning/`** is where the framework tracks everything about your project. Don't edit these files manually — the framework manages them.
+
+---
+
+## Quick Reference Card
+
+```
+◆ QUALIA DEVELOPER FLOW
+
+  /qualia-new-project
+       ↓
+  For each phase:
+    /qualia-plan-phase N
+    /qualia-execute-phase N
+    /qualia-verify-work N
+       ↓
+  /qualia-complete-milestone
+       ↓
+  FINISH LINE:
+    /critique → /polish → /harden
+    /qualia-review --web
+    /pr
+       ↓
+  Fawzi deploys
+       ↓
+  /client-handoff
+       ↓
+  Done.
+
+  Lost? Type /qualia
+```

package/framework/qualia-engine/templates/lab-notes.md

@@ -0,0 +1,16 @@
+# Lab Notes — [Project Name]
+
+> What failed, why it failed, and what worked instead.
+> Read by planners and researchers to avoid repeating dead-end approaches.
+> Updated via `/learn` or manually during debugging sessions.
+
+---
+
+<!-- Entry format:
+### Phase N: [Phase Title]
+
+**Tried:** [approach that was attempted]
+**Failed because:** [root cause — be specific]
+**Better approach:** [what actually worked, or what to try next]
+**Date:** YYYY-MM-DD
+-->

package/framework/qualia-engine/templates/roadmap.md

@@ -113,15 +113,9 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
-**MANDATORY FINAL PHASES — Every client project must end with these 3 phases:**
+**FEATURE PHASES ONLY — Do NOT add review, deploy, or handoff phases to the roadmap.**
 
-| Phase | Name | What it does | Skills used |
-|-------|------|-------------|-------------|
-| N-2 | **Quality Review & Polish** | Code review (`/qualia-review`), design polish (`/critique` → `/polish` → `/harden`), fix all issues. No new features. | @qualia-review, @critique, @polish, @harden |
-| N-1 | **Deploy & Verify** | Deploy to production (`/ship`). Run 5-check post-deploy verification (HTTP 200, auth flow, console errors, API latency, UptimeRobot). | @ship, @deploy-verify |
-| N | **Client Handoff** | Generate client delivery document (`/client-handoff`). Final production audit (`/qualia-production-check`). Hand over credentials, docs, and access. | @client-handoff, @qualia-production-check |
-
-These are NOT optional. The roadmapper must always include them as the final 3 phases. Feature phases come first, then these 3 close out the milestone. An employee following the roadmap will naturally reach client handoff without having to discover it on their own.
+The finish line system handles polish → review → PR → deploy → handoff automatically after all feature phases are done (`/qualia-complete-milestone` triggers it). Adding them as roadmap phases causes employees to do the work twice.
 
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)

package/framework/qualia-engine/workflows/execute-phase.md

@@ -16,7 +16,7 @@ Read STATE.md before any operation to load project context.
 Load all context in one call:
 
 ```bash
-INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init execute-phase "${PHASE_ARG}")
+INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init execute-phase "${PHASE_ARG}")
 ```
 
 Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `parallelization`, `branching_strategy`, `branch_name`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`.
@@ -61,7 +61,7 @@ This is a suggestion only — execution continues normally regardless. The user
 Load plan inventory with wave grouping in one call:
 
 ```bash
-PLAN_INDEX=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js phase-plan-index "${PHASE_NUMBER}")
+PLAN_INDEX=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js phase-plan-index "${PHASE_NUMBER}")
 ```
 
 Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objective`, `files_modified`, `task_count`, `has_summary`), `waves` (map of wave number → plan IDs), `incomplete`, `has_checkpoints`.
@@ -113,14 +113,14 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
    STATE_CONTENT=$(cat .planning/STATE.md)
    CONFIG_CONTENT=$(cat .planning/config.json 2>/dev/null)
    # Content must be inlined — @ syntax doesn't work across Task() boundaries
-   EXECUTE_PLAN_WF=$(cat /home/qualia/.claude/qualia-engine/workflows/execute-plan.md)
-   SUMMARY_TMPL=$(cat /home/qualia/.claude/qualia-engine/templates/summary.md)
-   CHECKPOINTS_REF=$(cat /home/qualia/.claude/qualia-engine/references/checkpoints.md)
-   TDD_REF=$(cat /home/qualia/.claude/qualia-engine/references/tdd.md)
+   EXECUTE_PLAN_WF=$(cat /home/qualia/.claude/qualia-framework/workflows/execute-plan.md)
+   SUMMARY_TMPL=$(cat /home/qualia/.claude/qualia-framework/templates/summary.md)
+   CHECKPOINTS_REF=$(cat /home/qualia/.claude/qualia-framework/references/checkpoints.md)
+   TDD_REF=$(cat /home/qualia/.claude/qualia-framework/references/tdd.md)
    # Detect if plan involves frontend work
    IS_FRONTEND=$(echo "$PLAN_CONTENT" | grep -qiE '\.(tsx|jsx|css|scss)|frontend|ui|component|page|layout|dashboard|form|modal' && echo "true" || echo "false")
    if [ "$IS_FRONTEND" = "true" ]; then
-     DESIGN_CONTEXT=$(cat /home/qualia/.claude/qualia-engine/references/design-quality.md 2>/dev/null)
+     DESIGN_CONTEXT=$(cat /home/qualia/.claude/qualia-framework/references/design-quality.md 2>/dev/null)
      FRONTEND_SKILL=$(cat /home/qualia/.claude/skills/frontend-master/SKILL.md 2>/dev/null)
    fi
    ```
@@ -257,7 +257,7 @@ Plans with `autonomous: false` require user interaction.
    [Awaiting section from agent return]
    ```
 5. User responds: "approved"/"done" | issue description | decision selection
-6. **Spawn continuation agent (NOT resume)** using continuation-prompt.md template:
+6. **Spawn continuation agent (NOT resume)** using `/home/qualia/.claude/qualia-framework/references/continuation-prompt.md` template:
    - `{completed_tasks_table}`: From checkpoint return
    - `{resume_task_number}` + `{resume_task_name}`: Current task
    - `{user_response}`: What user provided
@@ -460,7 +460,7 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 |--------|--------|
 | `passed` | → update_roadmap |
 | `human_needed` | Present items for human testing, get approval or feedback |
-| `gaps_found` | Present gap summary, offer `/qualia:plan-phase {phase} --gaps` |
+| `gaps_found` | Present gap summary, offer `/qualia-plan-phase {phase} --gaps` |
 
 **If human_needed:**
 ```
@@ -486,15 +486,15 @@ All automated checks passed. {N} items need human testing:
 ---
 ## ▶ Next Up
 
-`/qualia:plan-phase {X} --gaps`
+`/qualia-plan-phase {X} --gaps`
 
 <sub>`/clear` first → fresh context window</sub>
 
 Also: `cat {phase_dir}/{phase}-VERIFICATION.md` — full report
-Also: `/qualia:verify-work {X}` — manual testing first
+Also: `/qualia-verify-work {X}` — manual testing first
 ```
 
-Gap closure cycle: `/qualia:plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/qualia:execute-phase {X} --gaps-only` → verifier re-runs automatically (see below).
+Gap closure cycle: `/qualia-plan-phase {X} --gaps` reads VERIFICATION.md → creates gap plans with `gap_closure: true` → user runs `/qualia-execute-phase {X} --gaps-only` → verifier re-runs automatically (see below).
 
 **Mandatory re-verification after gap closure:**
 
@@ -504,7 +504,7 @@ When executing with `--gaps-only`, after all gap plans complete (aggregate_resul
 2. aggregate_results reports completion
 3. verify_phase_goal re-runs (spawn qualia-verifier again)
 4. **If `passed`:** → update_roadmap (phase complete)
-5. **If `gaps_found` again:** Present new gaps, offer another `/qualia:plan-phase {X} --gaps` cycle. **Never mark phase complete with gaps.**
+5. **If `gaps_found` again:** Present new gaps, offer another `/qualia-plan-phase {X} --gaps` cycle. **Never mark phase complete with gaps.**
 6. **If `human_needed`:** Present for manual testing as usual
 
 A phase MUST NOT be marked complete in ROADMAP.md until verification returns `passed` or the user explicitly approves after `human_needed`. There is no bypass.
@@ -514,7 +514,7 @@ A phase MUST NOT be marked complete in ROADMAP.md until verification returns `pa
 Mark phase complete in ROADMAP.md (date, status). **Only reachable when verification status is `passed` or user approved `human_needed` items.**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md .planning/REQUIREMENTS.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs(phase-{X}): complete phase execution" --files .planning/ROADMAP.md .planning/STATE.md .planning/phases/{phase_dir}/*-VERIFICATION.md .planning/REQUIREMENTS.md
 ```
 </step>
 
@@ -526,7 +526,7 @@ node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs(phase-{
 
 **Phase {X+1}: {Name}** — {Goal}
 
-`/clear` then `/qualia:plan-phase {X+1}`
+`/clear` then `/qualia-plan-phase {X+1}`
 ```
 
 **If milestone complete:**
@@ -535,7 +535,7 @@ MILESTONE COMPLETE!
 
 All {N} phases executed.
 
-`/clear` then `/qualia:complete-milestone`
+`/clear` then `/qualia-complete-milestone`
 ```
 </step>
 
@@ -553,7 +553,7 @@ Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task bloc
 </failure_handling>
 
 <resumption>
-Re-run `/qualia:execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
+Re-run `/qualia-execute-phase {phase}` → discover_plans finds completed SUMMARYs → skips them → resumes from first incomplete plan → continues wave execution.
 
 STATE.md tracks: last completed plan, current wave, pending checkpoints.
 </resumption>

package/framework/qualia-engine/workflows/new-project.md

@@ -18,7 +18,7 @@ INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-p
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`.
 
-**If `project_exists` is true:** Error — project already initialized. Use `/qualia:progress`.
+**If `project_exists` is true:** Error — project already initialized. Use `/qualia-progress`.
 
 **If `has_git` is false:** Initialize git:
 ```bash
@@ -54,14 +54,12 @@ Use AskUserQuestion:
 - header: "Existing Code"
 - question: "I detected existing code in this directory. Would you like to map the codebase first?"
 - options:
-  - "Map codebase first" — Run /qualia:map-codebase to understand existing architecture (Recommended)
+  - "Map codebase first" — Run /qualia-map-codebase to understand existing architecture (Recommended)
   - "Skip mapping" — Proceed with project initialization
 
 **If "Map codebase first":**
-```
-Run `/qualia:map-codebase` first, then return to `/qualia:new-project`
-```
-Exit command.
+
+Run the codebase mapping INLINE — invoke the `/qualia-map-codebase` skill directly, wait for it to complete, then continue to Step 3. Do NOT exit the flow and tell the user to re-run — that breaks the experience.
 
 **If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
 
@@ -230,95 +228,35 @@ node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: ini
 
 ## 5. Workflow Preferences
 
-**Round 1 — Core workflow settings (4 questions):**
+**Use sensible defaults. Ask ONE question:**
 
 ```
 questions: [
   {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Depth",
-    question: "How thorough should planning be?",
-    multiSelect: false,
-    options: [
-      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
-      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Execution",
-    question: "Run plans in parallel?",
+    header: "Settings",
+    question: "Use recommended settings? (Interactive, standard depth, all quality agents, balanced models)",
     multiSelect: false,
     options: [
-      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
-      { label: "Sequential", description: "One plan at a time" }
+      { label: "Yes (Recommended)", description: "Best for client projects — all quality gates enabled" },
+      { label: "Quick mode", description: "Faster: skip research, fewer phases (3-5), budget models" },
+      { label: "Customize", description: "Choose each setting individually" }
     ]
-  },
-  // Git Tracking: always committed. Removed as a question — .planning/ must be in git for team collaboration and portal sync.
+  }
 ]
 ```
 
-**Round 2 — Workflow agents:**
-
-These spawn additional agents during planning/execution. They add tokens and time but improve quality.
-
-| Agent | When it runs | What it does |
-|-------|--------------|--------------|
-| **Researcher** | Before planning each phase | Investigates domain, finds patterns, surfaces gotchas |
-| **Plan Checker** | After plan is created | Verifies plan actually achieves the phase goal |
-| **Verifier** | After phase execution | Confirms must-haves were delivered |
+**If "Yes (Recommended)":** Use all defaults below.
+**If "Quick mode":** Use quick defaults (depth: quick, research: false, plan_check: false, model_profile: budget).
+**If "Customize":** Show individual options for mode, depth, execution, research, plan_check, verifier, model_profile as separate AskUserQuestion calls.
 
-All recommended for important projects. Skip for quick experiments.
-
-```
-questions: [
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "Model Profile",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
-    ]
-  }
-]
-```
+**Defaults (Recommended):**
+- mode: interactive
+- depth: standard (5-8 phases)
+- parallelization: true
+- model_profile: balanced
+- workflow.research: true
+- workflow.plan_check: true
+- workflow.verifier: true
 
 Create `.planning/config.json` with all settings:
 
@@ -345,22 +283,19 @@ Create `.planning/config.json` with all settings:
 node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
 ```
 
-**Note:** Run `/qualia:settings` anytime to update these preferences.
+**Note:** Run `/qualia-settings` anytime to update these preferences.
 
 ## 5.5. Resolve Model Profile
 
 Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
 
-## 6. Research Decision
+## 6. Research Phase
 
-Use AskUserQuestion:
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stacks, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
+Check `config.json` → `workflow.research`. If true, run research. If false, skip to step 7.
+
+Do NOT ask the user again — this was already decided in step 5 (workflow preferences).
 
-**If "Research first":**
+**If research is enabled:**
 
 Display stage banner:
 ```
@@ -775,11 +710,7 @@ Create roadmap:
 3. Map every v1 requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
 5. Validate 100% coverage
-6. **MANDATORY: After all feature phases, add these 3 final phases:**
-   - **Quality Review & Polish** — code review (/qualia-review), design polish (/critique → /polish → /harden), fix all issues. No new features.
-   - **Deploy & Verify** — deploy to production (/ship), 5-check post-deploy verification (HTTP 200, auth, console, latency, UptimeRobot).
-   - **Client Handoff** — generate delivery document (/client-handoff), final production audit (/qualia-production-check), hand over credentials and docs.
-   These 3 phases are NOT optional for client projects. They ensure the project goes from "features done" to "client has their project."
+6. **FEATURE PHASES ONLY.** Do NOT add review, deploy, or handoff phases. The finish line system (/qualia-complete-milestone → polish → review → PR → deploy → handoff) handles the 70%-to-100% journey automatically after all feature phases are done. Adding them to the roadmap causes duplication.
 7. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
 8. Return ROADMAP CREATED with summary
 
@@ -950,25 +881,17 @@ Note in STATE.md: `env_setup: pending` so future commands can warn.
 **Check if project involves frontend work:**
 
 ```bash
-# Detect from roadmap, requirements, or project type
 HAS_FRONTEND=$(grep -qiE 'website|landing|dashboard|ui|frontend|page|component|SaaS|web app' .planning/PROJECT.md .planning/ROADMAP.md 2>/dev/null && echo "true" || echo "false")
 ```
 
-**If `HAS_FRONTEND` is true:** Run `/critique` to gather design context.
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► DESIGN CONTEXT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+**If `HAS_FRONTEND` is true:** Run a brief design consultation (NOT `/critique` — there's no code to critique yet).
 
-Execute the critique skill:
-1. Read `/home/qualia/.claude/skills/critique/SKILL.md`
-2. Follow its process: scan codebase for existing design patterns, ask UX-focused questions, write Design Context section
-3. The skill persists design context to the project's CLAUDE.md (or `.claude/` config)
+Ask the employee 3 questions using AskUserQuestion:
+1. **Aesthetic direction** — "What feel should this project have?" (options: Clean/minimal, Bold/striking, Warm/friendly, Corporate/professional)
+2. **Color palette** — "Any brand colors or preferences?" (freeform — or offer to pick based on aesthetic)
+3. **Reference sites** — "Any websites you'd like it to look/feel like?" (freeform)
 
-This runs ONCE per project. All subsequent `/qualia:execute-phase` runs will have the design context available for the frontend-master skill and the diagnostic design pass.
+Write `.planning/DESIGN.md` with the answers structured as a design brief. This is read by the frontend guard before any UI work starts.
 
 **If `HAS_FRONTEND` is false:** Skip silently.
 
@@ -1051,8 +974,8 @@ Present completion with next steps:
 - [ ] ROADMAP.md created with phases, requirement mappings, success criteria
 - [ ] STATE.md initialized
 - [ ] REQUIREMENTS.md traceability updated
-- [ ] If frontend project: `/critique` run to set design context
-- [ ] User knows next step is `/qualia:discuss-phase 1`
+- [ ] If frontend project: DESIGN.md created with design brief
+- [ ] User knows next step is `/qualia-discuss-phase 1`
 
 **Atomic commits:** Each phase commits its artifacts immediately. If context is lost, artifacts persist.