qualia-framework 5.5.0 → 5.8.0

package/skills/qualia-polish-loop/SKILL.md

@@ -1,201 +0,0 @@
----
-name: qualia-polish-loop
-description: "Autonomous visual-polish loop — screenshots a live URL at three viewports, scores 8 design dimensions against the rubric using vision, fixes issues in the codebase, re-screenshots, loops until every dimension scores ≥ 3 or the kill-switch fires. Trigger on 'polish loop', 'visual loop', 'screenshot polish', 'visual QA loop', 'fix what I see', 'make it look right', 'iterate on the design until it's correct'. v5.1 flagship — closes the design-iteration churn friction."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Agent
-argument-hint: "{url} [--brief PATH] [--max 8] [--viewports 375,768,1440] [--ref PATH] [--budget 100000]"
----
-
-# /qualia-polish-loop — Autonomous Visual-Polish Loop
-
-See its own work. Fix its own work. Stop only when correct.
-
-## What it does
-
-Takes a URL + design brief. Screenshots at 3 viewports (mobile / tablet / desktop). Spawns a vision evaluator that scores 8 dimensions of `qualia-design/design-rubric.md` against the brief with cited evidence. Spawns up to 3 fix-builders in parallel for the top issues. Re-screenshots. Loops until all dimensions ≥ 3 or the kill-switch trips (regression, budget, or max iterations).
-
-Different from `/qualia-polish`: that one is read+edit+slop-detect, single pass. This one is **see+edit+verify+repeat** with a real loop and real screenshots.
-
-## When to use
-
-- After `/qualia-build` or `/qualia-verify` when visual issues remain that text-based slop-detect can't catch (mobile-only breakage, motion missing, hero-video framing)
-- When the user says "it doesn't look right" / "fix what I see" / "the mobile version is broken"
-- As an opt-in upgrade to `/qualia-polish --redesign` Stage 4 (vision loop)
-- Before `/qualia-ship` for a final visual QA pass
-
-## Pre-flight (sequential, every invocation)
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner polish
-```
-
-Run these in order. Halt on the first failure.
-
-| Gate | Check | If fail |
-|---|---|---|
-| Substrate | `qualia-design/design-rubric.md`, `qualia-design/design-laws.md` exist | Run `npx qualia install` |
-| Brief | `--brief` PATH if provided, else `.planning/DESIGN.md`, else PRODUCT.md | If none, HALT: "No design brief found. Pass --brief or run /qualia-new." |
-| Browser | `node ~/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs --url about:blank --out /tmp/qpl-preflight` exits 0 | HALT with the script's setup hint |
-| URL reachable | `curl -fsS -o /dev/null -w '%{http_code}' "$URL"` returns 2xx/3xx | HALT — start the dev server first |
-| Working tree | `git status --porcelain` is empty | HALT — "Loop commits per iteration. Stash or commit pending changes first." |
-| Budget | Estimate iters × ~14.5K tokens; warn if > 100K | If `--budget` not set, default 100K. Surface estimate to user. |
-
-State the preflight explicitly:
-
-```
-QPL_PREFLIGHT: substrate=pass brief={path} browser=pass url=200 git=clean budget=100K
-```
-
-## Loop (max 8 iterations, default 6)
-
-Single state file at `/tmp/qpl-{timestamp}/state.json` keeps the deterministic counters (iteration, fingerprints, fixes, verdict) out of the LLM context.
-
-```bash
-RUN_ID="qpl-$(date +%s)"
-STATE="/tmp/${RUN_ID}/state.json"
-node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs init \
-  --state "$STATE" --url "$URL" --brief "$BRIEF" \
-  --max "${MAX:-8}" --budget "${BUDGET:-100000}"
-```
-
-Each iteration:
-
-### 1. Capture (deterministic, ~3-5s)
-
-```bash
-ITER_DIR="/tmp/${RUN_ID}/iter-${N}"
-node ~/.claude/skills/qualia-polish-loop/scripts/playwright-capture.mjs \
-  --url "$URL" --out "$ITER_DIR" --viewports 375,768,1440 --wait 1500
-```
-
-Three PNGs land in `$ITER_DIR/{mobile,tablet,desktop}-*.png`. The capture script auto-selects a backend: Playwright if `import('playwright')` resolves, else the cached `~/.cache/ms-playwright/chromium-*` binary, else `google-chrome` / `chromium` on PATH.
-
-### 2. Evaluate (vision — single Agent spawn per iteration)
-
-Spawn `Agent` with `subagent_type="qualia-visual-evaluator"`. Inline the rubric, the brief, the screenshots paths, the viewport meta, and the previous iteration's issues (if any). The agent reads the screenshots itself and returns a single JSON envelope per the contract in `agents/visual-evaluator.md`.
-
-Save the agent's JSON to `$ITER_DIR/eval.json`. The exact spawn template lives in REFERENCE.md (so the SKILL.md stays under 250 lines per progressive-disclosure discipline).
-
-### 3. Decide (deterministic)
-
-```bash
-node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs record \
-  --state "$STATE" --eval "$ITER_DIR/eval.json"
-```
-
-Exit codes: `0` = SUCCESS (all dims ≥ 3), `1` = CONTINUE (more iterations), `3` = KILLED (regression / budget / max).
-
-The orchestrator computes the verdict per `qualia-design/design-rubric.md`:
-
-- **all aggregate scores ≥ 3 AND no critical issues remain** → SUCCESS, exit loop
-- **same issue fingerprint recurred 3 consecutive iterations** → KILL, `LOOP_REGRESSION_DETECTED`
-- **tokens used exceeds budget** → KILL, `OUT_OF_BUDGET`
-- **iteration count = max** → KILL, `MAX_ITERATIONS_REACHED`
-- **else** → CONTINUE
-
-### 4. Fix (parallel, up to 3 builders)
-
-For the top 3 issues from `eval.json.top_issues`, spawn `qualia-builder` agents IN THE SAME RESPONSE TURN (parallel). Each builder receives the issue, the design tokens from DESIGN.md, and explicit "fix only this dimension, do not refactor" rules. Template in REFERENCE.md.
-
-Each builder commits its fix via the orchestrator's slop-detect-gated commit:
-
-```bash
-node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs commit-fix \
-  --state "$STATE" --file "$AFFECTED_FILE" --slug "{issue-slug}"
-```
-
-This stages the file, runs `slop-detect` first (critical findings BLOCK and the builder must retry), then commits with `qpl-{N}: {slug}`. Every fix is a real revertable git commit. Failed fixes leave the working tree clean — no half-edits.
-
-### 5. Redeploy (default: dev-localhost)
-
-Default mode does NOT redeploy. The loop assumes the dev server is running with HMR; the next capture re-screenshots the changed page. Verify the dev server is still up:
-
-```bash
-curl -fsS -o /dev/null "$URL" || HALT "dev server died at iteration $N"
-```
-
-For Vercel-preview mode (opt-in via `--deploy preview`), run `vercel deploy` (NOT `--prod`) and update `URL` to the deploy URL before the next capture. Slower (~30-60s/iter), but works against a fully-built environment when HMR isn't reliable.
-
-### 6. Loop back to Capture, increment N
-
-## Post-loop
-
-```bash
-node ~/.claude/skills/qualia-polish-loop/scripts/loop.mjs report --state "$STATE" \
-  > .planning/visual-polish-loop.md
-git add .planning/visual-polish-loop.md
-git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" \
-    commit -m "qpl-final: visual-polish-loop report"
-```
-
-Then a closing card via `qualia-ui`:
-
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Iterations: {N}/{max}"
-node ~/.claude/bin/qualia-ui.js ok "Final aggregate: {sum}/40 (avg {avg})"
-node ~/.claude/bin/qualia-ui.js ok "Fixes committed: {count}"
-node ~/.claude/bin/qualia-ui.js ok "Tokens used: {N}K of {budget}K"
-node ~/.claude/bin/qualia-ui.js end "VISUAL POLISH LOOP — {SUCCESS|KILLED-AT-N|OUT-OF-BUDGET}" "/qualia-verify or /qualia-ship"
-```
-
-## Hard rules
-
-1. **Vision-eval is anchored.** The rubric criteria are inlined in the eval prompt verbatim. Never spawn the evaluator with "tell me what you think" — that's how you get "looks great!" hallucinations. The verbatim contract is in REFERENCE.md.
-2. **Per-iteration commits.** Every fix gets `qpl-{N}: {slug}` prefix so the user can `git revert` any iteration cleanly. The orchestrator enforces this via `loop.mjs commit-fix`.
-3. **Slop-detect gate.** Critical findings BLOCK the commit. The fix-builder must retry (or the loop kills if the same fingerprint recurs 3x).
-4. **No silent destruction.** All edits go through git. Failed iterations leave clear `qpl-N:` commit trail. No working-tree side effects.
-5. **`prefers-reduced-motion` honored.** If reduced motion is set, the evaluator scores motion on CSS-declaration quality, not visible animation. Don't penalize "no motion" when reduced motion is on.
-6. **Budget discipline.** Token usage is tracked in state. KILL at cap. Surface partial progress.
-7. **Cleanup on exit.** No orphan browser processes (the capture script spawns short-lived headless processes, but verify nothing lingers via `pgrep -f chrome --headless`). Temp dirs left for forensic debugging until the next run.
-
-## Failure modes
-
-| Symptom | Likely cause | Action |
-|---|---|---|
-| `playwright-capture.mjs` exits 2 with `no_browser_backend` | No Chrome/Chromium found anywhere | `npx playwright install chromium` or install Google Chrome |
-| Screenshot is blank | Page not done rendering | Increase `--wait` to 3000ms; retry once |
-| Vision agent says "looks great!" to everything | Rubric not inlined / prompt drift | Verify REFERENCE.md prompt is being used verbatim. Check `agents/visual-evaluator.md` is on disk. |
-| Same issue every iteration | Fix-builder not addressing root cause | Kill at 3 recurrences (automatic). Read `state.json.fingerprints[*]` for diagnosis. Hand-fix and resume. |
-| Dev server died mid-loop | Port conflict / crash | Detect via curl heartbeat in step 5. HALT — restart server, run loop with `--resume STATE`. |
-| Token budget blown | Too many iterations needed | KILL at cap (automatic). Report partial progress. Consider tightening DESIGN.md or pre-running `/qualia-polish` once first. |
-
-## Setup notes for users
-
-The loop requires headless Chrome/Chromium. Two ways to get it:
-
-```bash
-# A. Playwright (recommended — best stability + waiting semantics)
-npx playwright install chromium
-
-# B. System Chrome (fallback — works if google-chrome or chromium is on PATH)
-# Already installed on most dev machines; nothing to do.
-```
-
-The capture script tries Playwright first, then the cached chromium binary, then PATH lookups. No npm dependency on Playwright is added to your project — it's optional.
-
-## Self-tests (the spec mandates 3 scenarios)
-
-`docs/playwright-loop-pilot-results.md` records the outcome of running the loop against:
-1. `fixtures/clean.html` (well-designed page) — expect SUCCESS in 1-2 iterations
-2. `fixtures/broken.html` (deliberately bad page) — expect SUCCESS in 4-6 iterations after fixes
-3. Synthetic kill-switch test — verify regression detection fires at iteration 4
-
-Run them with `bash skills/qualia-polish-loop/scripts/_self-tests.sh` (if present) or follow the manual instructions in REFERENCE.md.
-
-## Token-budget discipline
-
-| Max iterations | Estimated tokens | Notes |
-|---|---|---|
-| 2 | ~30K | tight — only for known-clean pages |
-| 4 | ~60K | standard |
-| 6 | ~90K | default |
-| 8 | ~120K | maximum — set `--budget 150000` to allow |
-
-Each iteration costs roughly: 3 PNG vision reads (~9K), rubric prompt (~2K), 3 fix-builder spawns with file reads (~3.5K). Plus the orchestrator's deterministic CLI calls (~negligible). The state file persists outside Claude's context entirely — only the per-iteration eval JSON and fix outcomes flow back in.

