qualia-framework 2.6.0 → 3.1.0

package/framework/qualia-framework/workflows/progress.md

@@ -1,389 +0,0 @@
-<purpose>
-Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="init_context">
-**Load progress context:**
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init progress)
-```
-
-Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`.
-
-If `project_exists` is false (no `.planning/` directory):
-
-```
-No planning structure found.
-
-Run /qualia-new-project to start a new project.
-```
-
-Exit.
-
-If missing STATE.md: suggest `/qualia-new-project`.
-
-**If ROADMAP.md missing but PROJECT.md exists:**
-
-This means a milestone was completed and archived. Go to **Route F** (between milestones).
-
-If missing both ROADMAP.md and PROJECT.md: suggest `/qualia-new-project`.
-</step>
-
-<step name="load">
-**Load full project context:**
-
-- Read `.planning/STATE.md` for living memory (position, decisions, issues)
-- Read `.planning/ROADMAP.md` for phase structure and objectives
-- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
-- Read `.planning/config.json` for settings (model_profile, workflow toggles)
-  </step>
-
-<step name="recent">
-**Gather recent work context:**
-
-- Find the 2-3 most recent SUMMARY.md files
-- Extract from each: what was accomplished, key decisions, any issues logged
-- This shows "what we've been working on"
-  </step>
-
-<step name="position">
-**Parse current position from init context:**
-
-- Use `current_phase` and `next_phase` from init for position
-- Use `phases` array for plan counts per phase
-- Note `paused_at` if work was paused
-- Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
-- Count pending todos: use `init todos` or `list-todos`
-- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
-  </step>
-
-<step name="report">
-**Present rich status report:**
-
-```
-# [Project Name]
-
-**Progress:** [████████░░] 8/10 plans complete
-**Overall:**  [██████░░░░] ~70% to client-ready  {only show if all phases done}
-**Profile:** [quality/balanced/budget]
-
-## Recent Work
-- [Phase X, Plan Y]: [what was accomplished - 1 line]
-- [Phase X, Plan Z]: [what was accomplished - 1 line]
-
-## Current Position
-Phase [N] of [total]: [phase-name]
-Plan [M] of [phase-total]: [status]
-CONTEXT: [✓ if CONTEXT.md exists | - if not]
-
-## Key Decisions Made
-- [decision 1 from STATE.md]
-- [decision 2]
-
-## Blockers/Concerns
-- [any blockers or concerns from STATE.md]
-
-## Pending Todos
-- [count] pending — /qualia-check-todos to review
-
-## Active Debug Sessions
-- [count] active — /qualia-debug to continue
-(Only show this section if count > 0)
-
-## What's Next
-[Next phase/plan objective from ROADMAP]
-```
-
-</step>
-
-<step name="route">
-**Determine next action based on verified counts.**
-
-**Step 1: Count plans, summaries, and issues in current phase**
-
-List files in the current phase directory:
-
-```bash
-ls -1 .planning/phases/[current-phase-dir]/*-PLAN.md 2>/dev/null | wc -l
-ls -1 .planning/phases/[current-phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l
-ls -1 .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null | wc -l
-```
-
-State: "This phase has {X} plans, {Y} summaries."
-
-**Step 1.5: Check for unaddressed UAT gaps**
-
-Check for UAT.md files with status "diagnosed" (has gaps needing fixes).
-
-```bash
-# Check for diagnosed UAT with gaps
-grep -l "status: diagnosed" .planning/phases/[current-phase-dir]/*-UAT.md 2>/dev/null
-```
-
-Track:
-- `uat_with_gaps`: UAT.md files with status "diagnosed" (gaps need fixing)
-
-**Step 2: Route based on counts**
-
-| Condition | Meaning | Action |
-|-----------|---------|--------|
-| uat_with_gaps > 0 | UAT gaps need fix plans | Go to **Route E** |
-| summaries < plans | Unexecuted plans exist | Go to **Route A** |
-| summaries = plans AND plans > 0 | Phase complete | Go to Step 3 |
-| plans = 0 | Phase not yet planned | Go to **Route B** |
-
----
-
-**Route A: Unexecuted plan exists**
-
-Find the first PLAN.md without matching SUMMARY.md.
-Read its `<objective>` section.
-
-```
----
-
-## ▶ Next Up
-
-**{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md]
-
-`/qualia-execute-phase {phase}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
----
-
-**Route B: Phase needs planning**
-
-Check if `{phase}-CONTEXT.md` exists in phase directory.
-
-**If CONTEXT.md exists:**
-
-```
----
-
-## ▶ Next Up
-
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>✓ Context gathered, ready to plan</sub>
-
-`/qualia-plan-phase {phase-number}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-**If CONTEXT.md does NOT exist:**
-
-```
----
-
-## ▶ Next Up
-
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-
-`/qualia-discuss-phase {phase}` — gather context and clarify approach
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia-plan-phase {phase}` — skip discussion, plan directly
-- `/qualia-list-phase-assumptions {phase}` — see Claude's assumptions
-
----
-```
-
----
-
-**Route E: UAT gaps need fix plans**
-
-UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
-
-```
----
-
-## ⚠ UAT Gaps Found
-
-**{phase}-UAT.md** has {N} gaps requiring fixes.
-
-`/qualia-plan-phase {phase} --gaps`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia-execute-phase {phase}` — execute phase plans
-- `/qualia-verify-work {phase}` — run more UAT testing
-
----
-```
-
----
-
-**Step 3: Check milestone status (only when phase complete)**
-
-Read ROADMAP.md and identify:
-1. Current phase number
-2. All phase numbers in the current milestone section
-
-Count total phases and identify the highest phase number.
-
-State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
-
-**Route based on milestone status:**
-
-| Condition | Meaning | Action |
-|-----------|---------|--------|
-| current phase < highest phase | More phases remain | Go to **Route C** |
-| current phase = highest phase | Milestone complete | Go to **Route D** |
-
----
-
-**Route C: Phase complete, more phases remain**
-
-Read ROADMAP.md to get the next phase's name and goal.
-
-```
----
-
-## ✓ Phase {Z} Complete
-
-## ▶ Next Up
-
-**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
-
-`/qualia-discuss-phase {Z+1}` — gather context and clarify approach
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/qualia-plan-phase {Z+1}` — skip discussion, plan directly
-- `/qualia-verify-work {Z}` — user acceptance test before continuing
-
----
-```
-
----
-
-**Route D: Milestone complete (needs archiving)**
-
-```
----
-
-## Milestone phases done!
-
-All {N} phases finished. Time to archive.
-
-## ▶ Next Up
-
-**Archive Milestone** — then the finish line begins
-
-`/qualia-complete-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
----
-
-**Route G: Finish Line (post-milestone, 70% → 100%)**
-
-Check STATE.md for `finish_line` field. If milestone is archived but `finish_line` is not `"complete"`, the project is in the finish line.
-
-```
----
-
-## ── FINISH LINE ── Getting Client-Ready
-
-Features are built. Now polish, review, and ship.
-
-  ── Progress to Client-Ready ──────────
-  ✓ Build phases       complete
-  ✓ Milestone audit    passed
-  ✓ Milestone archived
-  {▶ or ✓} Design polish      {← you are here | done}
-  {▶ or · or ✓} Code review
-  {▶ or · or ✓} Pull request
-  {· or ✓} Deploy (Fawzi reviews + deploys)
-  {· or ✓} Client handoff
-
-## ▶ Next Up
-
-{Based on finish_line value in STATE.md:}
-  "needs_polish" → `/critique` — then `/polish` then `/harden`
-  "needs_review" → `/qualia-review --web` (or `--ai` for AI/voice projects)
-  "needs_pr"     → `/pr` — create pull request for Fawzi
-  "ready_for_deploy" → "Waiting for Fawzi to review PR and deploy."
-  "deployed"     → `/client-handoff` — prepare delivery document
-
----
-```
-
-**Skip logic for finish line steps:**
-- If project has NO frontend (AI agent, voice agent, edge functions) → skip design polish, set `finish_line: "needs_review"`
-- If finish_line field doesn't exist but milestone is archived → set `finish_line: "needs_polish"` and show Route G
-
----
-
-**Route F: Between milestones (ROADMAP.md missing, PROJECT.md exists)**
-
-A milestone was completed and archived. Ready to start the next milestone cycle.
-
-Read MILESTONES.md to find the last completed milestone version.
-
-```
----
-
-## ✓ Milestone v{X.Y} Complete
-
-Ready to plan the next milestone.
-
-## ▶ Next Up
-
-**Start Next Milestone** — questioning → research → requirements → roadmap
-
-`/qualia-new-milestone`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-</step>
-
-<step name="edge_cases">
-**Handle edge cases:**
-
-- Phase complete but next phase not planned → offer `/qualia-plan-phase [next]`
-- All work complete → offer milestone completion
-- Blockers present → highlight before offering to continue
-- Handoff file exists → mention it, offer `/qualia-resume-work`
-  </step>
-
-</process>
-
-<success_criteria>
-
-- [ ] Rich context provided (recent work, decisions, issues)
-- [ ] Current position clear with visual progress
-- [ ] What's next clearly explained
-- [ ] Smart routing: /qualia-execute-phase if plans exist, /qualia-plan-phase if not
-- [ ] User confirms before any action
-- [ ] Seamless handoff to appropriate qualia command
-      </success_criteria>

