start-vibing 4.0.2 → 4.1.1

package/template/.claude/skills/super-design/references/superpowers-and-distribution.md

@@ -0,0 +1,136 @@
+# Superpowers framework + private distribution reference — PLACEHOLDER
+
+> **This file is a placeholder.** The complete content was delivered as the
+> "Superpowers and Private Claude Skill Distribution: 2026 Playbook" artifact
+> in the conversation history. Paste it here (~25KB).
+
+## What the content covers
+
+### Part 1 — Jesse Vincent's Superpowers framework
+- What Superpowers actually is (Claude Code plugin, ~14 skills + session-start hook)
+- Distribution via github.com/obra/superpowers + Anthropic marketplace
+- Four stated principles: TDD, systematic over ad-hoc, complexity reduction,
+  evidence over claims
+- The pipeline: brainstorming → writing-plans → subagent-driven-development →
+  two-stage review → verification-before-completion → finishing-a-development-branch
+- Jesse Vincent's background (Request Tracker, Perl pumpking, K-9 Mail,
+  Keyboardio, VaccinateCA, Prime Radiant)
+- Release cadence: v5.0.7 (Mar 31, 2026), last commit Apr 16, 2026
+- Install: `/plugin install superpowers@claude-plugins-official`
+- 355,657 installs shown on claude.com/plugins/superpowers
+- Cross-platform: Cursor, Codex, OpenCode, Gemini CLI, GitHub Copilot CLI
+- Reception: Simon Willison endorsement, benchmark skepticism, 94% PR rejection rate
+- Relationship to Anthropic Agent Skills (complementary, not competing)
+
+### Part 2 — Publishing Claude skills privately in 2026
+
+#### Anthropic's official distribution layer
+- Skills Directory (Dec 18, 2025) at claude.com/connectors
+- Only partner-gated, no open submission
+- Claude Code plugin marketplace anthropics/claude-plugins-official
+- Reserved marketplace names list
+- Mahesh Murag (PM) quote: "no revenue-sharing arrangements at this time"
+- 3,000+ community upvotes requesting monetization, zero response from Anthropic
+- Claude Marketplace at claude.com/platform/marketplace is procurement, NOT a skill store
+
+#### Private marketplace mechanism (code.claude.com/docs/en/plugin-marketplaces)
+Six channels that work today:
+1. Private GitHub repo (GITHUB_TOKEN env)
+2. Private GitLab/Bitbucket/self-hosted git (SSH key pre-loaded)
+3. Self-hosted HTTP JSON (LiteLLM Enterprise reference)
+4. Private npm registry (.npmrc auth)
+5. Container seed (CLAUDE_CODE_PLUGIN_SEED_DIR env)
+6. Managed settings allowlist (strictKnownMarketplaces)
+
+Example marketplace.json:
+```json
+{
+  "name": "super-design-private",
+  "owner": { "name": "Your Agency", "email": "dev@agency.com" },
+  "plugins": [
+    { "source": "github", "repo": "your-org/super-design-skill", "ref": "v1.0.0" }
+  ]
+}
+```
+
+Install flow:
+```
+/plugin marketplace add your-org/super-design-marketplace
+/plugin install super-design@super-design-marketplace
+```
+
+#### Team/Enterprise org-wide skill sharing (Dec 18, 2025)
+- Admin-provisioned org-wide (default-on)
+- Peer-to-peer sharing (off by default)
+- Peer-to-org sharing (off by default)
+- Skills don't sync across surfaces (Claude.ai / API / Claude Code separate)
+- Collision order: enterprise > personal > project > plugin
+
+#### Monetization platform comparison
+
+| Platform | Fee | Strengths | Weaknesses |
+|---|---|---|---|
+| **Polar.sh** | 4% + $0.40 | MoR; license keys + GitHub benefits auto; best for super-design | Newer platform |
+| **Lemon Squeezy** | 5% + $0.50 | Strong license API | Higher fees; onboarding rejections |
+| **Gumroad** | 10% + $0.50 | Dominant for existing paid skills | 10% painful at scale |
+| **Stripe** | 2.9% + $0.30 | Lowest fees | NOT merchant-of-record; build your own license server |
+| **Paddle** | varies | MoR | Avoid post-2025 FTC settlement friction |
+| **GitHub Sponsors** | 0% | Auto-invite sponsors to private repo | Monthly tiers only, not one-time |
+
+#### License-key mechanics in Claude Code
+- Phone-home validation (24h cached)
+- Ed25519-signed offline files (~50 lines using cryptography.hazmat)
+- Encrypted assets (AES-256-GCM)
+- Watermarking via invisible unicode
+- Telemetry keyed on sha256(license_key)
+
+#### Existing paid Claude skills (all Gumroad, zero enforcement)
+- Brian Wagner: $9-$49 bundles
+- Aakash Gupta Job Search OS: $49 one-time / $250/year
+- Usama Akram: 300+ skill bundle
+- RAXXO Studios: €5 single, 8-skill bundle
+- Alex McFarland: Plugin Marketplace Builder (Substack)
+- Sahil Lavingia (Gumroad founder): free as visibility play
+
+Price anchors: $9-$19 single, $29-$49 bundles, $49-$99 15+ skill systems, $250+/year subscription.
+
+#### Legal: license choices for paid distribution
+- **Elastic License 2.0 (RECOMMENDED for super-design)**: 3 short restrictions —
+  no hosted reselling, no circumventing license-key, no removing copyright
+- **PolyForm Shield 1.0.0**: source-available on GitHub, no competitor use
+- **PolyForm Internal Use 1.0.0**: read-only eval version
+- **Custom proprietary EULA**: per-organization seat license, no ML training clause
+
+Trademark: CLAUDE registered USPTO, use nominative fair-use, include
+"not affiliated with Anthropic" disclaimer.
+
+#### Recommended stack for super-design
+Phase 1 (internal-only): private GitHub repo + PolyForm Internal Use +
+`/plugin marketplace add` with GITHUB_TOKEN.
+
+Phase 2 (selling to agencies): Polar.sh as merchant-of-record. Product with:
+- License Keys benefit (3-activation limit)
+- GitHub Repository benefit pointing at private repo
+- Optional file-download of super-design.skill ZIP
+
+Pricing: $149 one-time per seat OR $29/month.
+
+scripts/verify_license.py: 24-hour cached Polar validation pattern (~40 lines Python).
+
+Files: LICENSE (Elastic 2.0 verbatim), EULA.md (plain-English addendum),
+README.md with buy → GitHub invite → export SUPER_DESIGN_LICENSE_KEY → use.
+
+Telemetry abuse detection via sha256(license_key) pings.
+
+#### Deeper moat (if super-design becomes real business)
+Hosted execution: Stripe-billed service running audits on your infrastructure.
+Heuristics and prompts never touch customer's machine. Tabnine/Wallaby
+precedent. Agent37.com positioning as "Gumroad for Claude skills" with
+hosted-runtime + Stripe billing is worth evaluating.
+
+## Where super-design uses this
+
+- **LICENSE** (Elastic 2.0 verbatim) — see top-level file
+- **EULA.md** (per-organization seat license) — see top-level file
+- **README.md** install instructions use the private-marketplace pattern
+- **Future scripts/verify_license.py** would follow Polar.sh 24h-cache pattern

