qualia-framework 2.5.1 → 3.1.0

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

@@ -1,470 +0,0 @@
-<purpose>
-Display the complete Qualia command reference. Output ONLY the reference content. Do NOT add project-specific analysis, git status, next-step suggestions, or any commentary beyond the reference.
-</purpose>
-
-<reference>
-# Qualia Command Reference
-
-**Qualia Engine** creates hierarchical project plans optimized for solo agentic development with Claude Code.
-
-## Quick Start
-
-1. `/qualia:new-project` - Initialize project (includes research, requirements, roadmap)
-2. `/qualia:plan-phase 1` - Create detailed plan for first phase
-3. `/qualia:execute-phase 1` - Execute the phase
-
-## Staying Updated
-
-Qualia evolves fast. Update periodically:
-
-```bash
-npx qualia-framework-cc@latest
-```
-
-## Core Workflow
-
-```
-/qualia:new-project → /qualia:plan-phase → /qualia:execute-phase → repeat
-```
-
-### Project Initialization
-
-**`/qualia:new-project`**
-Initialize new project through unified flow.
-
-One command takes you from idea to ready-for-planning:
-- Deep questioning to understand what you're building
-- Optional domain research (spawns 4 parallel researcher agents)
-- Requirements definition with v1/v2/out-of-scope scoping
-- Roadmap creation with phase breakdown and success criteria
-
-Creates all `.planning/` artifacts:
-- `PROJECT.md` — vision and requirements
-- `config.json` — workflow mode (interactive/yolo)
-- `research/` — domain research (if selected)
-- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
-- `ROADMAP.md` — phases mapped to requirements
-- `STATE.md` — project memory
-
-Usage: `/qualia:new-project`
-
-**`/qualia:map-codebase`**
-Map an existing codebase for brownfield projects.
-
-- Analyzes codebase with parallel Explore agents
-- Creates `.planning/codebase/` with 7 focused documents
-- Covers stack, architecture, structure, conventions, testing, integrations, concerns
-- Use before `/qualia:new-project` on existing codebases
-
-Usage: `/qualia:map-codebase`
-
-### Phase Planning
-
-**`/qualia:discuss-phase <number>`**
-Help articulate your vision for a phase before planning.
-
-- Captures how you imagine this phase working
-- Creates CONTEXT.md with your vision, essentials, and boundaries
-- Use when you have ideas about how something should look/feel
-
-Usage: `/qualia:discuss-phase 2`
-
-**`/qualia:research-phase <number>`**
-Comprehensive ecosystem research for niche/complex domains.
-
-- Discovers standard stack, architecture patterns, pitfalls
-- Creates RESEARCH.md with "how experts build this" knowledge
-- Use for 3D, games, audio, shaders, ML, and other specialized domains
-- Goes beyond "which library" to ecosystem knowledge
-
-Usage: `/qualia:research-phase 3`
-
-**`/qualia:list-phase-assumptions <number>`**
-See what Claude is planning to do before it starts.
-
-- Shows Claude's intended approach for a phase
-- Lets you course-correct if Claude misunderstood your vision
-- No files created - conversational output only
-
-Usage: `/qualia:list-phase-assumptions 3`
-
-**`/qualia:plan-phase <number>`**
-Create detailed execution plan for a specific phase.
-
-- Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
-- Breaks phase into concrete, actionable tasks
-- Includes verification criteria and success measures
-- Multiple plans per phase supported (XX-01, XX-02, etc.)
-
-Usage: `/qualia:plan-phase 1`
-Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md`
-
-### Execution
-
-**`/qualia:execute-phase <phase-number>`**
-Execute all plans in a phase.
-
-- Groups plans by wave (from frontmatter), executes waves sequentially
-- Plans within each wave run in parallel via Task tool
-- Verifies phase goal after all plans complete
-- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md
-
-Usage: `/qualia:execute-phase 5`
-
-### Quick Mode
-
-**`/qualia:quick`**
-Execute small, ad-hoc tasks with Qualia guarantees but skip optional agents.
-
-Quick mode uses the same system with a shorter path:
-- Spawns planner + executor (skips researcher, checker, verifier)
-- Quick tasks live in `.planning/quick/` separate from planned phases
-- Updates STATE.md tracking (not ROADMAP.md)
-
-Use when you know exactly what to do and the task is small enough to not need research or verification.
-
-Usage: `/qualia:quick`
-Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
-
-### Roadmap Management
-
-**`/qualia:add-phase <description>`**
-Add new phase to end of current milestone.
-
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
-
-Usage: `/qualia:add-phase "Add admin dashboard"`
-
-**`/qualia:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
-
-- Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
-
-Usage: `/qualia:insert-phase 7 "Fix critical auth bug"`
-Result: Creates Phase 7.1
-
-**`/qualia:remove-phase <number>`**
-Remove a future phase and renumber subsequent phases.
-
-- Deletes phase directory and all references
-- Renumbers all subsequent phases to close the gap
-- Only works on future (unstarted) phases
-- Git commit preserves historical record
-
-Usage: `/qualia:remove-phase 17`
-Result: Phase 17 deleted, phases 18-20 become 17-19
-
-### Milestone Management
-
-**`/qualia:new-milestone <name>`**
-Start a new milestone through unified flow.
-
-- Deep questioning to understand what you're building next
-- Optional domain research (spawns 4 parallel researcher agents)
-- Requirements definition with scoping
-- Roadmap creation with phase breakdown
-
-Mirrors `/qualia:new-project` flow for brownfield projects (existing PROJECT.md).
-
-Usage: `/qualia:new-milestone "v2.0 Features"`
-
-**`/qualia:complete-milestone <version>`**
-Archive completed milestone and prepare for next version.
-
-- Creates MILESTONES.md entry with stats
-- Archives full details to milestones/ directory
-- Creates git tag for the release
-- Prepares workspace for next version
-
-Usage: `/qualia:complete-milestone 1.0.0`
-
-### Progress Tracking
-
-**`/qualia:progress`**
-Check project status and intelligently route to next action.
-
-- Shows visual progress bar and completion percentage
-- Summarizes recent work from SUMMARY files
-- Displays current position and what's next
-- Lists key decisions and open issues
-- Offers to execute next plan or create it if missing
-- Detects 100% milestone completion
-
-Usage: `/qualia:progress`
-
-### Session Management
-
-**`/qualia:resume-work`**
-Resume work from previous session with full context restoration.
-
-- Reads STATE.md for project context
-- Shows current position and recent progress
-- Offers next actions based on project state
-
-Usage: `/qualia:resume-work`
-
-**`/qualia:pause-work`**
-Create context handoff when pausing work mid-phase.
-
-- Creates .continue-here file with current state
-- Updates STATE.md session continuity section
-- Captures in-progress work context
-
-Usage: `/qualia:pause-work`
-
-### Debugging
-
-**`/qualia:debug [issue description]`**
-Systematic debugging with persistent state across context resets.
-
-- Gathers symptoms through adaptive questioning
-- Creates `.planning/debug/[slug].md` to track investigation
-- Investigates using scientific method (evidence → hypothesis → test)
-- Survives `/clear` — run `/qualia:debug` with no args to resume
-- Archives resolved issues to `.planning/debug/resolved/`
-
-Usage: `/qualia:debug "login button doesn't work"`
-Usage: `/qualia:debug` (resume active session)
-
-### Todo Management
-
-**`/qualia:add-todo [description]`**
-Capture idea or task as todo from current conversation.
-
-- Extracts context from conversation (or uses provided description)
-- Creates structured todo file in `.planning/todos/pending/`
-- Infers area from file paths for grouping
-- Checks for duplicates before creating
-- Updates STATE.md todo count
-
-Usage: `/qualia:add-todo` (infers from conversation)
-Usage: `/qualia:add-todo Add auth token refresh`
-
-**`/qualia:check-todos [area]`**
-List pending todos and select one to work on.
-
-- Lists all pending todos with title, area, age
-- Optional area filter (e.g., `/qualia:check-todos api`)
-- Loads full context for selected todo
-- Routes to appropriate action (work now, add to phase, brainstorm)
-- Moves todo to done/ when work begins
-
-Usage: `/qualia:check-todos`
-Usage: `/qualia:check-todos api`
-
-### User Acceptance Testing
-
-**`/qualia:verify-work [phase]`**
-Validate built features through conversational UAT.
-
-- Extracts testable deliverables from SUMMARY.md files
-- Presents tests one at a time (yes/no responses)
-- Automatically diagnoses failures and creates fix plans
-- Ready for re-execution if issues found
-
-Usage: `/qualia:verify-work 3`
-
-### Milestone Auditing
-
-**`/qualia:audit-milestone [version]`**
-Audit milestone completion against original intent.
-
-- Reads all phase VERIFICATION.md files
-- Checks requirements coverage
-- Spawns integration checker for cross-phase wiring
-- Creates MILESTONE-AUDIT.md with gaps and tech debt
-
-Usage: `/qualia:audit-milestone`
-
-**`/qualia:plan-milestone-gaps`**
-Create phases to close gaps identified by audit.
-
-- Reads MILESTONE-AUDIT.md and groups gaps into phases
-- Prioritizes by requirement priority (must/should/nice)
-- Adds gap closure phases to ROADMAP.md
-- Ready for `/qualia:plan-phase` on new phases
-
-Usage: `/qualia:plan-milestone-gaps`
-
-### Configuration
-
-**`/qualia:settings`**
-Configure workflow toggles and model profile interactively.
-
-- Toggle researcher, plan checker, verifier agents
-- Select model profile (quality/balanced/budget)
-- Updates `.planning/config.json`
-
-Usage: `/qualia:settings`
-
-**`/qualia:set-profile <profile>`**
-Quick switch model profile for Qualia agents.
-
-- `quality` — Opus everywhere except verification
-- `balanced` — Opus for planning, Sonnet for execution (default)
-- `budget` — Sonnet for writing, Haiku for research/verification
-
-Usage: `/qualia:set-profile budget`
-
-### Utility Commands
-
-**`/qualia:help`**
-Show this command reference.
-
-**`/qualia:update`**
-Update Qualia to latest version with changelog preview.
-
-- Shows installed vs latest version comparison
-- Displays changelog entries for versions you've missed
-- Highlights breaking changes
-- Confirms before running install
-- Better than raw `npx qualia-framework-cc`
-
-Usage: `/qualia:update`
-
-**`/qualia:join-discord`**
-Join the Qualia Discord community.
-
-- Get help, share what you're building, stay updated
-- Connect with other Qualia users
-
-Usage: `/qualia:join-discord`
-
-## Files & Structure
-
-```
-.planning/
-├── PROJECT.md            # Project vision
-├── ROADMAP.md            # Current phase breakdown
-├── STATE.md              # Project memory & context
-├── config.json           # Workflow mode & gates
-├── todos/                # Captured ideas and tasks
-│   ├── pending/          # Todos waiting to be worked on
-│   └── done/             # Completed todos
-├── debug/                # Active debug sessions
-│   └── resolved/         # Archived resolved issues
-├── codebase/             # Codebase map (brownfield projects)
-│   ├── STACK.md          # Languages, frameworks, dependencies
-│   ├── ARCHITECTURE.md   # Patterns, layers, data flow
-│   ├── STRUCTURE.md      # Directory layout, key files
-│   ├── CONVENTIONS.md    # Coding standards, naming
-│   ├── TESTING.md        # Test setup, patterns
-│   ├── INTEGRATIONS.md   # External services, APIs
-│   └── CONCERNS.md       # Tech debt, known issues
-└── phases/
-    ├── 01-foundation/
-    │   ├── 01-01-PLAN.md
-    │   └── 01-01-SUMMARY.md
-    └── 02-core-features/
-        ├── 02-01-PLAN.md
-        └── 02-01-SUMMARY.md
-```
-
-## Workflow Modes
-
-Set during `/qualia:new-project`:
-
-**Interactive Mode**
-
-- Confirms each major decision
-- Pauses at checkpoints for approval
-- More guidance throughout
-
-**YOLO Mode**
-
-- Auto-approves most decisions
-- Executes plans without confirmation
-- Only stops for critical checkpoints
-
-Change anytime by editing `.planning/config.json`
-
-## Planning Configuration
-
-Configure how planning artifacts are managed in `.planning/config.json`:
-
-**`planning.commit_docs`** (default: `true`)
-- `true`: Planning artifacts committed to git (standard workflow)
-- `false`: Planning artifacts kept local-only, not committed
-
-When `commit_docs: false`:
-- Add `.planning/` to your `.gitignore`
-- Useful for OSS contributions, client projects, or keeping planning private
-- All planning files still work normally, just not tracked in git
-
-**`planning.search_gitignored`** (default: `false`)
-- `true`: Add `--no-ignore` to broad ripgrep searches
-- Only needed when `.planning/` is gitignored and you want project-wide searches to include it
-
-Example config:
-```json
-{
-  "planning": {
-    "commit_docs": false,
-    "search_gitignored": true
-  }
-}
-```
-
-## Common Workflows
-
-**Starting a new project:**
-
-```
-/qualia:new-project        # Unified flow: questioning → research → requirements → roadmap
-/clear
-/qualia:plan-phase 1       # Create plans for first phase
-/clear
-/qualia:execute-phase 1    # Execute all plans in phase
-```
-
-**Resuming work after a break:**
-
-```
-/qualia:progress  # See where you left off and continue
-```
-
-**Adding urgent mid-milestone work:**
-
-```
-/qualia:insert-phase 5 "Critical security fix"
-/qualia:plan-phase 5.1
-/qualia:execute-phase 5.1
-```
-
-**Completing a milestone:**
-
-```
-/qualia:complete-milestone 1.0.0
-/clear
-/qualia:new-milestone  # Start next milestone (questioning → research → requirements → roadmap)
-```
-
-**Capturing ideas during work:**
-
-```
-/qualia:add-todo                    # Capture from conversation context
-/qualia:add-todo Fix modal z-index  # Capture with explicit description
-/qualia:check-todos                 # Review and work on todos
-/qualia:check-todos api             # Filter by area
-```
-
-**Debugging an issue:**
-
-```
-/qualia:debug "form submission fails silently"  # Start debug session
-# ... investigation happens, context fills up ...
-/clear
-/qualia:debug                                    # Resume from where you left off
-```
-
-## Getting Help
-
-- Read `.planning/PROJECT.md` for project vision
-- Read `.planning/STATE.md` for current context
-- Check `.planning/ROADMAP.md` for phase status
-- Run `/qualia:progress` to check where you're up to
-</reference>

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

