qualia-framework 2.6.0 → 3.1.0

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

@@ -1,982 +0,0 @@
-<purpose>
-Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-## 1. Setup
-
-**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-project)
-```
-
-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 `has_git` is false:** Initialize git:
-```bash
-git init
-```
-
-## 1.5. Scan Uploaded Files for Tech Stack Conflicts
-
-**Before asking any questions**, check if the user placed files in the project directory:
-
-```bash
-ls *.pdf *.docx *.doc *.txt *.md *.png *.jpg *.jpeg 2>/dev/null | head -10
-```
-
-If files are found, read them. If ANY file mentions a tech stack that differs from the Qualia standard (Next.js + React + TypeScript + Supabase + Vercel), you MUST ask the user:
-
-Use AskUserQuestion:
-- header: "Tech Stack"
-- question: "The uploaded document mentions {detected stack}. Which stack should we use?"
-- options:
-  - "Qualia stack (Recommended)" — Next.js + React + TypeScript + Supabase + Vercel. This is what we build with.
-  - "Document stack" — Use {detected stack} as specified in the document. The workflow adapts.
-
-**Never silently adopt a non-Qualia stack from uploaded documents.** Always confirm first.
-
-If no files found or no stack conflict: skip silently.
-
-## 2. Brownfield Offer
-
-**If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
-
-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)
-  - "Skip mapping" — Proceed with project initialization
-
-**If "Map codebase first":**
-
-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.
-
-## 3. Deep Questioning
-
-**Display stage banner:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► QUESTIONING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Open the conversation:**
-
-Ask inline (freeform, NOT AskUserQuestion):
-
-"What do you want to build?"
-
-Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
-
-**Follow the thread:**
-
-Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
-
-Keep following threads. Each answer opens new threads to explore. Ask about:
-- What excited them
-- What problem sparked this
-- What they mean by vague terms
-- What it would actually look like
-- What's already decided
-
-Consult `questioning.md` for techniques:
-- Challenge vagueness
-- Make abstract concrete
-- Surface assumptions
-- Find edges
-- Reveal motivation
-
-**Check context (background, not out loud):**
-
-As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
-
-**Decision gate:**
-
-When you could write a clear PROJECT.md, use AskUserQuestion:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-## 3.5. Template Selection
-
-**Detect project type from questioning answers.** Look for signals:
-- "website", "landing page", "marketing site", "SaaS" → `website`
-- "chatbot", "AI assistant", "chat agent", "AI agent" → `ai-agent`
-- "voice agent", "phone agent", "call bot", "VAPI", "Retell" → `voice-agent`
-- "mobile app", "iOS", "Android", "React Native", "Expo" → `mobile-app`
-
-**If a project type is detected:**
-
-Use AskUserQuestion:
-- header: "Template"
-- question: "This looks like a {type} project. Use the {type} template? Pre-populates standard phases so you only plan what's unique."
-- options:
-  - "Use template (Recommended)" — Pre-populate phases from {type} template, customize during roadmap
-  - "Skip template" — Build roadmap from scratch through full questioning
-
-**If "Use template":**
-1. Read the template: `~/.claude/qualia-framework/templates/projects/{type}.md`
-2. Store template choice in memory for Step 8 (roadmap creation)
-3. Set `template_type` = detected type
-4. Set `template_phases` = phases from template file
-
-**If "Skip template" OR no type detected:** Continue normally. Set `template_type` = null.
-
-## 4. Write PROJECT.md
-
-Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
-
-**For greenfield projects:**
-
-Initialize requirements as hypotheses:
-
-```markdown
-## Requirements
-
-### Validated
-
-(None yet — ship to validate)
-
-### Active
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-```
-
-All Active requirements are hypotheses until shipped and validated.
-
-**For brownfield projects (codebase map exists):**
-
-Infer Validated requirements from existing code:
-
-1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
-2. Identify what the codebase already does
-3. These become the initial Validated set
-
-```markdown
-## Requirements
-
-### Validated
-
-- ✓ [Existing capability 1] — existing
-- ✓ [Existing capability 2] — existing
-- ✓ [Existing capability 3] — existing
-
-### Active
-
-- [ ] [New requirement 1]
-- [ ] [New requirement 2]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-```
-
-**Key Decisions:**
-
-Initialize with any decisions made during questioning:
-
-```markdown
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice from questioning] | [Why] | — Pending |
-```
-
-**Last updated footer:**
-
-```markdown
----
-*Last updated: [date] after initialization*
-```
-
-Do not compress. Capture everything gathered.
-
-**Commit PROJECT.md:**
-
-```bash
-mkdir -p .planning
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
-```
-
-## 5. Workflow Preferences
-
-**Use sensible defaults. Ask ONE question:**
-
-```
-questions: [
-  {
-    header: "Settings",
-    question: "Use recommended settings? (Interactive, standard depth, all quality agents, balanced models)",
-    multiSelect: false,
-    options: [
-      { 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" }
-    ]
-  }
-]
-```
-
-**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.
-
-**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:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "depth": "quick|standard|comprehensive",
-  "parallelization": true|false,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false
-  }
-}
-```
-
-**commit_docs is always true.** Never add `.planning/` to `.gitignore` — it must be tracked for team collaboration and portal sync.
-
-**Commit config.json:**
-
-```bash
-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.
-
-## 5.5. Resolve Model Profile
-
-Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
-
-## 6. Research Phase
-
-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 is enabled:**
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► RESEARCHING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Researching [domain] ecosystem...
-```
-
-Create research directory:
-```bash
-mkdir -p .planning/research
-```
-
-**Determine milestone context:**
-
-Check if this is greenfield or subsequent milestone:
-- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
-- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
-
-Display spawning indicator:
-```
-◆ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
-```
-
-Spawn 4 parallel qualia-project-researcher agents with rich context:
-
-```
-Task(prompt="First, read /home/qualia/.claude/agents/qualia-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Stack dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: Research the standard stack for building [domain] from scratch.
-Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
-</milestone_context>
-
-<question>
-What's the standard 2025 stack for [domain]?
-</question>
-
-<project_context>
-[PROJECT.md summary - core value, constraints, what they're building]
-</project_context>
-
-<downstream_consumer>
-Your STACK.md feeds into roadmap creation. Be prescriptive:
-- Specific libraries with versions
-- Clear rationale for each choice
-- What NOT to use and why
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Versions are current (verify with Context7/official docs, not training data)
-- [ ] Rationale explains WHY, not just WHAT
-- [ ] Confidence levels assigned to each recommendation
-</quality_gate>
-
-<output>
-Write to: .planning/research/STACK.md
-Use template: /home/qualia/.claude/qualia-framework/templates/research-project/STACK.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
-
-Task(prompt="First, read /home/qualia/.claude/agents/qualia-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Features dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What features do [domain] products have? What's table stakes vs differentiating?
-Subsequent: How do [target features] typically work? What's expected behavior?
-</milestone_context>
-
-<question>
-What features do [domain] products have? What's table stakes vs differentiating?
-</question>
-
-<project_context>
-[PROJECT.md summary]
-</project_context>
-
-<downstream_consumer>
-Your FEATURES.md feeds into requirements definition. Categorize clearly:
-- Table stakes (must have or users leave)
-- Differentiators (competitive advantage)
-- Anti-features (things to deliberately NOT build)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
-- [ ] Complexity noted for each feature
-- [ ] Dependencies between features identified
-</quality_gate>
-
-<output>
-Write to: .planning/research/FEATURES.md
-Use template: /home/qualia/.claude/qualia-framework/templates/research-project/FEATURES.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
-
-Task(prompt="First, read /home/qualia/.claude/agents/qualia-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Architecture dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: How are [domain] systems typically structured? What are major components?
-Subsequent: How do [target features] integrate with existing [domain] architecture?
-</milestone_context>
-
-<question>
-How are [domain] systems typically structured? What are major components?
-</question>
-
-<project_context>
-[PROJECT.md summary]
-</project_context>
-
-<downstream_consumer>
-Your ARCHITECTURE.md informs phase structure in roadmap. Include:
-- Component boundaries (what talks to what)
-- Data flow (how information moves)
-- Suggested build order (dependencies between components)
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Components clearly defined with boundaries
-- [ ] Data flow direction explicit
-- [ ] Build order implications noted
-</quality_gate>
-
-<output>
-Write to: .planning/research/ARCHITECTURE.md
-Use template: /home/qualia/.claude/qualia-framework/templates/research-project/ARCHITECTURE.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
-
-Task(prompt="First, read /home/qualia/.claude/agents/qualia-project-researcher.md for your role and instructions.
-
-<research_type>
-Project Research — Pitfalls dimension for [domain].
-</research_type>
-
-<milestone_context>
-[greenfield OR subsequent]
-
-Greenfield: What do [domain] projects commonly get wrong? Critical mistakes?
-Subsequent: What are common mistakes when adding [target features] to [domain]?
-</milestone_context>
-
-<question>
-What do [domain] projects commonly get wrong? Critical mistakes?
-</question>
-
-<project_context>
-[PROJECT.md summary]
-</project_context>
-
-<downstream_consumer>
-Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
-- Warning signs (how to detect early)
-- Prevention strategy (how to avoid)
-- Which phase should address it
-</downstream_consumer>
-
-<quality_gate>
-- [ ] Pitfalls are specific to this domain (not generic advice)
-- [ ] Prevention strategies are actionable
-- [ ] Phase mapping included where relevant
-</quality_gate>
-
-<output>
-Write to: .planning/research/PITFALLS.md
-Use template: /home/qualia/.claude/qualia-framework/templates/research-project/PITFALLS.md
-</output>
-", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
-```
-
-After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
-
-```
-Task(prompt="
-<task>
-Synthesize research outputs into SUMMARY.md.
-</task>
-
-<research_files>
-Read these files:
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
-</research_files>
-
-<output>
-Write to: .planning/research/SUMMARY.md
-Use template: /home/qualia/.claude/qualia-framework/templates/research-project/SUMMARY.md
-Commit after writing.
-</output>
-", subagent_type="qualia-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
-```
-
-Display research complete banner and key findings:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Key Findings
-
-**Stack:** [from SUMMARY.md]
-**Table Stakes:** [from SUMMARY.md]
-**Watch Out For:** [from SUMMARY.md]
-
-Files: `.planning/research/`
-```
-
-**If "Skip research":** Continue to Step 7.
-
-## 7. Define Requirements
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► DEFINING REQUIREMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Load context:**
-
-Read PROJECT.md and extract:
-- Core value (the ONE thing that must work)
-- Stated constraints (budget, timeline, tech limitations)
-- Any explicit scope boundaries
-
-**If research exists:** Read research/FEATURES.md and extract feature categories.
-
-**Present features by category:**
-
-```
-Here are the features for [domain]:
-
-## Authentication
-**Table stakes:**
-- Sign up with email/password
-- Email verification
-- Password reset
-- Session management
-
-**Differentiators:**
-- Magic link login
-- OAuth (Google, GitHub)
-- 2FA
-
-**Research notes:** [any relevant notes]
-
----
-
-## [Next Category]
-...
-```
-
-**If no research:** Gather requirements through conversation instead.
-
-Ask: "What are the main things users need to be able to do?"
-
-For each capability mentioned:
-- Ask clarifying questions to make it specific
-- Probe for related capabilities
-- Group into categories
-
-**Scope each category:**
-
-For each category, use AskUserQuestion:
-
-- header: "[Category name]"
-- question: "Which [category] features are in v1?"
-- multiSelect: true
-- options:
-  - "[Feature 1]" — [brief description]
-  - "[Feature 2]" — [brief description]
-  - "[Feature 3]" — [brief description]
-  - "None for v1" — Defer entire category
-
-Track responses:
-- Selected features → v1 requirements
-- Unselected table stakes → v2 (users expect these)
-- Unselected differentiators → out of scope
-
-**Identify gaps:**
-
-Use AskUserQuestion:
-- header: "Additions"
-- question: "Any requirements research missed? (Features specific to your vision)"
-- options:
-  - "No, research covered it" — Proceed
-  - "Yes, let me add some" — Capture additions
-
-**Validate core value:**
-
-Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
-
-**Generate REQUIREMENTS.md:**
-
-Create `.planning/REQUIREMENTS.md` with:
-- v1 Requirements grouped by category (checkboxes, REQ-IDs)
-- v2 Requirements (deferred)
-- Out of Scope (explicit exclusions with reasoning)
-- Traceability section (empty, filled by roadmap)
-
-**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
-
-**Requirement quality criteria:**
-
-Good requirements are:
-- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
-- **User-centric:** "User can X" (not "System does Y")
-- **Atomic:** One capability per requirement (not "User can login and manage profile")
-- **Independent:** Minimal dependencies on other requirements
-
-Reject vague requirements. Push for specificity:
-- "Handle authentication" → "User can log in with email/password and stay logged in across sessions"
-- "Support sharing" → "User can share post via link that opens in recipient's browser"
-
-**Present full requirements list:**
-
-Show every requirement (not counts) for user confirmation:
-
-```
-## v1 Requirements
-
-### Authentication
-- [ ] **AUTH-01**: User can create account with email/password
-- [ ] **AUTH-02**: User can log in and stay logged in across sessions
-- [ ] **AUTH-03**: User can log out from any page
-
-### Content
-- [ ] **CONT-01**: User can create posts with text
-- [ ] **CONT-02**: User can edit their own posts
-
-[... full list ...]
-
----
-
-Does this capture what you're building? (yes / adjust)
-```
-
-If "adjust": Return to scoping.
-
-**Commit requirements:**
-
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
-```
-
-## 8. Create Roadmap
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► CREATING ROADMAP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning roadmapper...
-```
-
-Spawn qualia-roadmapper agent with context:
-
-```
-Task(prompt="
-<planning_context>
-
-**Project:**
-@.planning/PROJECT.md
-
-**Requirements:**
-@.planning/REQUIREMENTS.md
-
-**Research (if exists):**
-@.planning/research/SUMMARY.md
-
-**Config:**
-@.planning/config.json
-
-</planning_context>
-
-<template_context>
-Template type: {template_type or 'none'}
-{If template_type is set, inline the full template file content from ~/.claude/qualia-framework/templates/projects/{template_type}.md}
-</template_context>
-
-<instructions>
-Create roadmap:
-1. If template provided: use template phases as starting structure, merge with project-specific requirements. Mark template-sourced phases with `source: template`. Add skill references and team fields from template.
-2. If no template: derive phases from requirements (don't impose structure)
-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. **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
-
-Write files first, then return. This ensures artifacts persist even if context is lost.
-</instructions>
-", subagent_type="qualia-roadmapper", model="{roadmapper_model}", description="Create roadmap")
-```
-
-**Handle roadmapper return:**
-
-**If `## ROADMAP BLOCKED`:**
-- Present blocker information
-- Work with user to resolve
-- Re-spawn when resolved
-
-**If `## ROADMAP CREATED`:**
-
-Read the created ROADMAP.md and present it nicely inline:
-
-```
----
-
-## 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] |
-| 3 | [Name] | [Goal] | [REQ-IDs] | [count] |
-...
-
-### Phase Details
-
-**Phase 1: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-3. [criterion]
-
-**Phase 2: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-
-[... continue for all phases ...]
-
----
-```
-
-**CRITICAL: Ask for approval before committing:**
-
-Use AskUserQuestion:
-- header: "Roadmap"
-- question: "Does this roadmap structure work for you?"
-- options:
-  - "Approve" — Commit and continue
-  - "Adjust phases" — Tell me what to change
-  - "Review full file" — Show raw ROADMAP.md
-
-**If "Approve":** Continue to commit.
-
-**If "Adjust phases":**
-- Get user's adjustment notes
-- Re-spawn roadmapper with revision context:
-  ```
-  Task(prompt="
-  <revision>
-  User feedback on roadmap:
-  [user's notes]
-
-  Current ROADMAP.md: @.planning/ROADMAP.md
-
-  Update the roadmap based on feedback. Edit files in place.
-  Return ROADMAP REVISED with changes made.
-  </revision>
-  ", subagent_type="qualia-roadmapper", model="{roadmapper_model}", description="Revise roadmap")
-  ```
-- Present revised roadmap
-- Loop until user approves
-
-**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.
-
-**Commit roadmap (after approval):**
-
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
-```
-
-## 9. Environment Setup
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► ENVIRONMENT SETUP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Detect what's needed based on project type and stack:**
-
-Check PROJECT.md and research/STACK.md for:
-- Supabase → needs project creation or linking
-- Vercel → needs project linking
-- Environment variables → needs `.env.local`
-- External services (Stripe, VAPI, etc.) → needs API keys
-
-**Present setup checklist:**
-
-Use AskUserQuestion:
-- header: "Env Setup"
-- question: "Let's set up the development environment. Which of these are ready?"
-- multiSelect: true
-- options (dynamically generated from detection):
-  - "Supabase project exists" — I have a Supabase project ready to link
-  - "Vercel project exists" — I have a Vercel project ready
-  - "I'll set these up now" — Walk me through creating them
-  - "Skip for now" — I'll handle environment setup myself later
-
-**If "I'll set these up now":**
-
-Walk through each needed service:
-
-1. **Supabase** (if detected):
-   ```bash
-   supabase init  # If no supabase/ directory
-   supabase link --project-ref <ref>  # User provides ref
-   ```
-
-2. **Vercel** (if detected):
-   ```bash
-   vercel link  # Interactive linking
-   ```
-
-3. **Environment variables:**
-   Create `.env.local` with placeholders:
-   ```bash
-   cat > .env.local << 'EOF'
-   # Supabase
-   NEXT_PUBLIC_SUPABASE_URL=
-   NEXT_PUBLIC_SUPABASE_ANON_KEY=
-   SUPABASE_SERVICE_ROLE_KEY=
-
-   # Add other detected services...
-   EOF
-   ```
-
-   Tell user: "Fill in the values from your Supabase dashboard (Settings → API). I'll wait."
-
-4. **Verify setup:**
-   ```bash
-   # Check Supabase connection
-   supabase status 2>/dev/null
-
-   # Check env vars are populated (not empty)
-   grep -c "=$" .env.local  # Should be 0 if all filled
-   ```
-
-**If "Skip for now":**
-Note in STATE.md: `env_setup: pending` so future commands can warn.
-
-## 9.5. Design Context (frontend projects)
-
-**Check if project involves frontend work:**
-
-```bash
-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 a brief design consultation (NOT `/critique` — there's no code to critique yet).
-
-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)
-
-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.
-
-**Commit setup:**
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "chore: environment setup" --files .env.local supabase/config.toml
-```
-
-Ensure `.env.local` is in `.gitignore` (create/append if needed).
-
-## 10. Done
-
-Present completion with next steps:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► PROJECT INITIALIZED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**[Project Name]**
-
-| Artifact       | Location                    |
-|----------------|-----------------------------|
-| Project        | `.planning/PROJECT.md`      |
-| Config         | `.planning/config.json`     |
-| Research       | `.planning/research/`       |
-| Requirements   | `.planning/REQUIREMENTS.md` |
-| Roadmap        | `.planning/ROADMAP.md`      |
-| Environment    | `.env.local`                |
-
-**[N] phases** | **[X] requirements** | Ready to build ✓
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
-
-/qualia-plan-phase 1 — plan the first phase
-
-**Also available:**
-- /qualia-discuss-phase 1 — discuss approach before planning
-
-───────────────────────────────────────────────────────────────
-```
-
-</process>
-
-<output>
-
-- `.planning/PROJECT.md`
-- `.planning/config.json`
-- `.planning/research/` (if research selected)
-  - `STACK.md`
-  - `FEATURES.md`
-  - `ARCHITECTURE.md`
-  - `PITFALLS.md`
-  - `SUMMARY.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
-
-</output>
-
-<success_criteria>
-
-- [ ] .planning/ directory created
-- [ ] Git repo initialized
-- [ ] Brownfield detection completed
-- [ ] Deep questioning completed (threads followed, not rushed)
-- [ ] PROJECT.md captures full context → **committed**
-- [ ] config.json has workflow mode, depth, parallelization → **committed**
-- [ ] Research completed (if selected) — 4 parallel agents spawned → **committed**
-- [ ] Requirements gathered (from research or conversation)
-- [ ] User scoped each category (v1/v2/out of scope)
-- [ ] REQUIREMENTS.md created with REQ-IDs → **committed**
-- [ ] qualia-roadmapper spawned with context
-- [ ] Roadmap files written immediately (not draft)
-- [ ] User feedback incorporated (if any)
-- [ ] ROADMAP.md created with phases, requirement mappings, success criteria
-- [ ] STATE.md initialized
-- [ ] REQUIREMENTS.md traceability updated
-- [ ] 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.
-
-</success_criteria>