qualia-framework 2.4.0 → 2.4.2

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

@@ -0,0 +1,200 @@
+---
+name: qualia-evolve
+description: "Self-optimization loop — analyzes metrics, Lab Notes, and session history across all shipped projects, then proposes framework improvements. The Karpathy loop for the framework itself. Use after shipping a project, or periodically to improve the framework."
+user-invocable: true
+args:
+  - name: project
+    description: "Project to collect metrics from (defaults to current directory)"
+    required: false
+---
+
+# Qualia Evolve — Framework Self-Optimization
+
+The recursive improvement loop. Reads real project outcomes, identifies what's working and what's failing, and proposes targeted changes to skill prompts, agent instructions, templates, and defaults.
+
+**This is NOT code optimization.** This optimizes the FRAMEWORK — the prompts, the flow, the defaults, the instructions that shape how every future project runs.
+
+## Usage
+
+`/qualia-evolve` — Full optimization cycle (collect + analyze + propose)
+`/qualia-evolve --collect` — Just collect metrics from current project
+`/qualia-evolve --analyze` — Just analyze existing metrics (no collection)
+
+## Process
+
+### 1. Collect Metrics (if not --analyze only)
+
+Run the metrics harness on the current project:
+
+```bash
+bash ~/.claude/qualia-framework/bin/collect-metrics.sh "$(pwd)"
+```
+
+This appends a row to `~/.claude/knowledge/framework-metrics.md`.
+
+### 2. Load All Evidence
+
+Read these files — they're the raw data for optimization:
+
+```bash
+# Framework metrics (all shipped projects)
+cat ~/.claude/knowledge/framework-metrics.md 2>/dev/null
+
+# Session digest (recent sessions across all projects)
+cat ~/.claude/knowledge/session-digest.md 2>/dev/null
+
+# Global learned patterns
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+
+# Optimization objective (what "better" means)
+cat ~/.claude/qualia-framework/OBJECTIVE.md
+```
+
+Also scan for Lab Notes across all projects:
+
+```bash
+find ~/Projects/*/. -name "LAB-NOTES.md" -path "*/.planning/*" 2>/dev/null | while read f; do
+  echo "=== $(dirname $(dirname $f) | xargs basename) ==="
+  cat "$f"
+done
+```
+
+### 3. Spawn Analysis Agents (Fan-out)
+
+Spawn 3 parallel agents to analyze different dimensions:
+
+**Agent 1: Flow Efficiency Analyst**
+```
+Analyze framework metrics and session digests.
+- Which projects took the most sessions? Why?
+- Where do employees get stuck? (look for /qualia-idk calls, long sessions, repeated phases)
+- Which phases consistently need gap-fix plans? (high deviation signal)
+- Are preferences defaults working? (do people customize, or use recommended?)
+- What's the trend? Is the framework getting faster or slower?
+Return: top 3 flow bottlenecks with evidence.
+```
+
+**Agent 2: Failure Pattern Analyst**
+```
+Analyze Lab Notes across all projects and learned-patterns.md.
+- What approaches keep failing? Are we still recommending them in skill prompts?
+- Are there common anti-patterns that multiple projects hit?
+- Which agent instructions lead to the most deviations?
+- Are there failure categories? (e.g., "auth always needs 2 tries", "Supabase RLS is always missed first pass")
+Return: top 3 recurring failure patterns with root cause.
+```
+
+**Agent 3: Quality Gate Analyst**
+```
+Analyze verification pass rates and post-deploy issues.
+- Which phases fail verification most often? What type of failures?
+- Are the quality gates catching real issues or adding overhead?
+- Is the red-team QA agent finding things the verifier misses?
+- What gets caught at /qualia-review that should have been caught earlier?
+Return: top 3 quality gaps with evidence.
+```
+
+### 4. Synthesize Findings
+
+Spawn the synthesizer agent with all 3 reports:
+
+```
+Downstream consumer: Fawzi reviewing framework improvement proposals.
+Cross-reference findings. Identify root causes that explain multiple symptoms.
+A flow bottleneck might be caused by a failure pattern which is caused by a quality gap.
+```
+
+### 5. Propose Framework Changes
+
+For each finding, propose a SPECIFIC change:
+
+```markdown
+## Proposed Changes
+
+### Change 1: [title]
+**Evidence:** [metrics/lab notes that support this]
+**Root cause:** [why this is happening]
+**Proposed fix:** [exact file + exact change]
+**Expected impact:** [which metric improves and by how much]
+**Risk:** [what could go wrong]
+
+### Change 2: ...
+```
+
+Rules for proposals:
+- Every change must cite evidence from metrics or Lab Notes
+- Every change must target a specific file (skill, agent, template, or default)
+- Every change must predict which metric it improves
+- Maximum 5 changes per cycle (don't over-optimize)
+- Never change OBJECTIVE.md or collect-metrics.sh (those are the fixed harness)
+
+### 6. Present to Fawzi for Approval
+
+Show the proposals with evidence. For each one:
+
+```
+"Change [N]: [title]
+ Evidence: [data]
+ File: [path]
+ Change: [what specifically changes]
+
+ Apply? (yes/no/modify)"
+```
+
+### 7. Apply Approved Changes
+
+For each approved change:
+1. Read the target file
+2. Make the specific edit
+3. Sync to `~/Projects/qualia-framework/` (the git-tracked copy)
+4. Log the change to `~/.claude/knowledge/framework-evolution.md`
+
+### 8. Commit Evolution
+
+```bash
+cd ~/Projects/qualia-framework && git add -A && git commit -m "evolve: [summary of changes]"
+```
+
+## Evolution Log
+
+Every change gets logged to `~/.claude/knowledge/framework-evolution.md`:
+
+```markdown
+## [Date] — Cycle [N]
+
+**Trigger:** Post-ship analysis of [project]
+**FQS before:** [score]
+
+### Changes Applied
+1. [change description] → [file modified]
+2. ...
+
+### Changes Rejected
+1. [change description] — Reason: [why]
+
+### Predicted Impact
+- [metric]: [expected change]
+```
+
+This log is read in future cycles to track whether changes actually helped.
+
+## Bounded Time Budget
+
+The optimization pass should complete in ~10 minutes:
+- Metrics collection: 30 seconds
+- Evidence loading: 1 minute
+- 3 analysis agents (parallel): 3-5 minutes
+- Synthesis: 2 minutes
+- Proposal + approval: 2-3 minutes
+
+Do NOT spend more than 15 minutes total. If analysis is taking too long, present what you have.
+
+## Agents Used
+
+| Agent | Role |
+|-------|------|
+| `general-purpose` (x3) | Flow, Failure, Quality analysis |
+| `qualia-research-synthesizer` | Cross-cutting synthesis |
+
+---
+> Run `/qualia-evolve` after shipping a project. The framework gets smarter every time.

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

@@ -86,4 +86,4 @@ Update `.planning/STATE.md` phase status to `executed`.
 Domain skill context from PLAN.md `@skill` references is automatically resolved and inlined into each executor subagent prompt. Plans referencing skills like `frontend-design`, `supabase`, `financial-ledger`, etc. will have those patterns available to executors.
 
 ---
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help` · Done for today? Type `/qualia-report`

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

@@ -0,0 +1,32 @@
+---
+name: qualia-guide
+description: "Show the developer guide — how the Qualia framework works, the full project flow, and the 10 commands that matter. Use this skill whenever the user says 'guide', 'how does this work', 'explain the framework', 'qualia guide', 'show me the flow', or is confused about how to use the framework."
+user-invocable: true
+args: []
+---
+
+# Qualia Developer Guide
+
+Display the employee guide that explains how the full workflow works.
+
+## Process
+
+1. Read `~/.claude/qualia-framework/references/employee-guide.md`
+2. Output its contents directly — this IS the guide, formatted for terminal display
+3. If in a project with `.planning/`, also show current position:
+   - Read STATE.md
+   - Show which step of the flow they're currently on
+   - Highlight the next command to run
+
+## Output Enhancement
+
+After showing the guide, if in a project, add:
+
+```
+── YOUR CURRENT POSITION ───────────────
+  You are at: [phase/step name]
+  Next command: /[command]
+```
+
+---
+> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help` · Done for today? Type `/qualia-report`

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

@@ -13,100 +13,102 @@ Display the complete reference of all available Qualia workflow skills, organize
 
 ## Output
 
-Reference: `~/.claude/qualia-framework/workflows/help.md`
-
-Display the command reference below. Output only — no analysis, no suggestions, just the reference.
+Display the command reference below. Organized in two sections: **Essential** (the commands you actually use) and **Advanced** (everything else).
 
 ---
 
-### "I'm starting a new project"
-| Command | What it does |
-|---------|-------------|
-| `/qualia-new-project` | Full project setup: questioning → research → requirements → roadmap → environment |
-| `/qualia-new-milestone` | Start a new milestone on an existing project |
+```
+◆ QUALIA COMMAND REFERENCE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-### "I need to plan and build"
-| Command | What it does |
-|---------|-------------|
-| `/qualia-plan-phase` | Create detailed execution plans for the next phase |
-| `/qualia-execute-phase` | Build the phase (spawns subagents, runs in waves) |
-| `/qualia-discuss-phase` | Clarify decisions before planning |
-| `/qualia-list-phase-assumptions` | Surface hidden assumptions before planning |
-| `/qualia-research-phase` | Research a topic before planning |
-| `/qualia-quick` | Quick one-off tasks without full phase workflow |
+### ESSENTIAL — The commands you need every day
 
-### "I finished building — what now?"
 | Command | What it does |
 |---------|-------------|
-| `/qualia-verify-work` | Test that what was built matches the plan (UAT) |
-| `/qualia-progress` | See how far along the project is + what's next |
-| `/qualia` | Quick router — tells you the exact next command to run |
+| `/qualia` | **"What do I do next?"** — reads state, tells you the exact next command |
+| `/qualia-new-project` | Start a new project from scratch |
+| `/qualia-plan-phase N` | Plan a phase |
+| `/qualia-execute-phase N` | Build a phase |
+| `/qualia-verify-work N` | Test a phase |
+| `/critique` | Review the design |
+| `/polish` | Fix spacing, alignment, details |
+| `/harden` | Handle edge cases, errors |
+| `/qualia-review --web` | Code quality + security audit |
+| `/pr` | Create a pull request |
+
+### NAVIGATION — When you're lost or stuck
 
-### "I need to review and fix quality"
 | Command | What it does |
 |---------|-------------|
-| `/qualia-review` | Code review — security, quality, architecture. Use `--web` for web apps, `--ai` for AI agents |
-| `/qualia-optimize` | Find and fix performance, design, and code issues |
-| `/qualia-design` | One-shot design fix — critique + polish + harden + responsive |
-| `/qualia-production-check` | Final audit before handing to client (5 specialist agents) |
+| `/qualia-guide` | **New to the framework?** Shows how everything works |
+| `/qualia-idk` | **Stuck?** Analyzes your situation, suggests what to do |
+| `/qualia-progress` | See how far along the project is |
+| `/qualia-debug` | Structured debugging when something is broken |
+
+### SESSION — Starting and ending your day
 
-### "I need to deploy"
 | Command | What it does |
 |---------|-------------|
-| `/ship` | **The standard deploy command.** Quality gates → git → deploy → verify. Use this. |
-| `/deploy` | Quick deploy without quality gates (advanced) |
-| `/deploy-verify` | Post-deploy verification only (usually called by /ship) |
+| `/qualia-report` | Log what you did today (Fawzi reviews these) |
+| `/qualia-pause-work` | Save context before ending session |
+| `/qualia-resume-work` | Pick up where you left off |
+
+---
 
-### "I'm done — time to deliver to client"
+<details>
+<summary>ADVANCED — Full command reference (you rarely need these)</summary>
+
+### Planning
 | Command | What it does |
 |---------|-------------|
-| `/qualia-audit-milestone` | Verify all requirements are met before wrapping up |
-| `/qualia-complete-milestone` | Archive milestone, tag release, generate changelog |
-| `/client-handoff` | Generate the client delivery document (features, credentials, maintenance notes) |
-| `/qualia-plan-milestone-gaps` | Create fix phases if the audit found gaps |
+| `/qualia-discuss-phase` | Clarify decisions before planning |
+| `/qualia-list-phase-assumptions` | Surface hidden assumptions |
+| `/qualia-research-phase` | Research a topic before planning |
+| `/qualia-quick` | Quick one-off tasks without full workflow |
 
-### "I'm stuck or confused"
+### Quality & Design
 | Command | What it does |
 |---------|-------------|
-| `/qualia-idk` | **Use this when you don't know what to do.** Analyzes your situation and suggests next steps. |
-| `/qualia-help` | This reference (you're looking at it) |
-| `/qualia-debug` | Structured debugging when something is broken |
-| `/qualia-progress` | See where the project stands |
+| `/qualia-design` | One-shot design fix (critique + polish + harden + responsive) |
+| `/qualia-optimize` | Find perf, design, and code issues |
+| `/qualia-production-check` | Final audit before client handoff |
 
-### "I need to pause or resume"
+### Milestone Lifecycle
 | Command | What it does |
 |---------|-------------|
-| `/qualia-pause-work` | Save session context before stopping |
-| `/qualia-resume-work` | Restore context and pick up where you left off |
+| `/qualia-audit-milestone` | Verify all requirements met |
+| `/qualia-complete-milestone` | Archive milestone, tag release |
+| `/qualia-plan-milestone-gaps` | Create fix phases from audit gaps |
+| `/qualia-new-milestone` | Start next milestone on existing project |
+| `/client-handoff` | Generate client delivery document |
 
-### "I need to track tasks and notes"
+### Deploy (Fawzi only)
 | Command | What it does |
 |---------|-------------|
-| `/qualia-add-todo` | Capture an idea or task for later |
-| `/qualia-check-todos` | Review pending todos |
-| `/learn` | Save a lesson from a mistake |
-| `/memory` | See what Claude remembers |
+| `/ship` | Full deploy pipeline with quality gates |
+| `/deploy` | Quick deploy without gates |
+| `/deploy-verify` | Post-deploy verification |
 
-### "I'm building a specific type of thing"
+### Specialized Builders
 | Command | What it does |
 |---------|-------------|
-| `/frontend-master` | Premium, distinctive UI components |
+| `/frontend-master` | Premium UI components |
 | `/voice-agent` | Retell AI + ElevenLabs voice agent |
 | `/openrouter-agent` | AI chatbot with OpenRouter |
 | `/mobile-expo` | React Native / Expo mobile app |
 | `/supabase` | Database, auth, edge functions, RLS |
 | `/seo-master` | SEO audit and optimization |
-| `/rag` | RAG system (embeddings + retrieval) |
 
-### Which review/audit skill should I use?
-| Situation | Use |
-|-----------|-----|
-| Before deploying (code quality) | `/qualia-review` |
-| Before client handoff (is it ready?) | `/qualia-production-check` |
-| Finding issues to fix (perf, design) | `/qualia-optimize` |
-| AI/voice agent safety check | `/qualia-review --ai` |
-| Auditing the framework itself | `/qualia-framework-audit` |
+### Notes & Memory
+| Command | What it does |
+|---------|-------------|
+| `/qualia-add-todo` | Capture a task for later |
+| `/qualia-check-todos` | Review pending todos |
+| `/learn` | Save a lesson from a mistake |
+
+</details>
 
 ---
 
-**Tip:** Most of the time, just describe what you want in plain language. The framework will route to the right skill automatically. Say "and ship" when you want it deployed.
+**Tip:** Most of the time, just describe what you want in plain language. Or type `/qualia` — it always knows what's next.

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

@@ -31,7 +31,7 @@ Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `pr
 **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, offer `/qualia-map-codebase` first.
+**Brownfield detection:** If existing code found without a codebase map, scan the codebase structure before proceeding.
 
 ### 1. Deep Questioning
 
@@ -88,18 +88,24 @@ node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize pro
 
 ### 4. Workflow Preferences
 
-Ask the employee about how they want to work:
+Use sensible defaults. Only ask ONE question:
 
-**Core settings:**
-- **Mode:** YOLO (auto-approve) or Interactive (confirm each step)?
-- **Depth:** Quick (3-5 phases) / Standard (5-8 phases) / Comprehensive (8-12 phases)?
-- **Execution:** Parallel (independent plans run simultaneously) or Sequential?
+```
+"Use recommended settings? (Interactive mode, standard depth, all quality agents, balanced profile)"
+  → Yes (Recommended) — use all defaults
+  → Customize — show individual options
+```
 
-**Quality agents (all recommended for client projects):**
-- **Researcher:** Investigate domain before planning each phase?
-- **Plan Checker:** Verify plans will achieve their goals?
-- **Verifier:** Confirm deliverables match phase goals after execution?
-- **Model Profile:** Quality (Opus) / Balanced (Sonnet) / Budget (Haiku)?
+**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.
 
@@ -145,19 +151,9 @@ node ~/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requ
 
 Spawn qualia-roadmapper agent with PROJECT.md, REQUIREMENTS.md, research, config, and the project type template.
 
-**CRITICAL — The roadmap MUST include these mandatory final phases:**
-
-After all feature phases, the roadmap must always end with:
+**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.
 
-| Phase | Name | Purpose |
-|-------|------|---------|
-| N-2 | **Quality Review & Polish** | Run `/qualia-review`, fix issues, run design polish (`/critique` → `/polish` → `/harden`). No new features. |
-| N-1 | **Deploy & Verify** | Run `/ship` to production. Post-deploy verification (HTTP 200, auth, console, latency, UptimeRobot). |
-| N | **Client Handoff** | Run `/client-handoff` to generate delivery document. Final production check (`/qualia-production-check`). Hand credentials, docs, and access to client. |
-
-These are NOT optional. Every client project needs review, deploy, and handoff. The employee should never have to discover these steps on their own.
-
-**If using a project type template:** Use its phases as the feature scaffold, then append the 3 mandatory final phases.
+**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.
 
@@ -181,9 +177,16 @@ Walk the employee through setup. If they want to skip: note `env_setup: pending`
 
 ### 9. Design Context (frontend projects)
 
-If the project involves frontend work (detected from roadmap or project type):
+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.
 
-Run `/critique` to gather design context — brand colors, typography preferences, layout style, reference sites. This runs ONCE and persists to the project's `.planning/DESIGN.md` so all future phases have design context.
+**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
 
@@ -208,10 +211,9 @@ Run `/critique` to gather design context — brand colors, typography preference
 
 ## The Full Journey
 
-Phase 1-{N-3}: Feature phases (build the product)
-Phase {N-2}: Quality Review & Polish
-Phase {N-1}: Deploy & Verify
-Phase {N}: Client Handoff
+Phase 1-{N}: Feature phases (build the product)
+  ↓ after all phases verified
+Finish Line: Polish → Review → PR → Deploy → Handoff (automated by /qualia)
 
 ## ▶ Next
 
@@ -224,7 +226,7 @@ Run `/qualia-plan-phase 1` to plan the first phase.
 |-------|------|------|
 | `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 mandatory final phases |
+| `qualia-roadmapper` | `~/.claude/agents/qualia-roadmapper.md` | Creates ROADMAP.md with feature phases |
 
 ---
 > Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`