qualia-framework 2.6.0 → 3.2.0

package/framework/skills/qualia-new-project/SKILL.md

@@ -1,232 +0,0 @@
----
-name: qualia-new-project
-description: "Initialize a new Qualia workflow project from scratch — questioning, research, requirements, roadmap, environment setup, design context. Use this skill whenever the user says 'new project', 'start project', 'init project', 'qualia new', or wants to begin a brand new project with the Qualia workflow. Also trigger when user mentions setting up .planning directory, creating a roadmap, or starting fresh on a new client project."
----
-
-# Qualia New Project — Full Project Initialization
-
-Initialize a new project with the complete Qualia workflow: questioning → research → requirements → roadmap → environment → design context. Produces everything needed for an employee to start building and carry through to client handoff.
-
-## Usage
-
-`/qualia-new-project` — Start new project initialization
-`/qualia-new-project "Build AI chatbot for client X"` — Start with initial description
-
-## Process
-
-Reference: `~/.claude/qualia-framework/workflows/new-project.md` (the full 1000+ line workflow — follow it exactly)
-
-### 0. Pre-flight
-
-**Initialize context:**
-```bash
-INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-project)
-```
-
-Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `project_exists`, `has_existing_code`, `needs_codebase_map`, `has_git`.
-
-- If `project_exists` is true → Error: "Project already initialized. Run `/qualia-progress` to see status."
-- If `has_git` is false → `git init`
-
-**Scan for uploaded files** (PDFs, docs, images). If they mention a non-Qualia stack, ask:
-> "The document mentions {stack}. Use the Qualia stack (Next.js + Supabase + Vercel) or the document's stack?"
-
-**Brownfield detection:** If existing code found without a codebase map, scan the codebase structure before proceeding.
-
-### 1. Deep Questioning
-
-Reference: `~/.claude/qualia-framework/references/questioning.md`
-
-**Start open:** "What do you want to build?"
-
-Then follow threads — dig into what they said. This is dream extraction, not an interview. Ask about:
-- What is it? Who is it for?
-- What problem does it solve?
-- What does "done" look like?
-- What are the constraints (timeline, budget, existing systems)?
-
-Use AskUserQuestion with concrete options to help them think. Challenge vagueness. Make abstract things concrete ("walk me through using this").
-
-**Decision gate:** When you have enough to write PROJECT.md, ask:
-> "I think I understand. Ready to create PROJECT.md, or want to explore more?"
-
-### 2. Detect Project Type & Load Template
-
-Based on questioning answers, detect the project type:
-
-| Signal | Type | Template |
-|--------|------|----------|
-| website, landing page, marketing, SaaS | `website` | `templates/projects/website.md` |
-| chatbot, AI assistant, chat agent | `ai-agent` | `templates/projects/ai-agent.md` |
-| voice agent, phone agent, call bot, Retell | `voice-agent` | `templates/projects/voice-agent.md` |
-| mobile app, iOS, Android, Expo | `mobile-app` | `templates/projects/mobile-app.md` |
-
-**Always load the matching template.** Read it from `~/.claude/qualia-framework/templates/projects/{type}.md`. This gives you the standard phase structure for this project type — the roadmap will use it as a scaffold.
-
-Ask the employee to confirm:
-> "This looks like a {type} project. I'll use the {type} template for the phase structure. Sound right?"
-
-If no type detected, build the roadmap from scratch.
-
-### 3. Write PROJECT.md
-
-Template: `~/.claude/qualia-framework/templates/project.md`
-
-Synthesize all context into `.planning/PROJECT.md`:
-- Project name, description, client
-- Core Value (the ONE thing that must work)
-- Requirements (Active = hypotheses until shipped)
-- Context, Constraints, Key Decisions
-- Tech stack decisions
-- Deploy target
-
-**Commit immediately:**
-```bash
-mkdir -p .planning
-node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
-```
-
-### 4. Workflow Preferences
-
-Use sensible defaults. Only ask ONE question:
-
-```
-"Use recommended settings? (Interactive mode, standard depth, all quality agents, balanced profile)"
-  → Yes (Recommended) — use all defaults
-  → Customize — show individual options
-```
-
-**Defaults** (written to `.planning/config.json`):
-- Mode: Interactive
-- Depth: Standard (5-8 phases)
-- Execution: Parallel
-- Researcher: enabled
-- Plan Checker: enabled
-- Verifier: enabled
-- Model Profile: Balanced
-
-**If "Customize":** Show the individual options as AskUserQuestion. Otherwise skip straight to config.json creation.
-
-Write `.planning/config.json` with all settings.
-
-**Commit:**
-```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
-```
-
-### 5. Research Phase (if selected)
-
-Spawn 4 parallel research agents:
-1. **Stack research** → `.planning/research/STACK.md`
-2. **Features research** → `.planning/research/FEATURES.md`
-3. **Architecture research** → `.planning/research/ARCHITECTURE.md`
-4. **Pitfalls research** → `.planning/research/PITFALLS.md`
-
-Then spawn synthesizer → `.planning/research/SUMMARY.md`
-
-Present key findings to employee before moving on.
-
-### 6. Define Requirements
-
-Load context from PROJECT.md and research (if exists).
-
-**If research exists:** Present features by category (table stakes vs differentiators). Let employee scope each category for v1 using AskUserQuestion with multiSelect.
-
-**If no research:** Gather requirements conversationally.
-
-Generate `.planning/REQUIREMENTS.md` with:
-- v1 Requirements grouped by category (with REQ-IDs like AUTH-01, CONT-02)
-- v2 Requirements (deferred)
-- Out of Scope (with reasons)
-- Traceability section (filled by roadmap)
-
-**Show full requirements list for approval.** Loop until employee confirms.
-
-**Commit:**
-```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
-```
-
-### 7. Create Roadmap
-
-Spawn qualia-roadmapper agent with PROJECT.md, REQUIREMENTS.md, research, config, and the project type template.
-
-**Roadmap contains FEATURE PHASES ONLY.** Do NOT add review, deploy, or handoff phases to the roadmap. The finish line system (`/qualia-complete-milestone` → polish → review → PR → deploy → handoff) handles the 70%-to-100% journey automatically after all feature phases are done. Adding them to the roadmap would cause employees to do them twice.
-
-**If using a project type template:** Use its phases as the feature scaffold.
-
-**Present roadmap to employee for approval.** Show phase table with goals, requirements mapped, and success criteria. Loop until approved.
-
-**Commit:**
-```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
-```
-
-### 8. Environment Setup
-
-Detect what's needed from PROJECT.md and stack:
-
-- **Supabase** → Link or create project, init schema
-- **Vercel** → Link project
-- **Environment variables** → Create `.env.local` with placeholders
-- **External services** → Note which API keys are needed (Stripe, Retell, OpenRouter, etc.)
-
-Walk the employee through setup. If they want to skip: note `env_setup: pending` in STATE.md.
-
-**Starter template:** If a matching starter exists at `~/Projects/qualia-erp/templates/{type}-starter/`, offer to scaffold from it.
-
-### 9. Design Context (frontend projects)
-
-If the project involves frontend work (detected from roadmap or project type), create `.planning/DESIGN.md` with a brief design consultation:
-
-Ask the employee 3 questions using AskUserQuestion:
-1. **Aesthetic direction** — "What feel should this project have?" (options: Clean/minimal, Bold/striking, Warm/friendly, Corporate/professional)
-2. **Color palette** — "Any brand colors or preferences?" (freeform — or offer to pick based on aesthetic)
-3. **Reference sites** — "Any websites you'd like it to look/feel like?" (freeform)
-
-Write `.planning/DESIGN.md` with the answers. This is read by the frontend guard before any UI work.
-
-**Do NOT run `/critique` here** — there's no code to critique yet. Design consultation creates the brief; `/critique` reviews implemented UI later.
-
-### 10. Done — Present Summary
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Qualia ► PROJECT INITIALIZED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**[Project Name]** — [type] project for [client]
-
-| Artifact       | Location                    |
-|----------------|-----------------------------|
-| Project        | .planning/PROJECT.md        |
-| Config         | .planning/config.json       |
-| Research       | .planning/research/         |
-| Requirements   | .planning/REQUIREMENTS.md   |
-| Roadmap        | .planning/ROADMAP.md        |
-| State          | .planning/STATE.md          |
-| Design         | .planning/DESIGN.md         |
-
-**[N] phases** | **[X] requirements** | Ready to build ✓
-
-## The Full Journey
-
-Phase 1-{N}: Feature phases (build the product)
-  ↓ after all phases verified
-Finish Line: Polish → Review → PR → Deploy → Handoff (automated by /qualia)
-
-## ▶ Next
-
-Run `/qualia-plan-phase 1` to plan the first phase.
-(Or `/qualia-discuss-phase 1` to discuss approach first.)
-```
-
-### Agents Used
-| Agent | File | Role |
-|-------|------|------|
-| `qualia-project-researcher` | `~/.claude/agents/qualia-project-researcher.md` | Domain ecosystem research (4 parallel) |
-| `qualia-research-synthesizer` | `~/.claude/agents/qualia-research-synthesizer.md` | Synthesizes parallel research |
-| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md with feature phases |
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-pause-work/SKILL.md

@@ -1,96 +0,0 @@
----
-name: qualia-pause-work
-description: "Save session context for seamless handoff between Claude sessions. Use this skill whenever the user says 'pause', 'save progress', 'stop for now', 'pause work', 'handoff', 'save thoughts', or wants to preserve their current working state before ending a session. Also trigger when user mentions 'continue later', 'pick up tomorrow', or needs to create a checkpoint of current work. Supports both full project handoff and lightweight thoughts mode."
----
-
-# Qualia Pause Work — Session Handoff
-
-Save current session context so the next session can pick up exactly where you left off.
-
-## Usage
-
-`/qualia-pause-work` — Full project-aware handoff (creates `.continue-here.md`)
-`/qualia-pause-work --thoughts` — Lightweight thought dump (saves to `~/.claude/thoughts/`)
-
-## Default Mode (Project Handoff)
-
-### 1. Read Current State
-
-Load `.planning/STATE.md` and check current phase status.
-
-Reference: `~/.claude/qualia-framework/workflows/pause-work.md`
-
-### 2. Create `.continue-here.md`
-
-Write a handoff file at the project root with:
-
-```markdown
-# Continue Here
-
-## Session Summary
-What was accomplished this session.
-
-## Current Phase
-Phase X: [name] — [status]
-
-## In Progress
-- What's partially done
-- Where exactly work stopped
-
-## Next Steps
-1. Immediate next action
-2. Following actions
-
-## Key Decisions Made
-- Decision 1 and rationale
-- Decision 2 and rationale
-
-## Blockers / Open Questions
-- Any unresolved issues
-
-## Files Modified
-- List of changed files with brief description
-```
-
-### 3. Git Commit
-
-Stage and commit with a descriptive message (add only modified files, never `git add -A`):
-```bash
-git add <list of modified files>
-git commit -m "WIP: [phase name] - [brief description of state]"
-```
-
-## Thoughts Mode (`--thoughts`)
-
-Lightweight handoff for non-project work or quick brainstorming sessions.
-
-### Save Location
-`~/.claude/thoughts/handoff-{timestamp}.md`
-
-### Structure
-```markdown
-# Handoff — {date}
-
-## Accomplished
-- What got done
-
-## Current State
-- Where things stand
-
-## In Progress
-- Partially complete work
-
-## Next Steps
-1. What to do next
-
-## Key Decisions
-- Important choices made
-
-## Blockers
-- What's stuck
-
-## Commands to Resume
-- Specific commands or files to look at
-```
-
-No git commit in thoughts mode — it's just a text dump for context restoration.

package/framework/skills/qualia-plan-milestone-gaps/SKILL.md

@@ -1,57 +0,0 @@
----
-name: qualia-plan-milestone-gaps
-description: "Create fix phases from milestone audit gaps — reads the most recent audit report and generates ROADMAP.md entries for all identified gaps. Use this skill whenever the user says 'plan gaps', 'fix gaps', 'plan milestone gaps', 'create fix phases', or wants to turn audit findings into actionable phases. Also trigger after a milestone audit reveals gaps that need addressing."
----
-
-# Qualia Plan Milestone Gaps — Gap-to-Phase Conversion
-
-Read the most recent milestone audit report and create ROADMAP.md phases to close all identified gaps.
-
-## Usage
-
-`/qualia-plan-milestone-gaps` — Auto-detect latest audit, create fix phases
-
-## Process
-
-### 1. Find Latest Audit
-
-```bash
-ls -t .planning/v*-MILESTONE-AUDIT.md | head -1
-```
-
-Read the most recent `v*-MILESTONE-AUDIT.md` file.
-
-Reference: `~/.claude/qualia-framework/workflows/plan-milestone-gaps.md`
-
-### 2. Load Project Context
-
-Read these files for full context:
-- `.planning/PROJECT.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
-
-### 3. Extract and Group Gaps
-
-From the audit report, extract all gaps (items marked as failing or incomplete). Group related gaps into logical phases:
-- Group by feature area or component
-- Keep phases small (completable in 1-2 sessions)
-- Order by dependency — fix foundations before features
-
-### 4. Create ROADMAP.md Entries
-
-Append new phases to ROADMAP.md. Each gap-fix phase should include:
-- Phase number (continuing from existing phases)
-- Name: `Fix: [area]`
-- Description of what gaps it closes
-- Status: `not started`
-- Reference to specific audit gaps being addressed
-
-### 5. Update STATE.md
-
-Update the phase table in STATE.md to reflect the new fix phases.
-
-### 6. Report
-
-Tell the user how many gaps were found, how many fix phases were created, and suggest:
-> "Fix phases created. Run `/qualia-plan-phase [next-phase-number]` to plan the first fix."

