qualia-framework 2.2.1 → 2.4.1

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

@@ -13,12 +13,12 @@ Read all files referenced by the invoking prompt's execution_context before star
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
 ```bash
-INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init new-project)
+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 `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.
 
@@ -137,7 +135,7 @@ Use AskUserQuestion:
   - "Skip template" — Build roadmap from scratch through full questioning
 
 **If "Use template":**
-1. Read the template: `~/.claude/qualia-engine/templates/projects/{type}.md`
+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
@@ -225,100 +223,40 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
 ```
 
 ## 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:**
+**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.
 
-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 |
-
-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:
 
@@ -342,25 +280,22 @@ Create `.planning/config.json` with all settings:
 **Commit config.json:**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
+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:
 ```
@@ -430,7 +365,7 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 Write to: .planning/research/STACK.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/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")
 
@@ -470,7 +405,7 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 
 <output>
 Write to: .planning/research/FEATURES.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/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")
 
@@ -510,7 +445,7 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 
 <output>
 Write to: .planning/research/ARCHITECTURE.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/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")
 
@@ -550,7 +485,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 Write to: .planning/research/PITFALLS.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/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")
 ```
@@ -573,7 +508,7 @@ Read these files:
 
 <output>
 Write to: .planning/research/SUMMARY.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/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")
@@ -729,7 +664,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 8. Create Roadmap
@@ -765,7 +700,7 @@ Task(prompt="
 
 <template_context>
 Template type: {template_type or 'none'}
-{If template_type is set, inline the full template file content from ~/.claude/qualia-engine/templates/projects/{template_type}.md}
+{If template_type is set, inline the full template file content from ~/.claude/qualia-framework/templates/projects/{template_type}.md}
 </template_context>
 
 <instructions>
@@ -775,8 +710,9 @@ 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. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-7. Return ROADMAP CREATED with summary
+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>
@@ -866,7 +802,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval):**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+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
@@ -945,31 +881,23 @@ 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.
+**If `HAS_FRONTEND` is true:** Run a brief design consultation (NOT `/critique` — there's no code to critique yet).
 
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► DESIGN CONTEXT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-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.
 
 **Commit setup:**
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "chore: environment setup" --files .env.local supabase/config.toml
+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).
@@ -1002,14 +930,10 @@ Present completion with next steps:
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/qualia:discuss-phase 1 — gather context and clarify approach
-
-<sub>/clear first → fresh context window</sub>
-
----
+/qualia-plan-phase 1 — plan the first phase
 
 **Also available:**
-- /qualia:plan-phase 1 — skip discussion, plan directly
+- /qualia-discuss-phase 1 — discuss approach before planning
 
 ───────────────────────────────────────────────────────────────
 ```
@@ -1050,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.