package/skills/qualia-prd/SKILL.md

@@ -1,199 +0,0 @@
----
-name: qualia-prd
-description: "Synthesize the current conversation into a durable Product Requirements Document (PRD) at .planning/PRD-{slug}.md. Optionally opens a parent GitHub issue. No interview — synthesizes what's already been discussed. Trigger on 'qualia-prd', 'turn this into a PRD', 'write this up as a feature spec', 'make a spec from this discussion', 'PRD this', 'externalize this idea', 'capture this as a spec'. Pairs with /qualia-issues to break the PRD into vertical-slice issues. Distinct from /qualia-plan (phase-operational) — /qualia-prd is feature-durable. v5.3 flagship from Matt Pocock's /to-prd pattern."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - Agent
-argument-hint: "[slug] [--issue] [--no-issue] [--update PATH]"
----
-
-# /qualia-prd — Conversation → durable feature spec
-
-You've been discussing a feature in chat. `/qualia-prd` synthesizes that conversation into a durable PRD on disk so the spec lives outside the chat context. From there, `/qualia-issues` can split it into vertical-slice GH issues, and `/qualia-plan` can plan a phase against it.
-
-**Distinct from `/qualia-new`:** `/qualia-new` is project setup (one-shot — JOURNEY.md, PRODUCT.md, CONTEXT.md). `/qualia-prd` is mid-project feature spec capture. You'll run it dozens of times across a project's life; you run `/qualia-new` once.
-
-## When to use
-
-- Mid-project, when a feature has been discussed enough that you want it durable
-- Before `/qualia-issues` so the issues link back to a real spec
-- Before `/qualia-plan` if the phase needs a feature spec upstream of it
-- When the conversation is about to compact and the PRD context would be lost
-
-## Pre-flight
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner plan
-```
-
-| Gate | Check | If fail |
-|---|---|---|
-| In a project | `.planning/` exists | HALT — "Run `/qualia-new` first or use `/qualia-quick` for one-off work" |
-| PRODUCT.md present | `.planning/PRODUCT.md` readable | NUDGE — proceed but recommend running `/qualia-new` to seed PRODUCT.md |
-| CONTEXT.md present | `.planning/CONTEXT.md` readable | NUDGE — PRD will use ad-hoc terminology instead of the glossary |
-| Working tree | `git status --porcelain` empty | OK to be dirty — PRD is additive, no logic changes |
-| Slug | First arg or auto-derive from first heading | Auto-derive: kebab-case the conversation's main feature topic |
-
-## Process
-
-### 1. Slug + path
-
-```bash
-SLUG="${1:-$(date +%Y%m%d)-feature}"   # or auto-derive from conversation
-PRD_PATH=".planning/PRD-${SLUG}.md"
-```
-
-If `--update PATH` is provided, update an existing PRD instead of writing a new one. The synthesis preserves existing sections that haven't been touched in conversation; only changed sections get rewritten.
-
-### 2. Spawn synthesizer (forked subagent — preserves taste, cheap on context)
-
-The synthesis runs in a **forked subagent**. Forks inherit the full conversation history + share the prompt cache, so the agent can pull the design discussion, decisions, ADR-worthy moments, and user voice without re-loading anything. The fork writes the PRD file and returns just the path + 1-line summary — keeps the parent session lean.
-
-```
-Agent(
-  subagent_type="general-purpose",
-  description="Synthesize conversation → PRD",
-  prompt=`
-You are synthesizing this conversation's feature discussion into a durable PRD.
-
-# Output location
-Write to: ${PRD_PATH}
-
-# Inputs you have (from forked context)
-- The full conversation up to this point
-- @.planning/PRODUCT.md  (project register, voice, anti-references)
-- @.planning/CONTEXT.md  (domain glossary — USE these terms, do not invent synonyms)
-- @.planning/decisions/*.md (ADRs constraining the design space)
-
-# PRD structure (copy this skeleton; fill from conversation)
-
-\`\`\`markdown
----
-name: {feature name}
-slug: ${SLUG}
-created: ${date}
-status: draft | accepted | shipped | abandoned
----
-
-# {Feature name}
-
-## Why this exists
-{1-3 sentences: what problem does this solve, for whom, why now}
-
-## User stories
-- As a {persona}, I want to {do X} so that {outcome}.
-- ...
-
-## Acceptance criteria
-Observable, testable behaviors. Each must be verifiable post-build.
-- [ ] {criterion 1}
-- [ ] {criterion 2}
-
-## Out of scope (mandatory)
-What this feature is NOT. Pin this down so scope creep is detectable.
-- {explicit non-goal 1}
-- {explicit non-goal 2}
-
-## Modules touched
-List the deep modules / files / packages this PRD will modify or create.
-Use CONTEXT.md domain language. Surface interface changes explicitly.
-
-| Module | Interface change | Rationale |
-|---|---|---|
-| {module} | {new method / removed export / signature change} | {why} |
-
-## Testing decisions
-Which behaviors get tests, what kind (unit / integration / e2e), where the
-seams are. /qualia-test --tdd will read this.
-
-## Open questions
-Things the conversation flagged but didn't resolve. /qualia-discuss can
-walk these down before /qualia-plan.
-
-## References
-- Conversation timestamp: {ISO}
-- Related ADRs: docs/adr/...
-- Related PRDs: .planning/PRD-...
-\`\`\`
-
-# Discipline
-- NO interview. Synthesize what was DISCUSSED. If a section has nothing in
-  the conversation, leave a TODO marker — do NOT invent.
-- Use CONTEXT.md domain terms. If the user said "lesson" but CONTEXT.md says
-  "module", normalize to "module" and note the alias.
-- Voice = PRODUCT.md voice. No "Welcome to" / "Get Started" / em-dashes in
-  user-facing copy snippets.
-- Output: write the file, then return ONLY \`{ "path": "...", "summary": "1 sentence" }\`.
-`
-)
-```
-
-### 3. Optional GH issue
-
-If `--issue` (or default when `gh` is configured AND `.planning/agents/tracker.md` exists), open a parent issue linking to the PRD path:
-
-```bash
-PRD_BODY=$(cat "${PRD_PATH}")
-gh issue create \
-  --title "PRD: {feature name}" \
-  --body-file "${PRD_PATH}" \
-  --label "prd,needs-triage"
-```
-
-Pass `--no-issue` to skip. The PRD itself is the source of truth — the GH issue is a notification surface.
-
-### 4. Commit
-
-```bash
-git add "${PRD_PATH}"
-git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" \
-  commit -m "prd(${SLUG}): {feature name}"
-```
-
-### 5. End-card + next-command hint
-
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "PRD: ${PRD_PATH}"
-node ~/.claude/bin/qualia-ui.js ok "Issue: {url or 'skipped'}"
-node ~/.claude/bin/qualia-ui.js end "PRD CAPTURED" "/qualia-issues   # break into vertical slices"
-```
-
-## Token discipline (mandatory)
-
-This skill is the v5.3 reply to Matt's instruction-budget thesis. Three rules:
-
-1. **Forked subagent, file output.** The synthesis runs in a fork; main session never sees the full PRD body. Only `{path, summary}` flows back.
-2. **No re-summarization.** When the parent session needs the PRD later, it Reads the file (or a later skill does). Never paste the PRD body into chat to "confirm."
-3. **Fork prefix is stable.** Role + PRD skeleton are stable across spawns — Anthropic prompt caching applies. Per-invocation cost is ~5K tokens for the fork + ~2K for the synthesis output.
-
-## Failure modes
-
-| Symptom | Cause | Action |
-|---|---|---|
-| `.planning/ not found` | Not in a Qualia project | HALT; recommend `/qualia-new` or `/qualia-quick` |
-| Conversation has no clear feature topic | Skill invoked too early | NUDGE — ask the user "what feature are we PRD-ing? Pick a slug or paste a 1-line summary" |
-| `gh` not configured | No GitHub auth | Skip issue creation silently; print PRD path |
-| PRD path collision | Slug already exists | Append `-2`, `-3` to slug; surface to user |
-| Empty conversation context | Fresh session | HALT — "/qualia-prd needs a discussion to synthesize. Discuss first, then run." |
-
-## Rules
-
-1. **Don't interview.** This is synthesis, not a deep-dive. If gaps exist, mark TODO and recommend `/qualia-discuss`.
-2. **CONTEXT.md is law.** Use the project's terms. Don't invent.
-3. **One PRD per feature.** If two features got conflated in conversation, write two PRDs and link them.
-4. **Voice match.** PRODUCT.md voice. No generic SaaS copy.
-5. **Forked context, file output.** Token discipline above.
-6. **Commit immediately.** PRDs are durable artifacts — they ship in git.
-
-## Pairs with
-
-- `/qualia-discuss` — run BEFORE if the conversation has open questions
-- `/qualia-issues` — run AFTER to break PRD into vertical-slice GH issues
-- `/qualia-plan` — run AFTER `/qualia-issues` if you want a phase plan
-- `/qualia-new` — runs ONCE at project setup; `/qualia-prd` is the per-feature equivalent