@@ -1,220 +0,0 @@
-<purpose>
-Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering the entire roadmap.
-</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:
-- First argument: integer phase number to insert after
-- Remaining arguments: phase description
-
-Example: `/qualia:insert-phase 72 Fix critical auth bug`
--> after = 72
--> description = "Fix critical auth bug"
-
-Validation:
-
-```bash
-if [ $# -lt 2 ]; then
-  echo "ERROR: Both phase number and description required"
-  echo "Usage: /qualia:insert-phase <after> <description>"
-  echo "Example: /qualia:insert-phase 72 Fix critical auth bug"
-  exit 1
-fi
-```
-
-Parse first argument as integer:
-
-```bash
-after_phase=$1
-shift
-description="$*"
-
-# Validate after_phase is an integer
-if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
-  echo "ERROR: Phase number must be an integer"
-  exit 1
-fi
-```
-
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init phase-op "${after_phase}")
-```
-
-Check `roadmap_exists` from init JSON. If false:
-```
-ERROR: No roadmap found (.planning/ROADMAP.md)
-```
-Exit.
-
-Read roadmap content for parsing.
-</step>
-
-<step name="verify_target_phase">
-Verify that the target phase exists in the roadmap:
-
-1. Search for "### Phase {after_phase}:" heading
-2. If not found:
-
-   ```
-   ERROR: Phase {after_phase} not found in roadmap
-   Available phases: [list phase numbers]
-   ```
-
-   Exit.
-
-3. Verify phase is in current milestone (not completed/archived)
-</step>
-
-<step name="find_existing_decimals">
-Calculate next decimal phase number:
-
-```bash
-DECIMAL_INFO=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js phase next-decimal "${after_phase}")
-```
-
-Extract from JSON:
-- `next`: The next available decimal (e.g., "06.1", "06.3")
-- `existing`: Array of existing decimals (e.g., ["06.1", "06.2"])
-- `base_phase`: Normalized base phase (e.g., "06")
-
-Store the result:
-```bash
-decimal_phase=$(echo "$DECIMAL_INFO" | jq -r '.next')
-```
-
-Examples:
-- Phase 72 with no decimals -> next is 72.1
-- Phase 72 with 72.1 -> next is 72.2
-- Phase 72 with 72.1, 72.2 -> next is 72.3
-</step>
-
-<step name="generate_slug">
-Convert the phase description to a kebab-case slug.
-
-Use `generate-slug` command (init phase-op provides `phase_slug` for existing phase, but this is a new phase):
-```bash
-slug=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js generate-slug "$description" --raw)
-```
-
-Phase directory name: `{decimal-phase}-{slug}`
-Example: `06.1-fix-critical-auth-bug` (phase 6 insertion)
-</step>
-
-<step name="create_phase_directory">
-Create the phase directory structure:
-
-```bash
-phase_dir=".planning/phases/${decimal_phase}-${slug}"
-mkdir -p "$phase_dir"
-```
-
-Confirm: "Created directory: $phase_dir"
-</step>
-
-<step name="update_roadmap">
-Insert the new phase entry into the roadmap:
-
-1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
-2. Insert new phase heading with (INSERTED) marker:
-
-   ```
-   ### Phase {decimal_phase}: {Description} (INSERTED)
-
-   **Goal:** [Urgent work - to be planned]
-   **Depends on:** Phase {after_phase}
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (run /qualia:plan-phase {decimal_phase} to break down)
-
-   **Details:**
-   [To be added during planning]
-   ```
-
-3. Write updated roadmap back to file
-
-The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
-
-Preserve all other content exactly (formatting, spacing, other phases).
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the inserted phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" -> "### Roadmap Evolution" add entry:
-   ```
-   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
-
-Add note about insertion reason if appropriate.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {decimal_phase} inserted after Phase {after_phase}:
-- Description: {description}
-- Directory: .planning/phases/{decimal-phase}-{slug}/
-- Status: Not planned yet
-- Marker: (INSERTED) - indicates urgent work
-
-Roadmap updated: {roadmap-path}
-Project state updated: .planning/STATE.md
-
----
-
-## Next Up
-
-**Phase {decimal_phase}: {description}** -- urgent insertion
-
-`/qualia:plan-phase {decimal_phase}`
-
-<sub>`/clear` first -> fresh context window</sub>
-
----
-
-**Also available:**
-- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<anti_patterns>
-
-- Don't use this for planned work at end of milestone (use /qualia:add-phase)
-- Don't insert before Phase 1 (decimal 0.1 makes no sense)
-- Don't renumber existing phases
-- Don't modify the target phase content
-- Don't create plans yet (that's /qualia:plan-phase)
-- Don't commit changes (user decides when to commit)
-</anti_patterns>
-
-<success_criteria>
-Phase insertion is complete when:
-
-- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
-- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
-- [ ] Phase inserted in correct position (after target phase, before next integer phase)
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] Decimal number calculated correctly (based on existing decimals)
-- [ ] User informed of next steps and dependency implications
-</success_criteria>