1# Project Instructions for Claude
  2
  3## Skill bootstrap: skip the post-update-cleanup step
  4
  5The `<post-update-cleanup>` block at the top of `.claude/skills/impeccable/SKILL.md` runs `scripts/cleanup-deprecated.mjs` and then self-deletes. **Do not run it in this repo, and do not delete the block.** This repo is the source of truth for the Impeccable skill; the cleanup script scans for "leftover" skill files to remove and its judgment doesn't fit a repo where the skill lives in `skill/`. The block is also regenerated from `skill/SKILL.md` on every `bun run build`, so any deletion churns back on the next build. Skip the step silently and proceed.
  6
  7Same rule for AGENTS.md and every other harness-specific instruction file: treat post-update-cleanup as a no-op in this repo.
  8
  9## Architecture (v3.0+)
 10
 11There is **one** user-invocable skill, `impeccable`, with **23 commands** underneath it. Users type `/impeccable polish`, `/impeccable audit`, etc. The skill is defined in `skill/`:
 12
 13- `SKILL.md` — frontmatter (with the auto-trigger-optimized description and the `allowed-tools` list), shared design laws, and the **Commands** router table.
 14- `reference/` — one `<command>.md` per command (`audit.md`, `polish.md`, `critique.md`, etc.) plus the domain reference files (`typography.md`, `color-and-contrast.md`, etc.). When a sub-command is matched, the router loads its reference file.
 15- `reference/brand.md` and `reference/product.md` — the two register references. SKILL.md's Setup section selects one based on the task cue, the surface in focus, or the `register` field in PRODUCT.md (first match wins).
 16- `scripts/command-metadata.json` — single source of truth for each command's description, argument hint, and (eventually) category. Both the build and `pin.mjs` read from this.
 17- `scripts/pin.mjs` — creates/removes lightweight redirect shims so users can have `/audit` as a standalone shortcut that delegates to `/impeccable audit`.
 18- `scripts/cleanup-deprecated.mjs` — runs once after an update to remove leftover files from renamed/merged commands.
 19
 20**Do not add standalone skills** unless there's a strong reason. The consolidation was deliberate: the `/` menu pollution problem is real and gets worse as users install more plugins.
 21
 22### Register (brand vs product)
 23
 24Every design task belongs to one of two registers:
 25
 26- **Brand** — design IS the product: marketing, landing pages, brand sites, campaign surfaces, portfolios, long-form content. Distinctiveness is the bar. Spans every visual lane (tech-minimal, luxury, editorial-magazine, consumer-warm, brutalist, etc.) — do not default to only one.
 27- **Product** — design SERVES the product: app UI, admin, dashboards, tools. Earned familiarity is the bar — fluent users of Linear / Figma / Notion / Raycast / Stripe should trust it.
 28
 29PRODUCT.md at the project root carries a `## Register` section with a bare value (`brand` or `product`). `/impeccable teach` asks about register first because it shapes every downstream answer.
 30
 31Sub-command reference files add a short `## Register` section near the top *only where the answer diverges between the two*. Don't restate the register files' content in sub-commands — link instead. Sub-commands where register meaningfully diverges today: `typeset`, `animate`, `bolder`, `delight`, `colorize`, `layout`, `quieter`.
 32
 33**a11y lives in `audit.md`**, not in SKILL.md, `brand.md`, or `product.md`. Models over-cautious themselves into safe, underdesigned output when reminded about accessibility at design time. The audit command is the dedicated place for that check.
 34
 35## CSS
 36
 37Plain hand-written CSS, no Tailwind. Imported into Astro pages/layouts via frontmatter `import` statements; Vite resolves `@import` chains automatically.
 38
 39The CSS architecture (under `site/styles/`):
 40- `main.css` — Main entry point, imports the partials and defines tokens/reset
 41- `workflow.css` — Commands section, glass terminal, magazine spread styles
 42- `sub-pages.css` — `/docs`, `/anti-patterns`, `/tutorials`, detail pages
 43- `tokens.css` — OKLCH color tokens (ink, charcoal, ash, mist, cream, accent)
 44- `footer.css` — shared across all pages, imported in `Base.astro`
 45
 46Edit any of these directly and the dev server hot-reloads. No rebuild needed for CSS changes.
 47
 48## Color token rule
 49
 50- **`--color-ink`** (10% lightness) is for body copy. Use it even for small text.
 51- **`--color-charcoal`** (25% lightness) reads as washed-out gray in small text. Only use for headings or larger body copy at ≥16px.
 52- **`--color-ash`** (55%) is for secondary labels, captions, relationship meta lines.
 53- **Never use pure black or pure white.** Use the tinted tokens.
 54
 55## Prose: read STYLE.md before writing user-facing copy
 56
 57Editorial brief is at `STYLE.md` (root). Read it before editing the homepage, sub-pages, command editorials, tutorials, or READMEs. The site has been called out for AI prose; the rules there exist to keep that from creeping back.
 58
 59The build's `validateProse` step (in `scripts/build.js`) enforces a denylist: em dashes (`—` and HTML entities), the `--` em-dash substitute, `load-bearing`, `highest-leverage`, `biggest unlock`, `seamless`, `robust`, `delve`, `elevate`, `empower`, `underscore`, `pivotal`, `tapestry`, `data-driven`, `reflex defaults`, `collapses into monoculture`, `in today's`, `gone are the days`, `whether you're`, `let's dive in`, `in summary`, `in conclusion`, `moreover`, `furthermore`. Each rule prints a rationale and a suggested replacement when it fires. **Do not silently work around the regex.** If a banned word has earned a real meaning here, raise it as a STYLE.md amendment.
 60
 61The validator scans `site/pages/`, `site/content/`, `site/components/`, `site/layouts/`, `README.md`, `README.npm.md`. It deliberately skips `skill/` because LLM-facing reference instructions sometimes need technical phrasings the marketing copy can't.
 62
 63The deeper structural issues (negation pivot, triadic auto-pilot, uniform paragraph rhythm, hollow confidence) require human judgment. STYLE.md lists them. Use them on every editorial pass.
 64
 65## Editorial content lives under `site/content/`
 66
 67Skill editorials and tutorials are read by `scripts/build.js` (for taglines and downstream tooling) and by Astro's content collection (for what actually renders on the site). One tree, one place to edit:
 68- `site/content/skills/<id>.md` — optional editorial wrapper with frontmatter `tagline` plus body sections
 69- `site/content/tutorials/<slug>.md` — full tutorial content
 70- `site/data/anti-patterns-catalog.js` — detection-rule catalog (visual examples, gallery items, layer definitions)
 71
 72## Development Server
 73
 74```bash
 75bun run dev        # Bun dev server at http://localhost:3000
 76bun run preview    # Build + Cloudflare Pages local preview
 77```
 78
 79The dev server runs Astro (`astro dev`). Editing files in `site/content/skills/`, `skill/`, or `scripts/lib/sub-pages-data.js` requires a **server restart** (not just a browser reload) to see the change. CSS, components, and pages hot-reload fine without a restart.
 80
 81**Legacy URL redirects** are emitted to `_redirects` by `scripts/build.js` (via `generateCFConfig`); the dynamic `/skills/:id → /docs/:id` redirect lives in `site/public/_redirects` (Cloudflare Pages reads both at deploy). Current redirects: `/skills` → `/docs`, `/skills/:id` → `/docs/:id`, `/cheatsheet` → `/docs`, `/gallery` → `/visual-mode#try-it-live`.
 82
 83## Deployment
 84
 85Hosted on Cloudflare Pages. Static assets served from `build/`, API routes handled via `_redirects` rewrites (JSON) and Pages Functions (downloads).
 86
 87```bash
 88bun run deploy     # Build + deploy to Cloudflare Pages
 89```
 90
 91## Build System
 92
 93The build system compiles the impeccable skill from `skill/` to provider-specific formats in `dist/`:
 94
 95```bash
 96bun run build      # Build all providers
 97bun run rebuild    # Clean and rebuild
 98```
 99
