qualia-framework 2.5.1 → 3.1.0

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

@@ -1,559 +0,0 @@
-<purpose>
-Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean — delegates plan execution to subagents.
-</purpose>
-
-<core_principle>
-Orchestrator coordinates, not executes. Each subagent loads the full execute-plan context. Orchestrator: discover plans → analyze deps → group waves → spawn agents → handle checkpoints → collect results.
-</core_principle>
-
-<required_reading>
-Read STATE.md before any operation to load project context.
-</required_reading>
-
-<process>
-
-<step name="initialize" priority="first">
-Load all context in one call:
-
-```bash
-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`.
-
-**If `phase_found` is false:** Error — phase directory not found.
-**If `plan_count` is 0:** Error — no plans found in phase.
-**If `state_exists` is false but `.planning/` exists:** Offer reconstruct or continue.
-
-When `parallelization` is false, plans within a wave execute sequentially.
-</step>
-
-<step name="handle_branching">
-Check `branching_strategy` from init:
-
-**"none":** Skip, continue on current branch.
-
-**"phase" or "milestone":** Use pre-computed `branch_name` from init:
-```bash
-git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
-```
-
-All subsequent commits go to this branch. User handles merging.
-</step>
-
-<step name="validate_phase">
-From init JSON: `phase_dir`, `plan_count`, `incomplete_count`.
-
-Report: "Found {plan_count} plans in {phase_dir} ({incomplete_count} incomplete)"
-
-**Team suggestion (optional):** Check if the phase in ROADMAP.md has a `team:` field (e.g., `team: full-stack-team`). If present, suggest:
-
-```
-Note: This phase has a team template configured (full-stack-team).
-Consider using `/team full-stack "<phase goal>"` for coordinated multi-agent execution.
-Continuing with standard execution...
-```
-
-This is a suggestion only — execution continues normally regardless. The user can cancel and run `/team` instead, or let standard execution proceed.
-</step>
-
-<step name="discover_and_group_plans">
-Load plan inventory with wave grouping in one call:
-
-```bash
-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`.
-
-**Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
-
-Report:
-```
-## Execution Plan
-
-**Phase {X}: {Name}** — {total_plans} plans across {wave_count} waves
-
-| Wave | Plans | What it builds |
-|------|-------|----------------|
-| 1 | 01-01, 01-02 | {from plan objectives, 3-8 words} |
-| 2 | 01-03 | ... |
-```
-</step>
-
-<step name="execute_waves">
-Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`, sequential if `false`.
-
-**For each wave:**
-
-1. **Describe what's being built (BEFORE spawning):**
-
-   Read each plan's `<objective>`. Extract what's being built and why.
-
-   ```
-   ---
-   ## Wave {N}
-
-   **{Plan ID}: {Plan Name}**
-   {2-3 sentences: what this builds, technical approach, why it matters}
-
-   Spawning {count} agent(s)...
-   ---
-   ```
-
-   - Bad: "Executing terrain generation plan"
-   - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
-
-2. **Read files and spawn agents:**
-
-   Content must be inlined — `@` syntax doesn't work across Task() boundaries.
-
-   ```bash
-   PLAN_CONTENT=$(cat "{plan_path}")
-   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-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-framework/references/design-quality.md 2>/dev/null)
-     FRONTEND_SKILL=$(cat /home/qualia/.claude/skills/frontend-master/SKILL.md 2>/dev/null)
-   fi
-   ```
-
-   **Resolve domain skill references from plan:**
-
-   ```bash
-   # Extract @skill references from plan
-   SKILL_REFS=$(echo "$PLAN_CONTENT" | grep -oP '@/home/qualia/.claude/skills/[^\s]+/SKILL\.md' | sort -u)
-
-   # Inline each skill's content into domain context
-   DOMAIN_CONTEXT=""
-   for ref in $SKILL_REFS; do
-     SKILL_PATH="${ref#@}"
-     if [ -f "$SKILL_PATH" ]; then
-       SKILL_NAME=$(basename "$(dirname "$SKILL_PATH")")
-       DOMAIN_CONTEXT="${DOMAIN_CONTEXT}
-
---- Skill: ${SKILL_NAME} ---
-$(cat "$SKILL_PATH")
-"
-     fi
-   done
-   ```
-
-   Each agent prompt:
-
-   ```
-   <objective>
-   Execute plan {plan_number} of phase {phase_number}-{phase_name}.
-   Commit each task atomically. Create SUMMARY.md. Update STATE.md.
-   </objective>
-
-   <execution_context>
-   {execute_plan_wf}
-   {summary_tmpl}
-   {checkpoints_ref}
-   {tdd_ref}
-   </execution_context>
-
-   <context>
-   Plan:
-   {plan_content}
-
-   Project state:
-   {state_content}
-
-   Config (if exists):
-   {config_content}
-   </context>
-
-   {If DOMAIN_CONTEXT is non-empty:}
-   <domain_skills>
-   These skill guidelines apply to this plan. Follow these patterns.
-   {DOMAIN_CONTEXT}
-   </domain_skills>
-
-   <success_criteria>
-   - [ ] All tasks executed
-   - [ ] Each task committed individually
-   - [ ] SUMMARY.md created in plan directory
-   - [ ] STATE.md updated with position and decisions
-   </success_criteria>
-   ```
-
-   **If `IS_FRONTEND` is true**, append this block to the agent prompt before `</success_criteria>`:
-
-   ```
-   <design_quality>
-   This plan involves frontend work. Use the frontend-master skill as your primary design guide.
-
-   {frontend_skill}
-
-   Build-time standards summary:
-   {design_context}
-   </design_quality>
-   ```
-
-   And add to success_criteria:
-   ```
-   - [ ] Frontend components meet design quality standards (no generic look, states handled, copy is clear, transitions present)
-   ```
-
-3. **Wait for all agents in wave to complete.**
-
-4. **Report completion — spot-check claims first:**
-
-   For each SUMMARY.md:
-   - Verify first 2 files from `key-files.created` exist on disk
-   - Check `git log --oneline --all --grep="{phase}-{plan}"` returns ≥1 commit
-   - Check for `## Self-Check: FAILED` marker
-
-   If ANY spot-check fails: report which plan failed, route to failure handler — ask "Retry plan?" or "Continue with remaining waves?"
-
-   If pass:
-   ```
-   ---
-   ## Wave {N} Complete
-
-   **{Plan ID}: {Plan Name}**
-   {What was built — from SUMMARY.md}
-   {Notable deviations, if any}
-
-   {If more waves: what this enables for next wave}
-   ---
-   ```
-
-   - Bad: "Wave 2 complete. Proceeding to Wave 3."
-   - Good: "Terrain system complete — 3 biome types, height-based texturing, physics collision meshes. Vehicle physics (Wave 3) can now reference ground surfaces."
-
-5. **Handle failures:** Report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
-
-6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
-
-7. **Proceed to next wave.**
-</step>
-
-<step name="checkpoint_handling">
-Plans with `autonomous: false` require user interaction.
-
-**Flow:**
-
-1. Spawn agent for checkpoint plan
-2. Agent runs until checkpoint task or auth gate → returns structured state
-3. Agent return includes: completed tasks table, current task + blocker, checkpoint type/details, what's awaited
-4. **Present to user:**
-   ```
-   ## Checkpoint: [Type]
-
-   **Plan:** 03-03 Dashboard Layout
-   **Progress:** 2/3 tasks complete
-
-   [Checkpoint Details from agent return]
-   [Awaiting section from agent return]
-   ```
-5. User responds: "approved"/"done" | issue description | decision selection
-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
-   - `{resume_instructions}`: Based on checkpoint type
-7. Continuation agent verifies previous commits, continues from resume point
-8. Repeat until plan completes or user stops
-
-**Why fresh agent, not resume:** Resume relies on internal serialization that breaks with parallel tool calls. Fresh agents with explicit state are more reliable.
-
-**Checkpoints in parallel waves:** Agent pauses and returns while other parallel agents may complete. Present checkpoint, spawn continuation, wait for all before next wave.
-</step>
-
-<step name="aggregate_results">
-After all waves:
-
-```markdown
-## Phase {X}: {Name} Execution Complete
-
-**Waves:** {N} | **Plans:** {M}/{total} complete
-
-| Wave | Plans | Status |
-|------|-------|--------|
-| 1 | plan-01, plan-02 | ✓ Complete |
-| CP | plan-03 | ✓ Verified |
-| 2 | plan-04 | ✓ Complete |
-
-### Plan Details
-1. **03-01**: [one-liner from SUMMARY.md]
-2. **03-02**: [one-liner from SUMMARY.md]
-
-### Test Summary
-If any plan SUMMARY.md mentions test results, aggregate:
-```
-Tests: X passed, Y failed across {N} plans
-```
-If Y > 0, note in Issues Encountered.
-
-### Issues Encountered
-[Aggregate from SUMMARYs, or "None"]
-```
-</step>
-
-<step name="design_polish_pass">
-After all waves complete, check if this phase produced frontend work.
-
-```bash
-# Find the earliest commit from this phase across all plan numbering formats
-PHASE_BASE=$(git log --oneline --all --grep="(${PHASE_NUMBER}-" --reverse 2>/dev/null | head -1 | cut -d' ' -f1)
-if [ -z "$PHASE_BASE" ]; then
-  # Fallback: try zero-padded format
-  PADDED=$(printf "%02d" "${PHASE_NUMBER}")
-  PHASE_BASE=$(git log --oneline --all --grep="(${PADDED}-" --reverse 2>/dev/null | head -1 | cut -d' ' -f1)
-fi
-
-if [ -n "$PHASE_BASE" ]; then
-  FRONTEND_FILES=$(git diff --name-only ${PHASE_BASE}^..HEAD 2>/dev/null | grep -E '\.(tsx|jsx|css|scss)$' | head -30)
-else
-  # Last resort: check all uncommitted + recent commits
-  FRONTEND_FILES=$(git diff --name-only HEAD~20..HEAD 2>/dev/null | grep -E '\.(tsx|jsx|css|scss)$' | head -30)
-fi
-```
-
-**If no frontend files:** Skip to verify_phase_goal.
-
-**If frontend files exist:** Run the impeccable diagnostic-then-fix flow.
-
-### Step 1: Run /critique diagnostic
-
-```bash
-# Content must be inlined — @ syntax doesn't work across Task() boundaries
-CRITIQUE_SKILL=$(cat /home/qualia/.claude/skills/critique/SKILL.md 2>/dev/null)
-FRONTEND_SKILL=$(cat /home/qualia/.claude/skills/frontend-master/SKILL.md 2>/dev/null)
-```
-
-```
-Task(
-  prompt="You are a design director reviewing frontend work. Run a /critique diagnostic on all changed files.
-
-<skill>
-{critique_skill}
-</skill>
-
-<frontend_master>
-{frontend_skill}
-</frontend_master>
-
-<files_to_review>
-${FRONTEND_FILES}
-</files_to_review>
-
-<rules>
-- Read each file before reviewing
-- Follow the critique skill exactly: AI slop detection, visual hierarchy, information architecture, emotional resonance, states, typography, color, microcopy
-- For each issue, specify which command to run (from the Priority Issues > Command field)
-- Do NOT fix anything — only diagnose and recommend
-- Output a structured report with:
-  1. Anti-Patterns Verdict (pass/fail)
-  2. Priority Issues (each with: what, why, fix, command)
-  3. Minor Observations
-- If everything looks good, report 'Design quality meets standards — no fixes needed'
-</rules>",
-  subagent_type="qualia-executor",
-  description="Design critique for Phase ${PHASE_NUMBER}"
-)
-```
-
-### Step 2: Parse critique and run recommended commands
-
-Read the critique report. If it says "no fixes needed" — skip to verify_phase_goal.
-
-If issues were found, collect the unique recommended commands from the report (e.g., `/polish`, `/harden`, `/animate`, `/normalize`, `/clarify`, `/bolder`, `/distill`, etc.).
-
-For each recommended command, load the corresponding skill and spawn a fix agent:
-
-```bash
-# Load only the skills the critique recommended
-# Example: if critique recommended /polish and /harden
-for SKILL_NAME in ${RECOMMENDED_COMMANDS}; do
-  SKILL_CONTENT=$(cat /home/qualia/.claude/skills/${SKILL_NAME}/SKILL.md 2>/dev/null)
-  # Only proceed if skill file exists
-  if [ -n "$SKILL_CONTENT" ]; then
-    echo "Loading skill: ${SKILL_NAME}"
-  fi
-done
-```
-
-Spawn a single fix agent with all recommended skills loaded:
-
-```
-Task(
-  prompt="You are a design quality fixer. Apply the recommended fixes from the critique report.
-
-<critique_report>
-{critique_output}
-</critique_report>
-
-<skills>
-{For each recommended command, inline its SKILL.md content here}
-</skills>
-
-<frontend_master>
-{frontend_skill}
-</frontend_master>
-
-<files_to_fix>
-${FRONTEND_FILES}
-</files_to_fix>
-
-<rules>
-- Read each file before modifying — understand context first
-- Only modify files in the list above
-- Only fix what the critique identified — do not refactor or restructure logic
-- Apply each recommended skill to address its specific issues
-- Commit changes as: style(${PHASE_NUMBER}): design quality — [summary of what was fixed]
-- If a recommended fix would require architectural changes, skip it and note why
-</rules>",
-  subagent_type="qualia-executor",
-  description="Design fixes for Phase ${PHASE_NUMBER}"
-)
-```
-
-### Step 3: Report
-
-```
----
-## Design Quality Pass
-
-**Critique:** {pass/fail verdict}
-**Issues found:** {N}
-**Commands applied:** {list of skills that ran}
-**Fixed:** {summary of changes}
-
-{If issues were skipped: list why}
----
-```
-
-Report before proceeding to verify_phase_goal.
-</step>
-
-<step name="verify_phase_goal">
-Verify phase achieved its GOAL, not just completed tasks.
-
-```
-Task(
-  prompt="Verify phase {phase_number} goal achievement.
-Phase directory: {phase_dir}
-Phase goal: {goal from ROADMAP.md}
-Check must_haves against actual codebase. Create VERIFICATION.md.",
-  subagent_type="qualia-verifier",
-  model="{verifier_model}"
-)
-```
-
-Read status:
-```bash
-grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
-```
-
-| Status | Action |
-|--------|--------|
-| `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` |
-
-**If human_needed:**
-```
-## ✓ Phase {X}: {Name} — Human Verification Required
-
-All automated checks passed. {N} items need human testing:
-
-{From VERIFICATION.md human_verification section}
-
-"approved" → continue | Report issues → gap closure
-```
-
-**If gaps_found:**
-```
-## ⚠ Phase {X}: {Name} — Gaps Found
-
-**Score:** {N}/{M} must-haves verified
-**Report:** {phase_dir}/{phase}-VERIFICATION.md
-
-### What's Missing
-{Gap summaries from VERIFICATION.md}
-
----
-## ▶ Next Up
-
-`/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
-```
-
-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:**
-
-When executing with `--gaps-only`, after all gap plans complete (aggregate_results), automatically re-run verification — do NOT skip to update_roadmap. The flow is:
-
-1. Gap plans execute via execute_waves
-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.**
-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.
-</step>
-
-<step name="update_roadmap">
-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-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>
-
-<step name="offer_next">
-
-**If more phases:**
-```
-## Next Up
-
-**Phase {X+1}: {Name}** — {Goal}
-
-`/clear` then `/qualia-plan-phase {X+1}`
-```
-
-**If milestone complete:**
-```
-MILESTONE COMPLETE!
-
-All {N} phases executed.
-
-`/clear` then `/qualia-complete-milestone`
-```
-</step>
-
-</process>
-
-<context_efficiency>
-Orchestrator: ~10-15% context. Subagents: fresh 200k each. No polling (Task blocks). No context bleed.
-</context_efficiency>
-
-<failure_handling>
-- **Agent fails mid-plan:** Missing SUMMARY.md → report, ask user how to proceed
-- **Dependency chain breaks:** Wave 1 fails → Wave 2 dependents likely fail → user chooses attempt or skip
-- **All agents in wave fail:** Systemic issue → stop, report for investigation
-- **Checkpoint unresolvable:** "Skip this plan?" or "Abort phase execution?" → record partial progress in STATE.md
-</failure_handling>
-
-<resumption>
-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>