qualia-framework 4.5.0 → 5.1.0

package/skills/qualia-issues/SKILL.md

@@ -0,0 +1,151 @@
+---
+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-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-map
-description: "Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code."
+description: "Map an existing codebase to infer architecture, stack, conventions, what's already built, AND adapt Qualia to the repo's existing tracker/labels/glossary conventions (onboarding). For brownfield projects — run BEFORE /qualia-new so Validated requirements get inferred from existing code and Qualia commands respect the repo's existing process."
 allowed-tools:
   - Bash
   - Read
@@ -12,13 +12,13 @@ allowed-tools:
 
 # /qualia-map — Codebase Mapping (Brownfield)
 
-Scans an existing repo and produces `.planning/codebase/` — architecture, stack, conventions, concerns. Used by `/qualia-new` to infer what's already built and seed Validated requirements.
+Scans existing repo → `.planning/codebase/` (architecture, stack, conventions, concerns). `/qualia-new` uses this to infer capabilities and seed Validated reqs.
 
 ## When to Use
 
-- Taking over an existing client project
-- Adding features to a repo you didn't build
-- Before `/qualia-new` on any directory that already has code
+- Taking over existing client project
+- Adding features to repo you didn't build
+- Before `/qualia-new` on any directory with existing code
 
 ## Usage
 
@@ -48,48 +48,72 @@ If `ALREADY_MAPPED`, ask:
 node ~/.claude/bin/qualia-ui.js banner map
 ```
 
-### 3. Spawn Parallel Mapper Agents
+### 3. Spawn 5 Mapper Agents (parallel)
 
-Map 4 dimensions in parallel for speed. Each writes one file in `.planning/codebase/`:
+Each writes one file in `.planning/codebase/`:
 
 ```
