qualia-framework 2.6.0 → 3.2.0

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

@@ -1,326 +0,0 @@
-<purpose>
-Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- Argument is the phase number to remove (integer or decimal)
-- Example: `/qualia:remove-phase 17` → phase = 17
-- Example: `/qualia:remove-phase 16.1` → phase = 16.1
-
-If no argument provided:
-
-```
-ERROR: Phase number required
-Usage: /qualia:remove-phase <phase-number>
-Example: /qualia:remove-phase 17
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init phase-op "${target}")
-```
-
-Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
-
-Also read STATE.md and ROADMAP.md content for parsing current position.
-</step>
-
-<step name="validate_phase_exists">
-Verify the target phase exists in ROADMAP.md:
-
-1. Search for `### Phase {target}:` heading
-2. If not found:
-
-   ```
-   ERROR: Phase {target} not found in roadmap
-   Available phases: [list phase numbers]
-   ```
-
-   Exit.
-</step>
-
-<step name="validate_future_phase">
-Verify the phase is a future phase (not started):
-
-1. Compare target phase to current phase from STATE.md
-2. Target must be > current phase number
-
-If target <= current phase:
-
-```
-ERROR: Cannot remove Phase {target}
-
-Only future phases can be removed:
-- Current phase: {current}
-- Phase {target} is current or completed
-
-To abandon current work, use /qualia:pause-work instead.
-```
-
-Exit.
-
-3. Check for SUMMARY.md files in phase directory:
-
-```bash
-ls .planning/phases/{target}-*/*-SUMMARY.md 2>/dev/null
-```
-
-If any SUMMARY.md files exist:
-
-```
-ERROR: Phase {target} has completed work
-
-Found executed plans:
-- {list of SUMMARY.md files}
-
-Cannot remove phases with completed work.
-```
-
-Exit.
-</step>
-
-<step name="gather_phase_info">
-Collect information about the phase being removed:
-
-1. Extract phase name from ROADMAP.md heading: `### Phase {target}: {Name}`
-2. Find phase directory: `.planning/phases/{target}-{slug}/`
-3. Find all subsequent phases (integer and decimal) that need renumbering
-
-**Subsequent phase detection:**
-
-For integer phase removal (e.g., 17):
-- Find all phases > 17 (integers: 18, 19, 20...)
-- Find all decimal phases >= 17.0 and < 18.0 (17.1, 17.2...) → these become 16.x
-- Find all decimal phases for subsequent integers (18.1, 19.1...) → renumber with their parent
-
-For decimal phase removal (e.g., 17.1):
-- Find all decimal phases > 17.1 and < 18 (17.2, 17.3...) → renumber down
-- Integer phases unchanged
-
-List all phases that will be renumbered.
-</step>
-
-<step name="confirm_removal">
-Present removal summary and confirm:
-
-```
-Removing Phase {target}: {Name}
-
-This will:
-- Delete: .planning/phases/{target}-{slug}/
-- Renumber {N} subsequent phases:
-  - Phase 18 → Phase 17
-  - Phase 18.1 → Phase 17.1
-  - Phase 19 → Phase 18
-  [etc.]
-
-Proceed? (y/n)
-```
-
-Wait for confirmation.
-</step>
-
-<step name="delete_phase_directory">
-Use the init context from earlier. The `phase_dir` from `init phase-op` provides the path.
-
-Delete the target phase directory if it exists:
-
-```bash
-# phase_dir from init phase-op contains the path if found
-if [ -n "$phase_dir" ]; then
-  rm -rf "$phase_dir"
-  echo "Deleted: $phase_dir/"
-fi
-```
-
-If directory doesn't exist (`phase_found=false` from init), note: "No directory to delete (phase not yet created)"
-</step>
-
-<step name="renumber_directories">
-Rename all subsequent phase directories:
-
-For each phase directory that needs renumbering (in reverse order to avoid conflicts):
-
-```bash
-# Example: renaming 18-dashboard to 17-dashboard
-mv ".planning/phases/18-dashboard" ".planning/phases/17-dashboard"
-```
-
-Process in descending order (20→19, then 19→18, then 18→17) to avoid overwriting.
-
-Also rename decimal phase directories:
-- `17.1-fix-bug` → `16.1-fix-bug` (if removing integer 17)
-- `17.2-hotfix` → `17.1-hotfix` (if removing decimal 17.1)
-</step>
-
-<step name="rename_files_in_directories">
-Rename plan files inside renumbered directories:
-
-For each renumbered directory, rename files that contain the phase number:
-
-```bash
-# Inside 17-dashboard (was 18-dashboard):
-mv "18-01-PLAN.md" "17-01-PLAN.md"
-mv "18-02-PLAN.md" "17-02-PLAN.md"
-mv "18-01-SUMMARY.md" "17-01-SUMMARY.md"  # if exists
-# etc.
-```
-
-Also handle CONTEXT.md and DISCOVERY.md (these don't have phase prefixes, so no rename needed).
-</step>
-
-<step name="update_roadmap">
-Update ROADMAP.md:
-
-1. **Remove the phase section entirely:**
-   - Delete from `### Phase {target}:` to the next phase heading (or section end)
-
-2. **Remove from phase list:**
-   - Delete line `- [ ] **Phase {target}: {Name}**` or similar
-
-3. **Remove from Progress table:**
-   - Delete the row for Phase {target}
-
-4. **Renumber all subsequent phases:**
-   - `### Phase 18:` → `### Phase 17:`
-   - `- [ ] **Phase 18:` → `- [ ] **Phase 17:`
-   - Table rows: `| 18. Dashboard |` → `| 17. Dashboard |`
-   - Plan references: `18-01:` → `17-01:`
-
-5. **Update dependency references:**
-   - `**Depends on:** Phase 18` → `**Depends on:** Phase 17`
-   - For the phase that depended on the removed phase:
-     - `**Depends on:** Phase 17` (removed) → `**Depends on:** Phase 16`
-
-6. **Renumber decimal phases:**
-   - `### Phase 17.1:` → `### Phase 16.1:` (if integer 17 removed)
-   - Update all references consistently
-
-Write updated ROADMAP.md.
-</step>
-
-<step name="update_state">
-Update STATE.md:
-
-1. **Update total phase count:**
-   - `Phase: 16 of 20` → `Phase: 16 of 19`
-
-2. **Recalculate progress percentage:**
-   - New percentage based on completed plans / new total plans
-
-Do NOT add a "Roadmap Evolution" note - the git commit is the record.
-
-Write updated STATE.md.
-</step>
-
-<step name="update_file_contents">
-Search for and update phase references inside plan files:
-
-```bash
-# Find files that reference the old phase numbers
-grep -r "Phase 18" .planning/phases/17-*/ 2>/dev/null
-grep -r "Phase 19" .planning/phases/18-*/ 2>/dev/null
-# etc.
-```
-
-Update any internal references to reflect new numbering.
-</step>
-
-<step name="commit">
-Stage and commit the removal:
-
-```bash
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
-```
-
-The commit message preserves the historical record of what was removed.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {target} ({original-name}) removed.
-
-Changes:
-- Deleted: .planning/phases/{target}-{slug}/
-- Renumbered: Phases {first-renumbered}-{last-old} → {first-renumbered-1}-{last-new}
-- Updated: ROADMAP.md, STATE.md
-- Committed: chore: remove phase {target} ({original-name})
-
-Current roadmap: {total-remaining} phases
-Current position: Phase {current} of {new-total}
-
----
-
-## What's Next
-
-Would you like to:
-- `/qualia:progress` — see updated roadmap status
-- Continue with current phase
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<anti_patterns>
-
-- Don't remove completed phases (have SUMMARY.md files)
-- Don't remove current or past phases
-- Don't leave gaps in numbering - always renumber
-- Don't add "removed phase" notes to STATE.md - git commit is the record
-- Don't ask about each decimal phase - just renumber them
-- Don't modify completed phase directories
-</anti_patterns>
-
-<edge_cases>
-
-**Removing a decimal phase (e.g., 17.1):**
-- Only affects other decimals in same series (17.2 → 17.1, 17.3 → 17.2)
-- Integer phases unchanged
-- Simpler operation
-
-**No subsequent phases to renumber:**
-- Removing the last phase (e.g., Phase 20 when that's the end)
-- Just delete and update ROADMAP.md, no renumbering needed
-
-**Phase directory doesn't exist:**
-- Phase may be in ROADMAP.md but directory not created yet
-- Skip directory deletion, proceed with ROADMAP.md updates
-
-**Decimal phases under removed integer:**
-- Removing Phase 17 when 17.1, 17.2 exist
-- 17.1 → 16.1, 17.2 → 16.2
-- They maintain their position in execution order (after current last integer)
-
-</edge_cases>
-
-<success_criteria>
-Phase removal is complete when:
-
-- [ ] Target phase validated as future/unstarted
-- [ ] Phase directory deleted (if existed)
-- [ ] All subsequent phase directories renumbered
-- [ ] Files inside directories renamed ({old}-01-PLAN.md → {new}-01-PLAN.md)
-- [ ] ROADMAP.md updated (section removed, all references renumbered)
-- [ ] STATE.md updated (phase count, progress percentage)
-- [ ] Dependency references updated in subsequent phases
-- [ ] Changes committed with descriptive message
-- [ ] No gaps in phase numbering
-- [ ] User informed of changes
-</success_criteria>

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

@@ -1,74 +0,0 @@
-<purpose>
-Research how to implement a phase. Spawns qualia-phase-researcher with phase context.
-
-Standalone research command. For most workflows, use `/qualia:plan-phase` which integrates research automatically.
-</purpose>
-
-<process>
-
-## Step 0: Resolve Model Profile
-
-@/home/qualia/.claude/qualia-framework/references/model-profile-resolution.md
-
-Resolve model for:
-- `qualia-phase-researcher`
-
-## Step 1: Normalize and Validate Phase
-
-@/home/qualia/.claude/qualia-framework/references/phase-argument-parsing.md
-
-```bash
-PHASE_INFO=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js roadmap get-phase "${PHASE}")
-```
-
-If `found` is false: Error and exit.
-
-## Step 2: Check Existing Research
-
-```bash
-ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
-```
-
-If exists: Offer update/view/skip options.
-
-## Step 3: Gather Phase Context
-
-```bash
-# Phase section from roadmap (already loaded in PHASE_INFO)
-echo "$PHASE_INFO" | jq -r '.section'
-cat .planning/REQUIREMENTS.md 2>/dev/null
-cat .planning/phases/${PHASE}-*/*-CONTEXT.md 2>/dev/null
-# Decisions from state-snapshot (structured JSON)
-node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js state-snapshot | jq '.decisions'
-```
-
-## Step 4: Spawn Researcher
-
-```
-Task(
-  prompt="<objective>
-Research implementation approach for Phase {phase}: {name}
-</objective>
-
-<context>
-Phase description: {description}
-Requirements: {requirements}
-Prior decisions: {decisions}
-Phase context: {context_md}
-</context>
-
-<output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
-</output>",
-  subagent_type="qualia-phase-researcher",
-  model="{researcher_model}"
-)
-```
-
-## Step 5: Handle Return
-
-- `## RESEARCH COMPLETE` — Display summary, offer: Plan/Dig deeper/Review/Done
-- `## CHECKPOINT REACHED` — Present to user, spawn continuation
-- `## RESEARCH INCONCLUSIVE` — Show attempts, offer: Add context/Try different mode/Manual
-
-</process>

package/framework/qualia-framework/workflows/resume-project.md

@@ -1,306 +0,0 @@
-<trigger>
-Use this workflow when:
-- Starting a new session on an existing project
-- User says "continue", "what's next", "where were we", "resume"
-- Any planning operation when .planning/ already exists
-- User returns after time away from project
-</trigger>
-
-<purpose>
-Instantly restore full project context so "Where were we?" has an immediate, complete answer.
-</purpose>
-
-<required_reading>
-@/home/qualia/.claude/qualia-framework/references/continuation-format.md
-</required_reading>
-
-<process>
-
-<step name="initialize">
-Load all context in one call:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init resume)
-```
-
-Parse JSON for: `state_exists`, `roadmap_exists`, `project_exists`, `planning_exists`, `has_interrupted_agent`, `interrupted_agent_id`, `commit_docs`.
-
-**If `state_exists` is true:** Proceed to load_state
-**If `state_exists` is false but `roadmap_exists` or `project_exists` is true:** Offer to reconstruct STATE.md
-**If `planning_exists` is false:** This is a new project - route to /qualia:new-project
-</step>
-
-<step name="load_state">
-
-Read and parse STATE.md, then PROJECT.md:
-
-```bash
-cat .planning/STATE.md
-cat .planning/PROJECT.md
-```
-
-**From STATE.md extract:**
-
-- **Project Reference**: Core value and current focus
-- **Current Position**: Phase X of Y, Plan A of B, Status
-- **Progress**: Visual progress bar
-- **Recent Decisions**: Key decisions affecting current work
-- **Pending Todos**: Ideas captured during sessions
-- **Blockers/Concerns**: Issues carried forward
-- **Session Continuity**: Where we left off, any resume files
-
-**From PROJECT.md extract:**
-
-- **What This Is**: Current accurate description
-- **Requirements**: Validated, Active, Out of Scope
-- **Key Decisions**: Full decision log with outcomes
-- **Constraints**: Hard limits on implementation
-
-</step>
-
-<step name="check_incomplete_work">
-Look for incomplete work that needs attention:
-
-```bash
-# Check for continue-here files (mid-plan resumption)
-ls .planning/phases/*/.continue-here*.md 2>/dev/null
-
-# Check for plans without summaries (incomplete execution)
-for plan in .planning/phases/*/*-PLAN.md; do
-  summary="${plan/PLAN/SUMMARY}"
-  [ ! -f "$summary" ] && echo "Incomplete: $plan"
-done 2>/dev/null
-
-# Check for interrupted agents (use has_interrupted_agent and interrupted_agent_id from init)
-if [ "$has_interrupted_agent" = "true" ]; then
-  echo "Interrupted agent: $interrupted_agent_id"
-fi
-```
-
-**If .continue-here file exists:**
-
-- This is a mid-plan resumption point
-- Read the file for specific resumption context
-- Flag: "Found mid-plan checkpoint"
-
-**If PLAN without SUMMARY exists:**
-
-- Execution was started but not completed
-- Flag: "Found incomplete plan execution"
-
-**If interrupted agent found:**
-
-- Subagent was spawned but session ended before completion
-- Read agent-history.json for task details
-- Flag: "Found interrupted agent"
-  </step>
-
-<step name="present_status">
-Present complete project status to user:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PROJECT STATUS                                               ║
-╠══════════════════════════════════════════════════════════════╣
-║  Building: [one-liner from PROJECT.md "What This Is"]         ║
-║                                                               ║
-║  Phase: [X] of [Y] - [Phase name]                            ║
-║  Plan:  [A] of [B] - [Status]                                ║
-║  Progress: [██████░░░░] XX%                                  ║
-║                                                               ║
-║  Last activity: [date] - [what happened]                     ║
-╚══════════════════════════════════════════════════════════════╝
-
-[If incomplete work found:]
-⚠️  Incomplete work detected:
-    - [.continue-here file or incomplete plan]
-
-[If interrupted agent found:]
-⚠️  Interrupted agent detected:
-    Agent ID: [id]
-    Task: [task description from agent-history.json]
-    Interrupted: [timestamp]
-
-    Resume with: Task tool (resume parameter with agent ID)
-
-[If pending todos exist:]
-📋 [N] pending todos — /qualia:check-todos to review
-
-[If blockers exist:]
-⚠️  Carried concerns:
-    - [blocker 1]
-    - [blocker 2]
-
-[If alignment is not ✓:]
-⚠️  Brief alignment: [status] - [assessment]
-```
-
-</step>
-
-<step name="determine_next_action">
-Based on project state, determine the most logical next action:
-
-**If interrupted agent exists:**
-→ Primary: Resume interrupted agent (Task tool with resume parameter)
-→ Option: Start fresh (abandon agent work)
-
-**If .continue-here file exists:**
-→ Primary: Resume from checkpoint
-→ Option: Start fresh on current plan
-
-**If incomplete plan (PLAN without SUMMARY):**
-→ Primary: Complete the incomplete plan
-→ Option: Abandon and move on
-
-**If phase in progress, all plans complete:**
-→ Primary: Transition to next phase
-→ Option: Review completed work
-
-**If phase ready to plan:**
-→ Check if CONTEXT.md exists for this phase:
-
-- If CONTEXT.md missing:
-  → Primary: Discuss phase vision (how user imagines it working)
-  → Secondary: Plan directly (skip context gathering)
-- If CONTEXT.md exists:
-  → Primary: Plan the phase
-  → Option: Review roadmap
-
-**If phase ready to execute:**
-→ Primary: Execute next plan
-→ Option: Review the plan first
-</step>
-
-<step name="offer_options">
-Present contextual options based on project state:
-
-```
-What would you like to do?
-
-[Primary action based on state - e.g.:]
-1. Resume interrupted agent [if interrupted agent found]
-   OR
-1. Execute phase (/qualia:execute-phase {phase})
-   OR
-1. Discuss Phase 3 context (/qualia:discuss-phase 3) [if CONTEXT.md missing]
-   OR
-1. Plan Phase 3 (/qualia:plan-phase 3) [if CONTEXT.md exists or discuss option declined]
-
-[Secondary options:]
-2. Review current phase status
-3. Check pending todos ([N] pending)
-4. Review brief alignment
-5. Something else
-```
-
-**Note:** When offering phase planning, check for CONTEXT.md existence first:
-
-```bash
-ls .planning/phases/XX-name/*-CONTEXT.md 2>/dev/null
-```
-
-If missing, suggest discuss-phase before plan. If exists, offer plan directly.
-
-Wait for user selection.
-</step>
-
-<step name="route_to_workflow">
-Based on user selection, route to appropriate workflow:
-
-- **Execute plan** → Show command for user to run after clearing:
-  ```
-  ---
-
-  ## ▶ Next Up
-
-  **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md]
-
-  `/qualia:execute-phase {phase}`
-
-  <sub>`/clear` first → fresh context window</sub>
-
-  ---
-  ```
-- **Plan phase** → Show command for user to run after clearing:
-  ```
-  ---
-
-  ## ▶ Next Up
-
-  **Phase [N]: [Name]** — [Goal from ROADMAP.md]
-
-  `/qualia:plan-phase [phase-number]`
-
-  <sub>`/clear` first → fresh context window</sub>
-
-  ---
-
-  **Also available:**
-  - `/qualia:discuss-phase [N]` — gather context first
-  - `/qualia:research-phase [N]` — investigate unknowns
-
-  ---
-  ```
-- **Transition** → ./transition.md
-- **Check todos** → Read .planning/todos/pending/, present summary
-- **Review alignment** → Read PROJECT.md, compare to current state
-- **Something else** → Ask what they need
-</step>
-
-<step name="update_session">
-Before proceeding to routed workflow, update session continuity:
-
-Update STATE.md:
-
-```markdown
-## Session Continuity
-
-Last session: [now]
-Stopped at: Session resumed, proceeding to [action]
-Resume file: [updated if applicable]
-```
-
-This ensures if session ends unexpectedly, next resume knows the state.
-</step>
-
-</process>
-
-<reconstruction>
-If STATE.md is missing but other artifacts exist:
-
-"STATE.md missing. Reconstructing from artifacts..."
-
-1. Read PROJECT.md → Extract "What This Is" and Core Value
-2. Read ROADMAP.md → Determine phases, find current position
-3. Scan \*-SUMMARY.md files → Extract decisions, concerns
-4. Count pending todos in .planning/todos/pending/
-5. Check for .continue-here files → Session continuity
-
-Reconstruct and write STATE.md, then proceed normally.
-
-This handles cases where:
-
-- Project predates STATE.md introduction
-- File was accidentally deleted
-- Cloning repo without full .planning/ state
-  </reconstruction>
-
-<quick_resume>
-If user says "continue" or "go":
-- Load state silently
-- Determine primary action
-- Execute immediately without presenting options
-
-"Continuing from [state]... [action]"
-</quick_resume>
-
-<success_criteria>
-Resume is complete when:
-
-- [ ] STATE.md loaded (or reconstructed)
-- [ ] Incomplete work detected and flagged
-- [ ] Clear status presented to user
-- [ ] Contextual next actions offered
-- [ ] User knows exactly where project stands
-- [ ] Session continuity updated
-      </success_criteria>