package/framework/skills/qualia-plan-phase/SKILL.md

@@ -1,104 +0,0 @@
----
-name: qualia-plan-phase
-description: "Create detailed execution plans for a project phase with optional research and verification. Use this skill whenever the user says 'plan phase', 'plan next phase', 'create plan', or wants to plan out how a specific phase of work should be executed. Also trigger when user mentions 'PLAN.md', 'phase planning', or needs to break a roadmap phase into concrete implementation steps. Supports research integration, gap closure planning, and plan verification."
----
-
-# Qualia Plan Phase — Phase Planning
-
-Create detailed PLAN.md files for a project phase, with optional research and verification loop.
-
-## Usage
-
-`/qualia-plan-phase 3` — Plan phase 3
-`/qualia-plan-phase` — Auto-detect next unplanned phase
-`/qualia-plan-phase 3 --research` — Force research before planning
-`/qualia-plan-phase 3 --skip-research` — Skip research even if recommended
-`/qualia-plan-phase 3 --gaps` — Plan gap closure (after verify-work found issues)
-`/qualia-plan-phase 3 --skip-verify` — Skip plan verification step
-
-## Process
-
-### 1. Identify Target Phase
-
-If phase number provided, use it. Otherwise, scan ROADMAP.md for the first phase with status `not started` or `planned` without a PLAN.md.
-
-Reference: `~/.claude/qualia-framework/workflows/plan-phase.md`
-
-### 2. Research (if needed)
-
-Research is recommended when:
-- Phase involves unfamiliar tech or APIs
-- Phase has complex architectural decisions
-- User passes `--research` flag
-
-Skip if `--skip-research` is passed or if research already exists at `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md`.
-
-If research is needed, use the qualia-research-phase skill first.
-
-### 3. Create PLAN.md
-
-Write to `.planning/phases/{phase}-{slug}/PLAN.md`:
-
-```markdown
-# Phase {N}: {Name} — Execution Plan
-
-## Objective
-What this phase accomplishes.
-
-## Prerequisites
-- What must be done/ready before starting
-
-## Implementation Steps
-
-### Step 1: {description}
-- Files to create/modify
-- Key implementation details
-- Acceptance criteria
-
-### Step 2: {description}
-...
-
-## Verification Checklist
-- [ ] Each testable outcome
-- [ ] Integration points work
-- [ ] No regressions
-
-## Risks & Mitigations
-- Risk 1 → Mitigation
-```
-
-For `--gaps` mode, the plan focuses specifically on closing gaps identified by verify-work, referencing the UAT.md findings.
-
-### 4. Verify Plan (unless --skip-verify)
-
-Spawn the qualia-plan-checker agent to review the plan for:
-- Completeness against requirements
-- Realistic scope
-- Clear acceptance criteria
-- No missing dependencies
-
-Reference: `~/.claude/agents/qualia-plan-checker.md`
-
-If checker finds issues, revise the plan and re-verify.
-
-### 5. Update State
-
-Update `.planning/STATE.md` to reflect the phase is now `planned`.
-
-Reference UI/brand guidelines: `~/.claude/qualia-framework/references/ui-brand.md`
-
-For complex phases touching multiple subsystems, consider `/deep-research` before phase research to establish architectural direction.
-
-### 6. Next Step
-
-> "Phase {N} planned. Run `/qualia-execute-phase {N}` to begin execution."
-
-### Agents Used
-| Agent | File | Role |
-|-------|------|------|
-| `qualia-planner` | `~/.claude/agents/qualia-planner.md` | Creates PLAN.md with goal-backward methodology |
-| `qualia-plan-checker` | `~/.claude/agents/qualia-plan-checker.md` | Validates plan completeness |
-| `qualia-phase-researcher` | `~/.claude/agents/qualia-phase-researcher.md` | Phase research (when --research) |
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-progress/SKILL.md