package/template/.claude/skills/super-design/scripts/detect-changes.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Usage: detect-changes.sh <last_sha> [<last_iso>]
+# Emits JSON: { mode, range_start, commits, files, classified }
+set -euo pipefail
+
+LAST_SHA="${1:-}"
+LAST_ISO="${2:-}"
+
+if [[ -z "$LAST_SHA" ]]; then echo '{"error":"missing last_sha"}'; exit 2; fi
+if ! git rev-parse --git-dir >/dev/null 2>&1; then echo '{"error":"not-a-git-repo"}'; exit 3; fi
+
+if git rev-parse --verify --quiet "${LAST_SHA}^{commit}" >/dev/null; then
+  if git merge-base --is-ancestor "$LAST_SHA" HEAD; then RANGE_START="$LAST_SHA"
+  else RANGE_START="$(git merge-base HEAD "$LAST_SHA" 2>/dev/null || echo "")"; fi
+else RANGE_START=""; fi
+
+if [[ -z "$RANGE_START" ]]; then
+  if [[ -n "$LAST_ISO" ]]; then
+    FILES="$(git log --since="$LAST_ISO" --name-only --pretty=format: 2>/dev/null | sort -u | sed '/^$/d' || true)"
+    COMMITS="$(git log --since="$LAST_ISO" --pretty=format:'%H|%s|%an|%aI' 2>/dev/null || true)"
+    MODE="since-time"
+  else echo '{"error":"lost-anchor-no-fallback-time"}'; exit 4; fi
+else
+  FILES="$(git diff --name-only "${RANGE_START}..HEAD" \
+    -- ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!yarn.lock' \
+       ':!.github/**' ':!**/*.test.*' ':!**/*.spec.*' ':!**/*.stories.*' | sort -u)"
+  COMMITS="$(git log --no-merges --pretty=format:'%H|%s|%an|%aI' "${RANGE_START}..HEAD" 2>/dev/null || true)"
+  MODE="sha-range"
+fi
+
+declare -A CLASSIFIED
+while IFS= read -r p; do
+  [[ -z "$p" ]] && continue
+  case "$p" in
+    tailwind.config.*|*.tokens.json|styles/tokens.css|styles/theme.css) CLASSIFIED[tokens]+="$p,";;
+    components/*|src/components/*|app/_components/*) CLASSIFIED[components]+="$p,";;
+    app/*/page.*|app/page.*|app/*/route.*|app/route.*|pages/*|src/pages/*|app/routes/*|src/routes/*) CLASSIFIED[routes]+="$p,";;
+    public/*|src/assets/*|assets/*) CLASSIFIED[imagery]+="$p,";;
+    package.json) CLASSIFIED[deps]+="$p,";;
+    references/design-theory.md|references/market-analysis.md) CLASSIFIED[theory]+="$p,";;
+    *.md|*.mdx) CLASSIFIED[content]+="$p,";;
+    *) CLASSIFIED[other]+="$p,";;
+  esac
+done <<< "$FILES"
+
+jq -Rn --arg mode "$MODE" --arg range_start "$RANGE_START" --arg last_iso "$LAST_ISO" \
+  --arg tokens "${CLASSIFIED[tokens]:-}" --arg components "${CLASSIFIED[components]:-}" \
+  --arg routes "${CLASSIFIED[routes]:-}" --arg imagery "${CLASSIFIED[imagery]:-}" \
+  --arg deps "${CLASSIFIED[deps]:-}" --arg theory "${CLASSIFIED[theory]:-}" \
+  --arg content "${CLASSIFIED[content]:-}" \
+  --argjson files "$(printf '%s\n' "$FILES" | jq -R . | jq -s .)" \
+  --argjson commits "$(printf '%s\n' "$COMMITS" | jq -R . | jq -s .)" '
+  def tolist(s): s | split(",") | map(select(length>0));
+  {mode:$mode, range_start:$range_start, since_iso:$last_iso,
+   commits:$commits, files:$files,
+   classified: {
+     tokens: tolist($tokens), components: tolist($components),
+     routes: tolist($routes), imagery: tolist($imagery),
+     deps: tolist($deps), theory: tolist($theory), content: tolist($content)
+   }
+  }'

package/template/.claude/skills/super-design/scripts/diff-tokens.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+PREV="${1:?usage: diff-tokens.sh <prev> <curr>}"
+CURR="${2:?usage: diff-tokens.sh <prev> <curr>}"
+jq -n --slurpfile a "$PREV" --slurpfile b "$CURR" '
+  ($a[0] // {}) as $before | ($b[0] // {}) as $after |
+  {
+    added: [$after | to_entries[] | select(.key as $k | ($before | has($k)) | not) | .key],
+    removed: [$before | to_entries[] | select(.key as $k | ($after | has($k)) | not) | .key],
+    modified: [$after | to_entries[] |
+      select(.key as $k | ($before | has($k)) and (.value != $before[$k])) |
+      { key: .key, before: $before[.key], after: .value }]
+  }'

package/template/.claude/skills/super-design/scripts/discover-routes.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+detect_framework() {
+  if   [[ -f next.config.js || -f next.config.ts || -f next.config.mjs ]]; then echo "next"
+  elif [[ -f remix.config.js || -d app/routes ]]; then echo "remix"
+  elif [[ -f svelte.config.js && -d src/routes ]]; then echo "sveltekit"
+  elif [[ -f astro.config.mjs || -f astro.config.ts ]]; then echo "astro"
+  elif [[ -f nuxt.config.ts || -f nuxt.config.js ]]; then echo "nuxt"
+  elif [[ -f app.config.ts && -d src/routes ]]; then echo "solid-start"
+  elif [[ -f gatsby-config.js || -f gatsby-config.ts ]]; then echo "gatsby"
+  elif [[ -f angular.json ]]; then echo "angular"
+  else echo "unknown"; fi
+}
+
+FW="$(detect_framework)"
+case "$FW" in
+  next)
+    APP="$(find app src/app -type f \( -name 'page.tsx' -o -name 'page.ts' -o -name 'page.jsx' -o -name 'page.js' -o -name 'page.md' -o -name 'page.mdx' -o -name 'route.ts' -o -name 'route.js' \) 2>/dev/null \
+      | sed -E 's|(^|/)(app|src/app)/||; s|/page\.[a-z]+$||; s|/route\.[a-z]+$||; s|^$|/|' \
+      | sed -E 's|\([^)]+\)/||g; /(^|\/)_/d' | sort -u || true)"
+    PG="$(find pages src/pages -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
+      | grep -vE '(^|/)(pages|src/pages)/(_app|_document|_error|404|500|api/)' \
+      | sed -E 's|(^|/)(pages|src/pages)/||; s|\.(tsx|ts|jsx|js|md|mdx)$||; s|index$||' | sort -u || true)"
+    printf '%s\n%s\n' "$APP" "$PG" | awk 'NF' | sed -E 's|^|/|; s|//|/|g' | sort -u | jq -Rn '[inputs]';;
+  sveltekit)
+    find src/routes -type f -name '+page.svelte' 2>/dev/null \
+      | sed -E 's|^src/routes||; s|/\+page\.svelte$||; s|\([^)]+\)/||g' \
+      | awk 'NF==0 {print "/"; next} {print}' | sort -u | jq -Rn '[inputs]';;
+  astro)
+    find src/pages -type f \( -name '*.astro' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
+      | sed -E 's|^src/pages||; s|\.(astro|md|mdx)$||; s|/index$||' | sort -u | jq -Rn '[inputs]';;
+  nuxt)
+    find pages app/pages -type f -name '*.vue' 2>/dev/null \
+      | sed -E 's|^(app/)?pages||; s|\.vue$||; s|/index$||' | sort -u | jq -Rn '[inputs]';;
+  remix)
+    find app/routes -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
+      | sed -E 's|^app/routes/||; s|\.(tsx|ts|jsx|js|md|mdx)$||; s|\.|/|g; s|_index$||; s|^|/|' \
+      | sort -u | jq -Rn '[inputs]';;
+  solid-start)
+    find src/routes -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' \) 2>/dev/null \
+      | sed -E 's|^src/routes||; s|\.(tsx|ts|jsx|js)$||; s|/index$||; s|\([^)]+\)/||g' \
+      | sort -u | jq -Rn '[inputs]';;
+  *) echo '[]';;
+esac

package/template/.claude/skills/super-design/scripts/extract-tokens.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const out = {};
+const tailwindConfigs = ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"];
+for (const candidate of tailwindConfigs) {
+  if (fs.existsSync(candidate)) {
+    try {
+      const { default: resolveConfig } = await import("tailwindcss/resolveConfig");
+      const cfg = (await import(pathToFileURL(path.resolve(candidate)).href)).default;
+      const resolved = resolveConfig(cfg);
+      flatten(resolved.theme, "tw", out);
+    } catch (e) { out[`_error_${candidate}`] = String(e.message || e); }
+    break;
+  }
+}
+try {
+  const postcss = (await import("postcss")).default;
+  const cssCandidates = ["styles/globals.css","src/styles/globals.css","app/globals.css","styles/theme.css","src/app/globals.css"];
+  for (const css of cssCandidates) {
+    if (!fs.existsSync(css)) continue;
+    const source = fs.readFileSync(css, "utf8");
+    const root = postcss.parse(source);
+    root.walkAtRules("theme", at => { at.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
+    root.walkRules(":root", rule => { rule.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
+  }
+} catch (e) { out._postcss_error = String(e.message || e); }
+
+console.log(JSON.stringify(out, null, 2));
+
+function flatten(obj, prefix, acc) {
+  if (obj == null) return;
+  if (typeof obj !== "object") { acc[prefix] = String(obj); return; }
+  for (const [k, v] of Object.entries(obj)) {
+    const key = `${prefix}.${k}`;
+    if (v && typeof v === "object" && !Array.isArray(v)) flatten(v, key, acc);
+    else acc[key] = Array.isArray(v) ? v.join(",") : String(v);
+  }
+}

package/template/.claude/skills/super-design/scripts/hash-pages.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Usage: hash-pages.sh <urls_file>
+set -euo pipefail
+URLS="${1:?usage: hash-pages.sh <urls_file>}"
+OUT_DIR="${OUT_DIR:-docs/super-design/.cache/hashes}"
+mkdir -p "$OUT_DIR"
+
+URLS="$URLS" OUT_DIR="$OUT_DIR" node --experimental-vm-modules <<'JS'
+import { chromium } from "playwright";
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const urlsFile = process.env.URLS;
+const outDir = process.env.OUT_DIR;
+const urls = readFileSync(urlsFile, "utf8").split("\n").map(s => s.trim()).filter(Boolean);
+const browser = await chromium.launch();
+const ctx = await browser.newContext({
+  viewport: { width: 1280, height: 800 }, reducedMotion: "reduce", deviceScaleFactor: 1,
+});
+const page = await ctx.newPage();
+const sha = s => createHash("sha256").update(s).digest("hex");
+const results = [];
+for (const url of urls) {
+  try {
+    await page.goto(url, { waitUntil: "networkidle", timeout: 30000 });
+    const html = (await page.content()).replace(/\s+/g, " ").trim();
+    const dom = await page.evaluate(() => {
+      const V = new Set(["nonce","data-timestamp","data-reactid","data-next-hydrate"]);
+      const walk = n => n.nodeType !== 1 ? "" :
+        `<${n.tagName.toLowerCase()}[${[...n.attributes].filter(a=>!V.has(a.name))
+          .map(a=>`${a.name}=${a.value}`).sort().join(",")}]${[...n.childNodes].map(walk).join("")}>`;
+      return walk(document.documentElement);
+    });
+    const buf = await page.screenshot({ fullPage: true, animations: "disabled", caret: "hide" });
+    results.push({ url, html_hash: "sha256:" + sha(html),
+      dom_structure_hash: "sha256:" + sha(dom), screenshot_hash: "sha256:" + sha(buf) });
+  } catch (e) { results.push({ url, error: String(e.message || e) }); }
+}
+writeFileSync(outDir + "/hashes.json", JSON.stringify(results, null, 2));
+await browser.close();
+console.log(JSON.stringify({ count: results.length, path: outDir + "/hashes.json" }));
+JS

package/template/.claude/skills/super-design/scripts/validate-state.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+STATE="${1:-docs/super-design/.audit-state.json}"
+if [[ ! -f "$STATE" ]]; then echo '{"status":"missing"}'; exit 2; fi
+jq -e '
+  (.schema_version | type == "string") and
+  (.last_audit_at  | fromdateiso8601 | . > 0) and
+  (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
+  (.skill_version  | type == "string") and
+  (.tools | type == "object")
+' "$STATE" >/dev/null 2>&1 || { echo '{"status":"corrupt"}'; exit 2; }
+AGE_DAYS=$(( ( $(date -u +%s) - $(jq -r '.last_audit_at | fromdateiso8601' "$STATE") ) / 86400 ))
+if (( AGE_DAYS > 180 )); then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
+elif (( AGE_DAYS > 90 )); then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1
+else echo "{\"status\":\"fresh\",\"age_days\":$AGE_DAYS}"; exit 0; fi

package/template/.claude/skills/super-design/scripts/verify-audit.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SESSION_DIR="${1:?usage: verify-audit.sh <session_dir>}"
+FINDINGS="$SESSION_DIR/findings.json"
+if [[ ! -f "$FINDINGS" ]]; then echo "FATAL: no findings.json at $FINDINGS" >&2; exit 2; fi
+
+jq -r '.[] | [.id, .screenshot_path, .snapshot_path] | @tsv' "$FINDINGS" | while IFS=$'\t' read -r id shot snap; do
+  if [[ ! -s "$shot" ]]; then echo "FAIL $id: missing/empty screenshot $shot" >&2; exit 1; fi
+  if [[ ! -s "$snap" ]]; then echo "FAIL $id: missing/empty snapshot $snap" >&2; exit 1; fi
+done
+
+jq -c '.[]' "$FINDINGS" | while read -r f; do
+  id=$(echo "$f" | jq -r .id)
+  q=$(echo "$f" | jq -r .snapshot_quote)
+  s=$(echo "$f" | jq -r .snapshot_path)
+  if ! grep -qF "$q" "$s"; then echo "FAIL $id: quote not found verbatim in $s" >&2; exit 1; fi
+done
+
+echo "OK: $(jq 'length' "$FINDINGS") findings verified"

package/template/.claude/skills/super-design/templates/audit-state.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "super-design/audit-state.schema.json",
+  "type": "object",
+  "required": ["schema_version","skill_version","last_audit_at","git_sha_at_audit","theory_doc_sha","tools","pages_audited","findings_counts"],
+  "properties": {
+    "schema_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "skill_version": { "type": "string" },
+    "last_audit_at": { "type": "string", "format": "date-time" },
+    "git_sha_at_audit": { "type": "string", "pattern": "^[0-9a-f]{7,64}$" },
+    "git_branch": { "type": "string" },
+    "is_shallow_clone": { "type": "boolean" },
+    "theory_doc_sha": { "type": "string" },
+    "market_analysis_sha": { "type": "string" },
+    "tools": { "type": "object", "additionalProperties": { "type": "string" } },
+    "framework": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "router": { "type": "string" },
+        "version": { "type": "string" }
+      }
+    },
+    "route_map": { "type": "array", "items": { "type": "string" } },
+    "pages_audited": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url","last_audited"],
+        "properties": {
+          "url": { "type": "string" },
+          "route_file": { "type": "string" },
+          "html_hash": { "type": "string" },
+          "dom_structure_hash": { "type": "string" },
+          "viewport_hashes": { "type": "object" },
+          "last_audited": { "type": "string", "format": "date-time" },
+          "findings_ids": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "components": { "type": "object", "additionalProperties": { "type": "string" } },
+    "token_hash": { "type": "string" },
+    "import_graph_sha": { "type": "string" },
+    "findings_counts": {
+      "type": "object",
+      "required": ["blockers","high","medium","nitpicks"],
+      "properties": {
+        "blockers": { "type": "integer" },
+        "high": { "type": "integer" },
+        "medium": { "type": "integer" },
+        "nitpicks": { "type": "integer" }
+      }
+    },
+    "research_at": { "type": "string", "format": "date-time" },
+    "ignored_paths": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/template/.claude/skills/super-design/templates/findings.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "super-design/findings.schema.json",
+  "type": "object",
+  "required": ["session_id", "findings"],
+  "properties": {
+    "session_id": { "type": "string" },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id","category","rule","impact","risk_for_fix","files_affected","dom_selector","page_url","viewport","screenshot_path","snapshot_path","snapshot_quote","computed_style_excerpt","severity","finding"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^F-\\d{4,}$" },
+          "category": { "enum": ["a11y","design","ux","perf","baymard","heuristic"] },
+          "rule": { "type": "string" },
+          "wcag_criterion": { "type": "string" },
+          "nielsen_heuristic": { "type": "string" },
+          "impact": { "enum": ["minor","moderate","serious","critical"] },
+          "severity": { "type": "integer", "minimum": 0, "maximum": 4 },
+          "risk_for_fix": { "enum": ["TRIVIAL","LOW","MEDIUM","HIGH"] },
+          "files_affected": { "type": "array", "items": { "type": "string" } },
+          "page_url": { "type": "string" },
+          "viewport": {
+            "type": "object",
+            "required": ["name","w","h"],
+            "properties": {
+              "name": { "type": "string" },
+              "w": { "type": "integer" },
+              "h": { "type": "integer" }
+            }
+          },
+          "screenshot_path": { "type": "string" },
+          "snapshot_path": { "type": "string" },
+          "snapshot_quote": { "type": "string" },
+          "dom_selector": { "type": "string" },
+          "computed_style_excerpt": { "type": "object" },
+          "evidence_hex_fg": { "type": "string" },
+          "evidence_hex_bg": { "type": "string" },
+          "evidence_contrast_ratio": { "type": "number" },
+          "evidence_px": { "type": "object" },
+          "suggested_fix": {
+            "type": "object",
+            "properties": {
+              "strategy": { "type": "string" },
+              "template_id": { "type": "string" },
+              "value_hint": { "type": "string" }
+            }
+          },
+          "finding": { "type": "string" },
+          "first_seen_at": { "type": "string", "format": "date-time" },
+          "status": { "enum": ["new","persisted","resolved"] }
+        }
+      }
+    }
+  }
+}

package/template/.claude/skills/super-design/templates/fix-history.md.tpl

@@ -0,0 +1,26 @@
+## {{session_date}} · `{{session_id}}` · branch `{{branch}}`
+
+**Counts:** Applied {{applied}} · Proposed {{proposed}} · Skipped {{skipped}} · Failed {{failed}}
+**Base:** `{{base_sha}}` · **Tip:** `{{tip_sha}}`
+
+### Applied
+| Finding | Category | Files | Commit |
+|---|---|---|---|
+{{applied_table}}
+
+### Proposed (awaiting approval)
+| Finding | Category | Files | Patch |
+|---|---|---|---|
+{{proposed_table}}
+
+### Skipped (HIGH risk — tracked as issues)
+| Finding | Issue | Reason |
+|---|---|---|
+{{skipped_table}}
+
+### Failed (rolled back)
+| Finding | Gate | Reason |
+|---|---|---|
+{{failed_table}}
+
+---

package/template/.claude/skills/super-design/templates/overview.md.tpl

@@ -0,0 +1,52 @@
+# Design audit overview — {{project_name}}
+
+> **{{mode_banner}}**
+> {{changelog_body}}
+
+## Executive summary
+
+{{executive_summary}}
+
+## Scorecard
+
+| Category | Score | Blockers | High | Medium | Nitpicks |
+|---|---|---|---|---|---|
+| Nielsen heuristics | {{nielsen_score}}/40 | {{n_blockers_nielsen}} | {{n_high_nielsen}} | {{n_medium_nielsen}} | {{n_nits_nielsen}} |
+| WCAG 2.2 AA | {{wcag_score}}% | {{n_blockers_wcag}} | {{n_high_wcag}} | {{n_medium_wcag}} | {{n_nits_wcag}} |
+| Core Web Vitals | {{cwv_badge}} | {{n_blockers_cwv}} | {{n_high_cwv}} | — | — |
+| Baymard (if applicable) | {{baymard_score}} | {{n_blockers_baymard}} | {{n_high_baymard}} | {{n_medium_baymard}} | — |
+
+## Top findings
+
+### 🚨 Blockers
+{{blockers_table}}
+
+### High priority
+{{high_table}}
+
+### Medium priority
+{{medium_table}}
+
+### Nitpicks
+{{nitpicks_table}}
+
+### ✅ Resolved since last audit
+{{resolved_table}}
+
+## Market positioning snapshot
+{{market_snapshot}}
+
+Full market analysis: `docs/super-design/market-analysis.md`.
+
+## Remediation roadmap
+{{roadmap_body}}
+
+## Appendix — evidence
+- Per-finding details: `docs/super-design/findings/F-*.md`
+- Screenshots: `docs/super-design/.cache/screenshots/`
+- axe-core outputs: `docs/super-design/.cache/axe/`
+- Web Vitals: `docs/super-design/.cache/vitals/`
+- Audit history: `docs/super-design/audit-history.md`
+
+---
+*Generated by super-design v{{version}} on {{timestamp}}. Session: `{{session_id}}`.*