qualia-framework 2.1.0

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

@@ -0,0 +1,422 @@
+<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-engine/references/ui-brand.md
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+Load all context in one call:
+
+```bash
+INIT=$(node /home/qualia/.claude/qualia-engine/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-engine/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-engine/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-engine/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>