package/framework/qualia-framework/workflows/quick.md

@@ -1,252 +0,0 @@
-<purpose>
-Execute small, ad-hoc tasks with Qualia guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier). Quick mode spawns qualia-planner (quick mode) + qualia-executor(s), tracks tasks in `.planning/quick/`, and updates STATE.md's "Quick Tasks Completed" table.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-**Step 1: Get task description**
-
-Prompt user interactively for the task description:
-
-```
-AskUserQuestion(
-  header: "Quick Task",
-  question: "What do you want to do?",
-  followUp: null
-)
-```
-
-Store response as `$DESCRIPTION`.
-
-If empty, re-prompt: "Please provide a task description."
-
----
-
-**Step 2: Initialize**
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init quick "$DESCRIPTION")
-```
-
-Parse JSON for: `planner_model`, `executor_model`, `commit_docs`, `next_num`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
-
-**If `roadmap_exists` is false:** Error — Quick mode requires an active project with ROADMAP.md. Run `/qualia:new-project` first.
-
-Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
-
----
-
-**Step 3: Create task directory**
-
-```bash
-mkdir -p "${task_dir}"
-```
-
----
-
-**Step 4: Create quick task directory**
-
-Create the directory for this quick task:
-
-```bash
-QUICK_DIR=".planning/quick/${next_num}-${slug}"
-mkdir -p "$QUICK_DIR"
-```
-
-Report to user:
-```
-Creating quick task ${next_num}: ${DESCRIPTION}
-Directory: ${QUICK_DIR}
-```
-
-Store `$QUICK_DIR` for use in orchestration.
-
----
-
-**Step 5: Plan (planner or inline)**
-
-Check if `$ARGUMENTS` contains `--no-plan`. Strip the flag from `$DESCRIPTION` if present.
-
-**5a. If `--no-plan` flag is set:**
-
-Skip the planner agent entirely. Create a minimal inline plan directly:
-
-```markdown
-# Plan: ${next_num} — ${DESCRIPTION}
-
-**Mode:** quick (no-plan)
-**Created:** ${date}
-
-## Task 1: ${DESCRIPTION}
-
-**What:** ${DESCRIPTION}
-**Files:** (determine from context)
-**Done when:** Change is applied and verified
-```
-
-Write this to `${QUICK_DIR}/${next_num}-PLAN.md` using the Write tool.
-Report: "Inline plan created (--no-plan): ${QUICK_DIR}/${next_num}-PLAN.md"
-
-**5b. If normal mode (no flag):**
-
-Spawn qualia-planner with quick mode context:
-
-```
-Task(
-  prompt="
-<planning_context>
-
-**Mode:** quick
-**Directory:** ${QUICK_DIR}
-**Description:** ${DESCRIPTION}
-
-**Project State:**
-@.planning/STATE.md
-
-</planning_context>
-
-<constraints>
-- Create a SINGLE plan with 1-3 focused tasks
-- Quick tasks should be atomic and self-contained
-- No research phase, no checker phase
-- Target ~30% context usage (simple, focused)
-</constraints>
-
-<output>
-Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
-Return: ## PLANNING COMPLETE with plan path
-</output>
-",
-  subagent_type="qualia-planner",
-  model="{planner_model}",
-  description="Quick plan: ${DESCRIPTION}"
-)
-```
-
-After planner returns:
-1. Verify plan exists at `${QUICK_DIR}/${next_num}-PLAN.md`
-2. Extract plan count (typically 1 for quick tasks)
-3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md"
-
-If plan not found, error: "Planner failed to create ${next_num}-PLAN.md"
-
----
-
-**Step 6: Spawn executor**
-
-Spawn qualia-executor with plan reference:
-
-```
-Task(
-  prompt="
-Execute quick task ${next_num}.
-
-Plan: @${QUICK_DIR}/${next_num}-PLAN.md
-Project state: @.planning/STATE.md
-
-<constraints>
-- Execute all tasks in the plan
-- Commit each task atomically
-- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
-- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
-</constraints>
-",
-  subagent_type="qualia-executor",
-  model="{executor_model}",
-  description="Execute: ${DESCRIPTION}"
-)
-```
-
-After executor returns:
-1. Verify summary exists at `${QUICK_DIR}/${next_num}-SUMMARY.md`
-2. Extract commit hash from executor output
-3. Report completion status
-
-If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"
-
-Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.
-
----
-
-**Step 7: Update STATE.md**
-
-Update STATE.md with quick task completion record.
-
-**7a. Check if "Quick Tasks Completed" section exists:**
-
-Read STATE.md and check for `### Quick Tasks Completed` section.
-
-**7b. If section doesn't exist, create it:**
-
-Insert after `### Blockers/Concerns` section:
-
-```markdown
-### Quick Tasks Completed
-
-| # | Description | Date | Commit | Directory |
-|---|-------------|------|--------|-----------|
-```
-
-**7c. Append new row to table:**
-
-Use `date` from init:
-```markdown
-| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
-```
-
-**7d. Update "Last activity" line:**
-
-Use `date` from init:
-```
-Last activity: ${date} - Completed quick task ${next_num}: ${DESCRIPTION}
-```
-
-Use Edit tool to make these changes atomically
-
----
-
-**Step 8: Final commit and completion**
-
-Stage and commit quick task artifacts:
-
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs(quick-${next_num}): ${DESCRIPTION}" --files ${QUICK_DIR}/${next_num}-PLAN.md ${QUICK_DIR}/${next_num}-SUMMARY.md .planning/STATE.md
-```
-
-Get final commit hash:
-```bash
-commit_hash=$(git rev-parse --short HEAD)
-```
-
-Display completion output:
-```
----
-
-QUALIA > QUICK TASK COMPLETE
-
-Quick Task ${next_num}: ${DESCRIPTION}
-
-Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md
-Commit: ${commit_hash}
-
----
-
-Ready for next task: /qualia:quick
-```
-
-</process>
-
-<success_criteria>
-- [ ] ROADMAP.md validation passes
-- [ ] User provides task description
-- [ ] Slug generated (lowercase, hyphens, max 40 chars)
-- [ ] Next number calculated (001, 002, 003...)
-- [ ] Directory created at `.planning/quick/NNN-slug/`
-- [ ] `${next_num}-PLAN.md` created by planner
-- [ ] `${next_num}-SUMMARY.md` created by executor
-- [ ] STATE.md updated with quick task row
-- [ ] Artifacts committed
-</success_criteria>