-Agent 1: Architecture scanner
+Agent 1: Architecture
   Agent(prompt="
-  Scan the current codebase and produce .planning/codebase/architecture.md.
+  Scan codebase → .planning/codebase/architecture.md.
   Identify: entry points, folder structure, module boundaries, data flow.
-  Focus on WHAT the codebase does, not HOW to fix it.
+  Focus on WHAT, not HOW to fix.
   ", subagent_type="general-purpose", description="Architecture scan")
 
-Agent 2: Stack detector
+Agent 2: Stack
   Agent(prompt="
-  Detect the tech stack. Read package.json, requirements.txt, Gemfile, etc.
-  Produce .planning/codebase/stack.md listing: runtime, framework, key libraries,
-  database, hosting, CI. Include version numbers.
+  Detect stack from package.json, requirements.txt, Gemfile, etc.
+  Output: .planning/codebase/stack.md (runtime, framework, key libs, DB, hosting, CI + versions).
   ", subagent_type="general-purpose", description="Stack detection")
 
-Agent 3: Conventions analyzer
+Agent 3: Conventions
   Agent(prompt="
-  Analyze code style and conventions. Sample 10-15 files across the codebase.
-  Produce .planning/codebase/conventions.md listing: naming, component patterns,
-  file organization, import style, test style, commit message format.
+  Analyze code style/conventions. Sample 10-15 files.
+  Output: .planning/codebase/conventions.md (naming, component patterns, file org, import style, test style, commit format).
   ", subagent_type="general-purpose", description="Conventions analysis")
 
-Agent 4: Concerns scanner
+Agent 4: Concerns
   Agent(prompt="
-  Scan for code quality concerns — NOT to fix, just to document.
-  Look for: TODO/FIXME, deprecated APIs, outdated dependencies, missing tests,
-  security smells (hardcoded secrets, no input validation).
-  Produce .planning/codebase/concerns.md.
+  Scan quality concerns (document, NOT fix).
+  Look for: TODO/FIXME, deprecated APIs, outdated deps, missing tests, security smells.
+  Output: .planning/codebase/concerns.md.
   ", subagent_type="general-purpose", description="Concerns scan")
+
+Agent 5: Onboarding adapter
+  Agent(prompt="
+  Detect existing process so Qualia honors it.
+  Output: .planning/codebase/onboarding.md with sections:
+
+  ## Issue tracker
+  - gh repo view --json url 2>/dev/null (GitHub?)
+  - Check: gitlab-ci.yml, .gitlab/ (GitLab?)
+  - Check: .scratch/, docs/issues/, ISSUES.md (local?)
+  - Else: 'none; Qualia uses .planning/decisions/ + tracking.json only'
+
+  ## Existing labels (only if GH/GL detected)
+  - gh label list --json name,description,color 2>/dev/null
+  - Map to canonical: bug, enhancement, needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix
+  - Output mapping table. Note missing canonical roles.
+
+  ## Domain docs
+  - Check: CONTEXT.md, GLOSSARY.md, docs/glossary.md, docs/domain.md, docs/adr/, doc/architecture/, .architecture/
+  - Output: location (or 'none; Qualia creates .planning/CONTEXT.md')
+
+  ## Existing agent files
+  - Check: CLAUDE.md, AGENTS.md, .cursor/, .cursorrules, .aider.conf.yml, .continue/
+  - List found. Qualia APPENDs substrate, never overwrites.
+
+  Terse. Each section < 10 lines. Programmatically parsed.
+  ", subagent_type="general-purpose", description="Onboarding adapter")
 ```
 
-### 4. Wait for All 4
+### 4. Wait for All 5
 
-After all 4 agents complete, read the 4 output files.
+All done → read 5 outputs.
 
 ### 5. Synthesize
 
-Create `.planning/codebase/README.md` — one-page summary linking to the 4 dimension files.
+Create `.planning/codebase/README.md` (one-page summary linking dimensions):
 
 ```markdown
 # Codebase Map
@@ -112,7 +136,7 @@ Based on existing code, this project already does:
 - {capability 2} (evidence: {file path})
 - {capability 3} (evidence: {file path})
 
-These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
+These become **Validated reqs** in PROJECT.md when `/qualia-new` runs.
 
 ## Dimension Details
 
@@ -120,8 +144,26 @@ These become **Validated requirements** in PROJECT.md when `/qualia-new` runs.
 - [Stack](./stack.md)
 - [Conventions](./conventions.md)
 - [Concerns](./concerns.md)
+- [Onboarding adapter](./onboarding.md)
+
+## Onboarding adapter snapshot
+
+- **Issue tracker:** {from onboarding.md}
+- **Domain docs:** {from onboarding.md}
+- **Existing agent files:** {from onboarding.md}
 ```
 
+### 5.5 Write adapter config (only if onboarding detected something)
+
+Read `.planning/codebase/onboarding.md`. Per detected dimension:
+
+- Issue tracker → `.planning/agents/tracker.md`
+- Labels → `.planning/agents/labels.md` (canonical mapping)
+- Domain docs at non-default path → `.planning/agents/domain.md`
+- CLAUDE.md/AGENTS.md found → APPEND `## Qualia substrate` (never overwrite)
+
+"none" → skip silently, defaults apply.
+
 ### 6. Commit
 
 ```bash
@@ -137,16 +179,17 @@ node ~/.claude/bin/qualia-ui.js end "CODEBASE MAPPED" "/qualia-new"
 
 ## What `/qualia-new` Does With This
 
-When `/qualia-new` runs AFTER `/qualia-map`, it:
+After `/qualia-map`:
 1. Reads `.planning/codebase/README.md`
 2. Extracts Validated capabilities
-3. Pre-populates PROJECT.md with Validated requirements section
-4. Skips questions about things already built
-5. Focuses questioning on NEW capabilities being added
+3. Pre-populates PROJECT.md Validated reqs
+4. Skips questions about existing capabilities
+5. Focuses on NEW capabilities
 
 ## Rules
 
-1. **Non-destructive.** This skill only READS code, never modifies it.
-2. **Four parallel agents.** Don't sequential-scan — parallel is ~4x faster.
-3. **Dimension files are structured.** The orchestrator downstream (`/qualia-new`) reads them programmatically.
-4. **Concerns ≠ fixes.** This skill documents concerns. It does NOT fix them. Use `/qualia-optimize` for that.
+1. **Non-destructive.** Only READS code. Writes to `.planning/codebase/`, `.planning/agents/`, and APPENDs to CLAUDE.md/AGENTS.md.
+2. **Five parallel agents.** No sequential scan.
+3. **Dimension files structured.** `/qualia-new` reads programmatically.
+4. **Concerns not fixes.** Document only. `/qualia-optimize` to fix.
+5. **Onboarding respects existing process.** GH issues → Qualia uses them. Never overwrite; only append.

package/skills/qualia-new/REFERENCE.md

@@ -0,0 +1,139 @@
+# /qualia-new Reference Templates
+
+Detailed agent-prompt templates and rendering formats referenced by SKILL.md.
+Each section is a verbatim template -- copy it, fill the `{placeholders}`, and spawn.
+
+## Researcher prompts (4 dimensions)
+
+Spawn all 4 as parallel `Agent()` calls in a single message. Each uses the same structure with a different `<dimension>`.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>stack</dimension>
+<domain>{inferred domain from PROJECT.md}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- research must cover scalability through Milestone 3+</milestone_context>
+<output_path>.planning/research/STACK.md</output_path>
+", subagent_type="qualia-researcher", description="Stack research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>features</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- distinguish v1 table stakes from v2 differentiators</milestone_context>
+<output_path>.planning/research/FEATURES.md</output_path>
+", subagent_type="qualia-researcher", description="Features research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>architecture</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- Phase 1 foundations must support final-milestone requirements</milestone_context>
+<output_path>.planning/research/ARCHITECTURE.md</output_path>
+", subagent_type="qualia-researcher", description="Architecture research")
+
+Agent(prompt="
+Read your role: @~/.claude/agents/researcher.md
+
+<dimension>pitfalls</dimension>
+<domain>{inferred domain}</domain>
+<project_context>{PROJECT.md summary}</project_context>
+<milestone_context>multi-milestone -- flag risks that stall LATER milestones, not just v1</milestone_context>
+<output_path>.planning/research/PITFALLS.md</output_path>
+", subagent_type="qualia-researcher", description="Pitfalls research")
+```
+
+## Synthesizer prompt
+
+Spawn after all 4 researchers complete.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/research-synthesizer.md
+
+Merge the 4 research files at .planning/research/ into .planning/research/SUMMARY.md.
+This is a multi-milestone project -- the SUMMARY must suggest a FULL milestone arc
+(2-5 milestones including Handoff), not just a v1 phase list. Include roadmap
+implications AND handoff implications (what client takeover requires).
+", subagent_type="qualia-research-synthesizer", description="Synthesize research")
+```
+
+## Roadmapper prompt
+
+Spawn with full-journey mandate. If the user passed `--full-detail`, set `<full_detail>true</full_detail>`.
+
+```
+Agent(prompt="
+Read your role: @~/.claude/agents/roadmapper.md
+
+<task>
+Create the FULL JOURNEY for this project:
+  - .planning/JOURNEY.md -- all milestones (2-5 including Handoff) with exit criteria
+  - .planning/REQUIREMENTS.md -- requirements grouped by milestone
+  - .planning/ROADMAP.md -- Milestone 1's phase detail (and ALL milestones if full_detail=true)
+
+User-scoped v1 features:
+{list of features selected in Step 9, grouped by category}
+
+Template type: {template_type from config.json}
+If set, use ~/.claude/qualia-templates/projects/{type}.md as the milestone arc starting point.
+
+<full_detail>{true if --full-detail, else false}</full_detail>
+  - false (default): Milestone 1 gets full phase detail; M2..M{N-1} stay as sketches. Detail fills in when each milestone opens via /qualia-milestone.
+  - true: every milestone (M1..Handoff) gets full phase-level detail in ROADMAP.md upfront. Useful when the client wants a fully-committed plan at kickoff.
+
+The final milestone MUST be named 'Handoff' with the fixed 4 phases
+(Polish, Content + SEO, Final QA, Handoff). Do not omit it.
+
+After writing, update STATE.md via:
+  node ~/.claude/bin/state.js init \
+    --project '{name}' --client '{client}' --type '{type}' \
+    --milestone_name '{Milestone 1 name}' \
+    --phases '<JSON: Milestone 1 phases only>' \
+    --total_phases <count>
+</task>
+", subagent_type="qualia-roadmapper", description="Create full journey")
+```
+
+## Journey ladder format
+
+The branded journey ladder rendered in Step 11. Use `node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md` for the programmatic version. The manual ASCII fallback format is below.
+
+```
+## Proposed Journey
+
+**{N} milestones to handoff** | **{X} requirements mapped** | All v1 requirements covered
+
+  +-- Milestone 1 . {Name}               [CURRENT]
+  |  Why now: {one line}
+  |  Exit: {outcome 1}, {outcome 2}
+  |  Phases: 1. {name} -> 2. {name} -> 3. {name}
+  |  Requirements: {REQ-IDs}
+  +--
+         |
+         v
+  +-- Milestone 2 . {Name}
+  |  Why now: {one line}
+  |  Exit: {outcome 1}, {outcome 2}
+  |  Phases: 1. {name} -> 2. {name}
+  |  Requirements: {REQ-IDs}
+  +--
+         |
+         v
+  ...
+         |
+         v
+  +-- Milestone {N} . Handoff           [FINAL]
+  |  Exit: Deployed, docs, credentials, walkthrough
+  |  Phases: 1. Polish -> 2. Content + SEO -> 3. Final QA -> 4. Handoff
+  +--
+
+Milestone 1 is fully planned. Milestones 2..{N-1} are sketched and will be detailed
+when they open. Milestone {N} (Handoff) uses the standard 4-phase template.
+```