@@ -1,53 +0,0 @@
----
-name: qualia-progress
-description: "Check project progress and get routed to the right next action. Use this skill whenever the user says 'progress', 'how far along', 'what happened', 'show progress', or wants a summary of what's been done and what comes next. Also trigger when user seems to need situational awareness about their project state before deciding what to do. Routes to the most logical next step based on current state."
----
-
-# Qualia Progress — Progress Check & Routing
-
-Check current progress, summarize state, and route to the most logical next action.
-
-## Usage
-
-`/qualia-progress` — Check progress and get next-step recommendation
-
-## Process
-
-### 1. Load State
-
-Read `.planning/STATE.md`, `.planning/ROADMAP.md`, and check `git status --short`.
-
-Reference: `~/.claude/qualia-framework/workflows/progress.md`
-
-### 2. Summarize Progress
-
-Present a concise summary:
-- Current milestone and phase
-- Phases completed vs total
-- Current phase status
-- Any uncommitted changes
-- Recent activity
-
-### 3. Route to Next Action
-
-Based on current state, recommend one of these routes:
-
-**Route A** — Phase needs planning:
-> "Phase {N} is next and unplanned. Run `/qualia-plan-phase {N}`."
-
-**Route B** — Phase is planned, needs execution:
-> "Phase {N} is planned and ready. Run `/qualia-execute-phase {N}`."
-
-**Route C** — Phase is executed, needs verification:
-> "Phase {N} is done but unverified. Run `/qualia-verify-work {N}`."
-
-**Route D** — Verification found gaps:
-> "Phase {N} has gaps from verification. Run `/qualia-plan-phase {N} --gaps`."
-
-**Route E** — All phases complete:
-> "All phases done! Run `/qualia-audit-milestone` to verify the milestone."
-
-**Route F** — Milestone audit complete:
-> "Milestone audit passed. Run `/qualia-complete-milestone` to archive and tag."
-
-Keep the output concise — this is a quick status check with routing, not a detailed report.