package/skills/qualia-quick/SKILL.md

@@ -1,44 +0,0 @@
----
-name: qualia-quick
-description: "Fast inline path for trivial fixes — ≤1 hour, typically 1 file, no plan, NO subagent spawn. The current Claude does the work directly. For a 1-5 file change that justifies a fresh builder context, use /qualia-task instead. Trigger on 'quick fix', 'small change', 'tweak', 'hot fix', 'one-line fix', 'typo', 'config tweak'."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
----
-
-# /qualia-quick — Quick Task
-
-For tasks under 1 hour that don't need full phase planning. Single file changes, bug fixes, config tweaks, typo fixes.
-
-## Process
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner quick
-```
-
-1. **Understand:** Ask what needs to be done (or read the instruction)
-2. **Build:** Do it directly — read before write, MVP only
-3. **Verify:** Run `npx tsc --noEmit`, test locally
-4. **Commit:** Atomic commit with clear message
-5. **Update:** Record the work through `state.js`
-
-End with:
-```bash
-node ~/.claude/bin/qualia-ui.js end "QUICK FIX DONE"
-```
-
-```bash
-git add {specific files}
-git commit -m "fix: {description}"
-```
-
-No plan file. No subagents. Just build and ship.
-
-```bash
-node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}" --tasks-done 1
-```
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-task/SKILL.md

@@ -1,98 +0,0 @@
----
-name: qualia-task
-description: "Single focused task with a FRESH builder subagent spawn — 1-3 hours, 1-5 files, atomic commit, validation contract. Heavier than /qualia-quick (which runs inline with no spawn) but lighter than /qualia-build (which needs a phase plan). Use when the user says 'build this one thing', 'add a component', 'implement this feature', 'qualia-task', or for any 1-5 file feature outside a full phase."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Agent
-  - AskUserQuestion
----
-
-# /qualia-task — Single Task Builder
-
-Build one thing properly. Fresh builder context, atomic commit, but no phase plan needed.
-
-## Usage
-`/qualia-task` — describe what to build interactively
-`/qualia-task {description}` — build it directly
-
-## When to Use
-- One feature, 1-5 files, clear scope, 1-3 hours of work
-- Adding a single feature, component, API route, or integration
-- Refactoring one module
-- Building something specific someone asked for
-
-## Process
-
-### 1. Clarify
-
-If no description provided, ask: **"What do you want to build?"**
-
-Then use AskUserQuestion:
-
-```
-question: "How complex is this task?"
-header: "Scope"
-options:
-  - label: "Small (1-2hrs)"
-    description: "Single file or component, straightforward implementation"
-  - label: "Medium (2-3hrs)"
-    description: "Multiple files, some integration work, needs testing"
-  - label: "Large (3hrs+)"
-    description: "Significant feature, multiple components — use /qualia-plan instead"
-```
-
-If "Large" — suggest `/qualia-plan` instead. Ask if they want to proceed anyway.
-
-### 2. Task Spec
-
-Write a quick task spec (don't save to file, just confirm with user):
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner task
-node ~/.claude/bin/qualia-ui.js info "What: {what to build}"
-node ~/.claude/bin/qualia-ui.js info "Files: {files to create/modify}"
-node ~/.claude/bin/qualia-ui.js info "Done: {what done looks like}"
-```
-
-Ask: **"Good to build?"**
-
-### 3. Build
-
-Spawn a builder agent with the task:
-
-```
-Agent(subagent_type: "qualia-builder")
-
-Task: {task description}
-Files: {files to create/modify}
-Acceptance Criteria: {observable completion criteria, 1-3 bullet points}
-
-Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
-```
-
-The builder runs in fresh context — reads before writing, follows rules, commits atomically.
-
-### 4. Verify
-
-After the builder finishes:
-- Run `npx tsc --noEmit` if TypeScript
-- Quick smoke test if applicable
-- Review what was built
-
-### 5. Report
-
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js ok "Task: {description}"
-node ~/.claude/bin/qualia-ui.js ok "Files: {files changed}"
-node ~/.claude/bin/qualia-ui.js ok "Commit: {commit hash}"
-node ~/.claude/bin/qualia-ui.js end "TASK COMPLETE"
-```
-
-```bash
-node ~/.claude/bin/state.js transition --to note --notes "{task description}" --tasks-done 1
-```
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.