qualia-framework 6.2.9 → 6.3.0

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 ~/.claude/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 ~/.claude/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 ~/.claude/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 ~/.claude/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 ~/.claude/bin/qualia-ui.js banner resume
-node ~/.claude/bin/qualia-ui.js info "Last session: {summary}"
-```
-
-If uncommitted changes:
-```bash
-node ~/.claude/bin/qualia-ui.js warn "{N} uncommitted files"
-```
-
-End with the next command:
-```bash
-node ~/.claude/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 ~/.claude/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 ~/.claude/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 ~/.claude/)"*. 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: `~/.claude/skills/{name}/SKILL.md`
-**Agent** → target: `${FRAMEWORK_DIR}/agents/{name}.md` (framework) or `~/.claude/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 ~/.claude/skills/qualia-learn/SKILL.md
-
-# Skill-that-spawns-an-agent reference:
-cat ~/.claude/skills/qualia-plan/SKILL.md
-
-# Interactive wizard reference:
-cat ~/.claude/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 ~/.claude/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: @~/.claude/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 ~/.claude/skills/{name}
-cp "${FRAMEWORK_DIR}/skills/{name}/SKILL.md" ~/.claude/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 `~/.claude/` 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

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 ~/.claude/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.