100Source files use placeholders that get replaced per-provider:
101- `{{model}}` — Model name (Claude, Gemini, GPT, etc.)
102- `{{config_file}}` — Config file name (CLAUDE.md, .cursorrules, etc.)
103- `{{ask_instruction}}` — How to ask user questions
104- `{{command_prefix}}` — `/` or `$` depending on provider
105- `{{available_commands}}` — auto-populated list of commands (from `IMPECCABLE_SUB_COMMANDS` in `scripts/lib/utils.js`)
106- `{{scripts_path}}` — provider-aware path to the skill's scripts directory
107
108### Harness output directories are tracked
109
110`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`, and the other 8 harness directories are **intentionally committed to the repo**. `npx skills` reads them directly from this repo at install time, and they enable clean submodule use. Do not gitignore them. Run `bun run build` to refresh them after editing `skill/`.
111
112Local state files inside harness directories (e.g. `.claude/scheduled_tasks.lock`, `.claude/settings.local.json`) ARE gitignored.
113
114### Generated sub-pages are gitignored
115
116`site/public/docs/`, `site/public/anti-patterns/`, `site/public/tutorials/`, `site/public/visual-mode/`, `site/public/slop/` are gitignored as legacy generator output paths. Astro's content collections drive the live site under `site/pages/docs/`, `site/pages/tutorials/`, etc.; nothing reads from those gitignored dirs anymore.
117
118## Testing
119
120```bash
121bun run test            # Default suite: unit + static framework fixtures
122bun run test:live-e2e   # Opt-in: full-cycle live-mode E2E across framework fixtures
123```
124
125Unit tests (build orchestration, detector logic) run via `bun test`. Fixture tests (jsdom-based HTML detection) run via `node --test` because bun is too slow with jsdom. The `test` script handles this split automatically.
126
127**Important:** `tests/build.test.js` uses `spyOn(transformers, 'transformCursor')` with the named exports from `scripts/lib/transformers/index.js`. Those named exports (`transformCursor`, `transformClaudeCode`, etc.) are kept specifically for test spying, even though `build.js` itself uses `createTransformer + PROVIDERS` directly. **Do not delete them as "dead code"** — I made that mistake once and broke 8 tests.
128
129### Live-mode E2E
130
131`tests/live-e2e.test.mjs` drives the entire user flow (handshake → pick → Go → cycle → accept → carbonize cleanup) against every fixture in `tests/framework-fixtures/` that declares a `runtime` block. Each fixture installs real deps, boots its framework dev server (Vite, Next, SvelteKit, Astro, Nuxt static), and runs Playwright Chromium against a deterministic fake agent that produces realistic variants in the exact format `reference/live.md` describes.
132
133```bash
134bun run test:live-e2e                                       # full suite, ~2 min, 19 fixtures
135IMPECCABLE_E2E_ONLY=vite8-react-modal bun run test:live-e2e # scope to one fixture
136IMPECCABLE_E2E_DEBUG=1 bun run test:live-e2e                # dump page DOM + dev-server tail on failure
137```
138
139**One-time setup**: `npx playwright install chromium` (the suite uses a specific Chromium build keyed to the bundled Playwright version).
140
141**Kept out of the default `bun run test`** because (a) it does real `npm install` per fixture, (b) it boots framework dev servers, (c) wall time is ~2 minutes, and (d) it requires Playwright's browser cache. Run it locally before shipping changes to anything in `skill/scripts/live-*.{mjs,js}`.
142
143The agent is pluggable via a one-method interface in `tests/live-e2e/agent.mjs`: `generateVariants(event, context) → { scopedCss, variants[] }`. The default fake agent emits canned variants that exercise all three param kinds (`range`, `steps`, `toggle`). The orchestrator (wrap, write, accept, carbonize) is agent-agnostic.
144
145**LLM agent (opt-in)**: set `IMPECCABLE_E2E_AGENT=llm` to swap the fake agent for `tests/live-e2e/agents/llm-agent.mjs`, which calls Claude (default Haiku 4.5) via `@anthropic-ai/sdk`. Requires `ANTHROPIC_API_KEY` in env; the test runner skips with a clear message when it's unset. Override the model with `IMPECCABLE_E2E_LLM_MODEL=claude-sonnet-4-6` if Haiku produces unreliable JSON. Caching is on — live.md is the cacheable prefix, and after the first call subsequent fixtures pay only the cache-read rate. Pass rate on a typical sweep is 18/19; the modal fixture's intrinsic state-loss flake is amplified by LLM latency and may need a re-run. **This path hits the API and costs money** — keep it out of CI unless you really want it there.
146
147Adding a new fixture is a matter of cloning a directory under `tests/framework-fixtures/`, swapping the source files, and writing a `fixture.json`. See `tests/framework-fixtures/README.md` for the full schema.
148
149## CLI
150
151The CLI lives in this repo under `cli/`: `cli/bin/` (entry + sub-commands), `cli/engine/` (the detect-antipatterns rule engine + browser variant), `cli/lib/` (helpers shared by CLI and Cloudflare Pages Functions). Published to npm as `impeccable`.
152
153```bash
154npx impeccable detect [file-or-dir-or-url...]   # detect anti-patterns
155npx impeccable detect --fast --json src/         # regex-only, JSON output
156npx impeccable live                              # start browser overlay server
157npx impeccable skills install                    # install skills
158npx impeccable --help                            # show help
159```
160
161The browser detector (`cli/engine/detect-antipatterns-browser.js`) is generated from the main engine. After changing `cli/engine/detect-antipatterns.mjs`, rebuild it:
162
163```bash
164bun run build:browser
165```
166
167**IMPORTANT**: Always use `node` (not `bun`) to run the detect CLI. Bun's jsdom implementation is extremely slow and will cause scans with HTML files to hang for minutes.
168
169## Versioning
170
171There are three independently versioned components. Only bump the one(s) that actually changed:
172
173**CLI** (npm package):
174- `package.json` → `version`
175- Bump when: CLI code changes (`cli/bin/`, `cli/engine/detect-antipatterns.mjs`, etc.)
176
177**Skills** (Claude Code plugin / skill definitions):
178- `.claude-plugin/plugin.json` → `version`
179- `.claude-plugin/marketplace.json` → `plugins[0].version`
180- Bump when: skill content changes (`skill/`, reference files, command metadata, etc.)
181
182**Chrome extension**:
183- `extension/manifest.json` → `version`
184- Bump when: extension code changes (`extension/`)
185
186**Website changelog** (`site/pages/index.astro`):
187- Hero version link text + new changelog entry in the changelog section
188- Update for user-facing changes only, not internal build/tooling details
189- Use the most prominent version that changed (skills version is usually the right one)
190
191After bumping, see **Releases** below for how to tag and publish.
192
193## Releases
194
195GitHub releases are tagged per-component, not per-version, since the three components ship independently. Tag prefixes: `skill-v`, `cli-v`, `ext-v`.
196
197Workflow for any component:
198
1991. Bump the manifest version (see Versioning above).
2002. Add a changelog entry to `site/pages/index.astro`. Skill entries use a bare `vX.Y.Z` label; CLI and extension entries use the prefixed forms `CLI vX.Y.Z` and `Extension vX.Y.Z`. The release script extracts notes by matching this label, so the prefix matters.
2013. Commit and push to `main`.
2024. Run `bun run release:<skill|cli|ext>`. Preview first with `node scripts/release.mjs <component> --dry-run`.
203
204The script refuses to run if: the working tree is dirty, HEAD is ahead of origin, the tag already exists, the matching changelog entry is missing, or (for skill/extension) `bun run build` / `bun run build:extension` produces uncommitted changes — meaning the harness output dirs or `extension/detector/` files weren't refreshed before the bump was committed.
205
206Skill releases attach `dist/universal.zip`. Extension releases run `bun run build:extension` first and attach `dist/extension.zip`. CLI releases print a reminder to run `npm publish` separately; extension releases print a reminder to upload the zip to the Chrome Web Store dashboard.
207
208If you need to fix release notes after the fact (typo, missing thank-you, formatting bug): `gh release edit <tag> --notes-file <md>`. The release script's `htmlToMarkdown` function is the cleanest source for regenerating notes from the changelog.
209
210## Adding New Commands
211
212All commands live under `/impeccable`. To add a new one:
213
2141. Create `skill/reference/<command>.md` with the command's instructions (this is what the LLM loads when the command is invoked)
2152. Add a row to the **Sub-command reference table** in `skill/SKILL.md`
2163. Add an entry to the **Command menu** section in the same file
2174. Add the command name to `IMPECCABLE_SUB_COMMANDS` in `scripts/lib/utils.js`
2185. Add it to `VALID_COMMANDS` in `skill/scripts/pin.mjs`
2196. Add its metadata (description + argumentHint) to `skill/scripts/command-metadata.json`
2207. Add its category to `SKILL_CATEGORIES` in `scripts/lib/sub-pages-data.js`
2218. Add its relationships (leadsTo / pairs / combinesWith) to `COMMAND_RELATIONSHIPS` in the same file
2229. Add the same category entry to `site/scripts/data.js` `commandCategories` and `commandProcessSteps` (for the homepage carousel)
22310. Add symbol + number to `commandSymbols` and `commandNumbers` in `site/scripts/components/framework-viz.js` (periodic table)
22411. Optional: write an editorial wrapper at `site/content/skills/<command>.md` with a short `tagline` and expanded body (When to use it / How it works / Try it / Pitfalls)
225
226The build system counts commands from the router table automatically. Update the command count in **all** of these locations when the total changes:
227
228- `site/pages/index.astro` — meta descriptions, hero box, section lead
229- `/cheatsheet` redirects to `/docs` (no standalone page)
230- `README.md` — intro, command count, commands table
231- `NOTICE.md` — command count
232- `AGENTS.md` — intro command count
233- `.claude-plugin/plugin.json` — description
234- `.claude-plugin/marketplace.json` — metadata description + plugin description
235
236The build validator (`generateCounts` in `scripts/build.js`) checks these files for stale numeric counts and fails the build if any disagree with the router table.
237
238## Adding editorial content for existing commands
239
240Editorial files live at `site/content/skills/<command>.md` and have a `tagline` frontmatter plus a body with the standard four sections:
241
242- **When to use it** — the specific scenarios this command owns
243- **How it works** — the internal process, phases, or approach
244- **Try it** — one or two concrete examples with expected output
245- **Pitfalls** — real failure modes, with alternatives to reach for instead
246
247The tagline is used by UI surfaces (magazine spread, docs cards) that need a short human-friendly label. The long description in `command-metadata.json` stays optimized for auto-trigger keyword matching in the AI harness.
248
249Every command should have an editorial file eventually, but the build does not require one: commands without editorials fall back to the frontmatter description.
250
251## Adding or modifying anti-pattern detection rules
252
253`cli/engine/detect-antipatterns.mjs` is the source of truth for the rule engine. It powers the CLI, the public-site overlay, the Chrome extension, and the homepage rule count. Five places stay in sync:
254
255| Where | How it stays in sync |
256|---|---|
257| `cli/engine/detect-antipatterns.mjs` (`ANTIPATTERNS` array + `checkXxx` logic) | Hand-edited |
258| `cli/engine/detect-antipatterns-browser.js` | `bun run build:browser` |
259| `extension/detector/detect.js` + `extension/detector/antipatterns.json` | `bun run build:extension` |
260| `site/public/js/generated/counts.js` (`DETECTION_COUNT`) | `bun run build` |
261| `skill/SKILL.md` and `reference/*.md` | Hand-edited if the rule introduces new design guidance |
262
263Always run all three builds and the test suite after a rule change:
264
265```bash
266bun run build && bun run build:browser && bun run build:extension && bun run test
267```
268
269### TDD order (non-negotiable)
270
2711. **Fixture** at `tests/fixtures/antipatterns/{rule-id}.html` with two columns (should-flag / should-pass), each case identified by a unique heading. Cover ≥4 flag cases and ≥5 false-positive shapes. Use **explicit pixel dimensions in CSS** because jsdom does no layout.
2722. **Failing test** in `tests/detect-antipatterns-fixtures.test.mjs` using the snippet-substring pattern (regex `/"([^"]+)"/` against `SHOULD_FLAG` / `SHOULD_PASS` lists). Run it and watch it fail before implementing.
2733. **Rule entry** in the `ANTIPATTERNS` array: `id`, `category` (`slop` for AI tells, `quality` for real design or a11y issues), `name`, `description`, optional `skillSection` and `skillGuideline`.
2744. **Pure check function** `checkXxx(opts)` returning `[{ id, snippet }]`. No DOM access in the pure function.
2755. **Two adapters**: `checkElementXxxDOM(el)` for the browser (`getComputedStyle` + `getBoundingClientRect`) and `checkElementXxx(el, tag, window)` for jsdom (`parseFloat(style.width)` instead of layout). Wire **both** into **both** element loops in `cli/engine/detect-antipatterns.mjs` — the browser loop (~line 1837) and the jsdom loop in `detectHtml` (~line 2058). Forgetting one is the most common mistake; symptom is "test passes, live page silent" or vice versa.
2766. **Verify on a live page**: `http://localhost:3000/fixtures/antipatterns/{rule-id}.html` and the homepage (no false positives). The two adapter paths can disagree, so manual browser checks catch what the fixture test can't.
277
278### Conventions and jsdom gotchas
279
280- **Snippet format**: wrap the identifying heading text in straight double quotes (e.g. `'icon tile above h3 "Lightning Fast"'`) so the fixture test can extract it. For rules not anchored to a heading, pick another stable identifier.
281- **jsdom doesn't lay out**: `getBoundingClientRect()` returns 0×0. Read `parseFloat(style.width)` and `parseFloat(style.height)` from explicit CSS instead.
282- **`background:` shorthand isn't decomposed in jsdom**: use the existing `resolveBackground()` and `resolveGradientStops()` helpers (~line 631 / 670).
283- **Computed colors aren't normalized in jsdom**: `parseGradientColors()` handles both hex and rgb forms.
284
285Reference rules to copy from: `side-tab` (border, ~line 312), `low-contrast` (color + gradient, ~line 339), `icon-tile-stack` (sibling relationship, ~line 425), `flat-type-hierarchy` (page-level, ~line 1080).
286
287## Evals Framework (separate private repo)
288
289The eval framework lives in a separate private repo at `~/code/impeccable-evals/`. It measures whether the `/impeccable` skill improves or harms AI-generated frontend design by running the same brief through a model with and without the skill loaded.
290
291**If you're picking up eval work, switch to that repo and read its `AGENT.md` first.** It captures model choices, sample size policy, lessons learned, common workflows, and gotchas.
292
293```bash
294cd ~/code/impeccable-evals
295bun run serve            # dashboard on http://localhost:8723
296```
297
298The eval runners read this repo's skill from `../impeccable/skill/` and staged provider skills from `../impeccable/build/_data/dist/*`. Run `bun run build` in this repo before an eval sweep if you want the Claude/Gemini staged skills to reflect your latest edits.
299
300### After structural skill changes, update `inline-skill.ts` in the evals repo
301
302The harness inlines `SKILL.md` into the system prompt for "skill-on", stripping sections irrelevant to an API-driven craft run. The stripped list in `runner/inline-skill.ts` needs to stay in sync with `SKILL.md`'s top-level `##` headings. As of v3.0, it should strip `## Setup (non-optional)` (was `## Context Gathering Protocol`), `## Commands` (was `## Command Router`), and `## Pin / Unpin`. Keep `## Shared design laws`. If you add or rename a top-level section, update the strip list there.