qualia-framework 4.5.0 → 5.3.0

package/skills/qualia-new/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-new
-description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, JOURNEY.md with all milestones to handoff, single approval gate, optional auto-chain into building. Use when starting any new client project."
+description: "Set up a new project from scratch — deep questioning, ALWAYS-AUTO research, CONTEXT.md domain glossary seed, decisions/ ADR folder initialized, JOURNEY.md with all milestones to handoff, single approval gate, optional auto-chain into building. Use when starting any new client project."
 allowed-tools:
   - Bash
   - Read
@@ -17,6 +17,12 @@ allowed-tools:
 
 # /qualia-new — New Project (Full Journey)
 
+## Reference templates
+
+Detailed agent-prompt templates and rendering formats live in `REFERENCE.md` (in this same skill folder). When a step below says "see REFERENCE.md section X", read that section before generating the spawn.
+
+---
+
 Initialize a project with the **entire arc mapped from kickoff to handoff**. All milestones defined upfront so the team follows a clear path, not improvising after each ship.
 
 ## Flags
@@ -107,6 +113,35 @@ git add .planning/PROJECT.md
 git commit -m "docs: initialize project"
 ```
 
+### Step 5a. Seed CONTEXT.md and decisions/ (v5.0 — REQUIRED)
+
+The domain glossary is the single highest-leverage piece of substrate — every road agent loads it BEFORE PROJECT.md/DESIGN.md. Misalignment is the #1 failure mode in AI coding; CONTEXT.md kills it.
+
+```bash
+# Copy template
+cp ~/.claude/qualia-templates/CONTEXT.md .planning/CONTEXT.md
+
+# Initialize ADR folder with the template available for reference
+mkdir -p .planning/decisions
+cp ~/.claude/qualia-templates/decisions/ADR-template.md .planning/decisions/_template.md
+```
+
+Then **seed the glossary from the questioning answers**. For each domain term that came up during Step 1 (Deep Questioning) — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
+- the term
+- a one-sentence definition
+- an `Avoid:` line listing rejected synonyms (terms the team should NOT use for this concept)
+
+If the user used multiple terms for the same thing during questioning, capture the disambiguation under `## Flagged ambiguities` (e.g. "User → AuthUser vs Customer").
+
+Replace `{{PROJECT_NAME}}` in CONTEXT.md with the project name.
+
+```bash
+git add .planning/CONTEXT.md .planning/decisions/
+git commit -m "docs: seed CONTEXT.md domain glossary + decisions/ folder"
+```
+
+The glossary stays terse — one sentence per entry. It's loaded into every agent spawn; bloat costs tokens. `/qualia-discuss` will grow it inline as decisions crystallize during phase planning.
+
 ### Step 5b. Write PRODUCT.md (v4.5.0 — REQUIRED)
 
 `PRODUCT.md` is the "who and why" every road agent reads before designing or building. It is **required** — the planner, builder, and verifier all load it as substrate.
@@ -183,62 +218,9 @@ mkdir -p .planning/research
 
 Say: **"Running 4 parallel research agents (stack, features, architecture, pitfalls)..."**
 
-Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope:
+Spawn 4 researchers in parallel (single message, 4 Agent tool calls), with multi-milestone scope. See REFERENCE.md section "Researcher prompts (4 dimensions)" for the verbatim prompt templates.
 
-```
-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")
-```
-
-**After all 4 complete, spawn synthesizer:**
-
-```
-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")
-```
+**After all 4 complete, spawn synthesizer.** See REFERENCE.md section "Synthesizer prompt" for the verbatim prompt template.
 
 **Commit:**
 ```bash
@@ -276,40 +258,7 @@ Gather any additional requirements the user wants that research missed.
 node ~/.claude/bin/qualia-ui.js banner roadmap
 ```
 
-Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones.
-
-```
-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")
-```
+Spawn the roadmapper with full-journey mandate. If the user passed `--full-detail`, include `<full_detail>true</full_detail>` in the prompt so the roadmapper writes complete phase detail for ALL milestones. See REFERENCE.md section "Roadmapper prompt" for the verbatim prompt template.
 
 ### Step 11. Present the Journey (single view)
 
@@ -321,37 +270,7 @@ node ~/.claude/bin/qualia-ui.js journey-tree .planning/JOURNEY.md
 
 This shows M1..M{N} as a vertical ladder: shipped milestones get a green dot, current gets a teal diamond with `[CURRENT]` tag, future get dim open circles. Handoff gets `[FINAL]` tag. Why-now + phase sketch render under current and final.
 
-Also narrate the one-glance summary:
-
-```
-## 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}
-  └─
-         ↓
-  ┌─ Milestone 2 · {Name}
-  │  Why now: {one line}
-  │  Exit: {outcome 1}, {outcome 2}
-  │  Phases: 1. {name} → 2. {name}
-  │  Requirements: {REQ-IDs}
-  └─
-         ↓
-  ...
-         ↓
-  ┌─ 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.
-```
+Also narrate the one-glance summary. See REFERENCE.md section "Journey ladder format" for the ASCII template.
 
 ### Step 12. Approval Gate (single — for the whole journey)
 
@@ -422,6 +341,9 @@ Show summary:
 | Artifact       | Location                    |
 |----------------|-----------------------------|
 | Project        | .planning/PROJECT.md        |
+| Glossary       | .planning/CONTEXT.md        |
+| Decisions      | .planning/decisions/        |
+| Product        | .planning/PRODUCT.md        |
 | Journey        | .planning/JOURNEY.md        |
 | Requirements   | .planning/REQUIREMENTS.md   |
 | Roadmap (M1)   | .planning/ROADMAP.md        |
@@ -451,3 +373,5 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 5. **Milestone 1 is fully detailed.** M2..M{N-1} are sketched. Detail fills in when each milestone opens.
 6. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
 7. **Inline skill invocation.** When Step 0.5 offers `/qualia-map`, invoke it inline — don't exit.
+8. **CONTEXT.md is mandatory (v5.0).** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from questioning answers. Loaded by every road agent. Kept terse.
+9. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-optimize/REFERENCE.md

