qualia-framework 2.5.1 → 3.1.0

package/framework/qualia-framework/workflows/plan-phase.md

@@ -1,422 +0,0 @@
-<purpose>
-Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification. Default flow: Research (if needed) -> Plan -> Verify -> Done. Orchestrates qualia-phase-researcher, qualia-planner, and qualia-plan-checker agents with a revision loop (max 3 iterations).
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-
-@/home/qualia/.claude/qualia-framework/references/ui-brand.md
-</required_reading>
-
-<process>
-
-## 1. Initialize
-
-Load all context in one call:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init plan-phase "$PHASE")
-```
-
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `planning_exists`, `roadmap_exists`.
-
-**If `planning_exists` is false:** Error — run `/qualia:new-project` first.
-
-## 2. Parse and Normalize Arguments
-
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`).
-
-**If no phase number:** Detect next unplanned phase from roadmap.
-
-**If `phase_found` is false:** Validate phase exists in ROADMAP.md. If valid, create the directory using `phase_slug` and `padded_phase` from init:
-```bash
-mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
-```
-
-**Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
-
-## 3. Validate Phase
-
-```bash
-PHASE_INFO=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js roadmap get-phase "${PHASE}")
-```
-
-**If `found` is false:** Error with available phases. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
-
-## 4. Load CONTEXT.md
-
-```bash
-CONTEXT_CONTENT=$(cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null)
-```
-
-**CRITICAL:** Store `CONTEXT_CONTENT` now — pass to researcher, planner, checker, and revision agents.
-
-If CONTEXT.md exists, display: `Using phase context from: ${PHASE_DIR}/*-CONTEXT.md`
-
-## 5. Handle Research
-
-**Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
-
-**If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
-
-**If RESEARCH.md missing OR `--research` flag:**
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► RESEARCHING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning researcher...
-```
-
-### Spawn qualia-phase-researcher
-
-```bash
-PHASE_DESC=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js roadmap get-phase "${PHASE}" | jq -r '.section')
-REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requirements" | head -50)
-STATE_SNAP=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js state-snapshot)
-# Extract decisions from state-snapshot JSON: jq '.decisions[] | "\(.phase): \(.summary) - \(.rationale)"'
-```
-
-Research prompt:
-
-```markdown
-<objective>
-Research how to implement Phase {phase_number}: {phase_name}
-Answer: "What do I need to know to PLAN this phase well?"
-</objective>
-
-<phase_context>
-IMPORTANT: If CONTEXT.md exists below, it contains user decisions from /qualia:discuss-phase.
-- **Decisions** = Locked — research THESE deeply, no alternatives
-- **Claude's Discretion** = Freedom areas — research options, recommend
-- **Deferred Ideas** = Out of scope — ignore
-
-{context_content}
-</phase_context>
-
-<additional_context>
-**Phase description:** {phase_description}
-**Requirements:** {requirements}
-**Prior decisions:** {decisions}
-</additional_context>
-
-<output>
-Write to: {phase_dir}/{phase}-RESEARCH.md
-</output>
-```
-
-```
-Task(
-  prompt="First, read /home/qualia/.claude/agents/qualia-phase-researcher.md for your role and instructions.\n\n" + research_prompt,
-  subagent_type="general-purpose",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-### Handle Researcher Return
-
-- **`## RESEARCH COMPLETE`:** Display confirmation, continue to step 6
-- **`## RESEARCH BLOCKED`:** Display blocker, offer: 1) Provide context, 2) Skip research, 3) Abort
-
-## 6. Check Existing Plans
-
-```bash
-ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null
-```
-
-**If exists:** Offer: 1) Add more plans, 2) View existing, 3) Replan from scratch.
-
-## 7. Read Context Files
-
-Read and store for planner agent (`@` syntax doesn't work across Task() boundaries):
-
-```bash
-STATE_CONTENT=$(cat .planning/STATE.md)
-ROADMAP_CONTENT=$(cat .planning/ROADMAP.md)
-REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
-RESEARCH_CONTENT=$(cat "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null)
-VERIFICATION_CONTENT=$(cat "${PHASE_DIR}"/*-VERIFICATION.md 2>/dev/null)
-UAT_CONTENT=$(cat "${PHASE_DIR}"/*-UAT.md 2>/dev/null)
-```
-
-## 8. Spawn qualia-planner Agent
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► PLANNING PHASE {X}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning planner...
-```
-
-Planner prompt:
-
-```markdown
-<planning_context>
-**Phase:** {phase_number}
-**Mode:** {standard | gap_closure}
-
-**Project State:** {state_content}
-**Roadmap:** {roadmap_content}
-**Requirements:** {requirements_content}
-
-**Phase Context:**
-IMPORTANT: If context exists below, it contains USER DECISIONS from /qualia:discuss-phase.
-- **Decisions** = LOCKED — honor exactly, do not revisit
-- **Claude's Discretion** = Freedom — make implementation choices
-- **Deferred Ideas** = Out of scope — do NOT include
-
-{context_content}
-
-**Research:** {research_content}
-**Gap Closure (if --gaps):** {verification_content} {uat_content}
-</planning_context>
-
-<downstream_consumer>
-Output consumed by /qualia:execute-phase. Plans need:
-- Frontmatter (wave, depends_on, files_modified, autonomous)
-- Tasks in XML format
-- Verification criteria
-- must_haves for goal-backward verification
-</downstream_consumer>
-
-<quality_gate>
-- [ ] PLAN.md files created in phase directory
-- [ ] Each plan has valid frontmatter
-- [ ] Tasks are specific and actionable
-- [ ] Dependencies correctly identified
-- [ ] Waves assigned for parallel execution
-- [ ] must_haves derived from phase goal
-</quality_gate>
-```
-
-```
-Task(
-  prompt="First, read /home/qualia/.claude/agents/qualia-planner.md for your role and instructions.\n\n" + filled_prompt,
-  subagent_type="general-purpose",
-  model="{planner_model}",
-  description="Plan Phase {phase}"
-)
-```
-
-## 9. Handle Planner Return
-
-- **`## PLANNING COMPLETE`:** Display plan count. If `--skip-verify` or `plan_checker_enabled` is false (from init): skip to step 13. Otherwise: step 10.
-- **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
-- **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
-
-## 9.5. Check files_modified Overlap
-
-Before running the plan-checker, scan ALL existing PLAN files across the project for `files_modified` overlap with the new plan(s).
-
-```bash
-# Collect files_modified from the NEW plans in this phase
-NEW_FILES=$(grep -h '^files_modified:' "${PHASE_DIR}"/*-PLAN.md 2>/dev/null | sed 's/^files_modified:\s*//' | tr -d '[]"' | tr ',' '\n' | sed 's/^ *//;s/ *$//' | sort -u)
-
-# Collect files_modified from ALL OTHER phase plans
-OTHER_FILES=$(find .planning/phases -maxdepth 3 -name '*-PLAN.md' -not -path "${PHASE_DIR}/*" 2>/dev/null | while read f; do
-  grep -h '^files_modified:' "$f" 2>/dev/null | sed 's/^files_modified:\s*//' | tr -d '[]"' | tr ',' '\n' | sed 's/^ *//;s/ *$//' | while read file; do
-    echo "$file|$(basename "$(dirname "$f")")|$(basename "$f")"
-  done
-done | sort)
-```
-
-Compare overlaps:
-
-```bash
-# For each file in the new plan, check if it appears in other plans
-OVERLAPS=""
-while IFS= read -r new_file; do
-  [ -z "$new_file" ] && continue
-  MATCHES=$(echo "$OTHER_FILES" | grep "^${new_file}|" || true)
-  if [ -n "$MATCHES" ]; then
-    OVERLAPS="${OVERLAPS}\n- \`${new_file}\` also modified in: $(echo "$MATCHES" | cut -d'|' -f2-3 | tr '\n' ', ')"
-  fi
-done <<< "$NEW_FILES"
-```
-
-**If overlaps found:** Present warning and require user acknowledgment before continuing:
-
-```
-## ⚠ files_modified Overlap Detected
-
-The following files appear in plans from BOTH this phase and other phases:
-
-{OVERLAPS}
-
-This may cause merge conflicts or unintended overwrites during execution.
-```
-
-Use AskUserQuestion:
-- "Acknowledged — proceed to plan verification" (continue to step 10)
-- "Review plans first" (display conflicting plans, then re-ask)
-- "Abort — fix plans manually" (exit)
-
-**If no overlaps:** Continue silently to step 10.
-
-## 10. Spawn qualia-plan-checker Agent
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► VERIFYING PLANS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning plan checker...
-```
-
-```bash
-PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
-```
-
-Checker prompt:
-
-```markdown
-<verification_context>
-**Phase:** {phase_number}
-**Phase Goal:** {goal from ROADMAP}
-
-**Plans to verify:** {plans_content}
-**Requirements:** {requirements_content}
-
-**Phase Context:**
-IMPORTANT: Plans MUST honor user decisions. Flag as issue if plans contradict.
-- **Decisions** = LOCKED — plans must implement exactly
-- **Claude's Discretion** = Freedom areas — plans can choose approach
-- **Deferred Ideas** = Out of scope — plans must NOT include
-
-{context_content}
-</verification_context>
-
-<expected_output>
-- ## VERIFICATION PASSED — all checks pass
-- ## ISSUES FOUND — structured issue list
-</expected_output>
-```
-
-```
-Task(
-  prompt=checker_prompt,
-  subagent_type="qualia-plan-checker",
-  model="{checker_model}",
-  description="Verify Phase {phase} plans"
-)
-```
-
-## 11. Handle Checker Return
-
-- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
-- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
-
-## 12. Revision Loop (Max 3 Iterations)
-
-Track `iteration_count` (starts at 1 after initial plan + check).
-
-**If iteration_count < 3:**
-
-Display: `Sending back to planner for revision... (iteration {N}/3)`
-
-```bash
-PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
-```
-
-Revision prompt:
-
-```markdown
-<revision_context>
-**Phase:** {phase_number}
-**Mode:** revision
-
-**Existing plans:** {plans_content}
-**Checker issues:** {structured_issues_from_checker}
-
-**Phase Context:**
-Revisions MUST still honor user decisions.
-{context_content}
-</revision_context>
-
-<instructions>
-Make targeted updates to address checker issues.
-Do NOT replan from scratch unless issues are fundamental.
-Return what changed.
-</instructions>
-```
-
-```
-Task(
-  prompt="First, read /home/qualia/.claude/agents/qualia-planner.md for your role and instructions.\n\n" + revision_prompt,
-  subagent_type="general-purpose",
-  model="{planner_model}",
-  description="Revise Phase {phase} plans"
-)
-```
-
-After planner returns -> spawn checker again (step 10), increment iteration_count.
-
-**If iteration_count >= 3:**
-
-Display: `Max iterations reached. {N} issues remain:` + issue list
-
-Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
-
-## 13. Present Final Status
-
-Route to `<offer_next>`.
-
-</process>
-
-<offer_next>
-Output this markdown directly (not as a code block):
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► PHASE {X} PLANNED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)
-
-| Wave | Plans | What it builds |
-|------|-------|----------------|
-| 1    | 01, 02 | [objectives] |
-| 2    | 03     | [objective]  |
-
-Research: {Completed | Used existing | Skipped}
-Verification: {Passed | Passed with override | Skipped}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Execute Phase {X}** — run all {N} plans
-
-/qualia:execute-phase {X}
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
-- /qualia:plan-phase {X} --research — re-research first
-
-───────────────────────────────────────────────────────────────
-</offer_next>
-
-<success_criteria>
-- [ ] .planning/ directory validated
-- [ ] Phase validated against roadmap
-- [ ] Phase directory created if needed
-- [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
-- [ ] Research completed (unless --skip-research or --gaps or exists)
-- [ ] qualia-phase-researcher spawned with CONTEXT.md
-- [ ] Existing plans checked
-- [ ] qualia-planner spawned with CONTEXT.md + RESEARCH.md
-- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
-- [ ] qualia-plan-checker spawned with CONTEXT.md
-- [ ] Verification passed OR user override OR max iterations with user decision
-- [ ] User sees status between agent spawns
-- [ ] User knows next steps
-</success_criteria>