start-vibing 4.0.2 → 4.1.1

package/template/.claude/skills/super-design/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: super-design
+description: >
+  Performs end-to-end design audits on web projects. MUST BE USED when the user
+  mentions super-design, design audit, UX review, accessibility review, design
+  critique, competitor analysis, WCAG, Core Web Vitals, usability audit, or asks
+  to evaluate their website's design quality. Produces market analysis, live-site
+  UX audit (WCAG 2.2 AA, Nielsen heuristics, Baymard, CWV), and synthesized
+  overview. Re-audits only what changed since last run. On explicit user request,
+  applies surgical fixes with full rollback.
+version: 0.4.0
+---
+
+# super-design
+
+## What this skill does
+
+Four-phase pipeline with 6 specialist agents:
+
+1. **Market research** (sd-research) — auto-detects niche from repo, finds 5–10
+   competitors, extracts design language, produces market-analysis.md.
+2. **UI/UX audit** (sd-audit) — drives browser via Playwright MCP directly,
+   applies Nielsen's 10 heuristics, WCAG 2.2 AA, Baymard (if e-commerce), and
+   Core Web Vitals. Produces findings.json with SHOT+QUOTE+SEL+VAL evidence.
+3. **Synthesis** (sd-synthesis) — unifies research + audit into overview.md.
+4. **Fix** (sd-fix + two-stage verify) — optional. Applies safe fixes with
+   technical gates (types/lint/tests) AND semantic verification ("does this
+   fix actually resolve the finding, or just mask it?").
+
+## Entry flow
+
+### Step 1: Preflight
+
+```bash
+STATE=docs/super-design/.audit-state.json
+if [[ ! -f "$STATE" ]]; then MODE=first-audit
+elif ! bash .claude/skills/super-design/scripts/validate-state.sh; then MODE=first-audit
+else MODE=incremental-candidate
+fi
+```
+
+### Step 2: Scope decision (if incremental)
+
+Apply cascade from `references/change-detection-playbook.md` §4:
+- Run `scripts/detect-changes.sh $LAST_SHA` → classify changed files.
+- theory_doc_sha changed OR tokens changed OR major dep bump OR >180d old → FULL.
+- Only components changed → re-audit pages importing them (N=3 hops via madge).
+- Only routes added → audit those routes only.
+- Only content changed → rerun a11y+content on affected pages.
+- Nothing design-relevant → exit with note.
+
+Record scope in overview.md changelog banner.
+
+### Step 3: Dispatch (via Task tool)
+
+```
+1. sd-research    (skip if market-analysis.md <90d AND no dep/README change)
+2. sd-audit       (only scoped pages — uses Playwright MCP directly)
+3. sd-synthesis   (always; rebuilds overview.md)
+4. sd-fix         (ONLY if user asked; uses verify-technical + verify-semantic)
+```
+
+Pass findings via files under `.super-design/sessions/<id>/`, not chat.
+
+### Step 4: Write state + history
+
+- Atomic write `.audit-state.json` (.tmp then rename).
+- Append session to `audit-history.md`.
+- `git notes --ref=super-design add -f -m <json> HEAD`.
+
+### Step 5: Return summary (≤5 sentences)
+
+Do NOT paste overview into chat.
+
+## User flags
+
+- `--force-full` — ignore state, full audit
+- `--refresh-research` — rerun sd-research
+- `--only <cat>` — a11y | design | ux | perf | research
+- `--scope <url>` — specific route
+- `--fix` — run sd-fix after audit
+- `--dry-run` — artifacts without committing state
+- `--ci` — non-interactive, create PR, exit non-zero on blockers
+
+## References (Read on demand)
+
+- `references/design-theory.md`
+- `references/audit-methodology.md`
+- `references/market-research-playbook.md`
+- `references/change-detection-playbook.md`
+- `references/fix-agent-playbook.md`
+- `references/playwright-mcp-reference.md`
+- `references/skills-subagents-reference.md`
+
+## Hard rules
+
+1. Every finding MUST cite SHOT+QUOTE+SEL+VAL.
+2. Every fix MUST reference a finding ID in commit message.
+3. Never auto-apply fixes above LOW risk without user approval.
+4. Never edit outside configured source roots.
+5. Never commit to main — all fixes on session branch.
+6. Playwright MCP is the ONLY way to interact with live site.
+7. Summary to user ≤5 sentences; report lives in overview.md.
+8. Two-stage verify: technical gates (types/lint/tests) AND semantic ("does
+   this actually resolve the finding?"). Both must pass.

package/template/.claude/skills/super-design/hooks/guard-paths.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: reject Edit/MultiEdit/Write on protected paths."""
+import json, sys, re
+
+DENY_PATTERNS = [
+    r"^\.env", r"(^|/)node_modules/", r"(^|/)dist/", r"(^|/)\.next/",
+    r"(^|/)build/", r"(^|/)out/", r"package-lock\.json$",
+    r"pnpm-lock\.yaml$", r"yarn\.lock$", r"^\.git/",
+]
+ALLOW_PREFIXES = [
+    "src/", "app/", "pages/", "components/", "styles/", "public/",
+    "docs/super-design/", ".super-design/", ".claude/",
+]
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception as e:
+        print(f"guard-paths: invalid stdin JSON: {e}", file=sys.stderr)
+        sys.exit(0)
+    path = (payload.get("tool_input", {}) or {}).get("file_path", "")
+    if not path:
+        sys.exit(0)
+    rel = path.lstrip("./")
+    for pat in DENY_PATTERNS:
+        if re.search(pat, rel):
+            print(f"guard-paths: BLOCKED edit on protected path: {rel}", file=sys.stderr)
+            sys.exit(2)
+    if not any(rel.startswith(p) for p in ALLOW_PREFIXES):
+        print(f"guard-paths: WARN edit outside configured source roots: {rel}", file=sys.stderr)
+        sys.exit(0)
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()

package/template/.claude/skills/super-design/hooks/post-edit-lint.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: lint just-edited file; exit 2 on NEW errors."""
+import json, sys, subprocess, os, hashlib, pathlib
+
+EXT_LINTERS = {
+    ".ts":  ["npx", "eslint", "--format", "json"],
+    ".tsx": ["npx", "eslint", "--format", "json"],
+    ".js":  ["npx", "eslint", "--format", "json"],
+    ".jsx": ["npx", "eslint", "--format", "json"],
+    ".vue": ["npx", "eslint", "--format", "json"],
+    ".svelte": ["npx", "eslint", "--format", "json"],
+    ".astro":  ["npx", "eslint", "--format", "json"],
+}
+BASELINE_DIR = pathlib.Path(".super-design/.cache/lint-baselines")
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    path = (payload.get("tool_input", {}) or {}).get("file_path", "")
+    if not path or not os.path.exists(path):
+        sys.exit(0)
+    ext = os.path.splitext(path)[1]
+    cmd = EXT_LINTERS.get(ext)
+    if not cmd:
+        sys.exit(0)
+    try:
+        result = subprocess.run(cmd + [path], capture_output=True, text=True, timeout=30)
+    except Exception as e:
+        print(f"post-edit-lint: failed to run lint: {e}", file=sys.stderr)
+        sys.exit(0)
+    try:
+        data = json.loads(result.stdout or "[]")
+    except Exception:
+        sys.exit(0)
+    current_count = sum((f.get("errorCount", 0) + f.get("warningCount", 0)) for f in data)
+    BASELINE_DIR.mkdir(parents=True, exist_ok=True)
+    key = hashlib.sha256(path.encode()).hexdigest()[:16]
+    baseline_file = BASELINE_DIR / f"{key}.txt"
+    baseline_count = -1
+    if baseline_file.exists():
+        try:
+            baseline_count = int(baseline_file.read_text().strip())
+        except:
+            pass
+    if baseline_count < 0:
+        baseline_file.write_text(str(current_count))
+        sys.exit(0)
+    if current_count > baseline_count:
+        print(f"post-edit-lint: REGRESSION in {path}: {baseline_count} -> {current_count}", file=sys.stderr)
+        sys.exit(2)
+    baseline_file.write_text(str(current_count))
+    sys.exit(0)
+
+if __name__ == "__main__":
+    main()