qualia-framework 4.5.0 → 5.3.0

package/skills/qualia-polish-loop/scripts/score.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * score.mjs -- Qualia visual-polish loop scoring utility.
+ *
+ * Takes a JSON object with 8 dimension scores and computes pass/fail
+ * per the design rubric formula from rules/design-rubric.md.
+ *
+ * Usage:
+ *   echo '{"typography":3,"color":2,"spatial":3,"layout":3,"shadow":3,"motion":3,"microcopy":3,"container":3}' | node score.mjs
+ *   node score.mjs --file scores.json
+ *   node score.mjs --scores '{"typography":4,"color":3,...}'
+ *
+ * Output (JSON):
+ *   { total, avg, pass, failing: [{dim, score}], verdict }
+ *
+ * Exit codes:
+ *   0  all dimensions >= 3 (pass)
+ *   1  one or more dimensions < 3 (fail)
+ *   2  invocation error
+ */
+
+import { readFileSync } from "node:fs";
+import { argv, stdin, exit } from "node:process";
+
+const DIMENSIONS = [
+  "typography",
+  "color",
+  "spatial",
+  "layout",
+  "shadow",
+  "motion",
+  "microcopy",
+  "container",
+];
+
+const DIMENSION_ALIASES = {
+  "color cohesion": "color",
+  "color_cohesion": "color",
+  "spatial rhythm": "spatial",
+  "spatial_rhythm": "spatial",
+  "layout originality": "layout",
+  "layout_originality": "layout",
+  "shadow & depth": "shadow",
+  "shadow_depth": "shadow",
+  "shadow & depth hierarchy": "shadow",
+  "motion intent": "motion",
+  "motion_intent": "motion",
+  "microcopy specificity": "microcopy",
+  "microcopy_specificity": "microcopy",
+  "container depth": "container",
+  "container_depth": "container",
+  "container depth & nesting": "container",
+};
+
+function normalizeKey(key) {
+  const lower = key.toLowerCase().trim();
+  return DIMENSION_ALIASES[lower] || lower;
+}
+
+function parseScores(raw) {
+  if (typeof raw === "string") {
+    try {
+      raw = JSON.parse(raw);
+    } catch (e) {
+      console.error(`Invalid JSON: ${e.message}`);
+      exit(2);
+    }
+  }
+
+  const scores = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const normalized = normalizeKey(key);
+    if (DIMENSIONS.includes(normalized)) {
+      const num = parseInt(value, 10);
+      if (num < 1 || num > 5 || isNaN(num)) {
+        console.error(`Invalid score for ${key}: ${value} (must be 1-5)`);
+        exit(2);
+      }
+      scores[normalized] = num;
+    }
+  }
+
+  // Validate all dimensions present
+  const missing = DIMENSIONS.filter((d) => !(d in scores));
+  if (missing.length > 0) {
+    console.error(`Missing dimensions: ${missing.join(", ")}`);
+    exit(2);
+  }
+
+  return scores;
+}
+
+function computeResult(scores) {
+  const dims = DIMENSIONS.map((d) => scores[d]);
+  const total = dims.reduce((a, b) => a + b, 0);
+  const avg = +(total / dims.length).toFixed(2);
+  const failing = DIMENSIONS.filter((d) => scores[d] < 3).map((d) => ({
+    dim: d,
+    score: scores[d],
+  }));
+  const pass = failing.length === 0;
+
+  let verdict;
+  if (pass) {
+    verdict = "SUCCESS";
+  } else if (failing.some((f) => f.score === 1)) {
+    verdict = "CRITICAL_FAIL";
+  } else {
+    verdict = "FAIL";
+  }
+
+  return {
+    scores,
+    total,
+    max: 40,
+    avg,
+    pass,
+    failing,
+    verdict,
+  };
+}
+
+// -- CLI entry point --
+
+async function main() {
+  let input = null;
+
+  // Parse args
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--file" && argv[i + 1]) {
+      try {
+        input = readFileSync(argv[i + 1], "utf8");
+      } catch (e) {
+        console.error(`Cannot read file: ${e.message}`);
+        exit(2);
+      }
+      i++;
+    } else if (argv[i] === "--scores" && argv[i + 1]) {
+      input = argv[i + 1];
+      i++;
+    } else if (argv[i] === "--help" || argv[i] === "-h") {
+      console.log(`score.mjs -- Qualia visual-polish loop scoring utility
+
+Usage:
+  echo '{"typography":3,...}' | node score.mjs
+  node score.mjs --file scores.json
+  node score.mjs --scores '{"typography":4,...}'
+
+Dimensions: ${DIMENSIONS.join(", ")}
+Each scored 1-5. All must be >= 3 to pass.`);
+      exit(0);
+    }
+  }
+
+  // Read from stdin if no explicit input
+  if (!input) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+      chunks.push(chunk);
+    }
+    input = Buffer.concat(chunks).toString("utf8").trim();
+  }
+
+  if (!input) {
+    console.error("No input provided. Use --file, --scores, or pipe JSON to stdin.");
+    exit(2);
+  }
+
+  const scores = parseScores(input);
+  const result = computeResult(scores);
+
+  console.log(JSON.stringify(result, null, 2));
+  exit(result.pass ? 0 : 1);
+}
+
+main();

