qualia-framework 6.2.10 → 6.3.0

package/skills/qualia-triage/SKILL.md

@@ -1,152 +0,0 @@
----
-name: qualia-triage
-description: "State machine over open GH issues — labels each as needs-triage, needs-info, ready-for-agent, ready-for-human, or wontfix. Optionally routes ready-for-agent issues into an autonomous /qualia-build run. Pairs with /qualia-issues to enable the autonomous Ralph-Wiggum loop where agents pull work from the queue without human-in-loop. Use when user says 'triage', 'qualia-triage', 'route the queue', 'pull next from backlog', 'what's ready for the agent'. Hard dependency: requires .planning/agents/labels.md — run /qualia-map first if missing."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-
-# /qualia-triage — Issue Queue State Machine
-
-Walks the open issue queue, applies state labels, optionally routes `ready-for-agent` issues into autonomous build runs.
-
-## The state machine
-
-Every issue carries exactly one **category** label and exactly one **state** label.
-
-**Category labels** (mutually exclusive):
-- `bug` — something is broken
-- `enhancement` — new feature or improvement
-
-**State labels** (exactly one per issue):
-- `needs-triage` — initial state, awaiting maintainer evaluation
-- `needs-info` — clarification needed from reporter
-- `ready-for-agent` — fully specified, autonomous build can pull this
-- `ready-for-human` — requires human implementation (judgment, sensitive area, scope unclear)
-- `wontfix` — rejected
-
-**Flow:**
-
-```
-unlabeled → needs-triage → ┬→ needs-info → (response) → needs-triage
-                           ├→ ready-for-agent → (autonomous build) → closed
-                           ├→ ready-for-human → (human picks up) → closed
-                           └→ wontfix → closed
-```
-
-## Hard dependencies
-
-This skill cannot work meaningfully without:
-- `.planning/agents/labels.md` — canonical-role-to-existing-label mapping
-- `.planning/agents/tracker.md` — tells it where the queue lives
-- `gh` CLI authenticated (if tracker is GitHub)
-
-If missing, halt: "Run `/qualia-map` first to scan your repo and write the adapter config."
-
-## Process
-
-### 1. Load substrate
-
-```bash
-cat .planning/agents/labels.md
-cat .planning/agents/tracker.md
-cat .planning/CONTEXT.md 2>/dev/null
-```
-
-If labels are missing in the tracker, create them per the canonical mapping.
-
-### 2. List the queue
-
-```bash
-gh issue list --state open --limit 50 --json number,title,body,labels --jq '.'
-```
-
-### 3. Classify each unlabeled / needs-triage issue
-
-For each issue:
-
-**Read the body. Then assign one state per these criteria:**
-
-| State | Criteria |
-|---|---|
-| `ready-for-agent` | Acceptance criteria are explicit + observable. Touches files Qualia knows. No business-judgment calls. No security-sensitive areas without explicit ADR backing. |
-| `ready-for-human` | Requires judgment Qualia shouldn't make. Touches security/auth/payments without ADR. Scope is fuzzy. Risk is high. |
-| `needs-info` | Reporter left out reproduction steps, expected behavior, or scope is too vague to act on. |
-| `wontfix` | Out of project scope per PROJECT.md. Already implemented. Duplicate of #N. Conflicts with locked ADR. |
-
-For each issue, also assign category (`bug` if behavior is broken vs spec, `enhancement` otherwise).
-
-### 4. Apply labels
-
-```bash
-gh issue edit {N} --add-label "{state},{category}" --remove-label "needs-triage"
-```
-
-For `needs-info`, also post a comment with the specific questions. Use `--body-file` (never heredoc-interpolate) — issue text is user-controlled and could contain shell metacharacters or a rogue `EOF`:
-
-```bash
-COMMENT_FILE=$(mktemp -t qualia-triage.XXXXXX.md)
-cat > "$COMMENT_FILE" <<EOF_TEMPLATE
-Need a few more details to triage this:
-
-1. {specific question 1}
-2. {specific question 2}
-
-Once these are answered I'll re-triage.
-EOF_TEMPLATE
-
-gh issue comment {N} --body-file "$COMMENT_FILE"
-rm -f "$COMMENT_FILE"
-```
-
-### 5. Show the queue snapshot
-
-```
-Triaged {N} issues:
-
-ready-for-agent:  {count} ─ #123, #124, #126
-ready-for-human:  {count} ─ #125, #127
-needs-info:       {count} ─ #128
-wontfix:          {count} ─ #129
-```
-
-### 6. Optional autonomous loop
-
-```
-{N} issues ready-for-agent. Pull the next one into autonomous build?
-```
-
-`AskUserQuestion`:
-- header: "Auto-pull?"
-- question: "Pull #{first ready-for-agent} into autonomous /qualia-build?"
-- options:
-  - "Pull it" — feed the issue into a fresh /qualia-build run, then re-triage when done
-  - "Pause" — stop here, user picks up manually
-
-If "Pull it":
-1. Read the issue body fully
-2. Spawn `/qualia-build` with the issue body as task input
-3. After build completes and verifies green, comment the closing PR/commit on the issue and `gh issue close {N}`
-4. Loop back to step 6 (next ready-for-agent issue)
-
-The loop continues until the queue empties or the user pauses.
-
-### 7. Final report
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js end "QUEUE TRIAGED" "/qualia or /qualia-build {next}"
-```
-
-## Rules
-
-1. **One category, one state — always.** No issue without both labels (after triage). No issue with two of either.
-2. **`ready-for-agent` is conservative.** When in doubt, `ready-for-human`. Wrong agent-pull is more expensive than a human picking it up.
-3. **`needs-info` posts a comment.** Don't just label and walk away — the reporter must know what's blocking.
-4. **`wontfix` cites a reason.** Body or comment must say WHY (out of scope per PROJECT.md, conflicts with ADR-NNNN, duplicate of #N).
-5. **Autonomous loop is opt-in per session.** Don't auto-loop without the user pressing "Pull it" each cycle (until they explicitly ask for a continuous run).
-6. **Re-triage on response.** When `needs-info` issues get a reply, they return to `needs-triage` for re-evaluation.

package/skills/qualia-vibe/SKILL.md

@@ -1,229 +0,0 @@
----
-name: qualia-vibe
-description: "Fast aesthetic-token pivot — swap the design vibe (color, typography, motion, depth) without touching component structure, layout, routes, or behavior. Default mode proposes ONE direction (per rules/one-opinion.md). Sub-modes: --variants for A/B/C menu, --extract URL to reverse-engineer DESIGN.md, --sync to back-sync code → DESIGN.md. Triggers: 'different vibe', 'change the look', 'swap the aesthetic', 'try something bolder', 'match this site', 'sync the design file'. Route structural redesign to /qualia-polish --redesign and broken UI behavior to /qualia-fix."
-disable-model-invocation: false
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-# /qualia-vibe — Fast Aesthetic Pivot
-
-Swap the **vibe** without redoing the **app**. Tokens only: color, typography, depth, motion, brand accents. Component structure, routing, data flow, and layout grid stay exactly where they were. This is the difference between `/qualia-vibe` (~3 min) and `/qualia-polish --redesign` (~30 min).
-
-## When to use
-
-- Client said "I want a different vibe" / "make it look bolder" / "this feels too startup-y" → `/qualia-vibe`
-- You want to test if a different aesthetic is right BEFORE committing the redesign → `/qualia-vibe`
-- You want to match a reference site's design system → `/qualia-vibe --extract https://example.com`
-- Someone changed CSS vars or Tailwind config directly and DESIGN.md is out of sync → `/qualia-vibe --sync`
-- You want to enumerate options (rare — see `rules/one-opinion.md`) → `/qualia-vibe --variants 3`
-
-## When NOT to use
-
-- The complaint is "this component is broken" as behavior → `/qualia-fix`.
-- The complaint is "the spacing is wrong" or "this looks rough" → `/qualia-polish` (component or section scope).
-- The site has no DESIGN.md yet → run `/qualia-new` first; vibe is a PIVOT, not a cold start.
-- You want a structural redesign (layout, navigation, information architecture) → `/qualia-polish --redesign` (~30 min ground-up).
-
-## Layout-preservation contract
-
-`/qualia-vibe` ONLY changes:
-
-- Color tokens (CSS vars / Tailwind palette / brand accents).
-- Typography (font-family, scale, weights, italic accents).
-- Depth tokens (shadow elevations, border treatments).
-- Motion tokens (easing, duration, signature interactions).
-- The "Aesthetic direction" line in DESIGN.md §1.
-
-It does NOT touch:
-
-- Component structure (`return (…)` JSX is preserved).
-- Routing, data fetching, business logic.
-- Layout grid (responsive breakpoints, container widths).
-- Information architecture or copy.
-
-If the user actually wants structural change, route to `/qualia-polish --redesign`.
-
-## Modes
-
-### Default — propose one pivot, apply it
-
-Per `rules/one-opinion.md`. Read PRODUCT.md register + anti-references + scene sentence. Propose ONE concrete direction with one-paragraph justification. Ask one yes/no: "Ship this, or pivot?" If user pivots, ask what they didn't like, propose ONE alternative. Never widen.
-
-### `--variants N`
-
-The opt-in menu. Generate N concrete direction briefs (each 4 lines: direction / color / typography / motion). Use `AskUserQuestion` to let the user pick. Default N=3, max 5.
-
-### `--extract <URL or image path>`
-
-Reverse-engineer a DESIGN.md draft from a reference. Captures a screenshot at 1440 (via `scripts/playwright-capture.mjs`), runs an extract-mode vision prompt (NOT score-mode), outputs structured tokens matching DESIGN.md sections 1-7. User reviews + edits the draft before applying.
-
-### `--sync`
-
-Back-sync. Reads the codebase's actual CSS vars, Tailwind config, and font imports. Diffs against DESIGN.md. Outputs (a) tokens in code not in DESIGN.md ("undocumented"), (b) tokens in DESIGN.md not in code ("orphaned"), (c) tokens that drifted in value. With `--sync --write`, patches DESIGN.md to match code.
-
-## Process
-
-### 0. Pre-flight gates
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner vibe 2>/dev/null
-
-# DESIGN.md must exist
-test -f .planning/DESIGN.md || {
-  echo "DESIGN.md not found. Run /qualia-new (or /qualia-polish --redesign for a ground-up redesign) first."
-  exit 1
-}
-
-# PRODUCT.md should exist (for register + anti-references context)
-test -f .planning/PRODUCT.md || echo "Warning: PRODUCT.md missing — vibe proposals will be less anchored. Consider /qualia-new first."
-```
-
-### 1. Parse the mode
-
-- `--extract <url-or-path>` → go to Extract flow.
-- `--sync` (with optional `--write`) → go to Sync flow.
-- `--variants [N]` → go to Variants flow.
-- Direction explicitly named on command line (e.g. `/qualia-vibe brutalist`) → skip proposal, jump to Apply.
-- Otherwise → Default (propose one).
-
-### 2. Default flow (propose one)
-
-Read substrate:
-- `.planning/PRODUCT.md` (register, anti-references, scene sentence)
-- `.planning/DESIGN.md` (current direction, current token set)
-- `qualia-design/design-laws.md` (banned patterns)
-- `qualia-design/design-brand.md` OR `qualia-design/design-product.md` (matching register)
-
-Propose ONE direction. Output format:
-
-```
-Current: {DESIGN.md §1 direction line}
-Proposed: {ONE new direction, concrete — e.g. "editorial broadsheet, ivory ground, deep navy ink, italic Cormorant accents"}
-Why: {1-2 sentences citing PRODUCT.md register, anti-refs, scene sentence}
-Token deltas: {3-7 bullet token changes the pivot implies}
-Cost: ~3 min to apply, layout preserved.
-```
-
-Use `AskUserQuestion` with two options: `Ship this pivot` / `Different direction`.
-
-If "Different direction": ask one follow-up — "What about the proposal didn't fit?" — then propose ONE new direction with the rejection incorporated. Never enumerate alternatives.
-
-### 3. Apply
-
-Once user approves a direction:
-
-1. Update DESIGN.md §1 (Aesthetic direction).
-2. Update DESIGN.md §2 (Color — OKLCH token set).
-3. Update DESIGN.md §3 (Typography — font-family, scale).
-4. Update DESIGN.md §6 (Depth — shadow elevations).
-5. Update DESIGN.md §7 (Motion — easing, duration).
-6. Apply the same token changes to code:
-   - CSS vars in `app/globals.css` or `src/styles/globals.css` (whichever exists)
-   - `tailwind.config.{ts,js,mjs}` colors / fonts / spacing extensions
-   - Font imports (`@import url(...)` in CSS, or `<link>` in `app/layout.tsx`, or `next/font/google` calls)
-7. Run `node ${QUALIA_BIN}/slop-detect.mjs` on changed files. Block on critical findings (no banned fonts in the new vibe).
-8. Capture one screenshot at desktop (1440) for visual diff:
-   ```bash
-   mkdir -p .planning/assets/vibe
-   node ${QUALIA_SKILLS}/qualia-polish/scripts/playwright-capture.mjs \
-     --url ${URL:-http://localhost:3000} \
-     --out .planning/assets/vibe/vibe-after.png \
-     --width 1440
-   ```
-9. Commit:
-   ```bash
-   git -c user.name="Qualia Vibe" -c user.email="vibe@qualia.solutions" \
-     commit -m "vibe(pivot): {old direction} → {new direction}"
-   ```
-
-If the commit fails (no dev server, no slop-detect, network error), surface the exact failure — do NOT silently swallow.
-
-### 4. Variants flow
-
-```bash
-node ${QUALIA_SKILLS}/qualia-vibe/scripts/tokens.mjs propose-variants \
-  --product .planning/PRODUCT.md \
-  --design  .planning/DESIGN.md \
-  --count   ${N:-3}
-```
-
-Output N briefs side-by-side. `AskUserQuestion` with N options (one per variant) plus "None of these — propose something else". User picks one → continue to Apply (step 3).
-
-### 5. Extract flow
-
-```bash
-mkdir -p .planning/design
-node ${QUALIA_SKILLS}/qualia-vibe/scripts/extract.mjs \
-  --source ${URL_OR_IMAGE} \
-  --out    .planning/design/DESIGN-extracted.md
-```
-
-The script:
-1. If source is a URL, capture screenshot via `playwright-capture.mjs`.
-2. Sends screenshot + extract-mode prompt to visual-evaluator agent.
-3. Visual evaluator returns a JSON token bundle (color OKLCH, font families, scale, depth, motion).
-4. Script renders the bundle into a DESIGN.md draft.
-
-Present the draft. Diff against current DESIGN.md. User can: `Apply as new vibe`, `Save draft only`, or `Cancel`. If apply → Apply flow (step 3) using the extracted tokens.
-
-### 6. Sync flow
-
-```bash
-node ${QUALIA_SKILLS}/qualia-vibe/scripts/tokens.mjs sync \
-  --design .planning/DESIGN.md \
-  ${WRITE:+--write}
-```
-
-The script:
-1. Greps CSS for `:root { --token: value; }` declarations.
-2. Reads `tailwind.config.*` for colors / fonts / spacing extensions.
-3. Parses font imports.
-4. Diffs against DESIGN.md token sections.
-5. Prints three sections: `Undocumented (in code, not in DESIGN.md)`, `Orphaned (in DESIGN.md, not in code)`, `Drifted (different values)`.
-6. If `--write`, patches DESIGN.md to match code; commits with `vibe(sync): align DESIGN.md to code`.
-
-## Output contracts
-
-Vibe always writes ONE of these as its final line:
-
-- `DONE — vibe pivot: {old direction} → {new direction} ({sha})`
-- `DONE — vibe extract: draft saved to {path}`
-- `DONE — vibe sync: {N} drift findings ({sha if --write})`
-- `CANCELLED — user declined all proposed pivots`
-- `BLOCKED — {reason}` (DESIGN.md missing, slop-detect critical, etc.)
-
-## Rules
-
-1. **One opinion by default.** Per `rules/one-opinion.md`. Menus require explicit `--variants`.
-2. **Layout never changes.** If the proposal would require touching JSX structure, route to `/qualia-polish --redesign` and stop.
-3. **DESIGN.md and code stay in sync.** Every apply writes BOTH. Sync mode exists to recover from drift, not to normalize it.
-4. **slop-detect is the brake.** A pivot that introduces a banned font / gradient / hex-in-jsx is rejected. The new vibe must pass the same gates as the old one.
-5. **One screenshot, not three.** Vibe is fast by design. The full 3-viewport check belongs in `/qualia-polish --loop` after the vibe lands.
-6. **Commit identity is local.** Vibe sets git user inline so it works on fresh clones without global config.
-
-## Anti-patterns
-
-- ❌ Presenting "Here are 5 directions: pick one" when the user said "change the vibe". → Use `rules/one-opinion.md`: propose ONE.
-- ❌ Touching `return (…)` JSX. → If the pivot needs structural change, stop and route to `--redesign`.
-- ❌ Skipping slop-detect because "the user is in a hurry". → The vibe pivot is exactly when banned fonts/gradients sneak in.
-- ❌ Auto-running `--sync --write` without surfacing the diff first. → Always show drift before patching DESIGN.md.
-- ❌ Treating `--extract` output as ground truth. → It's a DRAFT. User must approve before apply.
-
-## Examples
-
-```
-/qualia-vibe                           # propose one pivot, apply on approval
-/qualia-vibe brutalist                 # explicit pivot to named direction
-/qualia-vibe --variants 3              # generate 3 options (use sparingly)
-/qualia-vibe --extract https://stripe.com
-/qualia-vibe --extract ./refs/inspo.png
-/qualia-vibe --sync                    # show drift between code and DESIGN.md
-/qualia-vibe --sync --write            # patch DESIGN.md to match code, commit
-```

package/skills/qualia-zoom/SKILL.md

@@ -1,51 +0,0 @@
----
-name: qualia-zoom
-description: "Zoom out and map an unfamiliar code area in domain-glossary terms — list the modules, who calls them, what they hide, and the smallest safe edit window. User-fired only (never auto). Use when you don't know an area of code well, before editing an unfamiliar file, or when the user says 'zoom out', 'map this area', 'show me the bigger picture', 'I don't know this code'."
-disable-model-invocation: true
-allowed-tools:
-  - Read
-  - Grep
-  - Glob
----
-
-# /qualia-zoom — Map an Unfamiliar Area
-
-I don't know this area of code well. Go up a layer of abstraction.
-
-Give me a map of:
-
-1. **Modules** in this area — what they expose, what they hide
-2. **Callers** — who uses these modules and from where
-3. **Dependencies** — what these modules pull in
-4. **Domain terms involved** — quoted from `.planning/CONTEXT.md` if it exists
-
-Use the **vocabulary in `.planning/CONTEXT.md`** wherever applicable. If a term in this code conflicts with the glossary, flag it for `/qualia-discuss` (which now grills + updates CONTEXT.md inline).
-
-## Output format
-
-```
-## Where you are
-{file or path being zoomed out from}
-
-## Module map
-- {module/file} — exposes: {x} — hides: {y}
-- ...
-
-## Caller map
-- {caller} → {module} (used for {purpose})
-- ...
-
-## Domain terms
-- {term from glossary} — appears in {files}
-- {term NOT in glossary but present in code} — flag for /qualia-discuss
-
-## Smallest safe edit window
-{which files form the natural unit for this change}
-```
-
-## Rules
-
-- Keep the report under **50 lines**. Orient, don't refactor.
-- **Don't propose changes** — that's the next skill's job.
-- Read `.planning/CONTEXT.md` first if it exists. Use its language.
-- If the area is huge, pick the entry point the user named and zoom from there.