qualia-framework 6.2.10 → 6.3.0

package/skills/qualia-idk/SKILL.md

@@ -1,166 +0,0 @@
----
-name: qualia-idk
-description: "Diagnostic intelligence for 'I don't know what's going on.' Runs two isolated scans (.planning/ vs codebase), cross-references against the user's confusion, then explains the situation in plain language with a concrete recommended next step. Use whenever the user says 'I don't know', 'something feels off', 'not sure what to do', 'am I doing this right', 'what's happening', 'help me understand'."
-allowed-tools:
-  - Bash
-  - Read
-  - Grep
-  - Glob
-  - Agent
----
-
-# /qualia-idk — "I Don't Know What's Going On"
-
-Not a router. A **diagnostician**. Use when the user isn't stuck on a command — they're stuck on *understanding*.
-
-## How This Differs from `/qualia`
-
-| `/qualia` | `/qualia-idk` |
-|---|---|
-| Mechanical: reads state.js, returns `/qualia-X` | Interpretive: reads the project + the code + the confusion |
-| "What command do I run next?" | "What is actually going on here?" |
-| Always returns a skill name | Returns an explanation + a recommendation |
-| Cheap, instant | Spawns 2 isolated agents, ~30s |
-
-Run `/qualia` first when the user knows what they're trying to do. Run `/qualia-idk` when the user's confusion is about the *situation itself*.
-
-## Process
-
-### Step 0. Banner
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner router
-node ${QUALIA_BIN}/qualia-ui.js spawn "diagnostic" "Reading planning and codebase in isolation..."
-```
-
-Say: **"Let me take a proper look."**
-
-### Step 1. Gather the User's Confusion
-
-Look at the conversation context (if any). Note:
-- What did the user just say or ask?
-- Any recent errors, failed commands, surprising output?
-- Any mismatch between what they expected and what happened?
-
-If there's nothing in conversation context yet, ask:
-- header: "What's unclear?"
-- question: "Where are you stuck? (one sentence is fine)"
-- Free text.
-
-Store this as `<user_confusion>`.
-
-### Step 2. Spawn Two Isolated Scans (Parallel)
-
-Two fresh subagents. Each sees ONLY its respective scope — no cross-contamination.
-
-```
-Agent(prompt="
-You are a read-only diagnostic scanner for the .planning/ folder only.
-
-Read ALL of the following if present:
-  - .planning/PROJECT.md
-  - .planning/JOURNEY.md
-  - .planning/REQUIREMENTS.md
-  - .planning/ROADMAP.md
-  - .planning/STATE.md
-  - .planning/tracking.json
-  - .planning/phase-*-plan.md (latest 1-2)
-  - .planning/phase-*-verification.md (latest 1-2)
-  - .planning/DESIGN.md (skim)
-  - .continue-here.md (if present)
-
-DO NOT read any source code — no src/, app/, components/, lib/, etc.
-DO NOT run any build tools.
-
-Produce a 'Plan View' report answering:
-  1. What is this project? (one sentence from PROJECT.md)
-  2. Where does the plan say we ARE? (current milestone + phase + status)
-  3. What does the plan say should be TRUE right now? (current phase's acceptance criteria / success criteria)
-  4. What does the plan say is UNFINISHED? (upcoming phases or unresolved gaps from latest verification)
-  5. Any plan-level inconsistencies? (e.g. tracking.json says phase 3 but STATE.md says phase 2, JOURNEY.md missing, roadmap out of sync)
-
-Keep it under 250 words. Be specific. No filler.
-", subagent_type="Explore", description="Plan-view scan")
-
-Agent(prompt="
-You are a read-only diagnostic scanner for the source code only.
-
-DO NOT read anything in .planning/ — skip it entirely.
-
-Scan the repo:
-  - Package/framework detection (package.json, requirements.txt, etc.)
-  - Entry points (app/, src/, pages/, index.*)
-  - Key files referenced in recent commits (git log --oneline -5, then inspect)
-  - Run quick static checks if applicable: 'npx tsc --noEmit' output, lint errors, test status
-  - Look for stubs: grep for TODO, FIXME, 'not implemented', empty catch blocks, unused exports
-
-Produce a 'Code View' report answering:
-  1. What does the code look like it's BUILDING? (inferred from structure + imports, not from docs)
-  2. What ACTUALLY WORKS right now? (compile status, recent commit messages, any obvious smoke signals)
-  3. What's STUBBED or INCOMPLETE? (concrete file:line citations)
-  4. What's RUNNING locally or deployed? (if there's a dev server log, vercel link, supabase project — flag it)
-  5. Any code-level inconsistencies? (imports that don't resolve, routes referenced but not defined, schema mismatches)
-
-Keep it under 250 words. Cite specific files/lines. No filler.
-", subagent_type="Explore", description="Code-view scan")
-```
-
-Wait for both. Don't proceed to synthesis until you have both reports.
-
-### Step 3. Synthesize
-
-With both reports + the user's confusion in hand, cross-reference:
-
-**Produce a structured diagnosis** (use this exact shape):
-
-```
-## What I see
-
-**The plan says:** {1-2 sentences — current milestone/phase/status, what should be true}
-
-**The code says:** {1-2 sentences — what actually exists, what works, what's stubbed}
-
-**The mismatch (if any):** {1-2 sentences — where plan and code disagree. If no mismatch, say "plan and code are consistent".}
-
-## What I think is happening
-
-{3-5 sentences, plain language. Tie the user's confusion to what you found. Avoid jargon. If the user said "the login is broken", don't say "the auth middleware has a type inference issue" — say "you're seeing the login fail because the signin function isn't actually imported into the login page, even though the plan says it should be. Someone wrote the helper but forgot to wire it up."}
-
-## What to do next
-
-1. **{concrete action}** — {one sentence why}
-2. **{concrete action}** — {one sentence why}
-3. **{optional third}** — {one sentence why}
-
-If one of these maps to an existing Qualia command, use it:
-  - `/qualia-plan {N} --gaps` if the mismatch is "plan says X but code has stubs"
-  - `/qualia-verify {N}` if the mismatch is "code says built but no verification exists"
-  - `/qualia-debug` if a specific error is the block
-  - `/qualia-map` if the plan and code have drifted far apart
-  - `/qualia-pause` if the user is overwhelmed and should step away
-```
-
-### Step 4. Close
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js divider
-node ${QUALIA_BIN}/qualia-ui.js end "DIAGNOSED" "{top-recommended action if it's a command, else leave blank}"
-```
-
-## Rules
-
-1. **Two isolated scans, always.** Plan view never peeks at code, code view never peeks at planning. This is what keeps the diagnosis honest — each agent sees one side of the story, and the synthesis catches the delta.
-2. **Plain language over jargon.** If you can't explain it to a non-dev, rewrite it.
-3. **No fake certainty.** If the scans come back thin (e.g., brand new repo), say "I don't have enough signal yet — here's what I'd do to gather more."
-4. **Never invent facts.** If the code-view scan didn't find something, don't say it exists. Cite files.
-5. **One recommendation primary, two backups.** Decision fatigue is the problem — give the user a lead option.
-6. **Don't re-run if state.js already knows.** If the user's confusion is purely "what's my next command", `/qualia` already handles that — gently suggest it instead of spawning agents.
-
-## When NOT to Use
-
-- User knows what they're doing and just wants the next command → `/qualia`
-- User has a specific error message → `/qualia-debug`
-- User wants to review code quality → `/qualia-review`
-- User wants to pause and come back → `/qualia-pause`
-
-`/qualia-idk` is specifically for **"I'm not sure what I'm even looking at"** situations. Route to sharper tools when the question is sharper.

package/skills/qualia-issues/SKILL.md

@@ -1,151 +0,0 @@
----
-name: qualia-issues
-description: "Break a phase plan into independent vertical-slice GitHub issues with needs-triage label. Each issue is demoable end-to-end (schema → API → UI → tests). Dependency-ordered. Externalizes Qualia work to the open queue so other agents, sessions, or human contributors can pull from it. Use when user says 'create issues from this plan', 'externalize the phase', 'turn this into GitHub issues', 'qualia-issues', 'split into tickets', or after /qualia-plan when the work should be parallelizable. Hard dependency: requires tracker config — run /qualia-map first if .planning/agents/tracker.md is missing."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Grep
-  - Glob
-  - AskUserQuestion
----
-
-# /qualia-issues — Phase Plan → Independent Vertical-Slice GH Issues
-
-Externalizes a phase plan to the GitHub issue queue. Each issue is a thin slice that delivers a complete demoable behavior end-to-end. Other Qualia sessions, autonomous agents, or human contributors can then pull from the queue.
-
-## Why vertical slices
-
-ANTI-PATTERN: chop the plan horizontally (issue 1 = "all schema work", issue 2 = "all API work", issue 3 = "all UI"). This creates dependencies that block parallelism, and no single issue is demoable on its own.
-
-CORRECT: each issue traverses every layer (schema → API → UI → tests) for one narrow user-facing behavior. Many thin slices > few thick ones.
-
-## Hard dependencies (per Matt Pocock's ADR-0001)
-
-This skill cannot work meaningfully without:
-- `.planning/agents/tracker.md` — tells it where to file issues (GH, GL, local)
-- `.planning/agents/labels.md` — tells it the canonical-role-to-existing-label mapping
-- `gh` CLI authenticated (if tracker is GitHub)
-
-**If any are missing, halt and tell the user:** "Run `/qualia-map` first — it scans your repo and writes the adapter config so Qualia honors your existing tracker conventions."
-
-## Process
-
-### 1. Determine phase
-
-Phase number from `$ARGUMENTS` if provided, else current from `node ${QUALIA_BIN}/state.js check`.
-
-### 2. Load substrate
-
-```bash
-cat .planning/agents/tracker.md
-cat .planning/agents/labels.md
-cat .planning/phase-{N}-plan.md
-cat .planning/CONTEXT.md 2>/dev/null
-cat .planning/PROJECT.md
-```
-
-If `phase-{N}-plan.md` is missing, halt: "No plan exists for phase {N}. Run `/qualia-plan {N}` first."
-
-### 3. Decompose into vertical slices
-
-Read the phase plan tasks. Group/split into slices where each slice:
-- Delivers ONE user-facing behavior end-to-end
-- Touches every relevant layer (schema, server, client, tests) needed for that behavior
-- Is independently demoable or verifiable
-- Has explicit blocking-dependencies on other slices (kept minimal)
-
-Use **CONTEXT.md domain language** in titles and descriptions. Don't say "user table" if the glossary says "AuthUser" or "Customer."
-
-### 4. Show proposed slices to user
-
-```
-Proposed slices for phase {N}:
-
-Slice 1: {title in domain language}
-  Behavior: {one sentence}
-  Touches: schema, server-action, page route, test
-  Blocks: none
-
-Slice 2: ...
-  Blocks: Slice 1 (needs the schema migration)
-```
-
-Use `AskUserQuestion`:
-- header: "Approve slices?"
-- question: "File these {N} issues?"
-- options: "File them" / "Re-decompose" / "Cancel"
-
-### 5. File issues in dependency order
-
-For each approved slice (in dependency order so blocking slices exist when blockees are filed):
-
-```bash
-# Write the body to a temp file FIRST — never heredoc-interpolate user content into shell.
-# Plan content (titles, behaviors, criteria) is user-controlled; shell metacharacters or a
-# rogue 'EOF' line in the plan would break out of the heredoc. --body-file eliminates the risk.
-BODY_FILE=$(mktemp -t qualia-issue.XXXXXX.md)
-cat > "$BODY_FILE" <<EOF_TEMPLATE
-## End-to-end behavior
-{one paragraph}
-
-## Acceptance criteria
-- [ ] {criterion 1 — observable behavior, not implementation detail}
-- [ ] {criterion 2}
-- [ ] tests pass for the slice
-
-## Blocks
-- {issue # of any blocking slice, or "none"}
-
-## Domain terms touched
-{terms from CONTEXT.md this slice involves}
-
-## Phase context
-Part of phase {N} ({phase name}). Plan: .planning/phase-{N}-plan.md.
-EOF_TEMPLATE
-
-gh issue create \
-  --title "{title in domain language}" \
-  --body-file "$BODY_FILE" \
-  --label "needs-triage,enhancement"
-
-rm -f "$BODY_FILE"
-```
-
-Capture the returned issue number for use in subsequent slices' "Blocks" fields.
-
-**Why temp file, not heredoc:** plan files (`.planning/phase-{N}-plan.md`) and CONTEXT.md are project repo content — anyone with commit access can write them. A crafted plan with shell metacharacters or a literal `EOF` line in the content could break out of an inline heredoc and execute arbitrary shell. `--body-file` reads the body as raw bytes, no shell expansion. The `EOF_TEMPLATE` token (vs the standard `EOF`) is also more resistant to accidental collisions.
-
-### 6. Write summary
-
-`.planning/phase-{N}-issues.md`:
-
-```markdown
-# Phase {N} — Issue Queue
-
-Filed {date}. Status: open queue.
-
-| # | Slice | Issue | Blocks |
-|---|---|---|---|
-| 1 | {title} | #123 | none |
-| 2 | {title} | #124 | #123 |
-```
-
-### 7. Commit and route
-
-```bash
-git add .planning/phase-{N}-issues.md
-git commit -m "docs(phase-{N}): externalize {N_slices} slices to GH issue queue"
-
-node ${QUALIA_BIN}/qualia-ui.js end "QUEUE FILED" "/qualia-triage"
-```
-
-## Rules
-
-1. **Each issue is demoable on its own.** If a "completed" issue can't be shown as working behavior, the slicing was wrong.
-2. **CONTEXT.md language is mandatory.** Issue titles use domain terms, not implementation jargon.
-3. **No file paths or line numbers in issue bodies.** Issues describe behavior. Implementation details live in the phase plan.
-4. **Acceptance criteria are observable behaviors.** "Form validates email format" not "regex.test() returns true".
-5. **Dependencies kept minimal.** If slice A blocks slice B blocks slice C blocks slice D, the slicing collapsed to horizontal — re-decompose.
-6. **`needs-triage` is the default label.** `/qualia-triage` will route from there.

package/skills/qualia-pause/SKILL.md

@@ -1,68 +0,0 @@
----
-name: qualia-pause
-description: "Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off. Trigger on 'pause', 'stop for now', 'save progress', 'continue later', 'pick up tomorrow'."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
----
-
-# /qualia-pause — Session Handoff
-
-Save context so the next session picks up where you left off.
-
-## Process
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner pause
-```
-
-### 1. Read State
-
-```bash
-cat .planning/STATE.md 2>/dev/null
-git status --short 2>/dev/null
-git log --oneline -5 2>/dev/null
-```
-
-### 2. Create `.continue-here.md`
-
-```markdown
-# Continue Here
-
-## Session Summary
-{What was accomplished — from conversation context + git log}
-
-## Current Phase
-Phase {N}: {name} — {status}
-
-## In Progress
-- {What's partially done}
-- {Where exactly work stopped}
-
-## Next Steps
-1. {Immediate next action}
-2. {Following action}
-
-## Decisions Made
-- {Decision and rationale}
-
-## Blockers
-- {Any unresolved issues}
-
-## Files Modified
-- {List from git status/diff}
-```
-
-### 3. Commit
-
-```bash
-git add .continue-here.md {any uncommitted work files}
-git commit -m "WIP: {phase name} — session handoff"
-```
-
-```bash
-node ${QUALIA_BIN}/state.js transition --to note --notes "Session paused — see .continue-here.md"
-```
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-resume/SKILL.md

@@ -1,52 +0,0 @@
----
-name: qualia-resume
-description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
-allowed-tools:
-  - Bash
-  - Read
----
-
-# /qualia-resume — Resume Work
-
-Restore context and route to the right next action.
-
-## Process
-
-### 1. Find Context (priority order)
-
-1. `.continue-here.md` — richest source, from `/qualia-pause`
-2. `.planning/STATE.md` — project state
-3. Git history — `git log --oneline -10` + `git diff --stat`
-
-### 2. Restore
-
-**If `.continue-here.md` exists:** Read fully. Summarize: what was done, what's in progress, next steps, blockers.
-
-**If only STATE.md:** Read STATE.md + tracking.json. Show current phase and status.
-
-**If neither:** Reconstruct from git. Present findings, ask user to confirm.
-
-### 3. Detect Incomplete Work
-
-- Phase has plan but no verification → execution may be incomplete
-- Uncommitted changes → `git status --short`
-- Phase marked in-progress in STATE.md
-
-### 4. Present and Route
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner resume
-node ${QUALIA_BIN}/qualia-ui.js info "Last session: {summary}"
-```
-
-If uncommitted changes:
-```bash
-node ${QUALIA_BIN}/qualia-ui.js warn "{N} uncommitted files"
-```
-
-End with the next command:
-```bash
-node ${QUALIA_BIN}/qualia-ui.js next "{next command}"
-```
-
-Clean up `.continue-here.md` after restoration (or offer to keep it).

package/skills/qualia-skill-new/SKILL.md

@@ -1,173 +0,0 @@
----
-name: qualia-skill-new
-description: "Author a new Qualia skill or agent. Use when the user says 'create a new skill', 'add a skill', 'I want to build a skill', 'make this a reusable command', 'turn this into a skill'. Generates the SKILL.md, registers it in the right location, and optionally ships to the framework repo."
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - AskUserQuestion
----
-
-# /qualia-skill-new — Author a New Skill
-
-You are about to create a reusable slash command. Skills are the leverage of the Qualia framework — if the team does something twice, it probably belongs here.
-
-## Process
-
-```bash
-node ${QUALIA_BIN}/qualia-ui.js banner skill-new
-```
-
-### 1. Scope Decision
-
-Ask the user with AskUserQuestion:
-
-```
-question: "Where should this skill live?"
-header: "Scope"
-options:
-  - label: "Framework skill (ships to the team)"
-    description: "Edit qualia-framework repo. Everyone gets it on next update."
-  - label: "Local skill (just me)"
-    description: "Lives only in ${QUALIA_SKILLS}/. Not shared."
-  - label: "Agent instead of a skill"
-    description: "This is a subagent role, not a slash command. Creates agents/{name}.md."
-```
-
-### 1a. Resolve framework directory
-
-If the user chose **Framework skill** or a framework-scoped **Agent**, resolve `${FRAMEWORK_DIR}` — the checkout path of this user's qualia-framework repo — BEFORE computing any target paths. Never hardcode `/home/<user>/...`; different teammates and operating systems have different paths.
-
-```bash
-# Priority order: env var → git detection → ask user
-FRAMEWORK_DIR="${QUALIA_FRAMEWORK_DIR:-}"
-if [ -z "$FRAMEWORK_DIR" ] && git -C . rev-parse --show-toplevel >/dev/null 2>&1; then
-  ORIGIN=$(git -C . config --get remote.origin.url 2>/dev/null)
-  case "$ORIGIN" in
-    *qualia-framework*) FRAMEWORK_DIR=$(git -C . rev-parse --show-toplevel) ;;
-  esac
-fi
-echo "${FRAMEWORK_DIR:-UNRESOLVED}"
-```
-
-If the command prints `UNRESOLVED`, ask the user: *"Where is your qualia-framework checkout? (absolute path, or type 'local' to save only to ${QUALIA_HOME}/)"*. If they type `local`, downgrade the scope to Local. Otherwise store the answer as `${FRAMEWORK_DIR}` for the rest of the session.
-
-**Framework** → target: `${FRAMEWORK_DIR}/skills/{name}/SKILL.md`
-**Local** → target: `${QUALIA_SKILLS}/{name}/SKILL.md`
-**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `${QUALIA_AGENTS}/{name}.md` (local)
-
-### 2. Gather Requirements
-
-Ask the user — one question at a time, natural conversation:
-
-1. **"What's the name?"** — kebab-case, prefix with `qualia-` for framework skills. E.g., `qualia-seed-db`.
-2. **"What does it do?"** — one sentence, used as the description.
-3. **"How does the user invoke it?"** — trigger phrases they'd naturally say. E.g., "seed the database", "load test data", "populate dev db".
-4. **"Does it need planning / building / verification?"** — if yes, it probably should spawn an agent. If no, it's a direct-action skill.
-5. **"What files does it read or write?"** — tells you what tools to restrict to.
-
-### 3. Read Reference Skills
-
-Before writing, read two existing skills that are structurally similar:
-
-```bash
-# Short direct-action skill reference:
-cat ${QUALIA_SKILLS}/qualia-learn/SKILL.md
-
-# Skill-that-spawns-an-agent reference:
-cat ${QUALIA_SKILLS}/qualia-plan/SKILL.md
-
-# Interactive wizard reference:
-cat ${QUALIA_SKILLS}/qualia-new/SKILL.md
-```
-
-Pick the closest pattern and copy its structure.
-
-### 4. Write the SKILL.md
-
-Every SKILL.md MUST have:
-
-```markdown
----
-name: {kebab-case-name}
-description: "{one sentence}. {trigger phrases}"
----
-
-# /{name} — {Human Title}
-
-{one-paragraph explanation}
-
-## Usage
-
-`/{name}` — {default behavior}
-`/{name} {arg}` — {with argument}
-
-## Process
-
-### 1. {First Step}
-{specifics}
-
-### 2. {Second Step}
-{specifics}
-
-### N. Update State (only if this skill changes project state)
-
-```bash
-node ${QUALIA_BIN}/state.js transition --to {status} ...
-```
-Do NOT manually edit STATE.md or tracking.json.
-```
-
-**Description field rules:**
-- MUST include trigger phrases the user would naturally say
-- The Claude Code router matches user messages against descriptions — if you don't list triggers, the skill never fires
-- Bad: `"Manages database seeding."` (no triggers)
-- Good: `"Seed the database with test data. Trigger on 'seed db', 'load test data', 'populate dev'."`
-
-### 5. Test the Skill
-
-Spawn a fresh subagent to simulate running the skill — does it make sense without the context you have right now?
-
-```
-Agent(prompt="
-Read this skill: @${QUALIA_SKILLS}/{name}/SKILL.md
-
-Pretend the user just said '{one of the trigger phrases}'. Walk through what you would do, step by step. Flag anything ambiguous or missing.
-", subagent_type="general-purpose", description="Test skill {name}")
-```
-
-Fix any ambiguity the test agent found.
-
-### 6. Install (if framework skill)
-
-```bash
-# Framework skill — copy to local .claude for immediate testing
-mkdir -p ${QUALIA_SKILLS}/{name}
-cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ${QUALIA_SKILLS}/{name}/SKILL.md
-
-# Verify it parses
-node -e "const fs=require('fs');const os=require('os');const path=require('path');const c=fs.readFileSync(path.join(os.homedir(),'.claude/skills/{name}/SKILL.md'),'utf8');if(!c.includes('---'))throw new Error('missing frontmatter');if(!c.match(/^name:\s*\S/m))throw new Error('missing name');if(!c.match(/^description:\s*\S/m))throw new Error('missing description');console.log('OK')"
-```
-
-### 7. Commit (framework skills only)
-
-Do NOT commit unless the user explicitly says "commit" or "ship it".
-
-When they do:
-```bash
-cd "${FRAMEWORK_DIR}"
-git add skills/{name}/
-git commit -m "feat: add /{name} skill"
-```
-
-Remind the user to run `npx qualia-framework@latest update` on their other machines (always pin `@latest` — npx caches aggressively), or bump the version and `npm publish`.
-
-## Anti-Patterns
-
-- ❌ **Description without triggers** — the skill won't fire
-- ❌ **Multiple commands in one skill** — split into two skills
-- ❌ **Direct file writes instead of state.js** — always use state.js for STATE.md/tracking.json
-- ❌ **Hardcoded project paths** — use `.planning/` relative or `${QUALIA_HOME}/` absolute, never `/home/specific-user/`
-- ❌ **Skills that spawn agents without passing PROJECT.md and STATE.md context** — agents are blind by default
-- ❌ **Skills longer than ~150 lines** — split or move logic to an agent