package/skills/qualia-prd/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: qualia-prd
+description: "Synthesize the current conversation into a durable Product Requirements Document (PRD) at .planning/PRD-{slug}.md. Optionally opens a parent GitHub issue. No interview — synthesizes what's already been discussed. Trigger on 'qualia-prd', 'turn this into a PRD', 'write this up as a feature spec', 'make a spec from this discussion', 'PRD this', 'externalize this idea', 'capture this as a spec'. Pairs with /qualia-issues to break the PRD into vertical-slice issues. Distinct from /qualia-plan (phase-operational) — /qualia-prd is feature-durable. v5.3 flagship from Matt Pocock's /to-prd pattern."
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Agent
+argument-hint: "[slug] [--issue] [--no-issue] [--update PATH]"
+---
+
+# /qualia-prd — Conversation → durable feature spec
+
+You've been discussing a feature in chat. `/qualia-prd` synthesizes that conversation into a durable PRD on disk so the spec lives outside the chat context. From there, `/qualia-issues` can split it into vertical-slice GH issues, and `/qualia-plan` can plan a phase against it.
+
+**Distinct from `/qualia-new`:** `/qualia-new` is project setup (one-shot — JOURNEY.md, PRODUCT.md, CONTEXT.md). `/qualia-prd` is mid-project feature spec capture. You'll run it dozens of times across a project's life; you run `/qualia-new` once.
+
+## When to use
+
+- Mid-project, when a feature has been discussed enough that you want it durable
+- Before `/qualia-issues` so the issues link back to a real spec
+- Before `/qualia-plan` if the phase needs a feature spec upstream of it
+- When the conversation is about to compact and the PRD context would be lost
+
+## Pre-flight
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner plan
+```
+
+| Gate | Check | If fail |
+|---|---|---|
+| In a project | `.planning/` exists | HALT — "Run `/qualia-new` first or use `/qualia-quick` for one-off work" |
+| PRODUCT.md present | `.planning/PRODUCT.md` readable | NUDGE — proceed but recommend running `/qualia-new` to seed PRODUCT.md |
+| CONTEXT.md present | `.planning/CONTEXT.md` readable | NUDGE — PRD will use ad-hoc terminology instead of the glossary |
+| Working tree | `git status --porcelain` empty | OK to be dirty — PRD is additive, no logic changes |
+| Slug | First arg or auto-derive from first heading | Auto-derive: kebab-case the conversation's main feature topic |
+
+## Process
+
+### 1. Slug + path
+
+```bash
+SLUG="${1:-$(date +%Y%m%d)-feature}"   # or auto-derive from conversation
+PRD_PATH=".planning/PRD-${SLUG}.md"
+```
+
+If `--update PATH` is provided, update an existing PRD instead of writing a new one. The synthesis preserves existing sections that haven't been touched in conversation; only changed sections get rewritten.
+
+### 2. Spawn synthesizer (forked subagent — preserves taste, cheap on context)
+
+The synthesis runs in a **forked subagent**. Forks inherit the full conversation history + share the prompt cache, so the agent can pull the design discussion, decisions, ADR-worthy moments, and user voice without re-loading anything. The fork writes the PRD file and returns just the path + 1-line summary — keeps the parent session lean.
+
+```
+Agent(
+  subagent_type="general-purpose",
+  description="Synthesize conversation → PRD",
+  prompt=`
+You are synthesizing this conversation's feature discussion into a durable PRD.
+
+# Output location
+Write to: ${PRD_PATH}
+
+# Inputs you have (from forked context)
+- The full conversation up to this point
+- @.planning/PRODUCT.md  (project register, voice, anti-references)
+- @.planning/CONTEXT.md  (domain glossary — USE these terms, do not invent synonyms)
+- @.planning/decisions/*.md (ADRs constraining the design space)
+
+# PRD structure (copy this skeleton; fill from conversation)
+
+\`\`\`markdown
+---
+name: {feature name}
+slug: ${SLUG}
+created: ${date}
+status: draft | accepted | shipped | abandoned
+---
+
+# {Feature name}
+
+## Why this exists
+{1-3 sentences: what problem does this solve, for whom, why now}
+
+## User stories
+- As a {persona}, I want to {do X} so that {outcome}.
+- ...
+
+## Acceptance criteria
+Observable, testable behaviors. Each must be verifiable post-build.
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+
+## Out of scope (mandatory)
+What this feature is NOT. Pin this down so scope creep is detectable.
+- {explicit non-goal 1}
+- {explicit non-goal 2}
+
+## Modules touched
+List the deep modules / files / packages this PRD will modify or create.
+Use CONTEXT.md domain language. Surface interface changes explicitly.
+
+| Module | Interface change | Rationale |
+|---|---|---|
+| {module} | {new method / removed export / signature change} | {why} |
+
+## Testing decisions
+Which behaviors get tests, what kind (unit / integration / e2e), where the
+seams are. /qualia-test --tdd will read this.
+
+## Open questions
+Things the conversation flagged but didn't resolve. /qualia-discuss can
+walk these down before /qualia-plan.
+
+## References
+- Conversation timestamp: {ISO}
+- Related ADRs: docs/adr/...
+- Related PRDs: .planning/PRD-...
+\`\`\`
+
+# Discipline
+- NO interview. Synthesize what was DISCUSSED. If a section has nothing in
+  the conversation, leave a TODO marker — do NOT invent.
+- Use CONTEXT.md domain terms. If the user said "lesson" but CONTEXT.md says
+  "module", normalize to "module" and note the alias.
+- Voice = PRODUCT.md voice. No "Welcome to" / "Get Started" / em-dashes in
+  user-facing copy snippets.
+- Output: write the file, then return ONLY \`{ "path": "...", "summary": "1 sentence" }\`.
+`
+)
+```
+
+### 3. Optional GH issue
+
+If `--issue` (or default when `gh` is configured AND `.planning/agents/tracker.md` exists), open a parent issue linking to the PRD path:
+
+```bash
+PRD_BODY=$(cat "${PRD_PATH}")
+gh issue create \
+  --title "PRD: {feature name}" \
+  --body-file "${PRD_PATH}" \
+  --label "prd,needs-triage"
+```
+
+Pass `--no-issue` to skip. The PRD itself is the source of truth — the GH issue is a notification surface.
+
+### 4. Commit
+
+```bash
+git add "${PRD_PATH}"
+git -c user.name="Qualia Solutions" -c user.email="info@qualiasolutions.net" \
+  commit -m "prd(${SLUG}): {feature name}"
+```
+
+### 5. End-card + next-command hint
+
+```bash
+node ~/.claude/bin/qualia-ui.js divider
+node ~/.claude/bin/qualia-ui.js ok "PRD: ${PRD_PATH}"
+node ~/.claude/bin/qualia-ui.js ok "Issue: {url or 'skipped'}"
+node ~/.claude/bin/qualia-ui.js end "PRD CAPTURED" "/qualia-issues   # break into vertical slices"
+```
+
+## Token discipline (mandatory)
+
+This skill is the v5.3 reply to Matt's instruction-budget thesis. Three rules:
+
+1. **Forked subagent, file output.** The synthesis runs in a fork; main session never sees the full PRD body. Only `{path, summary}` flows back.
+2. **No re-summarization.** When the parent session needs the PRD later, it Reads the file (or a later skill does). Never paste the PRD body into chat to "confirm."
+3. **Fork prefix is stable.** Role + PRD skeleton are stable across spawns — Anthropic prompt caching applies. Per-invocation cost is ~5K tokens for the fork + ~2K for the synthesis output.
+
+## Failure modes
+
+| Symptom | Cause | Action |
+|---|---|---|
+| `.planning/ not found` | Not in a Qualia project | HALT; recommend `/qualia-new` or `/qualia-quick` |
+| Conversation has no clear feature topic | Skill invoked too early | NUDGE — ask the user "what feature are we PRD-ing? Pick a slug or paste a 1-line summary" |
+| `gh` not configured | No GitHub auth | Skip issue creation silently; print PRD path |
+| PRD path collision | Slug already exists | Append `-2`, `-3` to slug; surface to user |
+| Empty conversation context | Fresh session | HALT — "/qualia-prd needs a discussion to synthesize. Discuss first, then run." |
+
+## Rules
+
+1. **Don't interview.** This is synthesis, not a deep-dive. If gaps exist, mark TODO and recommend `/qualia-discuss`.
+2. **CONTEXT.md is law.** Use the project's terms. Don't invent.
+3. **One PRD per feature.** If two features got conflated in conversation, write two PRDs and link them.
+4. **Voice match.** PRODUCT.md voice. No generic SaaS copy.
+5. **Forked context, file output.** Token discipline above.
+6. **Commit immediately.** PRDs are durable artifacts — they ship in git.
+
+## Pairs with
+
+- `/qualia-discuss` — run BEFORE if the conversation has open questions
+- `/qualia-issues` — run AFTER to break PRD into vertical-slice GH issues
+- `/qualia-plan` — run AFTER `/qualia-issues` if you want a phase plan
+- `/qualia-new` — runs ONCE at project setup; `/qualia-prd` is the per-feature equivalent