@@ -0,0 +1,265 @@
+# /qualia-optimize Reference Templates
+
+Agent-prompt templates for SKILL.md. Copy, fill `{placeholders}`, spawn.
+
+## Frontend agent prompt
+
+```
+Agent(
+  prompt="Optimize frontend. Analyze planning docs + rules, then code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{DESIGN.md content}
+</planning>
+
+<rules>
+{rules/frontend.md content}
+</rules>
+
+<task>
+Analyze frontend:
+
+1. **UI Quality**
+   - Loading: every async op needs indicator
+   - Error: data-fetching components handle errors
+   - Empty: lists/tables handle zero items helpfully
+   - Responsive: no fixed px widths, breakpoints handled
+   - A11y: alt text, ARIA, keyboard nav
+
+2. **Design Alignment**
+   - Components vs DESIGN.md (colors, typography, spacing)
+   - rules/frontend.md compliance: distinctive fonts? sharp accents? transitions? No card grids / gradients?
+   - Consistency across app (buttons, spacing, colors)
+
+3. **Frontend Perf**
+   - Bundle: large imports -> tree-shake or dynamic import
+   - Images: next/image? width/height? lazy below fold?
+   - Fonts: next/font? No render-blocking?
+   - CSS: unused Tailwind? conflicts?
+   - Rendering: unnecessary re-renders, missing memo, heavy computations
+
+Per finding: What / Where (file:line) / Why (impact) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Frontend optimization analysis"
+)
+```
+
+## Backend agent prompt
+
+```
+Agent(
+  prompt="Optimize backend. Analyze planning docs + security rules, then code.
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+</planning>
+
+<rules>
+{rules/security.md content}
+</rules>
+
+<task>
+Analyze backend:
+
+1. **Security**
+   - RLS: every table needs RLS + policies
+   - Service role: grep client code (app/, components/, src/) for service_role -> must be ZERO
+   - Auth: mutations use server-side auth (supabase.auth.getUser())
+   - Validation: Zod before DB ops
+   - No dangerouslySetInnerHTML / eval()
+
+2. **Data Access**
+   - Writes via 'use server' actions, not direct client calls
+   - try/catch with meaningful errors
+   - revalidatePath/revalidateTag after mutations
+
+3. **Edge Functions** (if supabase/functions/ exists)
+   - Cold start: bundle size, dep count
+   - Error handling + logging
+   - CORS config
+   - Timeout protection
+
+4. **API Quality**
+   - Rate limiting on public endpoints
+   - Proper HTTP status codes
+   - Consistent error format
+
+Per finding: What / Where (file:line) / Why (impact) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Backend optimization analysis"
+)
+```
+
+## Performance oracle prompt
+
+```
+Agent(
+  prompt="Analyze cross-cutting perf issues.
+
+<planning>
+{PROJECT.md content}
+</planning>
+
+<task>
+Full-stack perf analysis:
+
+1. **DB Queries**
+   - N+1: .from() inside loops/.map()
+   - Missing indexes on .eq()/.filter()/.order() columns
+   - Sequential -> parallel (Promise.all)
+   - Over-fetching: SELECT * when specific columns suffice
+
+2. **API Latency**
+   - Sequential client calls -> batch
+   - Missing caching (stale times, HTTP cache headers)
+   - Large payloads without pagination
+
+3. **Bundle Size**
+   - Barrel exports blocking tree-shaking
+   - Large libs for single fns (lodash, moment)
+   - Missing dynamic imports for heavy components
+
+4. **Render Perf**
+   - Expensive computations without useMemo
+   - Handlers recreated per render without useCallback
+   - Large lists without virtualization
+   - Context providers causing unnecessary re-renders
+
+Per finding: What / Where (file:line) / Why (impact, quantified) / Fix / Severity (CRITICAL|HIGH|MEDIUM|LOW)
+</task>",
+  subagent_type="general-purpose",
+  description="Performance optimization analysis"
+)
+```
+
+## Architecture strategist prompt (deepening lens)
+
+`full`: after Wave 1 (synthesizes + deepens). `deepen`: sole agent (no Wave 1).
+
+```
+Agent(
+  prompt="Arch strategist: Ousterhout deepening lens + cross-cutting issues. Use domain language from CONTEXT.md.
+
+<wave1_findings>
+{Wave 1 findings; empty in --deepen mode}
+</wave1_findings>
+
+<planning>
+{PROJECT.md content}
+{REQUIREMENTS.md content}
+{CONTEXT.md content (domain glossary)}
+{decisions/*.md content (ADRs constraining refactor space)}
+</planning>
+
+<vocabulary>
+- **Module**: construct with interface + impl (fn, class, package, slice)
+- **Interface**: everything caller must know (types, invariants, error modes, ordering, config)
+- **Depth**: leverage at interface. Deep = high leverage. Shallow = interface ~ impl.
+- **Seam**: where interface lives; alterable without in-place editing.
+- **Locality**: change, bug, knowledge concentrated in one location.
+- **Deletion test**: deleting module makes complexity vanish across N callers -> earning keep.
+</vocabulary>
+
+<task>
+TWO sections:
+
+A) **Cross-cutting** (skip in --deepen):
+1. Recurring Wave 1 patterns -> structural problem
+2. Frontend-backend coupling
+3. Inconsistent patterns (server actions vs API routes)
+4. Missing abstractions (pattern repeated 3+ times)
+5. Dead code / unused exports
+
+B) **Deepening candidates** (always):
+Per candidate:
+- **Files**: file:line ranges
+- **Problem**: what's shallow, what leaks
+- **Solution**: new interface, what gets hidden
+- **Benefits**: locality, leverage, testability
+- **Deletion test**: deleting X -> N callers no longer need what?
+- **Domain terms**: CONTEXT.md terms touched or surfaced
+- **Severity**: CRITICAL | HIGH | MEDIUM | LOW
+
+Look for:
+- Shallow wrappers (interface ~ impl)
+- Pure fns extracted for testability only (no locality)
+- Concept-bouncing (1 concept -> 5+ files)
+- Cross-seam coupling (private detail leaking)
+- Untested/untestable sections (bad seams)
+
+REFUSE: 'extract helper fn' failing deletion test. More shallow modules = disease.
+
+Format: What/Where/Why/Fix/Severity.
+</task>",
+  subagent_type="general-purpose",
+  description="Architecture synthesis + deepening"
+)
+```
+
+## Parallel interface design prompt (`--deepen` Wave 3, fan-out × 3)
+
+Spawn 3 agents in the SAME response turn. Each gets the same candidate but a *different* design constraint so the alternatives differ structurally. Use this verbatim — the per-agent constraint is the only variable:
+
+```
+Agent(
+  prompt="Interface designer (variant {1|2|3}/3). Produce ONE radically different
+interface for this deep-module candidate. Other variants are running in parallel
+with different constraints — yours is uniquely framed by your design lens.
+
+<candidate>
+{candidate block from arch strategist: files, problem, current shallow signature}
+</candidate>
+
+<context>
+{INLINE .planning/CONTEXT.md (domain glossary — USE these terms verbatim)}
+{INLINE .planning/decisions/*.md (ADRs constraining the design space)}
+</context>
+
+<your_lens>
+Variant 1 → functional / data-oriented (no classes; pure functions; explicit data flow)
+Variant 2 → OOP / encapsulated (class with private state; methods on a stable receiver)
+Variant 3 → event-driven / message-based (subscriber model; commands and events)
+[Use whichever lens is assigned to YOU above — fan-out call passes only ONE]
+</your_lens>
+
+<task>
+Design the interface only. Do NOT implement. Output:
+
+1. **Interface sketch** (TypeScript signatures, 5-15 lines). Function/class/event
+   names use CONTEXT.md domain language. No invented synonyms.
+
+2. **Locality gain** (1 sentence): what concentrates in this module's seam that
+   was previously scattered across N files?
+
+3. **Testability** (1-3 lines): where do mocks / adapters live? What's a
+   1-line test name that would be easy to write against this interface?
+
+4. **Migration cost** (1 line): rough count — how many callers need updating?
+   Are any breaking changes? Can it be staged incrementally?
+
+5. **Trade-off** (1 sentence): what does THIS shape sacrifice compared to the
+   other two variants?
+
+Constraints:
+- Interface should be DEEP (high leverage per surface area). Refuse a shallow
+  wrapper that just renames the existing functions.
+- The deletion test must pass: deleting this module makes complexity vanish at
+  N callers, not just relocate it.
+- Use CONTEXT.md terms. Do NOT invent new vocabulary.
+- Output exactly the 5 numbered sections above. No prose preamble.
+</task>",
+  subagent_type="general-purpose",
+  description="Interface variant {N}/3 — {functional|OOP|event-driven} lens"
+)
+```
+
+After all 3 return, present a comparison table to the user (see SKILL.md Step 5b). User picks 1, 2, 3, or hybrid. Then a single synthesizer agent writes the Refactor RFC to `.planning/REFACTOR-{slug}.md` honoring the user's pick.
+
+**Token cost**: ~6K per variant × 3 variants = ~18K for the fan-out. Cached prefix (CONTEXT.md + ADRs + candidate block) is shared across the 3 spawns, so effective cost is closer to ~12K. The output rfc-pick stage adds ~3K. Total per-deepening-candidate: ~15K — well within Qualia's per-skill budget.
+
+**Skip variants when one would obviously dominate**: if the codebase is heavily functional (e.g., Effect-based) the OOP variant adds zero value. Strategist may suggest 2 lenses instead of 3 in that case. Default is always 3 unless explicitly noted.