@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/.claude/skills/verify/SKILL.md

@@ -1,160 +0,0 @@
----
-tier: lite
-name: verify
-description: "Verify post-build before committing. Matches change type to check list. Writes a marker the pre-commit hook reads. Runs after each task."
-problem: "Tests run but scope-drift and missed acceptance and ADR violations slip through."
-value: "Post-build gate that matches change type to check list. Runs before commit not after."
-inputs: [Change type or scope hint]
-outputs: [Check results per gate, Blocking findings, Ready-to-commit signal]
-user_invocable: true
-disable_model_invocation: false
----
-
-# Verify
-
-## What you get
-
-Post-build verification gate. Run `/verify` after any task before committing code. I look at the type of change. I run the matching verification. I confirm the production build passes.
-
-When everything clears, I write a marker at `state/markers/verify/<branch>.marker`. The pre-commit-gate hook reads that marker. Without it, the hook blocks your commit. This is the check between "tests green" and "safe to ship."
-
-## When to use it
-
-After each task, before committing code. Not before you push. Not once per session. Each task.
-
-If you change a pure function, run `/verify`. If you touch a route, run `/verify`. If you edit middleware, run `/verify`. The change-type table maps what you touched to what verification fires. One skipped `/verify` is how broken production builds ship — POA session 2026-04-12 lost hours to 6 CI deploys that broke because someone assumed "tests pass = safe."
-
-Docs-only edits and config edits are the exception. State "docs/config only" in the summary and skip verification.
-
-## FAQ
-
-### What is the marker and why does it matter?
-
-The pre-commit-gate hook reads `state/markers/verify/<branch>.marker`. If the marker is missing or older than 5 minutes, the hook blocks the commit. The hook emits `BLOCKED: /verify` which the blocked-items rule requires you to resolve (run `/verify`) or explicitly defer (with stated rationale — silence is not deferral).
-
-The 5-minute window means re-running `/verify` refreshes the marker. Ephemeral sessions (mobile claude.ai/code) also write to `/tmp/claude-verify-<branch>` for desktop parity.
-
-### Do I need to run tests AND the production build?
-
-Both. Tests can pass while the production build fails. Vitest and Jest are permissive. The production build applies stricter rules — type narrowing catches, tree-shaking issues, bundler-specific module resolution, Next.js route-segment contract violations, strict null checks in inferred unions.
-
-If tests pass but the build fails, `/verify` fails. Do not commit. Do not write the marker.
-
-Evidence why this matters: POA session 2026-04-12 shipped 5 PRs (#480, #486, #488, #490, #492) with all tests passing locally. All 6 resulting CI deploys failed because the production build applied stricter rules. Prod stuck on the old image until hotfix — hours of reversed velocity.
-
-### What about UI changes and visual review?
-
-UI component or page changes MUST run `/visual-review`. The skill screenshots each page via Playwright MCP, evaluates against the usability standard and the complement luminaries, and outputs a report to `docs/visual-reviews/YYYY-MM-DD-<page>.md`. No report = do not commit.
-
-Empty state is NOT verification — seed data first. If Playwright MCP is unavailable, do the manual check and note "manual — no screenshot" in the report.
-
-### What about substrate-affecting changes?
-
-Any staged or recently committed change matching the 12 patterns from `.claude/rules/cold-adopter-harness-discipline.md` § "When this rule fires" — hooks, skills, rules, agents, luminaries, lib, standards, schemas, sync templates, ADRs, workflows, scripts — runs `bash scripts/cold-adopter-harness-sync.sh --mode sync --target .` and reports pass/fail. Exit 0 = pass; exit 2 = at least one check failed; exit 3 = setup failure.
-
-Override: `SKIP_COLD_ADOPTER_HARNESS=1 /verify` (logged via trace-helper). The pre-commit-gate hook and CI workflow fire the same matcher independently. Three layers together give the coverage you need.
-
-### What if I wrote the test after the code?
-
-State so in the summary — "test written after; check for tautology." Reviewer audits the test against Beck's four rules of simple design (all tests pass; code reveals intention; no duplication; fewest elements). A passing suite that reads as pattern-match against the code you already shipped is green but not done.
-
-### What if the change traces to a use case?
-
-If the change implements behavior spec'd in a fully-dressed use case at `docs/use-cases/UC-NNN-*.md`, `/verify` includes a traceability check. Every main-scenario step and every extension line maps to at least one test assertion. State the mapping in the summary: `UC-001:3a → test X, UC-001:3b → test Y`. Missing mappings are gaps; tests without use-case traceability are orphan coverage. Per @luminary alistair-cockburn (*Writing Effective Use Cases*).
-
-**Extended per #1171 — decomposition + interaction-design + IA-model traceability.** If the change traces to a decomposition at `docs/decompositions/*.md`, `/verify` checks the responsibility assignment stays inside the deep-module boundary named in the decomposition body. If the change traces to an interaction design at `docs/interaction-designs/*.md`, `/verify` checks the state or sequence diagram scope. If the change traces to an IA model at `docs/ia-models/*.md`, `/verify` checks the entity + task-flow scope. Deviations surface to operator with accept-or-reshape choice — matching the adr-deviation-challenge.sh hook pattern (matcher extended per #1171 to fire on OOAD artifact edits). Advisory in V1 per adr-deviation-challenge calibration pattern.
-
-## Details below the fold
-
-### Procedure
-
-**Step 1 — Identify change type.**
-
-Pick the row that matches what you just changed:
-
-| Change type | Minimum verification |
-|---|---|
-| Pure function (scoring, parsing) | Unit test passes for that function |
-| Worker / agent / queue | Boot the worker + process at least one real job |
-| API route | Hit the endpoint, verify response shape |
-| Schema migration | Verify column exists in DB, ORM client regenerated |
-| Refactor (same logic, new files) | Run the code path end-to-end |
-| Middleware / auth | Verify protected routes redirect AND existing routes still work |
-| Scraper / data source | Trigger one real scrape, verify data lands in DB |
-| Config / env var | Verify the service picks up the new value |
-| UI component / page | **MUST gate**: run `/visual-review` (see FAQ above) |
-| Substrate-affecting change | **MUST gate**: cold-adopter-harness-sync (see FAQ above) |
-| Lite SKILL body change | **MUST gate**: `bash .claude/hooks/tests/verify-lite-tier-resolution.test.sh` — every lite composes_with target resolves under the lite filter (Task 1.8) |
-| Docs / config only | N/A — state "docs/config only" |
-
-**Step 2 — Run verification.**
-
-Execute the row's command. Show the command and output.
-
-**Step 3 — Test check.**
-
-- New pure function → unit test exists and passes. State the test file.
-- Modified tested code → test suite passes. State the count.
-- No testable logic → state why (docs, config, UI-only).
-
-TDD discipline per @luminary kent-beck (*Test-Driven Development: By Example*): red / green / refactor — write the failing test first, make it pass with the minimum code, refactor with tests as safety net. Tests written after the fact confirm what exists, not what matters.
-
-**Step 4 — Production build check (MUST gate).**
-
-Run the project's production build command. Not just type check. Not just tests. Build commands per stack:
-
-- Next.js: `npm run build` (or `pnpm build`, `yarn build`)
-- Node service: `npm run build` or `tsc --noEmit` with prod tsconfig
-- Library: `npm run build`
-
-If tests pass but the production build fails, `/verify` FAILS. Do not proceed. Do not write the marker.
-
-**Step 5 — Write the marker.**
-
-When `/verify` passes end-to-end, write the marker to both locations:
-
-```bash
-BRANCH_SLUG=$(git branch --show-current | tr '/' '-')
-# Desktop marker (fast; survives session; not machine-ephemeral)
-touch "/tmp/claude-verify-${BRANCH_SLUG}"
-# Ephemeral-safe marker (git-tracked; survives sandbox death)
-mkdir -p state/markers/verify
-date -u +%Y-%m-%dT%H:%M:%SZ > "state/markers/verify/${BRANCH_SLUG}.marker"
-git add "state/markers/verify/${BRANCH_SLUG}.marker"
-```
-
-Re-running `/verify` refreshes both markers. Do NOT write the markers if any step failed. Tests passing but build failing = `/verify` FAILED = no marker.
-
-The git-tracked marker is authoritative in ephemeral sessions. Desktop sessions use either; both are checked by pre-commit-gate with the 5-minute freshness window.
-
-**Step 6 — Write the summary.**
-
-```
-## Post-Build Verification
-- Change type: [from table]
-- Verification performed: [exact commands + output summary]
-- Tests: [file + count, or "no testable logic"]
-- Build: [passes / fails]
-- Result: [PASS / FAIL — if FAIL, do not commit]
-```
-
-### Anti-patterns
-
-- "Unit tests pass" as sufficient for workers, routes, scrapers
-- Batch-verifying 5+ tasks at once
-- Skipping verification because "it's a small change"
-- Treating compilation as verification
-- Writing the marker when the production build failed
-
-### Refs
-
-- `.claude/hooks/pre-commit-gate.sh` — reads the marker; emits `BLOCKED: /verify`
-- `.claude/rules/blocked-items.md` — the resolve-or-defer protocol the block triggers
-- `.claude/rules/cold-adopter-harness-discipline.md` — the 12-pattern matcher for substrate changes
-- `.claude/skills/visual-review/SKILL.md` — the UI gate this skill calls
-- `.claude/luminaries/kent-beck.md` — TDD discipline anchor
-- `.claude/luminaries/alistair-cockburn.md` — use-case traceability anchor
-
-## Output discipline
-
-Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/visual-review/SKILL.md

@@ -1,503 +0,0 @@
----
-tier: lite
-name: visual-review
-description: "Visual UX review \u2014 screenshot a rendered page and evaluate against design tokens, usability standard, and Creative Director / Designer luminaries. Requires Playwright MCP."
-problem: "Rendered pages ship with visual regressions. Design tokens drift from usability standards."
-value: "Visual UX review \u2014 screenshot a rendered page and evaluate against design tokens plus usability."
-inputs: [Page URL and viewport]
-outputs: [Screenshot at each viewport, Findings per usability rule, Token alignment report]
-user_invocable: true
-disable_model_invocation: false
-composes_baseline: anthropic-frontend-design
-requires:
-  cli: [npx]
-  mcp: [playwright]
----
-
-# Visual Review
-
-Screenshot a rendered page and evaluate it against the project's design
-system, usability standard, and luminary principles. This gives the
-Designer and Creative Director "eyes" on what was actually built.
-
-> **Baseline composition:** Bassclef's review composes on top of Anthropic's `frontend-design` skill defaults. Adopters firing plain Claude produce output evaluated against the baseline's typography + color + motion + spatial-composition guidance; this skill extends the evaluation with luminary-specific lenses (Tufte for data density, Ive for hierarchy, Rams for restraint, Cooper + Norman for affordances) plus bassclef's design-token + usability-standard discipline.
-
-## Prerequisites
-
-### Infrastructure check (run before first use)
-
-Check if Playwright MCP is available by looking for the
-`mcp__playwright__browser_navigate` tool. If it's NOT available:
-
-1. **Tell the user** — don't silently degrade:
-   > Visual review requires Playwright MCP but it's not available in this session.
-   > To install it, add the Playwright MCP server to your Claude Code config:
-   >
-   > ```json
-   > // In .claude/settings.json or ~/.claude/settings.json
-   > {
-   >   "mcpServers": {
-   >     "playwright": {
-   >       "command": "npx",
-   >       "args": ["@anthropic-ai/mcp-server-playwright"]
-   >     }
-   >   }
-   > }
-   > ```
-   >
-   > Then restart the session. Want me to add this to your settings now?
-
-2. **If the user says yes**, use the `/update-config` skill to add the
-   Playwright MCP server configuration, then tell them to restart.
-
-3. **If the user declines or this is an unattended session**, fall back
-   to manual verification mode: inspect code for tap targets, font sizes,
-   contrast values. Note "manual — no Playwright" in the report. This is
-   degraded mode, not a skip — a report is still required.
-
-### Stale browser recovery
-
-If Playwright MCP errors with "Target page, context or browser has been
-closed" or "Browser is already in use", a stale chrome process from a
-previous session is holding the lock. Fix:
-
-```bash
-pkill -f "mcp-chrome" 2>/dev/null; sleep 1
-```
-
-Then retry the navigation. This is common after long sessions, crashed
-agents, or overnight runs where the browser outlived the session.
-
-### Other prerequisites
-
-- A page must be running (local dev server, staging URL, etc.)
-- If the page requires auth, sign in first via Playwright before running this skill
-
-## Procedure
-
-### Step 1: Navigate and Screenshot (desktop + mobile)
-
-Screenshot at **both** viewports. A desktop-only review misses broken
-mobile layouts (sidebar eating half the screen, tables overflowing,
-tap targets too close together).
-
-```
-Desktop (1280px):
-1. Resize to 1280x800 via mcp__playwright__browser_resize
-2. Navigate to the target URL via mcp__playwright__browser_navigate
-3. Wait for the page to load
-4. Take a full-page screenshot via mcp__playwright__browser_take_screenshot
-5. Capture the accessibility snapshot via mcp__playwright__browser_snapshot
-
-Mobile (375px):
-6. Resize to 375x812 via mcp__playwright__browser_resize
-7. Take a full-page screenshot
-8. Capture the accessibility snapshot
-9. Check: does the sidebar collapse? Do tables reflow? Are tap targets ≥44px?
-```
-
-If the mobile viewport shows a broken layout (sidebar visible at full width,
-content pushed off-screen, horizontal scroll required), flag it as a
-**FAIL** — not a minor issue. Mobile is not optional.
-
-If the user didn't provide a URL, ask for one. Do not guess.
-
-### Step 2: Structural Analysis (from accessibility snapshot)
-
-Using the accessibility snapshot, evaluate:
-
-- **Heading hierarchy**: Are headings properly nested (h1 > h2 > h3)?
-- **Landmark regions**: Are banner, main, nav, contentinfo present?
-- **Interactive elements**: Do all buttons/links have accessible labels?
-- **Form structure**: Are form fields labeled? Are required fields marked?
-
-### Step 3: Usability Standard Check (from screenshot + snapshot)
-
-Evaluate against the 8-point usability standard (`.claude/rules/usability.md`):
-
-| Check | Method | Pass/Fail |
-|---|---|---|
-| 1. Role check | Is operator jargon visible? Database enums exposed? | |
-| 2. Scanning distance | Label-to-value gaps > 150px? | |
-| 3. Typography hierarchy | Key numbers 14px+ bold? Labels smaller + muted? Text < 11px? | |
-| 4. Jargon & copy | Raw enum values? Non-externalized labels? | |
-| 5. Attribution | Actions attributed to people, not just counts? | |
-| 6. Accessibility | Tap targets 44px+? Contrast 4.5:1+? Translucent text BGs? | |
-| 7. Consistency | Same badge/status treatment everywhere? | |
-| 8. Visual verification | Does what you SEE match what the code says? | |
-
-For checks that need measurement, use `mcp__playwright__browser_evaluate` to
-inspect computed styles:
-
-```js
-// Example: check tap target sizes
-document.querySelectorAll('button, a, [role="button"]').forEach(el => {
-  const rect = el.getBoundingClientRect();
-  if (rect.width < 44 || rect.height < 44) {
-    console.log(`Small target: ${el.textContent?.trim()} (${rect.width}x${rect.height})`);
-  }
-});
-```
-
-```js
-// Example: check text sizes
-document.querySelectorAll('*').forEach(el => {
-  const size = parseFloat(getComputedStyle(el).fontSize);
-  if (el.textContent?.trim() && size < 11) {
-    console.log(`Small text: "${el.textContent.trim().slice(0,30)}" at ${size}px`);
-  }
-});
-```
-
-### Step 4: Designer Evaluation (luminary lens)
-
-Evaluate what you SEE through these lenses:
-
-**Norman (usability)**:
-- Is the right action obvious? Can you tell what to do without thinking?
-- Are affordances clear? Do clickable things look clickable?
-- Is error prevention in place? Can the user make mistakes easily?
-
-**Cooper (goal-directed)**:
-- Does the page serve the user's primary goal directly?
-- Is there unnecessary friction between the user and their goal?
-
-**Krug (don't make me think)**:
-- Can you navigate without reading instructions?
-- Are choices obvious and unambiguous?
-
-### Step 5: Creative Director Evaluation (luminary lens)
-
-Evaluate the visual design through these lenses:
-
-**Lupton (typography)**:
-- Is there a clear typographic hierarchy (headline > subhead > body > caption)?
-- Is type used to tell a visual story, or is it all the same weight/size?
-- Do font choices support the brand's personality?
-
-**Albers (color)**:
-- Are colors working in context (not just in isolation)?
-- Is there a clear color hierarchy (primary action, secondary, muted)?
-- Are color relationships intentional or accidental?
-
-**Rams (good design)**:
-- Is the design honest? Does it promise only what it delivers?
-- Is it as little design as possible — less but better?
-- Could anything be removed without losing function?
-
-**Ive (craft)**:
-- Is there obsessive attention to detail (radii, shadows, weight, spacing)?
-- Does the digital surface feel considered, or thrown together?
-- Is there material honesty — do elements feel like what they are?
-
-**Kuznetsov (motion)** — if transitions/animations are present:
-- Do animations guide attention or just decorate?
-- Do state transitions convey meaning (loading, success, error)?
-- Is motion hierarchy clear (primary action animates, background stays still)?
-
-**Apple HIG (restraint)**:
-- Is there progressive disclosure, or is everything shown at once?
-- Is there visual clutter that could be removed?
-- Does the design show restraint and clarity?
-
-**Tufte (data display)** — if data is present:
-- Is the data-ink ratio high (minimal chartjunk)?
-- Are numbers formatted for scanning (aligned, consistent decimals)?
-- Is the most important data the most visually prominent?
-
-### Step 5.5: Prototype Drift Check (production UI only)
-
-When reviewing a production UI surface (not a prototype itself), diff
-the rendered production against the approved prototype referenced by
-the iteration goal or canvas. See
-`.claude/rules/prototype-production-coupling.md` §4.
-
-1. Locate the approved prototype for this surface — check the active
-   iteration goal's References block, or canvas under `docs/canvases/`,
-   for a `docs/prototypes/` path.
-2. If no prototype exists and the surface is user-visible: flag as a
-   finding ("prototype-production coupling rule §2 violation — no
-   prototype on file for this surface").
-3. If a prototype exists, render both and compare structurally:
-   - Layout: same regions, same hierarchy
-   - Affordances: same interaction targets, same visual weights
-   - Token fidelity: same color/spacing/type vocabulary
-4. Acceptable variances (call out with rationale):
-   - Responsive adaptation for viewport
-   - Real-data density shifts (more rows, truncation)
-   - Performance-driven simplifications (removed animations)
-5. Unacceptable (block merge as finding):
-   - Layout restructure
-   - Affordance changes (button → link, etc.)
-   - Hierarchy inversions
-   - Token substitutions not documented in an ADR
-
-Output: "Prototype drift: [none | minor (listed) | blocking (listed)]"
-
-### Step 6: Output Findings
-
-Write a structured report:
-
-```markdown
-## Visual Review: [page name / URL]
-
-**Screenshot**: [reference to saved file]
-**Date**: [today]
-**Reviewer**: Designer + Creative Director (automated)
-
-### Structural (accessibility snapshot)
-- [findings]
-
-### Usability Standard (8-point check)
-| Check | Result | Notes |
-|---|---|---|
-| 1. Role check | PASS/FAIL | |
-| ... | | |
-
-### Designer Findings
-- **Norman**: [findings]
-- **Cooper**: [findings]
-- **Krug**: [findings]
-
-### Creative Director Findings
-- **Lupton**: [findings]
-- **Albers**: [findings]
-- **Apple HIG**: [findings]
-- **Tufte**: [findings, if applicable]
-
-### Summary
-- **Critical** (must fix before merge): [list]
-- **Important** (should fix this iteration): [list]
-- **Minor** (log for future): [list]
-- **Positive** (what's working well): [list]
-
-### Verdict: PASS / PASS WITH NOTES / FAIL
-```
-
-## Luminary Separation — Creator vs. Evaluator
-
-When an iteration goal names a primary luminary, that luminary guided
-construction. Visual review must use **complementary luminaries** as
-evaluators — never grade your own homework.
-
-### Complement pairs
-
-| Primary (guided construction) | Evaluator (validates in visual review) | Tension |
-|---|---|---|
-| Norman (affordance) | Krug (simplicity) + Apple HIG (restraint) | "Is it obvious?" vs. "Is it too much?" |
-| Cooper (goals) | Norman (affordance) + Weinschenk (cognition) | "Right goal?" vs. "Right controls?" |
-| Krug (simplicity) | Cooper (goals) + Norman (affordance) | "Simple enough?" vs. "Complete enough?" |
-| Lupton (typography) | Tufte (data clarity) + Rams (honesty) | "Does it narrate?" vs. "Is it true?" |
-| Albers (color) | Heller (appropriateness) + Ive (craft) | "Does it work?" vs. "Does it feel right?" |
-| Tufte (data) | Lupton (hierarchy) + Rams (less but better) | "Shows the data?" vs. "Tells the story?" |
-| Prater (entity-derived) | Norman (affordance) + Morville (findability) | "Matches the model?" vs. "Users find it?" |
-| Morville (findability) | Prater (entity-derived) + Krug (simplicity) | "Can they find it?" vs. "Do they understand it?" |
-| Apple HIG (restraint) | Lupton (expression) + Walter (delight) | "Restrained enough?" vs. "Too sterile?" |
-| Rams (honesty) | Ive (craft) + Apple HIG (restraint) | "Honest?" vs. "Refined?" |
-| Material (systematic) | Apple HIG (restraint) + Tufte (data clarity) | "Systematic?" vs. "Necessary?" |
-| Tidwell (patterns) | Norman (affordance) + Cooper (goals) | "Proven pattern?" vs. "Right pattern for this goal?" |
-
-### How to apply
-
-1. Read the iteration goal's `primary_luminary:` field
-2. Look up the complement pair above
-3. In Step 4 (Designer Evaluation), weight the evaluator luminaries
-4. In Step 5 (Creative Director Evaluation), use the CD complement
-5. If no primary luminary is set, use all luminaries equally (default)
-
-The complement creates productive tension: the evaluator asks the questions
-the primary luminary wouldn't ask about their own approach.
-
-## Prototype Variant Evaluation
-
-When called during `/riff-prototypes`, visual review evaluates each
-variant and produces a **structured comparison** to inform the operator's
-selection. This replaces pure preference with evidence.
-
-### Procedure for prototype evaluation
-
-For each variant (2-3):
-1. Run the full visual review (Steps 1-5)
-2. Score each usability check (0-2: fail / partial / pass)
-3. Note which luminary principles are strongest and weakest
-4. Capture the variant's distinctive quality in one sentence
-
-Then produce a comparison:
-
-```markdown
-## Prototype Comparison
-
-| Criterion | Variant A (Norman) | Variant B (Lupton) | Variant C (Prater) |
-|---|---|---|---|
-| Usability score | 14/16 | 11/16 | 13/16 |
-| Strongest principle | Affordance clarity | Visual narrative | Domain coherence |
-| Weakest area | Visual storytelling | Tap target sizes | Discoverability |
-| Distinctive quality | "Every action is obvious" | "The page tells a story" | "Navigation mirrors the domain" |
-
-### Recommendation
-Based on the iteration goal's risk and value signals:
-- If retiring UX risk → [variant] scores highest on usability
-- If proving lovability → [variant] has strongest emotional quality
-- If proving viability → [variant] best serves the primary user goal
-
-**Recommended winner**: [variant] — [one sentence why]
-**Elements to carry from others**: [specific things worth keeping]
-```
-
-The operator makes the final call. The recommendation is evidence, not a decision.
-
-### What happens after selection
-
-1. Selected variant's luminary becomes `primary_luminary:` in iteration goal
-2. Complement pair is set for all subsequent visual reviews in this iteration
-3. `/ux-migration` runs next — gap analysis from prototype to production
-4. Construction builds the real thing, guided by the selected luminary
-5. Every UI commit during Construction triggers visual review with the complement evaluators
-
-## When to run this skill (MUST gate for UI changes)
-
-This skill is a **MUST gate** — not a suggestion — for these triggers:
-
-| Trigger | Gate level | Who invokes |
-|---|---|---|
-| Builder completes a UI change | **MUST** — blocks commit | Builder via /verify |
-| Prototype sprint variant evaluation | **MUST** — blocks selection | Designer |
-| Transition spot-check | **SHOULD** — logged if skipped | Creative Director |
-| Human requests it | **MUST** — explicit invocation | Anyone |
-
-**Evidence requirement**: Visual review produces a report file at
-`docs/visual-reviews/YYYY-MM-DD-{page-name}.md`. The pre-commit hook
-checks for this when UI files are staged. No report = warning.
-
-If Playwright MCP is unavailable, the agent MUST:
-1. State that Playwright MCP is not available
-2. Perform manual verification (tap targets, contrast, typography from code)
-3. Note "manual — no screenshot" in the report
-4. This is degraded mode, not a skip
-
-## Headless / CI Mode
-
-Visual review can run in headless environments (Docker, CI, staging) for
-automated pipeline verification. This extends the local-only default.
-
-### Environment detection
-
-At skill start, detect the environment:
-
-```bash
-# CI environment
-[ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ] || [ -n "$GITLAB_CI" ]
-
-# Docker / headless
-[ ! -d /tmp/.X11-unix ] && [ -z "$DISPLAY" ] && [ -z "$WAYLAND_DISPLAY" ]
-```
-
-### Headless Playwright configuration
-
-Playwright MCP runs headless by default — no display server needed. The
-screenshots are identical to headed mode. No special configuration required
-for headless operation.
-
-If running in Docker, ensure the container has:
-```dockerfile
-# Playwright dependencies
-RUN npx playwright install --with-deps chromium
-```
-
-### Targeting staging URLs
-
-Visual review can target any URL, not just localhost:
-
-```
-/visual-review https://staging.example.com/deals
-```
-
-When targeting staging:
-- Auth may differ — use staging credentials or service account
-- Data may differ — note in report: "Reviewed against staging data"
-- Network latency affects load times — increase wait timeouts
-- Never target production for automated reviews (read-only risk is low,
-  but the principle matters)
-
-### CI integration (GitHub Actions)
-
-Run visual review as a non-blocking PR check:
-
-```yaml
-# .github/workflows/visual-review.yml
-name: Visual Review
-on: [pull_request]
-
-jobs:
-  visual-review:
-    runs-on: ubuntu-latest
-    if: contains(github.event.pull_request.labels.*.name, 'ui-change')
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install dependencies
-        run: npm ci && npx playwright install --with-deps chromium
-
-      - name: Start dev server
-        run: npm run dev &
-        env:
-          PORT: 3000
-
-      - name: Wait for server
-        run: npx wait-on http://localhost:3000 --timeout 30000
-
-      - name: Run visual review
-        run: npx claude -p "/visual-review http://localhost:3000"
-        continue-on-error: true  # non-blocking initially
-
-      - name: Upload screenshots
-        uses: actions/upload-artifact@v4
-        with:
-          name: visual-review-screenshots
-          path: docs/visual-reviews/
-          if-no-files-found: warn
-```
-
-### PR artifact screenshots
-
-Screenshots are saved as PR artifacts for human review. The report
-references them:
-
-```markdown
-### Screenshots
-- Desktop (1280px): [artifact: visual-review-screenshots/desktop.png]
-- Mobile (375px): [artifact: visual-review-screenshots/mobile.png]
-```
-
-In CI, these are downloadable from the Actions run. In local review,
-they're at `docs/visual-reviews/`.
-
-### Blocking vs. non-blocking
-
-| Phase | Gate level | Recommended |
-|-------|-----------|------------|
-| Initial adoption | Non-blocking (continue-on-error) | Learn what it catches without blocking PRs |
-| After 2 weeks | Blocking for FAIL verdicts | FAIL = broken layout, not style nits |
-| Mature | Blocking for FAIL + PASS WITH NOTES | Full gate enforcement |
-
-Start non-blocking. Promote to blocking after the team trusts the verdicts.
-
-### Environment requirements summary
-
-| Environment | Display | Server | Auth | Notes |
-|-------------|---------|--------|------|-------|
-| Local dev | Headed or headless | localhost:3000 | Dev credentials | Default mode |
-| Docker | Headless | localhost:PORT | Dev credentials | Install playwright deps |
-| CI (GitHub Actions) | Headless | localhost:PORT | Dev credentials | Upload artifacts |
-| Staging | Headless | staging URL | Staging credentials | Note in report |
-| Production | Not recommended | — | — | Use staging instead |
-
-## What this skill does NOT do
-
-- Interactive flow testing (clicking through multi-step flows) — see /visual-qa
-- Design token generation — that's the Creative Director's job
-- Implementation fixes — flag issues, don't fix them
-
-## Output discipline
-
-Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.