package/framework/skills/qualia-quick/SKILL.md

@@ -1,89 +0,0 @@
----
-name: qualia-quick
-description: "Execute quick tasks with Qualia quality guarantees — atomic commits, STATE.md tracking, minimal overhead. Use this skill whenever the user says 'quick task', 'quick fix', 'just do this quickly', 'small change', 'hotfix', or wants to make a small change outside the normal phase workflow. Also trigger when user mentions 'quick bug fix', '--fix', or needs a fast targeted change with proper tracking. Supports no-plan mode and bug-fix mode with minimal-change discipline."
----
-
-# Qualia Quick — Quick Tasks with Guarantees
-
-Execute small tasks outside the normal phase workflow while maintaining Qualia quality standards: atomic commits, state tracking, and verification.
-
-## Usage
-
-`/qualia-quick "Add loading spinner to dashboard"` — Quick task with planning
-`/qualia-quick --no-plan "Update footer copyright year"` — Skip planner, just do it
-`/qualia-quick --fix "Login button not responding on mobile"` — Bug fix mode (implies --no-plan)
-
-## Process
-
-### 1. Load Context
-
-Read `.planning/STATE.md` for current project state.
-
-Reference: `~/.claude/qualia-framework/workflows/quick.md`
-
-### 2. Complexity Check
-
-Before planning or executing, classify the task:
-
-| Signal | Classification | Action |
-|--------|---------------|--------|
-| Single file change, familiar codebase | **Quick** | Proceed directly (no confirmation) |
-| `--no-plan` or `--fix` flag | **Quick** | Proceed directly (no confirmation) |
-| Typo, config, or copy change | **Quick** | Proceed directly (no confirmation) |
-| Multi-file change | **Non-trivial** | Present understanding, wait for confirmation |
-| Architectural impact (new table, new service, new API) | **Non-trivial** | Present understanding, wait for confirmation |
-| Unfamiliar codebase (first time working in this project) | **Non-trivial** | Present understanding, wait for confirmation |
-
-**If Non-trivial:** Before making changes, present:
-> "Here's what I understand: [1-2 sentence summary]. I'll modify [file list]. Correct?"
-
-Wait for user confirmation. Capture any corrections for the session.
-
-**If Quick:** Skip confirmation and proceed to Step 3.
-
-### 3. Plan (unless --no-plan or --fix)
-
-Quick-plan the task:
-- What files need changing
-- What the change looks like
-- How to verify it works
-
-Quick tasks do NOT create PLAN.md files — planning is lightweight and inline.
-
-### 4. Execute
-
-Implement the change. Quick tasks live in `.planning/quick/` — they're separate from planned phases.
-
-#### Fix Mode (`--fix`)
-Bug fix mode enforces minimal-change discipline:
-1. **Locate** — Find the exact source of the bug
-2. **Root Cause** — Understand why it's happening
-3. **Smallest Fix** — Make the minimum change that fixes it
-4. **Verify** — Confirm the fix works and nothing else broke
-
-Fix mode skips planning entirely (implies `--no-plan`).
-
-### 5. Verify
-
-Run the change and verify it works:
-- Does the feature/fix work as expected?
-- No console errors?
-- No regressions in related functionality?
-
-### 6. Track
-
-Update `.planning/STATE.md` — add entry to the "Quick Tasks Completed" table:
-
-| Date | Task | Status |
-|------|------|--------|
-| YYYY-MM-DD | Description | ✅ Done |
-
-**Important**: Quick tasks update STATE.md only, NOT ROADMAP.md. They're tracked separately from planned phases.
-
-### 7. Commit
-
-Atomic commit with descriptive message:
-```bash
-git add [specific files]
-git commit -m "quick: [description of change]"
-```