# Impeccable Documentation

> Technical reference for Impeccable: the `/impeccable` design skill (23 commands), multi-harness installer, deterministic anti-pattern detector CLI and browser extension, live browser iteration, project artifacts, and contributor build/test surfaces.

## Context Links

- [Agent index](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms.txt)
- [Human interactive docs](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4)
- [GitHub repository](https://github.com/pbakaus/impeccable)

## Repository Metadata

- Repository: pbakaus/impeccable

- Generated: 2026-08-05T07:51:10.999Z
- Updated: 2026-08-05T07:51:21.022Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 24

## Page Index

- 01. [Overview](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/01-overview.md) - What Impeccable exposes (skill, CLI detector, extension, live mode), runtime assumptions, and the shortest path from install to first successful command.
- 02. [Installation](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/02-installation.md) - Install paths for npx install/link/update, plugin install, submodule link, provider selection, scope (project vs global), and hook consent constraints.
- 03. [Quickstart](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/03-quickstart.md) - First successful session: install skills, run `/impeccable init`, load context via context.mjs, run a scoped design command, and optionally scan with detect.
- 04. [Modes and platform](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/04-modes-and-platform.md) - Visitor modes (Persuade, Operate, Read, Experience) and orthogonal platform values (web, ios, android, adaptive), including defaults, native reference loading, and web-only live/detect boundaries.
- 05. [Project artifacts](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/05-project-artifacts.md) - PRODUCT.md, DESIGN.md, design.json sidecar, surface briefs, `.impeccable/` layout, schema stamps, deprecated sections, and context resolution order.
- 06. [Commands and routing](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/06-commands-and-routing.md) - Single `/impeccable` skill, 23 sub-commands, Setup load order, no-argument routing, craft-floor gate, and when native command variants replace web references.
- 07. [Provider harnesses](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/07-provider-harnesses.md) - Supported AI harness directories, install aliases, frontmatter and hook capability matrix, and provider-specific trust or skills-enable steps.
- 08. [Initialize product context](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/08-initialize-product-context.md) - Run init to interview and write PRODUCT.md (including Platform), optionally document DESIGN.md from code, configure live when useful, and verify completion gates.
- 09. [Run design commands](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/09-run-design-commands.md) - Invoke evaluate and refine commands (audit, critique, polish, harden, layout, typeset, and related) with targets, expected artifacts, and verification signals.
- 10. [Live browser iteration](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/10-live-browser-iteration.md) - Start live mode, poll contract, generate/accept/discard/steer/manual-edit events, carbonize cleanup, roots resolution, and web-only platform constraints.
- 11. [Design hook](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/11-design-hook.md) - Provider-native edit hooks that scan writes for detector findings, intentional-finding workflow, quiet/disabled controls, and native-platform skip behavior.
- 12. [Pin shortcuts](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/12-pin-shortcuts.md) - Create and remove standalone harness shortcuts (for example `/audit`) that redirect to `/impeccable <command>` across discovered skill directories.
- 13. [Manage detector ignores](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/13-manage-detector-ignores.md) - Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config, including value scoping, reasons, and inline disable comments.
- 14. [CLI reference](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/14-cli-reference.md) - Commands for detect, ignores, install, link, update, check, and help: flags, defaults, exit codes, JSON output, URL scanning, and detect shorthand targets.
- 15. [Skill commands reference](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/15-skill-commands-reference.md) - Catalog of `/impeccable` sub-commands with argument hints, categories, reference files, and native variants for audit and adapt.
- 16. [Detector rules](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/16-detector-rules.md) - Deterministic rule registry: ids, slop vs quality categories, advisory rules, scopes, engines (jsdom, browser, regex), and finding shape for CLI and extension.
- 17. [Configuration reference](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/17-configuration-reference.md) - `.impeccable/config.json` and `config.local.json` keys for detector, hook, live, update, and staleness settings, plus live config.json fields and hard path excludes.
- 18. [Environment variables](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/18-environment-variables.md) - Documented IMPECCABLE_* and related env vars for context dir, update host/cache, live config, hook quiet/disable/depth/log, telemetry opt-out, and OpenCode config dirs.
- 19. [Plugin agents](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/19-plugin-agents.md) - Bundled finish-reviewer, documenter, asset-producer, and manual-edit-applier agents, plugin manifest contract, and hooks packaged for Claude Code and Grok plugin installs.
- 20. [Live framework recipes](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/20-live-framework-recipes.md) - Copy-paste live config shapes and adapter notes for Vite, Next.js, Nuxt, SvelteKit, TanStack, Astro, multipage, and CSP-aware fixtures under tests/framework-fixtures.
- 21. [Detect in CI](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/21-detect-in-ci.md) - Run impeccable detect non-interactively with --json/--quiet/--scope, interpret exit codes 0 and 2, apply project ignores, and wire optional Puppeteer URL scans.
- 22. [Doctor](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/22-doctor.md) - Run doctor for schema, config, and proxy truth-drift findings; apply auto fixes; route mention and route severities; opt out of boot staleness checks.
- 23. [Build and test](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/23-build-and-test.md) - Source-first vs release builds, browser and extension bundles, default and opt-in test suites (live-e2e, skill-behavior, plugin-e2e), and suite trigger mapping.
- 24. [Contributing](https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/24-contributing.md) - Source-of-truth layout under skill/, generated harness policy, issue-first PR rules, anti-pattern TDD order, and component release tags (skill-v, cli-v, ext-v).

## Source File Index

- `.claude-plugin/plugin.json`
- `AGENTS.md`
- `cli/bin/cli.js`
- `cli/bin/commands/ignores.mjs`
- `cli/bin/commands/skills.mjs`
- `cli/engine/cli/main.mjs`
- `cli/engine/detect-antipatterns.mjs`
- `cli/engine/engines/regex/detect-text.mjs`
- `cli/engine/engines/static-html/detect-html.mjs`
- `cli/engine/findings.mjs`
- `cli/engine/registry/antipatterns.mjs`
- `cli/engine/rules/checks.mjs`
- `cli/engine/shared/inline-ignores.mjs`
- `cli/lib/impeccable-config.mjs`
- `docs/adr-live-variant-mode.md`
- `docs/DEVELOP.md`
- `docs/HARNESSES.md`
- `docs/STYLE.md`
- `package.json`
- `plugin/hooks/hooks.json`
- `PRODUCT.md`
- `README.md`
- `README.npm.md`
- `scripts/benchmark-detector.mjs`
- `scripts/build.js`
- `scripts/lib/skill-categories.js`
- `scripts/lib/transformers/providers.js`
- `scripts/lib/utils.js`
- `scripts/lib/validate-plugin-manifest.js`
- `scripts/release.mjs`
- `scripts/run-tests.mjs`
- `scripts/test-suites.mjs`
- `skill/agents/impeccable-asset-producer.md`
- `skill/agents/impeccable-documenter.md`
- `skill/agents/impeccable-finish-reviewer.md`
- `skill/agents/impeccable-manual-edit-applier.md`
- `skill/reference/adapt.native.md`
- `skill/reference/android.md`
- `skill/reference/audit.md`
- `skill/reference/audit.native.md`
- `skill/reference/craft-floor.md`
- `skill/reference/critique.md`
- `skill/reference/doctor.md`
- `skill/reference/document.md`
- `skill/reference/hooks.md`
- `skill/reference/init.md`
- `skill/reference/ios.md`
- `skill/reference/live-setup.md`
- `skill/reference/live.md`
- `skill/reference/new-work.md`
- `skill/reference/operate.md`
- `skill/reference/polish.md`
- `skill/reference/routing.md`
- `skill/scripts/command-metadata.json`
- `skill/scripts/concept-seed.mjs`
- `skill/scripts/context-signals.mjs`
- `skill/scripts/context.mjs`
- `skill/scripts/critique-storage.mjs`
- `skill/scripts/detect-csp.mjs`
- `skill/scripts/doctor.mjs`
- `skill/scripts/hook-before-edit.mjs`
- `skill/scripts/hook-lib.mjs`
- `skill/scripts/hook.mjs`
- `skill/scripts/lib/artifact-schema.mjs`
- `skill/scripts/lib/design-parser.mjs`
- `skill/scripts/lib/impeccable-paths.mjs`
- `skill/scripts/lib/provider.mjs`
- `skill/scripts/lib/staleness-deep.mjs`
- `skill/scripts/lib/staleness-notice.mjs`
- `skill/scripts/lib/staleness.mjs`
- `skill/scripts/lib/surface-briefs.mjs`
- `skill/scripts/live-accept.mjs`
- `skill/scripts/live-server.mjs`
- `skill/scripts/live-wrap.mjs`
- `skill/scripts/live.mjs`
- `skill/scripts/live/frameworks/index.mjs`
- `skill/scripts/live/frameworks/nextjs.mjs`
- `skill/scripts/live/frameworks/sveltekit.mjs`
- `skill/scripts/live/roots.mjs`
- `skill/scripts/pin.mjs`
- `skill/SKILL.src.md`
- `tests/build.test.js`
- `tests/cli-ignores.test.js`
- `tests/detect-antipatterns-fixtures.test.mjs`
- `tests/doctor.test.mjs`
- `tests/framework-fixtures/README.md`
- `tests/inline-ignores.test.mjs`
- `tests/lib/impeccable-config.test.js`
- `tests/live-e2e.test.mjs`
- `tests/pin.test.mjs`
- `tests/skill-behavior/README.md`
- `tests/staleness.test.mjs`

---

## 01. Overview

> What Impeccable exposes (skill, CLI detector, extension, live mode), runtime assumptions, and the shortest path from install to first successful command.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/01-overview.md
- Generated: 2026-08-05T07:34:10.977Z

### Source Files

- `package.json`
- `README.md`
- `README.npm.md`
- `skill/SKILL.src.md`
- `cli/bin/cli.js`
- `PRODUCT.md`

---
title: "Overview"
description: "What Impeccable exposes (skill, CLI detector, extension, live mode), runtime assumptions, and the shortest path from install to first successful command."
---

Impeccable is a multi-surface design toolkit for AI coding agents: one invocable skill (`impeccable`) with 23 sub-commands, a deterministic anti-pattern detector (59 rules) published as the `impeccable` npm CLI and a Chrome extension, plus optional live browser iteration and provider-native edit hooks. Components version independently (CLI package, skill/plugin, extension). The open-source product lives in this repository; hosted catalog and site services are separate.

## Surfaces

| Surface | Entry | What it does | LLM required |
|---------|-------|--------------|--------------|
| Skill | `/impeccable <command> [target]` (or provider equivalent) | Setup, craft/evaluate/refine/enhance design work, pin shortcuts, hooks admin, doctor | Yes (runs inside a harness) |
| CLI | `npx impeccable <command>` | Install/link/update skills; `detect` scans files/URLs; `ignores` manages suppressions | No for detect |
| Chrome extension | Manifest V3 popup / DevTools panel | Runs the browser detector against the open page | No |
| Live mode | `/impeccable live` + `skill/scripts/live*.mjs` | Browser pick → generate/accept variants against a running app | Yes (agent drives poll loop) |
| Design hook | Provider hook manifests + `hook.mjs` / `hook-before-edit.mjs` | Scans UI writes for detector findings | No (post/pre tool) |

```text
User project
├── PRODUCT.md / DESIGN.md / .impeccable/     # durable context & config
├── <harness>/.skills/impeccable/            # installed skill + scripts
│
├── AI harness ──► /impeccable * ──► context.mjs + reference/*.md
│                      │
│                      ├─ design commands (audit, polish, …)
│                      ├─ live (web only)
│                      └─ hooks / doctor / pin
│
└── npx impeccable ──► detect | install | link | update | ignores
                              │
                   Chrome ext ─┘  shared rule registry (59)
```

### Skill (`impeccable`)

Source of truth: `skill/SKILL.src.md` and `skill/reference/*.md`. Build emits provider-specific harness trees (for example `.claude/skills/`, `.cursor/skills/`, `.agents/skills/`).

- **One user-invocable skill**, not 23 separate skills. Sub-commands are routed from the Commands table in `SKILL.src.md`.
- **Setup (non-optional each session):** run `node <skill-scripts>/context.mjs` once (optionally `--target <path>`), load the matched command reference (or `new-work.md`), then load `craft-floor.md` immediately before UI edits.
- **Utilities outside the design menu:** `pin` / `unpin`, `hooks`, `doctor` (maintenance; not counted among the 23 design commands).

Command groups (from the skill router):

| Category | Commands |
|----------|----------|
| Build | `craft` (deprecated alias), `shape`, `init`, `document`, `extract` |
| Evaluate | `critique`, `audit` |
| Refine | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` |
| Enhance | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` |
| Fix | `clarify`, `adapt`, `optimize` |
| Iterate | `live` |

Native platforms load `audit.native.md` / `adapt.native.md` instead of the web references when `PRODUCT.md` declares `ios`, `android`, or `adaptive`.

### CLI detector

Binary: `cli/bin/cli.js` → package bin `impeccable`.

```bash
npx impeccable detect [file-or-dir-or-url...]
npx impeccable src/                    # detect shorthand (path-shaped args)
npx impeccable detect --json --quiet .
npx impeccable ignores list
npx impeccable install|link|update|check|help
```

| Fact | Value |
|------|--------|
| Rules | 59 (`cli/engine/registry/antipatterns.mjs`): 32 `slop`, 27 `quality` |
| Engines | Static HTML/CSS (`engines/static-html`), regex on non-HTML source (`engines/regex`), Puppeteer URL/browser (`engines/browser`) |
| Scannable extensions | `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.less`, `.jsx`, `.tsx`, `.js`, `.ts`, `.vue`, `.svelte`, `.astro`, `.blade.php` |
| Exit codes | `0` clean (or only advisory); `2` non-advisory findings; `1` usage/error |
| Config | `.impeccable/config.json` + `config.local.json` (`detector.ignoreRules` / `ignoreFiles` / `ignoreValues`) |
| Node | `>=22.18.0` (`package.json` `engines`) |

`--fast` is accepted for compatibility and ignored; the full static scan always runs. Optional dependency `puppeteer` is required only for `http(s)://` / `file://` URL scans.

### Chrome extension

`extension/manifest.json` (MV3): `activeTab`, `scripting`, `storage`, `webNavigation`, host permissions `<all_urls>`. Injects the browser detector bundle (`detector/detect.js`) into the page; no API key.

### Live mode

Web-only interactive variant loop: boot `live.mjs`, open the app URL, poll with `live-poll.mjs`, handle `generate` / `steer` / `accept` / `discard` / `manual_edit_apply` / `exit`. State lives under `.impeccable/live/` (`config.json`, `roots.json`, sessions). Skipped for native platforms the same way detect/hook are.

### Design hook

Installed with skills on harnesses that support edit hooks (Claude Code, Cursor, Codex, Grok Build). Runs the detector on UI file writes; skips entirely when `## Platform` is `ios` / `android` / `adaptive`.

### Plugin package

Slim layout under `plugin/` for Claude Code marketplace and Grok plugin install: skill, hooks, and four agents (`impeccable-finish-reviewer`, `impeccable-documenter`, `impeccable-asset-producer`, `impeccable-manual-edit-applier`).

## Runtime assumptions

| Assumption | Detail |
|------------|--------|
| Node | CLI and skill scripts: Node `>=22.18.0` (ESM) |
| AI harness | Skill commands need a skills-capable agent (Cursor, Claude Code, Codex, Gemini CLI, Grok Build, GitHub Copilot, OpenCode, Pi, and others listed by the installer) |
| Provider neutrality | Skill packs are files under harness skill directories; no single model vendor is required |
| Project context | Design quality improves after `PRODUCT.md` (and usually `DESIGN.md`); missing product context does not always block narrow refinements |
| Platform | Default `web`. Native values change references and disable live, detect-on-hook, and web detector assumptions |
| Network | `install`/`update` pull from `https://impeccable.style`; detect file scans are local; URL detect needs Puppeteer |
| BYOK | Hosted concept catalogs / roll APIs are optional; degraded offline paths exist for some seed helpers |

## Modes and platform (orientation)

Two orthogonal axes:

- **Mode** (per surface, not stored in `PRODUCT.md`): **Persuade**, **Operate**, **Read**, **Experience** — what visitor success looks like on the surface in hand.
- **Platform** (bare value in `PRODUCT.md` `## Platform`): `web` (default), `ios`, `android`, `adaptive`. Missing or unrecognized values fall back to `web`.

Live mode, CLI detect against HTML/CSS/JS frameworks, and the design hook are **web-oriented**. Native platforms load `reference/ios.md` and/or `reference/android.md` via `context.mjs`.

## Project artifacts (minimal map)

| Path | Role |
|------|------|
| `PRODUCT.md` | Durable product/voice/platform context; schema stamp `<!-- impeccable:product-schema N -->` |
| `DESIGN.md` | Visual system (external design.md-compatible); sidecar `.impeccable/design.json` |
| `.impeccable/surfaces/` | Per-surface briefs (mode and surface strategy) |
| `.impeccable/config.json` | Shared detector/hook/live/update/staleness settings |
| `.impeccable/config.local.json` | Machine-local overrides (e.g. hook consent) |
| `.impeccable/live/` | Live config, roots, sessions |

`context.mjs` resolves product/design/surface brief and emits directives (including staleness). Prefer running it from the skill scripts path with cwd at the user project.

## Shortest path: install to first success

<Steps>
  <Step title="Prerequisites">
    Node.js 22.18+, a project root, and an AI coding harness that can load agent skills.
  </Step>
  <Step title="Install skills">
    From the project root:

```bash
npx impeccable install
```

    Interactive defaults detect harness folders and ask project vs global scope. Non-interactive example:

```bash
npx impeccable install -y --providers=claude,cursor,codex,grok --scope=project
```

    Reload or restart the harness so skills are discovered. Codex: approve hooks via `/hooks` when prompted. Grok Build: trust project hooks (`/hooks-trust` or `--trust`).
  </Step>
  <Step title="Initialize product context">
    Inside the harness:

```text
/impeccable init
```

    Writes `PRODUCT.md` (including platform). Optionally generate `DESIGN.md` via `/impeccable document` for existing UIs.
  </Step>
  <Step title="First design or detect pass">
    Design command (agent session, after Setup runs `context.mjs`):

```text
/impeccable audit src/components/Hero.tsx
/impeccable polish settings
```

    Or LLM-free detector:

```bash
npx impeccable detect src/
npx impeccable detect --json .
```

    Expect exit `0` or `2` (findings). Advisory rules never flip the exit code.
  </Step>
</Steps>

<Check>
First success criteria: skill appears as `/impeccable` (or provider prefix), `init` produces `PRODUCT.md`, and either a scoped design command runs with loaded context or `detect` completes with exit 0/2.
</Check>

### Alternate install paths

<Tabs>
  <Tab title="Plugin">
```bash
# Claude Code
/plugin marketplace add pbakaus/impeccable

# Grok Build
grok plugin install pbakaus/impeccable#plugin --trust
```
  </Tab>
  <Tab title="Submodule link">
```bash
git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
```
  </Tab>
  <Tab title="CLI-only detect">
```bash
npx impeccable detect path/to/ui
# No skill install required for local file scans
```
  </Tab>
</Tabs>

## Versioning and packages

| Component | Manifest | Typical tag prefix |
|-----------|----------|--------------------|
| CLI (npm `impeccable`) | root `package.json` | `cli-v` |
| Skill / Claude plugin | `.claude-plugin/plugin.json` (+ marketplace) | `skill-v` |
| Chrome extension | `extension/manifest.json` | `ext-v` |

npm publishes primarily `cli/` (detector + skills installer). Skills for harnesses are installed from the universal/provider bundles the CLI downloads or links, not from a full monorepo copy unless you submodule/link.

## Constraints and failure modes

| Situation | Behavior |
|-----------|----------|
| Unknown CLI bareword | Exit 1 with `Unknown command` (not treated as detect path) |
| Detect with findings | Exit 2; CI should treat 2 as fail when gating quality |
| URL detect without Puppeteer | URL mode unavailable until optional dep is present |
| Native `## Platform` | Hook skips scans; live routing skipped; native audit/adapt refs load |
| No `PRODUCT.md` | New surfaces / replacement worlds should init first; narrow refinements may proceed with offer-to-init |
| Hook trust (Codex/Grok) | Hooks silent until approved / trusted |
| Stale artifacts | Boot may emit `CONTEXT_STALE`; run `doctor` for deeper repair; do not auto-rewrite as a side effect of design work |

## Repository layout (product-relevant)

:::files
skill/                 # skill source (SKILL.src.md, reference/, scripts/, agents/)
cli/                   # npm CLI: bin, detect engine, ignores, skills install
extension/             # Chrome MV3 extension
plugin/                # slim plugin package (skills, agents, hooks)
scripts/               # build, release, provider transformers
tests/                 # unit, fixtures, live-e2e, skill-behavior, plugin-e2e
dist/                  # generated provider builds (validation / link source)
:::

Source-first development edits `skill/`, `cli/`, `extension/`, `scripts/`, `tests/`. Root harness folders are generated distribution artifacts for direct install; feature work should not stage harness churn unless intentionally refreshing release output.

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Install, link, update, providers, scope, and hook consent.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First session: init, context.mjs, design command, detect.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup order, no-argument menu, craft-floor, native variants.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    detect flags, exit codes, install/link/update, ignores.
  </Card>
  <Card title="Live mode" href="/live-mode">
    Poll contract, accept/carbonize, web-only constraints.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Persuade/Operate/Read/Experience and web/ios/android/adaptive.
  </Card>
</CardGroup>

---

## 02. Installation

> Install paths for npx install/link/update, plugin install, submodule link, provider selection, scope (project vs global), and hook consent constraints.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/02-installation.md
- Generated: 2026-08-05T07:33:31.428Z

### Source Files

- `cli/bin/cli.js`
- `cli/bin/commands/skills.mjs`
- `README.md`
- `README.npm.md`
- `docs/HARNESSES.md`
- `plugin/hooks/hooks.json`
- `.claude-plugin/plugin.json`

---
title: "Installation"
description: "Install paths for npx install/link/update, plugin install, submodule link, provider selection, scope (project vs global), and hook consent constraints."
---

Impeccable installs as provider-compiled skill trees plus optional design-hook manifests. The CLI entrypoints are `npx impeccable install`, `link`, `update`, and `check` (also under the legacy `skills` namespace). The installer downloads the universal bundle from `https://impeccable.style/api/download/bundle/universal` and copies per-provider skill variants into harness folders such as `.claude/skills/` or `~/.claude/skills/`.

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Node.js | `>=22.18.0` (`package.json` `engines`) |
| Network | Needed for `install` / `update` / `check` unless `IMPECCABLE_BUNDLE_PATH` points at a local zip or directory |
| Project root | CLI walks up from `cwd` to the nearest `.git`; falls back to `cwd` when none exists |
| AI harness | Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, GitHub Copilot, OpenCode, Pi, Kiro, Qoder, Trae, Trae CN, Rovo Dev, Mistral Vibe, or Antigravity |

Detector-only use (`npx impeccable detect`) does not require a skill install. Live mode, the design hook, and `/impeccable` commands need the skill payload in a harness the agent can load.

## Choose an install path

| Path | When to use | Writes skills | Writes hooks |
|------|-------------|---------------|--------------|
| CLI `install` | Default; project or global | Copy from universal bundle | Claude, Cursor, Codex, GitHub Copilot, Grok (when consented) |
| CLI `link` | Git submodule / local checkout | Symlinks into project harness dirs | No |
| Claude plugin marketplace | Claude Code only | Plugin-managed skill tree | Plugin `hooks.json` via `${CLAUDE_PLUGIN_ROOT}` |
| Grok plugin | Grok Build only | Slim `plugin/` package | `plugin/hooks/hooks.json` |
| Website ZIP / manual `cp` | Offline or custom layout | Manual | Manual (hooks optional) |

Recommended default:

```bash
npx impeccable install
```

Then reload the harness and run `/impeccable init` inside the agent session.

## CLI install (recommended)

### Commands

| Command | Role |
|---------|------|
| `npx impeccable install` | Download universal bundle; copy provider skill variants; optionally install hook manifests |
| `npx impeccable update` | Refresh existing copy installs from the same bundle API |
| `npx impeccable check` | Report whether installed skills match the remote bundle |
| `npx impeccable link` | Symlink skills from a local checkout (`dist/universal` or provider trees) |
| `npx impeccable help` | List skill commands (fetches catalog from impeccable.style) |

Legacy namespace still works: `npx impeccable skills install|link|update|check|help`. Top-level aliases route through the same handler.

### Flags

<ParamField body="--providers" type="string">
Comma-separated harness aliases (e.g. `claude,codex,cursor,grok`). Folder names like `.claude` are also accepted. Unknown names fail the install.
</ParamField>

<ParamField body="--scope" type="project | global">
Install root. Aliases: `project`/`local`/`repo`/`p` → project; `global`/`user`/`home`/`u` → user home. Also `--project`, `--local`, `--user`, `--home`, `--global`, and `--install-scope=`.
</ParamField>

<ParamField body="-y, --yes" type="boolean">
Non-interactive. With no `--providers`, uses detection or defaults (`.claude` + `.agents`). With no scope flag, installs **project** scope.
</ParamField>

<ParamField body="--no-hooks" type="boolean">
Skip hook manifests for this run only. Does **not** record a consent decision.
</ParamField>

<ParamField body="--force" type="boolean">
Reinstall skills when already present; replace malformed hook JSON after writing a `.bak`; for `link`, replace existing real skill dirs with symlinks.
</ParamField>

<ParamField body="--source" type="string">
`link` only. Checkout root (default `.impeccable`). Expects `dist/universal/` or provider skill folders at the root.
</ParamField>

### Interactive flow

Without `-y`, `install`:

1. Prints detected harnesses (project folders and global hints such as `~/.claude`, `~/.codex` → `.agents`, OpenCode config dir, Pi `~/.pi/agent/skills`).
2. Offers **Detected only** vs **Customize** provider multi-select.
3. Asks **Project** vs **Global** install location (default prefers project when project harness dirs exist).
4. Offers the design hook once (default yes) when consent is unset and hooks are not already present.
5. Downloads the universal bundle, copies per-provider skill trees (never a single shared symlink across providers), copies supported agents, and merges hook manifests when accepted.

### Non-interactive examples

<CodeGroup>
```bash title="Project install, Claude + Codex + Cursor"
npx impeccable install -y --providers=claude,codex,cursor --scope=project
```

```bash title="Global install, no hooks"
npx impeccable install -y --providers=claude,grok --scope=global --no-hooks
```

```bash title="Update project install"
npx impeccable update -y --project
```

```bash title="Update user-level install"
npx impeccable update -y --user
```
</CodeGroup>

### What gets written

**Project scope** (default): `<repo>/<provider>/skills/impeccable/` (and sibling skills from the bundle).  
**User (global) scope**: provider home layout, with overrides:

| Provider dir | Global skills path |
|--------------|--------------------|
| Most providers | `~/<provider>/skills/` |
| `.pi` | `~/.pi/agent/skills/` |
| `.opencode` | `$OPENCODE_CONFIG_DIR` or `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode` → `skills/` |
| `.agent` (Antigravity) | `~/.gemini/config/skills/` |

Project scope always uses `<provider>/skills` under the project root, including for Pi / OpenCode / Antigravity.

**Hook manifests** (when hooks install) always target the **project** root (`hookRoot`), even if skills were installed globally:

| Provider | Destination | Skill script |
|----------|-------------|--------------|
| Claude Code | `.claude/settings.local.json` (from bundle `settings.json`) | `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs` |
| Cursor | `.cursor/hooks.json` | `hook-before-edit.mjs` (blocks bad writes) |
| Codex | `.codex/hooks.json` (skill lives under `.agents`) | `.agents/skills/impeccable/scripts/hook.mjs` |
| GitHub Copilot | `.github/hooks/impeccable.json` | `.github/skills/impeccable/scripts/hook.mjs` |
| Grok Build | `.grok/hooks/impeccable.json` | PostToolUse + Stop deep pass |

Other harnesses get skills only; no documented hook surface.

**Native agents** (when present in the bundle): GitHub Copilot → `.github/agents/` or `~/.copilot/agents/`; Cursor → `.cursor/agents/` or `~/.cursor/agents/`. User-level Copilot agents can shadow project copies; the CLI warns when that happens.

### Bundle source

```text
https://impeccable.style/api/download/bundle/universal
```

Override for offline/CI:

```bash
IMPECCABLE_BUNDLE_PATH=/path/to/universal.zip npx impeccable install -y --providers=claude
# or a directory that already contains the extracted universal layout
```

Install deliberately copies per-provider compiled variants. It does not shell out to `npx skills add`, which can install uncompiled source or symlink every harness at one shared tree.

### Update and check

- `update` refreshes only trees that contain an `impeccable` (or legacy prefixed) skill, not arbitrary skills under the same folder.
- Linked installs are left alone: update the submodule (or source checkout), then rerun `link`.
- If both project and user installs exist and no scope is given, interactive update asks which; non-interactive (`-y`) defaults to **project** and prints how to target `--user`.
- `check` compares installed file hashes to the remote bundle after path normalization.

### Force and failure modes

| Situation | Behavior |
|-----------|----------|
| Skills already installed, no `--force` | May refresh outdated copies / missing hooks; otherwise reports up to date |
| Empty provider list after resolution | Exit 1; pass `--providers=...` |
| Bundle has no variants for targets | Exit 1: nothing installed |
| Malformed existing hook JSON | Aborts unless `--force` (backs up to `.bak`) |
| Download failure | Exit 1 with HTTP/message |
| Prompt abort | Exit 130 |

## Provider aliases

Pass any of these to `--providers=` (or the interactive selector):

| Input | Folder | Display name |
|-------|--------|--------------|
| `claude`, `claude-code` | `.claude` | Claude Code |
| `codex` | `.agents` | Codex CLI |
| `cursor` | `.cursor` | Cursor |
| `gemini` | `.gemini` | Gemini CLI |
| `github`, `copilot` | `.github` | GitHub Copilot |
| `grok`, `grok-build`, `xai` | `.grok` | Grok Build |
| `antigravity`, `agent` | `.agent` | Antigravity |
| `opencode` | `.opencode` | OpenCode |
| `pi` | `.pi` | Pi Coding Agent |
| `kiro` | `.kiro` | Kiro |
| `qoder` | `.qoder` | Qoder |
| `trae` / `trae-cn` | `.trae` / `.trae-cn` | Trae / Trae CN |
| `rovo-dev`, `rovodev` | `.rovodev` | Rovo Dev |
| `vibe` | `.vibe` | Mistral Vibe |
| `agents` | `.agents` | Codex / universal |

Detection order when `--providers` is omitted: project harness folders → global harness hints → default `[.claude, .agents]`.

## Scope: project vs global

```text
                    --scope=project (default for -y)
                    ┌─────────────────────────────┐
  repo root ───────►│ .<provider>/skills/…        │
                    │ hook manifests (project)    │
                    └─────────────────────────────┘

                    --scope=global | user | home
                    ┌─────────────────────────────┐
  $HOME ───────────►│ user skills layout (table)  │
                    │ hooks still under project   │
                    └─────────────────────────────┘
```

- Project skills are shareable in git when committed (team harness folders).
- Global skills apply across repos for that developer.
- Design hooks stay project-local so they only run where the repo is trusted.
- OpenCode global must use the config dir (`OPENCODE_CONFIG_DIR` / XDG / `~/.config/opencode`); writing only to `~/.opencode/skills` is not discoverable by OpenCode.

## Hook consent

Hook install is gated by `decideHookInstall`:

| Condition | Result |
|-----------|--------|
| `--no-hooks` | Skip this run; **no** consent written |
| `hook.consent` = `declined` in config | Skip; no prompt |
| `hook.consent` = `accepted` | Install/merge hooks |
| Hook already present for all selected providers | Treat as accepted; no prompt |
| Interactive, undecided | Explainer + `Install the design hook? (Y/n)` (default yes); write consent |
| Non-interactive (`-y` or no TTY), undecided | Install hooks (historical default); **do not** record consent |

Consent is stored under `.impeccable/config.local.json` as `hook.consent`: `"accepted"` | `"declined"`. Local config overrides shared `.impeccable/config.json`. The CLI best-effort gitignores `config.local.json` via `.git/info/exclude`.

Lifecycle knobs (quiet, disable, audit log) live under the shared `hook` key in config; see configuration reference. Change later with `/impeccable hooks on|off` inside a session that has the skill loaded.

### Provider trust after install

| Harness | Extra step |
|---------|------------|
| Codex | Open `/hooks` and approve after install/update; definition changes re-require approval; hooks disabled on Windows |
| Grok Build | Folder trust: `/hooks-trust` or launch with `--trust` |
| GitHub Copilot | Commit hook file on default branch; folder trust as required by Copilot |
| Cursor | Reload/restart if hooks do not pick up; enable Agent Skills (Nightly) as required by Cursor |
| Claude Code | Machine-local `settings.local.json`; no marketplace trust step for CLI-installed hooks |

Claude / Codex / Copilot / Grok: post-edit findings (Stop deep pass where supported). Cursor: pre-write block via `hook-before-edit.mjs`.

## Plugin install

### Claude Code marketplace

```bash
/plugin marketplace add pbakaus/impeccable
```

Then open `/plugin` and install **impeccable**. Marketplace metadata lives in `.claude-plugin/marketplace.json` with `source: "./plugin"`. The slim package under `plugin/` includes skills, agents, and `plugin/hooks/hooks.json` (commands use `${CLAUDE_PLUGIN_ROOT}`).

### Grok Build plugin

```bash
grok plugin install pbakaus/impeccable#plugin --trust
```

The `#plugin` fragment installs the slim package (not the full monorepo). Project CLI install remains valid:

```bash
npx impeccable install --providers=grok
```

That writes `.grok/skills/` and `.grok/hooks/impeccable.json`.

Plugin installs do not replace the detector CLI; use `npx impeccable detect` from the npm package separately when needed.

## Git submodule + link

```bash
git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
git add .gitmodules .impeccable .claude .cursor
git commit -m "Add Impeccable skills"
```

`link` resolves:

1. `<source>/dist/universal/` if present, else  
2. provider skill folders directly under `<source>`.

Behavior:

- Creates relative directory symlinks per skill under `<provider>/skills/<name>`.
- Skips existing non-matching paths unless `--force`.
- Does not install hooks; run `install`/`update` with hooks if needed, or configure manifests manually.
- Refresh: `git submodule update --remote .impeccable` then rerun `link`.

## Manual and website installs

- **Website:** download a provider ZIP from [impeccable.style](https://impeccable.style) and extract into the project.
- **From a built checkout:** copy the matching tree under `dist/<provider>/` (for example `dist/claude-code/.claude`, `dist/agents/.agents`, `dist/github/.github`).

Provider-specific enablement notes (Cursor Nightly + Agent Skills, Gemini CLI Skills setting, Trae dual config dirs, etc.) are documented in the repository README and harness matrix. Prefer `npx impeccable install` so hooks and per-provider variants stay consistent.

## Verify installation

<Steps>
<Step title="Confirm skill on disk">
Check for `impeccable/SKILL.md` under the expected skills dir, e.g. `.claude/skills/impeccable/SKILL.md` or `~/.claude/skills/impeccable/SKILL.md`.
</Step>
<Step title="Reload the harness">
Restart or reload the AI tool so it rediscovers skills and hooks.
</Step>
<Step title="Run setup in-session">
```text
/impeccable init
```
</Step>
<Step title="Optional: CLI health">
```bash
npx impeccable check
npx impeccable detect --help
```
</Step>
</Steps>

Expected post-install CLI message pattern: `Installed impeccable into: … (project|global)` and `Done! Run /impeccable init…`.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Skills missing in OpenCode global | Install with `--scope=global --providers=opencode`; confirm path under config dir, not only `~/.opencode/skills` |
| Codex hook never runs | Approve under `/hooks`; confirm Windows is not in use for hooks |
| Grok hooks silent | Run `/hooks-trust` or start with `--trust` |
| Cursor skills invisible | Nightly channel + enable Agent Skills |
| Install says already installed | `npx impeccable update` or `install --force` |
| Link skipped existing dirs | `npx impeccable link --force --source=…` |
| Offline install | Set `IMPECCABLE_BUNDLE_PATH` to a local universal zip/dir |
| Node too old for hooks | Hooks require Node 22+ on PATH; skill text may still load without the hook |

## Next

<CardGroup>
<Card title="Quickstart" href="/quickstart">
First successful session: init, context load, a scoped design command, optional detect.
</Card>
<Card title="Provider harnesses" href="/provider-harnesses">
Harness folders, frontmatter matrix, and provider trust steps.
</Card>
<Card title="Design hook" href="/design-hook">
Hook behavior, quiet/disable controls, and native-platform skip.
</Card>
<Card title="CLI reference" href="/cli-reference">
Full flags, exit codes, detect shorthand, and ignores.
</Card>
<Card title="Plugin agents" href="/plugin-agents">
Bundled agents and plugin manifest contract for Claude and Grok.
</Card>
</CardGroup>

---

## 03. Quickstart

> First successful session: install skills, run `/impeccable init`, load context via context.mjs, run a scoped design command, and optionally scan with detect.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/03-quickstart.md
- Generated: 2026-08-05T07:34:18.195Z

### Source Files

- `skill/SKILL.src.md`
- `skill/reference/init.md`
- `skill/scripts/context.mjs`
- `skill/scripts/command-metadata.json`
- `cli/bin/cli.js`
- `README.npm.md`

---
title: "Quickstart"
description: "First successful session: install skills, run `/impeccable init`, load context via context.mjs, run a scoped design command, and optionally scan with detect."
---

A first Impeccable session is four surfaces in order: CLI skill install into a harness folder, harness command `/impeccable init` writing `PRODUCT.md`, session boot via `node …/scripts/context.mjs`, then a scoped `/impeccable <command> [target]`. The detector CLI (`npx impeccable detect`) is optional and independent of the skill loop.

## Prerequisites

| Requirement | Detail |
|---|---|
| Node.js | `>=22.18.0` (`package.json` `engines`) |
| Project root | Run install and later CLI scans from the app or monorepo root you intend to work in |
| AI harness | A tool that loads Agent Skills (Claude Code, Cursor, Codex, Gemini CLI, Grok Build, and others) |
| Network | `npx impeccable install` / `update` fetches the published skill bundle |

No model API key is required for install or for deterministic `detect` scans. Design commands run inside your harness with that harness’s own model configuration (BYOK / provider-neutral skill files).

## Session flow

```text
  project root
       │
       ▼
  npx impeccable install          →  .claude|/.cursor|/… skills + optional hooks
       │
       ▼
  reload harness
       │
       ▼
  /impeccable init                →  PRODUCT.md (+ optional live config)
       │
       ▼
  node <skill>/scripts/context.mjs [--target path]
       │                            → PRODUCT / DESIGN / briefs / directives
       ▼
  /impeccable <cmd> [target]      →  command ref → craft-floor (before UI edits)
       │
       ▼  (optional)
  npx impeccable detect [paths]   →  exit 0 none / 2 findings
```

## Step-by-step

<Steps>
<Step title="Install skills into the harness">
From the project root:

```bash
npx impeccable install
```

Interactive install detects harness folders under the project and home directory (for example `~/.claude`, `~/.cursor`, `~/.codex`, `~/.grok`), lets you keep the detected set or customize providers, then chooses **project** or **global** scope. On supported harnesses it can also write project-local detector hook manifests.

Non-interactive (scripts / CI images):

```bash
npx impeccable skills install -y --providers=claude,cursor --scope=project
```

| Flag / form | Behavior |
|---|---|
| `install` or `skills install` | Same install path (`cli/bin/cli.js` routes both) |
| `-y` / `--yes` | Skip prompts; default scope is project unless `--scope=global` |
| `--providers=…` | Comma-separated aliases (`claude`, `cursor`, `codex`, `gemini`, `grok`, …) |
| `--scope=project\|global` | Project-local harness dirs vs user home install |
| `--no-hooks` | Skills only; skip hook manifests |

Successful install prints targets and ends with a prompt to run `/impeccable init` in the harness.

**Reload the harness** (new session or restart) so skills and hooks are picked up.
</Step>

<Step title="Run init once for product context">
In the AI harness, at the project root:

```text
/impeccable init
```

(`teach` is an alias for `init`.)

`init` captures durable product truth only. It:

1. Resolves any existing `PRODUCT.md` path the context loader would use, and updates it rather than inventing a second authority.
2. Scans the repo for product facts (docs, package boundaries, workflows, brand assets, platform signals).
3. Interviews for material gaps (at most three focused rounds before a new `PRODUCT.md`).
4. Writes `PRODUCT.md` with `<!-- impeccable:product-schema 1 -->` and a bare `## Platform` value: `web` (default), `ios`, `android`, or `adaptive`.
5. Optionally configures `.impeccable/live/config.json` for runnable web projects (skipped for native / non-runnable).
6. Recommends a next command from project state (`document`, a scoped refine command, `live`, or new-surface work).

`init` does **not** invent a visual world and does **not** write `DESIGN.md`. Visual world creation or replacement is owned by new-work flows after product truth exists; recording an incumbent system is `/impeccable document`.

### PRODUCT.md completion gate

Before build/shape/new-work, verify:

- `PRODUCT.md` exists at the resolved project path
- Confirmed product record is in the file (not only chat notes)

Template sections used when relevant: `Platform`, `Stack` (greenfield only), `Users`, `Product Purpose`, `Positioning`, `Operating Context`, `Capabilities and Constraints`, `Brand Commitments`, `Evidence on Hand`, `Product Principles`, `Accessibility & Inclusion`.
</Step>

<Step title="Load session context with context.mjs">
Every design session starts with **one** context load. The skill’s Setup step runs:

```bash
node <skill-base-dir>/scripts/context.mjs
# scoped monorepo / file path:
node <skill-base-dir>/scripts/context.mjs --target apps/web
```

Keep the process **cwd** at the user’s project. Do not rerun after a successful boot unless the session changes target in a way that requires a new resolution.

The script resolves context in this order (first match wins per file):

1. Active project root (`PRODUCT.md` / `DESIGN.md`)
2. Active project `.agents/context/` then `docs/`
3. Repo-root fallback when the active project is nested (monorepo / nested product)
4. `$IMPECCABLE_CONTEXT_DIR` only when defaults are empty
5. Active project root as the empty default

Stdout is agent-facing markdown blocks and directives, including:

| Signal | Meaning |
|---|---|
| `# PRODUCT.md` / `# DESIGN.md` | Loaded file bodies when present |
| `NO_PRODUCT_MD:` | No product record; init required for new surfaces / redesigns; narrow refinements may proceed on code |
| `BUILD_INIT_REQUIRED` / `PRODUCT_INIT_REQUIRED` | Gate new-surface work on init |
| `SCOPED_EXISTING_ALLOWED` | Scoped refine commands may use incumbent UI without blocking |
| `INCUMBENT_WORLD_UNDOCUMENTED` / `WORLD_DISCOVERY_REQUIRED` | DESIGN.md / world guidance when product exists |
| `NATIVE PLATFORM REFERENCE: …` | Inlined `ios.md` / `android.md` when platform is native |
| `CONTEXT_STALE` | Tier-1 artifact drift (report only unless user asks; `auto` fixes on next write) |
| `UPDATE_AVAILABLE` | Newer skill version (best-effort network check) |
| `MONOREPO_TARGET_REQUIRED` | Monorepo root without `--target`; re-run with a child path |

After init writes `PRODUCT.md` mid-session, resume without re-running `context.mjs`. Init itself loads native platform references when it just recorded `ios`, `android`, or `adaptive`.
</Step>

<Step title="Run a scoped design command">
With context loaded, invoke an explicit command and target:

```text
/impeccable polish settings
/impeccable audit src/components/Checkout
/impeccable critique landing
/impeccable layout dashboard
```

Setup order before edits:

1. Context already loaded (previous step)
2. Load the command’s reference under `skill/reference/<command>.md` (or `audit.native.md` / `adapt.native.md` when platform is native)
3. Inspect the target and incumbent visual truth (tokens, theme, CSS, components)
4. Load `reference/craft-floor.md` immediately before editing UI (not for planning-only work)

| Intent | Command examples |
|---|---|
| Evaluate quality | `audit`, `critique` |
| Ship readiness | `polish`, `harden` |
| Visual refine | `layout`, `typeset`, `colorize`, `bolder`, `quieter`, `distill` |
| Capture incumbent system | `document` (writes DESIGN.md from code) |
| Browser iteration (web only) | `live` (requires live config + dev server) |

No argument → the skill loads `reference/routing.md` and presents a menu; it does not auto-run a command.

Natural-language design requests without a named command are treated as general design work: missing `PRODUCT.md` on a new surface or replacement world routes through init, then new-work; narrow refinement of existing code can proceed and offer init afterward.
</Step>

<Step title="Optional: scan with detect">
The CLI detector is deterministic (no LLM). It is not required for skill commands but is a fast check on files or a live URL.

```bash
npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect --json .
npx impeccable detect https://example.com   # needs Puppeteer
# shorthand (path-shaped first arg defaults to detect):
npx impeccable src/
```

| Item | Behavior |
|---|---|
| Exit `0` | No primary findings |
| Exit `2` | Primary anti-patterns / quality findings |
| `--json` | Machine-readable findings |
| `--quiet` | Text mode: final count only |
| `--scope <name>` | Limit to design domains (e.g. `type`, `layout`) |
| `--fast` | Deprecated and ignored; full scan always runs |
| Config | Honors `.impeccable/config.json` and `config.local.json` detector ignores unless `--no-config` |

Use Node (not Bun) for HTML-heavy scans; Bun’s jsdom path is intentionally avoided for this CLI.
</Step>
</Steps>

## Provider and trust notes after install

Hooks are optional and project-scoped on supported harnesses:

| Harness | Hook surface | Consent |
|---|---|---|
| Claude Code | `.claude/settings.local.json` (or settings) → `hook.mjs` | Project settings load |
| Cursor | `.cursor/hooks.json` → `hook-before-edit.mjs` | Reload / restart if needed |
| Codex CLI | `.codex/hooks.json` | Approve via `/hooks` when prompted (again after hook definition changes) |
| Grok Build | `.grok/hooks/impeccable.json` | Project trust: `/hooks-trust` or `--trust` |
| Others | Skills only | No hook install |

Install without hooks: `npx impeccable skills install --no-hooks`.

Plugin alternatives (same skill entrypoint after install):

```bash
# Claude Code marketplace
/plugin marketplace add pbakaus/impeccable

# Grok Build slim plugin package
grok plugin install pbakaus/impeccable#plugin --trust
```

Submodule + link path (teams vendoring the repo):

```bash
git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
```

## Verification checklist

| Check | Pass signal |
|---|---|
| Skills installed | Harness lists `/impeccable` (or provider equivalent); install log names targets |
| Init complete | `PRODUCT.md` on disk with schema comment and confirmed product sections |
| Platform set | Bare `## Platform` value `web` / `ios` / `android` / `adaptive` (missing → treated as `web`) |
| Context boot | `context.mjs` prints product/design bodies or an explicit `NO_PRODUCT_MD:` directive (not silent empty output) |
| First design command | Agent loaded the matching `reference/*.md`, inspected the target, and (for UI edits) the craft floor |
| Detect (optional) | Exit code `0` or `2` with findings list; `--json` parses |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `/impeccable` unknown | Harness not reloaded or wrong install scope | Re-run install with explicit `--providers` and `--scope`; restart harness |
| Init re-asks everything | Conflicting / missing PRODUCT.md path | Use the path `context.mjs` resolves; update that file instead of creating a second product file |
| Context says monorepo target required | Ran at monorepo root without child selection | `node …/context.mjs --target apps/<name>` |
| Native guidance missing after init | Platform just set to `ios`/`android`/`adaptive` mid-session | Init loads platform refs itself; later sessions get them from `context.mjs` |
| Hooks never fire | Provider needs trust, or install used `--no-hooks` | Codex `/hooks`, Grok `/hooks-trust` / `--trust`; reinstall with hooks |
| Detect hangs under Bun | Unsupported runtime for jsdom path | Run `node` / `npx` (Node 22.18+) |
| Live command fails on native platform | Live and detect hooks are web-only | Use web platform or native command variants (`audit.native`, `adapt.native`) |

## What not to do on first session

- Do not skip install and paste skill text ad hoc; harness install places provider-shaped `SKILL.md`, `reference/`, and `scripts/`.
- Do not treat missing `DESIGN.md` alone as “greenfield”; incumbent CSS/components are visual authority until new-work replaces the world.
- Do not block narrow refinements on init when code already exists; offer init after, per `SCOPED_EXISTING_ALLOWED` / skill routing.
- Do not repair `CONTEXT_STALE` drift as a side quest of a design task unless the user asks (`auto` findings still apply on the next write to that file).

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Full install, link, update, scope, providers, and hook consent matrix.
  </Card>
  <Card title="Initialize product context" href="/init-and-document">
    Init interview gates, PRODUCT.md schema, document vs new-work ownership of DESIGN.md.
  </Card>
  <Card title="Run design commands" href="/run-design-commands">
    Evaluate and refine commands with targets, artifacts, and verification signals.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, no-argument menu, craft-floor gate, native reference variants.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    detect, install, link, update, check, ignores: flags and exit codes.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Web-only live mode after product setup and live config.
  </Card>
</CardGroup>

---

## 04. Modes and platform

> Visitor modes (Persuade, Operate, Read, Experience) and orthogonal platform values (web, ios, android, adaptive), including defaults, native reference loading, and web-only live/detect boundaries.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/04-modes-and-platform.md
- Generated: 2026-08-05T07:33:55.469Z

### Source Files

- `skill/SKILL.src.md`
- `skill/scripts/context.mjs`
- `skill/reference/operate.md`
- `skill/reference/new-work.md`
- `skill/reference/ios.md`
- `skill/reference/android.md`
- `skill/scripts/lib/artifact-schema.mjs`

---
title: Modes and platform
description: Visitor modes (Persuade, Operate, Read, Experience) and orthogonal platform values (web, ios, android, adaptive), including defaults, native reference loading, and web-only live/detect boundaries.
---

Impeccable separates **what the visitor comes to do** (mode) from **where the UI ships** (platform). Mode is per surface. Platform is per product, stored in `PRODUCT.md`, and steers which rulebooks load, which command variants apply, and whether browser tooling is available.

## Two orthogonal axes

| Axis | Question | Stored in | Scope |
|---|---|---|---|
| **Mode** | What does visitor success look like on this surface? | Surface brief under `.impeccable/surfaces/` | Per route, page, or artifact |
| **Platform** | What delivery target and native conventions apply? | `PRODUCT.md` → `## Platform` | Per product / project |

Mode does **not** live in `PRODUCT.md`. Platform does **not** live in surface briefs. A dashboard product can still have a Persuade marketing page; a fashion house can still have a Read docs site.

```mermaid
flowchart LR
  surface["Requested surface"] --> mode["Mode: Persuade / Operate / Read / Experience"]
  product["PRODUCT.md"] --> platform["Platform: web / ios / android / adaptive"]
  mode --> guidance["Surface strategy, color energy, motion, new-work questions"]
  platform --> refs["Native refs, command variants, web-only gates"]
```

## Visitor modes

Mode names the visitor's success condition on the surface in hand. Choose it from the **requested surface**, not from the product category.

| Mode | Visitor success | Typical surfaces | Design bias |
|---|---|---|---|
| **Persuade** | Decide and act; design *is* the product | Landing pages, marketing, campaigns, pricing | Earn attention and action; conversion lives inside the form's vocabulary |
| **Operate** | Complete a task | App UI, dashboards, editors, admin, settings, tools | Scanability, consistency, familiar affordances; brand in precise details |
| **Read** | Understand something | Docs, articles, guides, help, changelogs | Comprehension first; reading experience worth staying in |
| **Experience** | Be inside the work itself | Portfolios, galleries, showcases | Artifact leads from the first viewport; chrome recedes |

### Persistence and legacy Register

- Persist mode only in that surface's brief (scope + visitor mode, plus audience/job/constraints and direction).
- Write/read briefs with `node <skill>/scripts/surface-brief.mjs`.
- v4 retired `## Register` on `PRODUCT.md`. Nothing reads it. Boot staleness reports the section as deprecated so agents delete it when the user agrees instead of preserving it "just in case."

### Mode-sensitive guidance (without reloading every rulebook)

| Area | Persuade / Experience | Operate / Read |
|---|---|---|
| Color strategy | May take Committed, Full palette, or Drenched when the brief allows | Default Restrained (neutrals + one accent) |
| Typography | Faces with a point of view when the world earns them | System stacks and workhorse UI faces are usually right |
| Layout | Composition may be asymmetric or disruptive when the world earns it | Predictable structure, stable density, navigable linearity |
| Motion | May carry voice; prefer one rehearsed focal sequence | Feedback, state, continuity; fast routine transitions |
| Depth playbook | Mode bullets in `SKILL.md` + new-work for greenfield | `reference/operate.md` for Operate/Read depth |

Deeper Operate/Read craft (type scale, state vocabulary, product bans) lives in `skill/reference/operate.md`. New surfaces and replacement worlds load `skill/reference/new-work.md`, which asks mode-specific questions and enforces mode constraints at build time (for example: Operate may not obscure the task; Persuade must make the offer and action intelligible in the form's own vocabulary).

## Platform values

Platform answers delivery target and which native conventions apply. It is orthogonal to mode.

| Value | Meaning | References loaded at boot |
|---|---|---|
| `web` | Website or web app, including responsive mobile web | None extra (general skill rules apply) |
| `ios` | Native iOS / iPadOS app | `reference/ios.md` |
| `android` | Native Android app | `reference/android.md` |
| `adaptive` | One codebase that **adapts design language per OS** (Flutter, React Native, KMP when both targets differ by platform) | **Both** `ios.md` and `android.md` |

### Classification rules that people get wrong

- **Mobile web stays `web`.** A responsive site is not `ios` or `android`.
- **A native wrapper around a website does not make the design language native.** Record the language the app actually renders.
- **Material-everywhere on both phones is not `adaptive`.** A Flutter/RN app that uses one look (for example Material on iOS and Android) takes the single platform value that matches that language, not `adaptive`. `adaptive` means the UI genuinely adapts per OS.
- **Name the design language, not the toolchain.** Valid values are only `web`, `ios`, `android`, `adaptive`. Values like `flutter`, `react-native`, or `expo` are unrecognized.

### PRODUCT.md field shape

Record platform as a bare value under an exact `## Platform` heading:

```markdown
## Platform

web
```

or `ios`, `android`, or `adaptive`.

<ParamField body="## Platform" type="string" required>
Bare value on the first non-empty line after the heading. Case-insensitive. Exact heading match only (`## Platform notes` does not count). Empty section yields no value (treated as web).
</ParamField>

### Parsing, defaults, and aliases

`extractPlatform()` in `skill/scripts/context.mjs` implements:

| Input | Result |
|---|---|
| Missing `## Platform` or empty section | `null` → skill treats as **`web`** |
| `web` / `ios` / `android` / `adaptive` | That value |
| Short list of both targets only, e.g. `ios, android`, `android and ios`, `ios/android` | **`adaptive`** |
| Unrecognized value (`flutter`, prose, mixed junk) | `null` → treat as **`web`**, plus a **WARNING** directive naming the bad value |
| Prose that mentions both targets (`web only, not ios or android`) | **Not** adaptive; unrecognized |

Missing platform is silent web default (legacy-friendly). A *wrong* platform string is never silently web without a warning: boot prints that the value is unrecognized and that native references will not load until the field is fixed.

### Setting platform during init

1. Scan the project for stack and platform signals.
2. Form a hypothesis: `web`, `ios`, `android`, or `adaptive`.
3. Confirm when ambiguous (Step 3 of init).
4. Write the bare value under `## Platform` in `PRODUCT.md` (Step 4).
5. If the value is `ios`, `android`, or `adaptive`, load the matching native reference(s) immediately. Fresh projects had no `PRODUCT.md` when `context.mjs` ran, so init is the place those refs first enter the session.
6. Skip live-mode setup for native or non-runnable projects.

After init writes `PRODUCT.md`, resume design work **without** rerunning `context.mjs`; the native refs init loaded are the piece Setup could not have known.

## How platform changes a session

### Boot context (`context.mjs`)

Once per session, Setup runs `node <skill>/scripts/context.mjs` (optional `--target`). When product context loads successfully, the script:

1. Parses `## Platform` into `ctx.platform`.
2. Inlines native reference bodies as:

   `# NATIVE PLATFORM REFERENCE: IOS (reference/ios.md)`  
   and/or  
   `# NATIVE PLATFORM REFERENCE: ANDROID (reference/android.md)`

3. For native platforms, skips the web detector fallback directive (`MANUAL_DETECTOR_REQUIRED`).
4. For unrecognized raw platform strings, emits the WARNING above.

Native refs are distilled HIG / Material guidance (safe areas, system navigation, touch targets, semantic colors, platform controls). On native, visitor mode still applies, but platform conformance governs structure, navigation, and interaction; brand expresses in the layer the OS leaves open (tint, type, motion, content).

### Native command variants

The Commands table routes some work to platform-specific playbooks when `setup.platform` is native:

| Command | Web reference | Native reference |
|---|---|---|
| `audit` | `reference/audit.md` | `reference/audit.native.md` |
| `adapt` | `reference/adapt.md` | `reference/adapt.native.md` |

Web files carry a one-line guard: if the project is native, switch to the `.native.md` variant. Native audit scores platform conformance from source (SwiftUI / UIKit / Compose / React Native / Flutter); it does not use browser tooling or `detect.mjs`. One native variant covers ios, android, and adaptive; per-OS detail stays in the platform refs Setup already loaded.

Commands whose divergence is fully covered by platform refs (`animate`, `layout`, and most refine/enhance commands) have no separate native file.

### Web-only tooling boundaries

Live mode, the HTML/CSS detector, and the design edit hook operate on browser/HTML shapes. They are gated off for native platforms.

| Capability | Web (`web` or missing/legacy) | Native (`ios` / `android` / `adaptive`) |
|---|---|---|
| `/impeccable live` and live helpers | Available when configured | Do not lead with live; browser overlay does not apply |
| `detect.mjs` / `npx impeccable detect` | Available; routing may auto-scan dirty HTML/CSS | Skip; engine reads HTML/CSS, not native UI trees |
| Design hook (per-edit / Stop) | May run when enabled and manifests present | **Skipped** (`skipped: 'native-platform'`) |
| Manual detector fallback from context | Emitted when no hook is active | Not emitted |
| Native platform references | Not inlined | Inlined at boot |

Hook resolution uses the same PRODUCT.md path as the skill (`resolveProjectPlatform` → `extractPlatform`). That matters because React Native and Flutter trees use `.tsx` / `.ts` / `.js` extensions the hook already watches; without the platform gate, every native screen edit would draw web-shaped findings that contradict the native refs.

Routing (`reference/routing.md`) encodes the same rule for no-argument menus: if platform is native, do not lead with `live` or detect.

## Native platform expectations (summary)

### iOS (`reference/ios.md`)

Applies to SwiftUI, UIKit, React Native, Expo, and Flutter shipping to Apple hardware.

- Safe-area layout; system tab bar / nav stack / sheets
- Edge-swipe back stays alive; 44×44 pt minimum targets
- Dynamic Type + San Francisco for UI; semantic system colors; Dark Mode first-class
- Platform controls and SF Symbols; system transitions; honor Reduce Motion

### Android (`reference/android.md`)

Applies to Jetpack Compose, Views, React Native, Expo, and Flutter shipping to Android hardware.

- Material navigation by size (bar / rail / drawer); system Back always works
- Edge-to-edge with window insets; 48×48 dp targets
- Material type scale and color roles; Dynamic Color where it fits
- Material components and motion; honor Remove animations

### Adaptive

Loads **both** refs. Cross-platform code must still honor each OS's guarantees on that hardware (for example: even a Material-themed app on iPhone still owes safe-area insets, Reduce Motion, and edge-swipe back).

## Native evidence vs declared web

Tier-1 boot staleness (`checkNativePlatformEvidence`) only fires when the project **resolves to web** (explicit `web` or missing platform) but the tree shows native build evidence, for example:

- `pubspec.yaml` (Flutter → suggest `adaptive`)
- `ios/Podfile`, `ios/Runner.xcodeproj` → suggest `ios`
- `android/build.gradle` / `.kts` → suggest `android`
- `react-native`, `expo`, `@react-native/metro-config` dependencies → suggest `adaptive`

Finding id: `platform-native-evidence`, severity `mention`. Fix: ask whether `## Platform` should be the suggested value; if yes, write it and load the matching native reference before designing. Explicit native values are not re-checked this way.

## Worked examples

| Project | Mode on this task | Platform | What loads / what is blocked |
|---|---|---|---|
| SaaS marketing landing page | Persuade | `web` | General rules; live + detect allowed |
| Same SaaS app settings screen | Operate | `web` | `operate.md` depth; live + detect allowed |
| Product docs site | Read | `web` | Read mode + operate typography/consistency notes |
| iOS SwiftUI client | Operate (most screens) | `ios` | `ios.md` inlined; `audit.native` / `adapt.native`; no live/detect/hook scan |
| Flutter app with distinct iOS and Android chrome | Depends on surface | `adaptive` | Both native refs; web tooling off |
| Flutter app Material-everywhere on both OSes | Depends on surface | `android` (or the single language it actually uses), **not** `adaptive` | One platform ref |

## Verification checklist

After changing platform or starting a native project:

1. `PRODUCT.md` has `## Platform` with exactly one bare value.
2. `node <skill>/scripts/context.mjs` output includes the expected `# NATIVE PLATFORM REFERENCE: …` block(s), or none for web.
3. Unrecognized values produce a WARNING, not silent web guidance.
4. Native sessions do not receive `MANUAL_DETECTOR_REQUIRED` and do not run the design hook scan.
5. Surface briefs under `.impeccable/surfaces/` carry visitor mode for that surface only; no `## Register` on PRODUCT.md.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Web slop rules on RN/Flutter edits | Platform missing or `web` | Set `## Platform` to `ios`, `android`, or `adaptive` |
| No iOS/Android guidance after init-less session | `context.mjs` ran before PRODUCT.md existed | After writing platform, load the native ref(s) yourself, or re-run context once PRODUCT.md is present |
| WARNING for `flutter` / `react-native` | Toolchain name in Platform | Replace with design language: `ios`, `android`, or `adaptive` |
| Live offered on a native app | Routing ignored platform | Treat live as web-only; use native audit/adapt and platform refs |
| Mode "stuck" on brand vs product | Legacy `## Register` | Remove Register; set mode on the surface brief |
| Material app marked adaptive but ships one look | Misclassified adaptive | Use the single platform that matches the shipped language |

## Related pages

<CardGroup cols={2}>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md Platform field, surface briefs, schema stamps, and deprecated Register.
  </Card>
  <Card title="Initialize product context" href="/init-and-document">
    Interview flow that records Platform and loads native refs on first write.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    Native command variants, no-argument menu, and when live/detect are suppressed.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Web-only live mode, roots, and platform constraints.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Native-platform skip behavior and detector hook controls.
  </Card>
  <Card title="Skill commands reference" href="/skill-commands-reference">
    Full command catalog including audit.native and adapt.native.
  </Card>
</CardGroup>

---

## 05. Project artifacts

> PRODUCT.md, DESIGN.md, design.json sidecar, surface briefs, `.impeccable/` layout, schema stamps, deprecated sections, and context resolution order.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/05-project-artifacts.md
- Generated: 2026-08-05T07:33:32.967Z

### Source Files

- `skill/scripts/context.mjs`
- `skill/scripts/lib/artifact-schema.mjs`
- `skill/scripts/lib/impeccable-paths.mjs`
- `skill/scripts/lib/surface-briefs.mjs`
- `skill/scripts/lib/staleness.mjs`
- `skill/reference/init.md`
- `skill/reference/document.md`

---
title: "Project artifacts"
description: "PRODUCT.md, DESIGN.md, design.json sidecar, surface briefs, `.impeccable/` layout, schema stamps, deprecated sections, and context resolution order."
---

Impeccable persists durable project context as markdown and JSON under the active project root and `.impeccable/`. Session boot loads that material through `skill/scripts/context.mjs` (`loadContext` / CLI), injects matching platform references when `## Platform` is native, resolves a surface brief when the target is unambiguous, and emits machine-readable directives (`NO_PRODUCT_MD`, `RESOLVED_CONTEXT`, `CONTEXT_STALE`, and related) that route Setup and design commands.

## Artifact map

| Artifact | Canonical path | Owner command | Role |
| --- | --- | --- | --- |
| Product record | `PRODUCT.md` (also `Product.md` / `product.md`) | `init` | Durable product truth: users, purpose, positioning, platform, constraints |
| Design system | `DESIGN.md` (also `Design.md` / `design.md`) | `document` (scan/seed); new-work finish path | Durable visual system; optional YAML token frontmatter + eight canonical sections |
| Design sidecar | `.impeccable/design.json` | `document` Step 4b | Extensions Stitch frontmatter cannot hold: ramps, shadows, motion, breakpoints, HTML/CSS snippets, narrative |
| Surface briefs | `.impeccable/surfaces/<slug>.md` | new-work / shape persistence via `surface-brief.mjs` | Per-surface strategy (mode, job, direction); not global product or tokens |
| Shared config | `.impeccable/config.json` | CLI / hook / detector writers | Detector ignores, hook limits, `projectRoots`, update/staleness toggles |
| Local config | `.impeccable/config.local.json` | Local overrides | Same key space as shared config; machine-local |
| Live state | `.impeccable/live/` | live setup + runtime | `config.json`, `server.json`, `sessions/`, `annotations/` |
| Critique store | `.impeccable/critique/` | critique flows | Critique artifacts (path helper in `impeccable-paths.mjs`) |

Authority split:

- **PRODUCT.md** — product facts only. No palettes, type systems, or surface mode.
- **DESIGN.md** — visual system only. No page strategy or visitor mode.
- **Surface brief** — one route/file/URL: mode, audience, job, chosen direction, open decisions.
- **design.json** — machine extensions of DESIGN.md, not a second product record.

```text
project root
├── PRODUCT.md
├── DESIGN.md
└── .impeccable/
    ├── config.json
    ├── config.local.json          # optional local overrides
    ├── design.json                # canonical sidecar (schemaVersion 2)
    ├── surfaces/
    │   └── <slug>.md              # frontmatter + brief body
    ├── critique/
    └── live/
        ├── config.json
        ├── server.json
        ├── sessions/
        └── annotations/
```

Legacy locations still resolved for read, migrated on write when severity is `auto`:

| Legacy path | Canonical path |
| --- | --- |
| `DESIGN.json` (project or context dir) | `.impeccable/design.json` |
| `.impeccable-live.json` | `.impeccable/live/server.json` |
| `.impeccable-live/sessions|annotations` | `.impeccable/live/sessions|annotations` |
| skill `scripts/config.json` (live) | `.impeccable/live/config.json` (unless `IMPECCABLE_LIVE_CONFIG` is set) |

## PRODUCT.md

Written by `init`. Never written by `document`. New files land at `PROJECT_ROOT/PRODUCT.md`; updates use the path `context.mjs` already resolved so monorepo children do not fork a second authority without confirmation.

### Schema stamp

```html
<!-- impeccable:product-schema 1 -->
```

| Constant / API | Value / behavior |
| --- | --- |
| `PRODUCT_SCHEMA_VERSION` | `1` |
| `productStampLine(version)` | Emits the HTML comment line |
| `readProductSchemaVersion(markdown)` | Integer or `null` if unstamped |
| `stampProductSchema(markdown, version)` | Idempotent add/replace; keeps stamp in place when present; otherwise inserts under the leading `#` heading |

Schema versions track **record shape**, not skill release. A PRODUCT.md from skill v4.0.0 is not stale under v4.0.1 unless the template changes.

Missing stamp means "written before stamping existed", not invalid. Boot treats unstamped files without any v4 section markers as legacy product records.

### Section template (v4)

Bare-value field: **`## Platform`** is a single line: `web` | `ios` | `android` | `adaptive`.

| Section | Required content |
| --- | --- |
| Platform | Bare platform value |
| Stack | Greenfield stack choice only; omit when the codebase already answers |
| Users | Primary users, situation, job |
| Product Purpose | What it does, why, success |
| Positioning | Mechanism a neighbor cannot copy |
| Operating Context | Workflows, environments, tools, materials |
| Capabilities and Constraints | Confirmed functionality, constraints, undecided facts |
| Brand Commitments | Binding name/voice/assets; omit when none |
| Evidence on Hand | Real assets/proof with paths; absences that must not be fabricated |
| Product Principles | 3–5 durable strategic principles (not visual recipes) |
| Accessibility & Inclusion | Product-specific needs; omit when none established |

`PRODUCT_V4_SECTIONS` used as the legacy fallback when no stamp is present: `Positioning`, `Operating Context`, `Evidence on Hand`, `Product Principles`.

Omit irrelevant sections rather than inventing prose. Record undecided facts as open; do not invent testimonials, pricing, or deployment claims.

### Platform extraction

`extractPlatform(product)` reads the first non-empty line under `## Platform`:

| Input | Result |
| --- | --- |
| `web` / `ios` / `android` / `adaptive` | That value |
| Line naming both `ios` and `android` (list separators, `and`, etc.) | `adaptive` |
| Empty / missing section | `null` → skill treats as **web** |
| Unrecognized value (toolchain names, typos) | `null` + boot `WARNING` that the project is treated as `web` |

Native values cause `context.mjs` to inline `reference/ios.md` and/or `reference/android.md` into boot output. `adaptive` loads both.

### Deprecated sections

| Heading | Status |
| --- | --- |
| `## Register` | Deprecated. v4 replaced brand/product register with per-surface visitor modes (Persuade, Operate, Read, Experience). Nothing reads Register. |

Boot finding id: `product-deprecated-register` (`severity: mention`). Treat the section as absent; offer deletion; do not let the value steer design.

## DESIGN.md

Follows the external [DESIGN.md format](https://raw.githubusercontent.com/google-labs-code/design.md/main/docs/spec.md). **No product-schema stamp** — by design, so Stitch lint stays clean. Staleness uses sidecar schema version, sidecar mtime vs DESIGN.md mtime, section coverage, and deeper doctor proxies.

### Frontmatter (normative tokens)

Allowed top-level token groups: `colors`, `typography`, `rounded`, `spacing`, `components` (plus `name` / `description`). Token refs use `{path.to.token}`. Component sub-tokens are limited to eight props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, and backdrop filters do not belong in frontmatter.

### Body sections (fixed order)

1. Overview  
2. Colors  
3. Typography  
4. Layout  
5. Elevation & Depth  
6. Shapes  
7. Components  
8. Do's and Don'ts  

Omit unused sections; do not rename headings.

### Document modes

| Mode | When | Sidecar |
| --- | --- | --- |
| Scan (default) | Tokens/components/rendered output exist | Write/regenerate `.impeccable/design.json` |
| Seed | Pre-implementation scaffold after product truth exists | Skip sidecar; seed marker comment in DESIGN.md |

Do not silently overwrite an existing DESIGN.md; confirm refresh, overwrite, or merge.

## design.json sidecar

Canonical path: `.impeccable/design.json`. Candidates (first existing wins for reads):

1. `<projectRoot>/.impeccable/design.json`
2. `<projectRoot>/DESIGN.json`
3. `<contextDir>/DESIGN.json` when distinct

`DESIGN_SIDECAR_SCHEMA_VERSION` is **2**.

### schemaVersion 2 shape

```json
{
  "schemaVersion": 2,
  "generatedAt": "ISO-8601",
  "title": "Design System: …",
  "extensions": {
    "colorMeta": {},
    "typographyMeta": {},
    "shadows": [],
    "motion": [],
    "breakpoints": []
  },
  "components": [],
  "narrative": {
    "northStar": "",
    "overview": "",
    "keyCharacteristics": [],
    "rules": [],
    "dos": [],
    "donts": []
  }
}
```

| Field | Purpose |
| --- | --- |
| `extensions.colorMeta.<token>` | `role`, `displayName`, `canonical`, `tonalRamp` keyed by frontmatter color name |
| `extensions.typographyMeta.<token>` | Display names / purpose for type roles |
| `extensions.shadows` / `motion` / `breakpoints` | Tokens frontmatter cannot hold |
| `components[]` | Self-contained `html` + `css` for shadow-DOM panel render; `refersTo` maps to frontmatter component keys; classes prefixed `ds-` |
| `narrative` | North star, overview, rules, do/don'ts pulled from DESIGN.md prose |

**v1 → v2:** primitives moved to DESIGN.md frontmatter. Old sidecar `tokens.*` arrays are obsolete; outdated sidecars get finding `design-sidecar-schema-outdated` and should be regenerated with `document`.

## Surface briefs

Location: `.impeccable/surfaces/`. Version constant: `SURFACE_BRIEF_VERSION = 1`.

### Target normalization

| Input | Normalized form |
| --- | --- |
| Project-relative file | POSIX relative path from project root |
| Absolute path inside project | Relative path |
| `/route` (when not a real project file) | `route:/route` |
| `route:/…` | Normalized route (no `..`, strip query/hash) |
| `https://…` | Origin + path, no hash/search, no trailing slash |

Path for a target: `.impeccable/surfaces/<slug>.md` where slug is derived from the normalized target.

### Frontmatter written by `writeSurfaceBrief`

```yaml
---
version: 1
slug: "…"
primary_target: "src/pages/index.astro"
related_targets: []
---
```

Body stays small: scope and visitor mode; audience, job, action/task, proof/content, constraints; chosen direction and memorable moment; unresolved decisions. Do not copy PRODUCT.md facts or DESIGN.md tokens.

### CLI helper

```bash
node skill/scripts/surface-brief.mjs path <target>
node skill/scripts/surface-brief.mjs list
node skill/scripts/surface-brief.mjs read [target]
node skill/scripts/surface-brief.mjs write <primary-target> <body-file> [related-target ...]
```

### Resolution reasons (`resolveSurfaceBrief`)

| Reason | Meaning |
| --- | --- |
| `only-brief` | No target; exactly one brief exists → use it |
| `ambiguous` | No target; multiple briefs → none selected |
| `slug` | Exact path match for normalized target |
| `mapping` | Unique brief lists the target in primary/related |
| `ambiguous-target` | Multiple briefs claim the target |
| `not-found` / `invalid-target` / `none` | No usable brief |

Boot injects `# SURFACE BRIEF (path)` when one brief is selected. Otherwise, if candidates exist: `SURFACE_CONTEXT_AVAILABLE` with candidate JSON and instructions to run `surface-brief.mjs read`.

Orphaned file targets (primary path missing on disk) produce finding `surface-brief-orphaned` (`mention`). Route and URL primaries are not filesystem-checked.

## Context resolution order

Implemented in `resolveContext` / `loadContext` (`context.mjs`). First match wins per file class.

1. **Active project root** — directory selected by cwd, monorepo workspace child, or `--target` nearest context root. Looks for PRODUCT/DESIGN names in the root, then `.agents/context/`, then `docs/`.
2. **Repo-root inheritance** — when `projectRoot ≠ repoRoot` (monorepo or nested product), the same local search runs at the repo root as a **per-file fallback** (product and design can come from different levels).
3. **`IMPECCABLE_CONTEXT_DIR`** — absolute or cwd-relative escape hatch; only when neither product nor design was found above.
4. **Default** — if nothing found, `contextDir` is the active `projectRoot` and boot emits `NO_PRODUCT_MD` (and optionally visual-system directives).

Monorepo detection: workspace package-manager manifests, marker files (`pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`), and/or `.impeccable/config.json` `projectRoots` globs.

### Boot output shape

When PRODUCT exists, stdout concatenates (separated by `---`):

1. `# PRODUCT.md` body  
2. `# DESIGN.md` body if present  
3. Surface brief block or `SURFACE_CONTEXT_AVAILABLE`  
4. `RESOLVED_CONTEXT` JSON (`projectRoot`, `repoRoot`, paths, platform, surface brief reason/candidates, `hasVisualImplementation`)  
5. Native platform reference blocks when platform is ios/android/adaptive  
6. Gap directives (`INCUMBENT_WORLD_UNDOCUMENTED`, `WORLD_DISCOVERY_REQUIRED`, …)  
7. Staleness / update directives when applicable  

When PRODUCT is missing, boot still prints DESIGN.md if present (so a later init in-session does not lose visual authority) plus `NO_PRODUCT_MD` / `PRODUCT_INIT_REQUIRED` or the visual-incumbent variants.

`loadContext()` returns the structured form used by live scripts without requiring stdout parsing.

## Schema stamps and staleness

Three drift kinds:

| Kind | Owner | Typical fix |
| --- | --- | --- |
| Tool version | `computeUpdateDirective` in `context.mjs` | `npx impeccable update` |
| Schema | Tier 1 `collectBootFindings` / doctor | `init`, `document`, auto migrate |
| Truth | Human + `document` / `init` | Rewrite from interview or code |

Finding shape: `{ id, artifact, path, severity, summary, fix }`.

| Severity | Behavior |
| --- | --- |
| `auto` | Fix on next write; never shown to the user at boot |
| `mention` | State once (throttled ~weekly per project) |
| `route` | Name the owning command (`init`, `document`, …) |

### Tier 1 boot findings (cheap)

| Id | Artifact | Severity |
| --- | --- | --- |
| `product-deprecated-*` | PRODUCT.md | mention |
| `product-schema-legacy` | PRODUCT.md | route → `init` |
| `product-schema-outdated` | PRODUCT.md | route → `init` |
| `platform-native-evidence` | PRODUCT.md | mention (web resolve vs native files/deps) |
| `design-sidecar-legacy-path` | design.json | auto |
| `design-sidecar-schema-outdated` | design.json | route → `document` |
| `design-sidecar-stale` | design.json | mention (DESIGN.md newer than sidecar) |
| `config-unknown-keys` / `config-unknown-detector-keys` | config | mention |
| `surface-brief-orphaned` | surface brief | mention |
| `config-project-roots-match-nothing` | config | mention |

Opt out: `"stalenessCheck": false` in config, or `IMPECCABLE_NO_STALENESS_CHECK=1`. Tier 2 (git, ignore-list validation, deeper truth proxies) is on-demand via `doctor`.

## Config keys that touch artifacts

Recognized top-level keys in `.impeccable/config.json` and `config.local.json`:

| Key | Role |
| --- | --- |
| `hook` | Hook enablement and limits |
| `detector` | `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem`, `extensions` |
| `updateCheck` | Skill update polling |
| `stalenessCheck` | Boot staleness gate |
| `projectRoots` | Monorepo workspace globs for active-project discovery |
| `$schema`, `version` | Metadata only |

Unknown top-level or detector keys are reported; they do not apply.

## Environment variables

| Variable | Effect on artifacts / context |
| --- | --- |
| `IMPECCABLE_CONTEXT_DIR` | Alternate PRODUCT/DESIGN directory when defaults are empty |
| `IMPECCABLE_LIVE_CONFIG` | Override live config path |
| `IMPECCABLE_NO_STALENESS_CHECK` | Disable boot Tier 1 staleness emission |
| `IMPECCABLE_UPDATE_HOST` / `IMPECCABLE_UPDATE_CACHE` | Skill version check (not project artifacts) |

## Troubleshooting

| Symptom | Check |
| --- | --- |
| `NO_PRODUCT_MD` every session | File name case (`PRODUCT.md` / `Product.md` / `product.md`), fallback dirs, monorepo `--target` / child cwd |
| Wrong app’s PRODUCT in monorepo | Rerun with active child cwd or `--target`; read `RESOLVED_CONTEXT.projectRoot` |
| Native refs never load | `## Platform` missing, typo, or toolchain name instead of `ios`/`android`/`adaptive` |
| Register still steers output | Delete deprecated `## Register`; modes live in surface briefs |
| Live panel shows generic components | Missing or v1 sidecar → run `document` scan mode |
| Sidecar contradicts DESIGN.md | DESIGN.md mtime newer → `document` refresh sidecar only |
| Surface brief not injected | Multiple briefs without unambiguous target → pass target or `surface-brief.mjs read` |
| `projectRoots` ignored | Patterns match nothing → boot finding; repo root becomes active project |

## Next

<CardGroup>
  <Card title="Initialize product context" href="/init-and-document">
    Interview and write PRODUCT.md, document DESIGN.md, optional live config.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Visitor modes and platform values that govern which references load.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Full `.impeccable/config.json` and live config field list.
  </Card>
  <Card title="Doctor" href="/doctor">
    Tier 1/2 staleness findings, auto fixes, and opt-out.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    How Setup consumes context boot output and routes sub-commands.
  </Card>
</CardGroup>

---

## 06. Commands and routing

> Single `/impeccable` skill, 23 sub-commands, Setup load order, no-argument routing, craft-floor gate, and when native command variants replace web references.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/06-commands-and-routing.md
- Generated: 2026-08-05T07:33:35.780Z

### Source Files

- `skill/SKILL.src.md`
- `skill/reference/routing.md`
- `skill/reference/craft-floor.md`
- `skill/scripts/command-metadata.json`
- `skill/scripts/context-signals.mjs`
- `scripts/lib/utils.js`
- `scripts/lib/skill-categories.js`

---
title: "Commands and routing"
description: "Single `/impeccable` skill, 23 sub-commands, Setup load order, no-argument routing, craft-floor gate, and when native command variants replace web references."
---

Impeccable exposes **one** user-invocable skill, `impeccable`, with **23** design sub-commands listed in the Commands table of `skill/SKILL.src.md` (built to provider `SKILL.md`). Invocation is always `{{command_prefix}}impeccable [subcommand] [target]` (for example `/impeccable polish src/App.tsx`). Routing is agent-driven: Setup runs once, then the agent loads the matching `skill/reference/<command>.md` playbook (or a `.native.md` variant on native platforms). Utility surfaces (`pin`, `hooks`, `doctor`) live outside that table and do not count toward 23.

## Architecture: single skill, reference playbooks

```text
User: /impeccable [arg]
        │
        ▼
┌───────────────────────────────────────┐
│ Setup (every session, once)           │
│ 1. node …/context.mjs [--target path] │
│ 2. Load playbook (command | new-work) │
│ 3. craft-floor.md only before UI edit │
└───────────────────────────────────────┘
        │
   ┌────┴────────────────────────────┐
   │ arg empty?                      │
   ▼                                 ▼
reference/routing.md          explicit / implied command
context-aware menu            → reference/<cmd>.md
(+ context-signals.mjs)         or <cmd>.native.md
never auto-run                  on ios/android/adaptive
   │                                 │
   └──────── general design ─────────┘
            missing PRODUCT.md → init then new-work
            narrow refine → incumbent + offer init
```

| Surface | Role | Counts as design command? |
|---|---|---|
| `/impeccable <cmd>` | 23-row Commands table + `command-metadata.json` | Yes |
| `reference/new-work.md` | Shared playbook for new surfaces / replacement visual worlds | No (loaded by routing, not a table row) |
| `reference/craft-floor.md` | Quality floor + bans loaded immediately before UI edits | No |
| `reference/routing.md` | Bare `/impeccable` menu | No |
| `pin` / `hooks` / `doctor` | Maintenance utilities (SKILL body + refs, not Commands table) | No |

Source of truth for the **count of 23** is the router table in `skill/SKILL.src.md` (build validates README/plugin descriptions against that match). Each row maps to `skill/reference/<name>.md`. Metadata for pin shortcuts and argument-hint text lives in `skill/scripts/command-metadata.json` (also 23 keys, including deprecated `craft`).

## Commands table (23)

Categories below match the SKILL Commands table (user-facing labels). Build-time argument-hint grouping uses a separate map in `scripts/lib/skill-categories.js` (`create` / `evaluate` / `refine` / `simplify` / `harden` / `system`); `craft` is intentionally unmapped there so it stays out of the generated hint while still routing.

| Command | Category | Reference | Notes |
|---|---|---|---|
| `craft [feature]` | Build | `craft.md` | Deprecated alias for ordinary new-work; no extra behavior |
| `shape [feature]` | Build | `shape.md` | Task discovery; enters new-work only for visual-world decisions |
| `init` | Build | `init.md` | Writes PRODUCT.md; `teach` is an alias |
| `document` | Build | `document.md` | Generate DESIGN.md from code |
| `extract [target]` | Build | `extract.md` | Tokens / components into the system |
| `critique [target]` | Evaluate | `critique.md` | UX review + scoring |
| `audit [target]` | Evaluate | `audit.md` · **native:** `audit.native.md` | Technical quality report |
| `polish [target]` | Refine | `polish.md` | Pre-ship quality pass |
| `bolder [target]` | Refine | `bolder.md` | Amplify bland designs |
| `quieter [target]` | Refine | `quieter.md` | Tone down aggressive UI |
| `distill [target]` | Refine | `distill.md` | Strip to essence |
| `harden [target]` | Refine | `harden.md` | Errors, i18n, edge cases |
| `onboard [target]` | Refine | `onboard.md` | First-run / empty states |
| `animate [target]` | Enhance | `animate.md` | Motion (platform refs on native) |
| `colorize [target]` | Enhance | `colorize.md` | Strategic color |
| `typeset [target]` | Enhance | `typeset.md` | Type hierarchy |
| `layout [target]` | Enhance | `layout.md` | Spacing / rhythm |
| `delight [target]` | Enhance | `delight.md` | Memorable touches |
| `overdrive [target]` | Enhance | `overdrive.md` | Ambitious visual techniques |
| `clarify [target]` | Fix | `clarify.md` | UX copy |
| `adapt [target]` | Fix | `adapt.md` · **native:** `adapt.native.md` | Devices / contexts |
| `optimize [target]` | Fix | `optimize.md` | UI performance |
| `live` | Iterate | `live.md` | Browser variant mode (**web only**) |

Full argument hints and catalog copy: [Skill commands reference](/skill-commands-reference).

### Placeholders and suggestion lists

| Placeholder / list | Built from | Purpose |
|---|---|---|
| `{{command_hint}}` in skill frontmatter `argument-hint` | Keys of `command-metadata.json` grouped by `SKILL_CATEGORIES` | Autocomplete-style hint on the parent skill |
| `{{available_commands}}` | `IMPECCABLE_SUB_COMMANDS` in `scripts/lib/utils.js` (subset: design refine/evaluate/enhance names, not `init`/`document`/`live`/etc.) | In-body “next command” suggestions after transforms |
| `pin.mjs` `VALID_COMMANDS` | Same 23 names (incl. `craft`) | Standalone `/audit`-style shortcuts |

## Setup load order

Setup is non-optional and runs once per session before design work.

<Steps>
<Step title="Run context.mjs">
Execute `node {{scripts_path}}/context.mjs` once (keep cwd at the user project). Optional: `--target <path-or-route>` for a named surface. Loads PRODUCT.md, DESIGN.md, the matching surface brief, and inlines native platform guidance when `## Platform` is `ios`, `android`, or `adaptive`. Follow emitted directives; do not rerun. After `init` writes PRODUCT.md mid-session, resume **without** rerunning context; init loads the native platform reference itself for the platform it recorded.
</Step>
<Step title="Load the owning playbook">
Before acting: load the Commands-table reference for an explicit or clearly implied sub-command, **or** `reference/new-work.md` for a new surface / replacement visual world. Then inspect the target and at least one incumbent visual source (tokens, theme, CSS, component, or asset).
</Step>
<Step title="Load craft-floor only when editing UI">
After analysis and direction are resolved, load `reference/craft-floor.md` immediately before editing UI. Skip it for planning-only work.
</Step>
</Steps>

<Note>
`context.mjs` may emit `NO_PRODUCT_MD`, platform `WARNING` for unrecognized `## Platform` values (fallback: web), `CONTEXT_STALE` (Tier-1 drift; act only as directed—do not repair drift as a side quest of a design task unless severity is `auto`), and web-only detector/hook guidance.
</Note>

## Routing rules

From the Commands section of SKILL:

| Condition | Agent behavior |
|---|---|
| **No argument** | Load `reference/routing.md`; present a context-aware menu. **Never auto-run** a command. |
| **Explicit or clearly implied command** | Load its reference; on native platforms, load the native variant when one exists. Ask once if two commands fit. |
| **Otherwise (general design)** | Treat as general design work. Missing PRODUCT.md for a new surface / replacement world → `init` then new-work. Narrow refinement of existing code proceeds on the incumbent implementation as `context.mjs` directs; offer `init` afterward rather than blocking. |
| **Aliases** | `teach` → `init`. `craft` → ordinary new-work (deprecated, no extra steps). `shape` owns discovery, then new-work only for visual-world / surface-concept decisions. |

### No-argument path (`routing.md` + `context-signals.mjs`)

1. Setup has already run `context.mjs`.
2. If output reported `NO_PRODUCT_MD`: lead with `/impeccable init` (one-line why), still show the full menu; do not silently enter init.
3. Else run `node {{scripts_path}}/context-signals.mjs` once and reason over its JSON (no scores; agent ranks).
4. Lead with **2–3** highest-value commands + one-line reasons, then the full Commands table by category.
5. Optionally, if `scan.targets` is non-empty and platform is not native: run `node {{scripts_path}}/detect.mjs --json <targets>` once and fold hits into picks. On error or slow trees, skip; never block the menu.

#### `context-signals.mjs` JSON shape

| Field | Type | Use in menu reasoning |
|---|---|---|
| `setup.hasProduct` / `hasDesign` / `hasCode` | boolean | Missing design + has code → lead `document` |
| `setup.platform` | `web` \| `ios` \| `android` \| `adaptive` \| null | Gate `live` / detect; native skips HTML tooling |
| `critique.latest` | object \| null | `null` → offer critique; low `score` / non-zero `p0`/`p1` → polish or re-critique |
| `git.changedFiles` | string[] | Scope audit/polish to those files |
| `devServer.running` / `ports` | boolean / number[] | Lead with `live` only when running (web) |
| `scan.targets` / `scan.via` | string[] / `git-changes`\|`source-dir`\|`html`\|`root`\|null | Detect input; dirty markup wins |

Signals probes are best-effort and always print valid JSON. The script does **not** run the detector or score commands.

### Example bare invocation flow

```text
/impeccable
  → Setup: context.mjs
  → if NO_PRODUCT_MD → recommend init
  → else context-signals.mjs
  → optional detect.mjs --json <scan.targets>  (web only)
  → present 2–3 picks + full menu
  → wait for user confirmation
```

## Craft-floor gate

`reference/craft-floor.md` is the quality floor: verify checks (contrast, depth, spacing, type, motion, states, browser surfaces, copy, brief coverage) and refuse lists (scaffold defaults and surface habits). Load it **after** direction is settled and **immediately before** editing UI—not for planning-only work.

| Rule | Behavior |
|---|---|
| Brief wins | Pinned aesthetics override floor defaults; habit does not |
| Hook active | Design hook already enforces mechanical checks; act on findings instead of re-auditing each rule |
| Planning | Do not load craft-floor for analysis-only steps |
| Detector blind spots | Floor covers reflexes the detector does not catch |

When no automatic design hook is active and platform is web, `context.mjs` may emit `MANUAL_DETECTOR_REQUIRED` so the agent runs `detect.mjs` once after UI changes.

## Native command variants

Platform is orthogonal to visitor mode. PRODUCT.md `## Platform` is a bare value: `web` (default if missing), `ios`, `android`, or `adaptive`. Unrecognized values fall back to web with a WARNING. Setup inlines `reference/ios.md` and/or `reference/android.md` for native platforms.

| Situation | Reference loaded |
|---|---|
| `audit` + platform web | `audit.md` only |
| `audit` + `ios` / `android` / `adaptive` | **`audit.native.md` instead of** `audit.md` |
| `adapt` + platform web | `adapt.md` only |
| `adapt` + native | **`adapt.native.md` instead of** `adapt.md` |
| Other commands on native | Shared command ref; per-OS detail from platform refs already loaded by Setup (e.g. motion in `animate`) |
| `live`, bundled `detect.mjs`, design hook | **Web only** — do not lead with or apply on native platforms |

Web files for `audit` and `adapt` open with a one-line web-only guard that redirects native readers to the `.native.md` variant. One native variant covers all three native platform values; OS-specific rules stay in `ios.md` / `android.md`. Report skeleton changes for audit must stay in sync across web and native files.

```text
setup.platform
  web      → reference/audit.md | adapt.md | live OK | detect OK
  ios      → audit.native.md | adapt.native.md | + ios.md   | no live/detect/hook scan
  android  → audit.native.md | adapt.native.md | + android.md
  adaptive → audit.native.md | adapt.native.md | + ios.md + android.md
```

## Utilities outside the 23

| Invocation | Load | Role |
|---|---|---|
| `node {{scripts_path}}/pin.mjs <pin\|unpin> <command>` | — | Create/remove standalone harness shortcuts (e.g. `/audit` → `/impeccable audit`) |
| `/impeccable hooks <on\|off\|status|…>` | `reference/hooks.md` | Design detector hook for the project |
| `/impeccable doctor` | `reference/doctor.md` | Schema/config/proxy drift report and `--fix` for `auto` findings |

These are **not** in `IMPECCABLE_SUB_COMMANDS`, `command-metadata.json` command menus as design entries (doctor is excluded), `SKILL_CATEGORIES` design rows, or the 23-row table. Do not route them as craft commands.

## Constraints and failure modes

| Case | Expected behavior |
|---|---|
| Two commands fit equally | Ask once; do not run both |
| Auto-running after bare `/impeccable` | Incorrect — menu only until user confirms |
| Native project + `live` / detect lead | Incorrect — skip; browser overlay and HTML rules do not apply |
| Loading craft-floor during pure planning | Incorrect — load only before UI edit |
| Replacing design world via polish | Incorrect — redesign uses new-work and replaces DESIGN.md; refinement preserves identity |
| Acting on every `CONTEXT_STALE` finding during craft | Incorrect — report unless user asks; only `auto` applies on next write |
| Adding a 24th design command | Update SKILL table, `IMPECCABLE_SUB_COMMANDS` if needed, `VALID_COMMANDS`, `command-metadata.json`, `SKILL_CATEGORIES`, pin rules, and count validators — see contributing docs |

## Related pages

<CardGroup>
<Card title="Modes and platform" href="/modes-and-platform">
Visitor modes and orthogonal platform values, including native reference loading.
</Card>
<Card title="Skill commands reference" href="/skill-commands-reference">
Catalog of sub-commands, argument hints, categories, and native variants.
</Card>
<Card title="Run design commands" href="/run-design-commands">
Invoke evaluate and refine commands with targets and verification signals.
</Card>
<Card title="Initialize product context" href="/init-and-document">
Init interview, PRODUCT.md Platform, and document DESIGN.md.
</Card>
<Card title="Pin shortcuts" href="/pin-shortcuts">
Standalone harness shortcuts that redirect to `/impeccable <command>`.
</Card>
<Card title="Doctor" href="/doctor">
Artifact drift report and auto fixes outside the design menu.
</Card>
</CardGroup>

---

## 07. Provider harnesses

> Supported AI harness directories, install aliases, frontmatter and hook capability matrix, and provider-specific trust or skills-enable steps.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/07-provider-harnesses.md
- Generated: 2026-08-05T07:33:47.553Z

### Source Files

- `docs/HARNESSES.md`
- `cli/bin/commands/skills.mjs`
- `scripts/lib/transformers/providers.js`
- `scripts/lib/utils.js`
- `skill/scripts/lib/provider.mjs`
- `README.md`

---
title: "Provider harnesses"
description: "Supported AI harness directories, install aliases, frontmatter and hook capability matrix, and provider-specific trust or skills-enable steps."
---

Impeccable ships one skill payload, compiled into provider-specific trees under tracked root harness folders (for example `.claude/skills/impeccable`, `.cursor/skills/impeccable`, `.agents/skills/impeccable`). The CLI installer (`npx impeccable install|link|update`) and the release build both target those trees. Build config lives in `scripts/lib/transformers/providers.js`; install aliases, detection, hooks, and global path overrides live in `cli/bin/commands/skills.mjs`. Capability notes are summarized in `docs/HARNESSES.md` (point-in-time; verify against the live harness before relying on edge claims).

## Supported harness directories

`PROVIDER_DIRS` is the install surface. Each entry is a project-relative config directory that receives `skills/impeccable/` (and hooks/agents where applicable).

| Display name | Install input | Project dir | Primary skills path |
|--------------|---------------|-------------|---------------------|
| Antigravity | `antigravity` | `.agent` | `.agent/skills/` |
| Claude Code | `claude` | `.claude` | `.claude/skills/` |
| Codex CLI | `codex` | `.agents` | `.agents/skills/` |
| Cursor | `cursor` | `.cursor` | `.cursor/skills/` |
| Gemini CLI | `gemini` | `.gemini` | `.gemini/skills/` |
| GitHub Copilot | `github` | `.github` | `.github/skills/` |
| Grok Build | `grok` | `.grok` | `.grok/skills/` |
| Kiro | `kiro` | `.kiro` | `.kiro/skills/` |
| OpenCode | `opencode` | `.opencode` | `.opencode/skills/` |
| Pi Coding Agent | `pi` | `.pi` | `.pi/skills/` |
| Qoder | `qoder` | `.qoder` | `.qoder/skills/` |
| Trae | `trae` | `.trae` | `.trae/skills/` |
| Trae CN | `trae-cn` | `.trae-cn` | `.trae-cn/skills/` |
| Rovo Dev | `rovo-dev` | `.rovodev` | `.rovodev/skills/` |
| Mistral Vibe | `vibe` | `.vibe` | `.vibe/skills/` |

<Note>
Codex CLI is **not** installed under `.codex/skills`. Skills land in `.agents/skills/` (also the Codex primary skill path). Project hooks for Codex still write to `.codex/hooks.json`.
</Note>

### Cross-read paths

Some harnesses also load skills from shared or sibling folders:

| Harness | Also reads |
|---------|------------|
| Cursor | `.agents/skills/`, `.claude/skills/` |
| Gemini CLI | `.agents/skills/` |
| GitHub Copilot | `.agents/skills/`, `.claude/skills/` |
| OpenCode | `.agents/skills/`, `.claude/skills/` |
| Pi | `.agents/skills/` |
| Mistral Vibe | `.agents/skills/` (project), `~/.agents/skills/` (global) |
| Grok Build | `.agents/skills/`, `.claude/skills/`, `.cursor/skills/` (Claude/Cursor compat; configurable) |
| Antigravity | `.agents/skills/` (project), `~/.agents/skills/` (global) |

All supported trees use `{skill-name}/SKILL.md` plus optional `reference/`, `scripts/`, and `assets/`.

### Global skill path overrides

Project scope is always `<provider>/skills` under the project root. Global (user) installs use `<home>/<provider>/skills` except:

| Provider dir | Global skills directory |
|--------------|-------------------------|
| `.agent` (Antigravity) | `~/.gemini/config/skills` |
| `.pi` | `~/.pi/agent/skills` |
| `.opencode` | `$OPENCODE_CONFIG_DIR/skills`, else `$XDG_CONFIG_HOME/opencode/skills`, else `~/.config/opencode/skills` |

Writing OpenCode global skills to `~/.opencode/skills` is a known miss; the CLI uses the config dir above so `opencode debug skill` can list them.

## Install aliases

Pass aliases to `--providers` as comma-separated names (with or without a leading `.`).

| Alias | Resolves to |
|-------|-------------|
| `agent`, `antigravity` | `.agent` |
| `agents`, `codex` | `.agents` |
| `claude`, `claude-code` | `.claude` |
| `cursor` | `.cursor` |
| `gemini` | `.gemini` |
| `github`, `copilot` | `.github` |
| `grok`, `grok-build`, `xai` | `.grok` |
| `kiro` | `.kiro` |
| `opencode` | `.opencode` |
| `pi` | `.pi` |
| `qoder` | `.qoder` |
| `rovo-dev`, `rovodev` | `.rovodev` |
| `trae` | `.trae` |
| `trae-cn` | `.trae-cn` |
| `vibe` | `.vibe` |

Interactive install order (`PROVIDER_INPUT_ORDER`): `antigravity`, `claude`, `codex`, `cursor`, `gemini`, `github`, `grok`, `kiro`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, `vibe`.

When nothing is detected, defaults are `.claude` and `.agents`.

Detection when the project has no harness folder yet walks home hints such as `~/.claude`, `~/.codex` → `.agents`, `~/.gemini/antigravity*` → `.agent`, and OpenCode’s config dir.

## Install commands

```bash
# Detect harnesses, choose providers and project vs global scope
npx impeccable install

# Scripted
npx impeccable install --providers=claude,codex,cursor,grok --scope=project
npx impeccable install --providers=claude --scope=global -y

# Refresh existing installs
npx impeccable update

# Skip hook install for this run (does not rewrite recorded consent)
npx impeccable install --providers=claude --no-hooks

# Submodule / local checkout link
npx impeccable link --source=.impeccable --providers=claude,cursor
```

<ParamField body="--providers" type="string">
Comma-separated install aliases or dir names (for example `claude,cursor` or `.claude,.cursor`).
</ParamField>

<ParamField body="--scope" type="string">
`project` (default for project roots) or `global` (user-level skills dirs).
</ParamField>

<ParamField body="--no-hooks" type="boolean">
Skip design-hook manifest install for this run.
</ParamField>

<ParamField body="-y / --yes" type="boolean">
Non-interactive defaults (hooks default on when consent is unset).
</ParamField>

### Plugin installs (skill + agents + hooks package)

<Tabs>
  <Tab title="Claude Code">
```bash
/plugin marketplace add pbakaus/impeccable
# Then install Impeccable from /plugin
```
  </Tab>
  <Tab title="Grok Build">
```bash
grok plugin install pbakaus/impeccable#plugin --trust
```
The `#plugin` suffix installs the slim package under `plugin/` (skills, agents, hooks), not the full monorepo.
  </Tab>
</Tabs>

Manual `cp -r dist/<provider>/...` remains a fallback. Prefer `npx impeccable install` so hooks and agent sidecars are placed correctly.

## Build provider keys vs install dirs

The transformer factory (`PROVIDERS` in `scripts/lib/transformers/providers.js`) uses build keys that map to config dirs. A few names differ from install aliases:

| Build key | `configDir` | Notes |
|-----------|-------------|--------|
| `claude-code` | `.claude` | Full frontmatter + Claude hooks |
| `cursor` | `.cursor` | `hooks.json` at `.cursor/hooks.json` |
| `codex` | `.codex` | Hooks only; skills emitted under `agents` |
| `agents` | `.agents` | Codex primary skills tree; OpenAI metadata sidecar |
| `github` | `.github` | Copilot skills + `hooks/impeccable.json` |
| `grok` | `.grok` | Skills, agents, `hooks/impeccable.json` |
| `antigravity` | `.agent` | Not `.agents` |
| `gemini`, `kiro`, `opencode`, `pi`, `qoder`, `trae`, `trae-cn`, `rovo-dev`, `vibe` | matching dot-dir | Skills only (no Impeccable hook emission) |

Runtime placeholders (`PROVIDER_PLACEHOLDERS`) set `{{model}}`, `{{config_file}}`, `{{ask_instruction}}`, and `{{command_prefix}}`. Codex uses command prefix `$`; other providers use `/`. Source scripts default to `/` via `IMPECCABLE_COMMAND_PREFIX` in `skill/scripts/lib/provider.mjs`; the provider build rewrites that constant per target.

## Frontmatter capability matrix

Harnesses implement the [Agent Skills](https://agentskills.io/specification) frontmatter set to varying degrees. Impeccable only **emits** the fields listed in each provider’s `frontmatterFields` config; harnesses ignore unknown keys.

Spec fields: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`. Common extensions: `user-invocable`, `argument-hint`, `disable-model-invocation`, `model`, `effort`, `context`, `agent`, `hooks`.

| Field | Claude | Cursor | Gemini | Codex | Copilot | Grok | Kiro | OpenCode | Pi | Qoder | Rovo | Vibe | Antigravity |
|-------|:------:|:------:|:------:|:-----:|:-------:|:----:|:----:|:--------:|:--:|:-----:|:----:|:----:|:-----------:|
| `name` / `description` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| `license` / `compatibility` / `metadata` | Yes | Yes | Ignored | No* | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| `allowed-tools` | Yes | No | Ignored | No* | No | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes |
| `user-invocable` | Yes | No | No | No | Yes | Yes | No | Yes | No | Yes | Yes | Yes | No |
| `argument-hint` | Yes | No | No | No | Yes | Yes | No | Yes | No | Yes | Yes | No | No |
| `model` / `effort` | Yes | No | No | No | No | Yes | No | model only | No | No | No | No | No |

\*Codex skill body frontmatter is minimal; richer metadata goes to `agents/openai.yaml` when `writeOpenAIMetadata` is set. Grok also documents `when-to-use` as a supported extension.

**Impeccable emission** (what the build writes), by provider config:

| Provider | Emitted optional frontmatter beyond name/description |
|----------|------------------------------------------------------|
| Claude Code, OpenCode, Qoder, Rovo Dev, Grok | `user-invocable`, `argument-hint`, `license`, `compatibility`, `metadata`, `allowed-tools` |
| GitHub Copilot, Trae, Trae CN | `user-invocable`, `argument-hint`, `license`, `compatibility`, `metadata` |
| Cursor, Kiro | `license`, `compatibility`, `metadata` |
| Pi, Antigravity | `license`, `compatibility`, `metadata`, `allowed-tools` |
| Vibe | `user-invocable`, `license`, `compatibility`, `metadata`, `allowed-tools` |
| Gemini, Codex, agents | none (Codex/agents use OpenAI metadata sidecar) |

Runtime variable substitution inside skill bodies (`$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, …) is Claude Code–specific. Cross-provider text uses compile-time `{{placeholders}}` only.

## Design hook matrix

Impeccable installs hooks only for harnesses with a documented on-disk hook format. Other providers still get skills and commands.

| Harness | When | Manifest path | Script | Trust / enable |
|---------|------|---------------|--------|----------------|
| Claude Code | After edit (`PostToolUse`) | `.claude/settings.local.json` (gitignored); shared `settings.json` honored if the hook was moved there | `${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs` | Project trust as usual for Claude settings |
| Cursor | Before write (`preToolUse`) | `.cursor/hooks.json` | `.cursor/skills/impeccable/scripts/hook-before-edit.mjs` | Enable Agent Skills (Nightly/Beta setup below); reload if hooks do not pick up |
| Codex CLI | After edit | `.codex/hooks.json` (skill payload under `.agents`) | `.agents/skills/impeccable/scripts/hook.mjs` | Open `/hooks` after install/update and approve; definition changes can re-prompt; hooks flagged feature, disabled on Windows |
| GitHub Copilot | After edit | `.github/hooks/impeccable.json` (team-shared) | `.github/skills/impeccable/scripts/hook.mjs` | File on default branch + folder trust (CLI/cloud agent) |
| Grok Build | After edit + Stop deep pass | `.grok/hooks/impeccable.json` | `.grok/skills/impeccable/scripts/hook.mjs` | `/hooks-trust` or launch with `--trust` |
| All others | — | n/a | — | Skill-only install |

Claude/Codex/Copilot/Grok surface findings after edits (and Stop where supported). Cursor can **block** proposed writes that fail the detector.

### Hook consent

On interactive `install`/`update`, Impeccable explains the design hook and asks once (default yes). The answer is stored per developer in gitignored `.impeccable/config.local.json` via `getHookConsent` / `setHookConsent`. Recorded `declined` skips forever until consent is cleared; `--no-hooks` skips only that run without recording. Non-interactive runs default to installing hooks when consent is unset.

Malformed hook manifests abort install by default; `--force` backs up the file as `.bak` and replaces it. Unrelated hook entries are preserved when merging.

## Native subagent emission

Impeccable writes native agent files only where the on-disk format is stable:

| Harness | Location | Format |
|---------|----------|--------|
| Claude Code | Plugin `agents/` (marketplace / `plugin/`) | Markdown + YAML frontmatter |
| Grok Build | Plugin + project `.grok/agents/` | Markdown + YAML (Claude-compatible) |
| Codex CLI | Nested `<skill>/agents/` (auto-discovered with skill) | TOML |
| Cursor | `.cursor/agents/impeccable-*.md` (user: `~/.cursor/agents/`) | Markdown |
| GitHub Copilot | `.github/agents/impeccable-*.agent.md` (user: `~/.copilot/agents/`) | `.agent.md`; user-level can shadow project |

Canonical prompts live under `skill/agents/`. Spawn behavior differs: Claude and Grok can spawn programmatically; Codex requires user-allowed sub-agents; Cursor auto-delegates or uses `/name` and is not reliably skill-spawnable.

## Provider-specific trust and enable steps

<Steps>
  <Step title="Cursor skills enable">
    1. Cursor Settings → Beta → Nightly channel.
    2. Settings → Rules → enable **Agent Skills**.
    3. Install with `npx impeccable install --providers=cursor`.
    4. Reload Cursor if skills or hooks do not appear.
  </Step>
  <Step title="Codex hooks approve">
    1. Install with `npx impeccable install --providers=codex` (skills → `.agents`, hooks → `.codex/hooks.json`).
    2. In Codex, open `/hooks` and approve the project hook.
    3. Re-approve after updates that change the hook definition.
  </Step>
  <Step title="Grok folder trust">
    1. Prefer `npx impeccable install --providers=grok` or `grok plugin install pbakaus/impeccable#plugin --trust`.
    2. Run `/hooks-trust` once per project folder, or start the session with `--trust`.
    3. Grok can also load Claude layouts (`.claude/skills/`, Claude plugins) without native paths.
  </Step>
  <Step title="Claude marketplace plugin">
    1. `/plugin marketplace add pbakaus/impeccable`.
    2. Install from the plugin UI.
    3. Project CLI installs still place machine-local hooks in `.claude/settings.local.json`.
  </Step>
  <Step title="GitHub Copilot shared hook">
    1. Install with `--providers=github` so `.github/skills` and `.github/hooks/impeccable.json` exist.
    2. Commit the hook file; ensure it is on the default branch and the folder is trusted.
  </Step>
</Steps>

## Generated layout (conceptual)

```text
project/
├── .claude/skills/impeccable/     # Claude Code skill
│   └── scripts/hook.mjs
├── .claude/settings.local.json    # Claude hook (machine-local)
├── .cursor/skills/impeccable/
│   └── scripts/hook-before-edit.mjs
├── .cursor/hooks.json
├── .agents/skills/impeccable/     # Codex + universal skills tree
├── .codex/hooks.json              # Codex hooks (sidecar to .agents)
├── .github/skills/impeccable/
├── .github/hooks/impeccable.json
├── .grok/skills/impeccable/
├── .grok/hooks/impeccable.json
└── .impeccable/config.local.json  # hook consent (gitignored)
```

Tracked root harness folders in this repository are **generated distribution artifacts**. Edit `skill/` and rebuild; do not hand-edit provider trees in normal development PRs.

## Verification

| Check | Signal |
|-------|--------|
| Skill present | `<provider>/skills/impeccable/SKILL.md` exists for each installed target |
| Claude hook | `.claude/settings.local.json` (or `settings.json`) references `skills/impeccable/scripts/hook.mjs` |
| Cursor hook | `.cursor/hooks.json` references `hook-before-edit.mjs` |
| Codex hook | `.codex/hooks.json` points at `.agents/skills/impeccable/scripts/hook.mjs` and is approved in `/hooks` |
| Grok hook | `.grok/hooks/impeccable.json` present; session trusted |
| Invoke | `/impeccable` (or `$impeccable` on Codex-built skill text) lists or runs the skill after harness reload |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Skill missing after install | Wrong provider alias or scope | Pass explicit `--providers=...`; confirm project vs global dir |
| OpenCode global skill invisible | Skills under `~/.opencode` | Install global into OpenCode config dir (`OPENCODE_CONFIG_DIR` / XDG / `~/.config/opencode`) |
| Codex hook silent | Not trusted or wrong script path | Approve in `/hooks`; confirm script under `.agents/skills/...` |
| Grok hooks never run | Folder not trusted | `/hooks-trust` or `--trust` |
| Cursor skills ignored | Skills feature off | Nightly + Agent Skills enable; reload |
| Two providers share one realpath | Symlinked skill dirs | Installer deduplicates by realpath; update once per unique path |
| Malformed hooks.json aborts install | Bad pre-existing manifest | Fix manually or `install`/`update` with `--force` |

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Install, link, update, scope, and hook consent end-to-end.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Detector-on-edit behavior, quiet/disable controls, native-platform skip.
  </Card>
  <Card title="Plugin agents" href="/plugin-agents">
    Bundled agents and plugin manifest contract for Claude Code and Grok.
  </Card>
  <Card title="Pin shortcuts" href="/pin-shortcuts">
    Standalone `/audit`-style redirects across discovered skill directories.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    OpenCode config dirs, hook quiet/disable, and related env vars.
  </Card>
  <Card title="Contributing" href="/contributing">
    Source-of-truth under skill/ and generated harness policy.
  </Card>
</CardGroup>

---

## 08. Initialize product context

> Run init to interview and write PRODUCT.md (including Platform), optionally document DESIGN.md from code, configure live when useful, and verify completion gates.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/08-initialize-product-context.md
- Generated: 2026-08-05T07:44:25.234Z

### Source Files

- `skill/reference/init.md`
- `skill/reference/document.md`
- `skill/scripts/context.mjs`
- `skill/scripts/lib/artifact-schema.mjs`
- `skill/scripts/lib/design-parser.mjs`
- `skill/scripts/command-metadata.json`

---
title: "Initialize product context"
description: "Run init to interview and write PRODUCT.md (including Platform), optionally document DESIGN.md from code, configure live when useful, and verify completion gates."
---

`/impeccable init` captures durable product truth in `PRODUCT.md` (including bare `## Platform`). It never invents a visual world and never writes `DESIGN.md`. Optional `/impeccable document` records an incumbent system as root `DESIGN.md` plus `.impeccable/design.json`. Runnable web projects may also receive `.impeccable/live/config.json` during init wrap-up. Session boot runs `node <skill>/scripts/context.mjs` once; missing product context emits `NO_PRODUCT_MD` / `PRODUCT_INIT_REQUIRED` / `BUILD_INIT_REQUIRED` directives that divert build and shape work into init.

## Commands

| Command | Metadata | Writes | Does not write |
|---|---|---|---|
| `init` (`teach` alias) | Capture product context | `PRODUCT.md` (schema stamp), optional live config | `DESIGN.md`, surface briefs, visual worlds |
| `document` | Capture visual system | `DESIGN.md`, `.impeccable/design.json` (scan mode) | Product truth; seed mode skips the sidecar |
| `document --seed` | Pre-code world seed | Seed `DESIGN.md` only (requires `PRODUCT.md`) | Token frontmatter, sidecar |

Invoke as `/impeccable init` or `/impeccable document` (provider prefix may be `$` on some harnesses). `craft` is a deprecated alias for ordinary new-work, not for init.

## Prerequisites

- Skills installed for the active harness (project or global scope).
- Working directory at the user project root (or monorepo child that owns product context).
- An answer mechanism for interviews (structured question tool, decision page, or live human). Unattended inference is allowed only after a real probe fails; label every inferred fact in `PRODUCT.md`.

## Init workflow

<Steps>
<Step title="Load current state">
Use the `PRODUCT.md` path resolved by `context.mjs`. Update that file; do not create a competing authority. In a nested app inheriting root context, confirm shared versus app-specific scope before writing.

| Existing state | Action |
|---|---|
| No `PRODUCT.md` | Explore, interview, write |
| `PRODUCT.md` exists | Ask what is stale or missing; do not reopen confirmed fields without reason |
| Legacy file, no `## Platform` | Default platform is `web` unless evidence says otherwise |
| Only `DESIGN.md` | Leave design file untouched; create `PRODUCT.md` |
| Redesign/rebrand | Preserve confirmed product truth; visual replacement is later new-work |
</Step>

<Step title="Explore the project">
Scan product docs and copy; package/config boundaries; features, workflows, routes, roles; names, logos, legal assets; platform/a11y signals; and the dev entry when live mode may apply. Treat repository evidence as hypothesis, not approval. Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive`. Mobile web and native wrappers around websites stay `web`.
</Step>

<Step title="Interview for product truth">
Ask only material gaps. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new `PRODUCT.md`. Priority unknowns:

1. Primary user, situation, and job
2. What the product makes possible and its differentiated mechanism
3. Durable constraints, assets, evidence, and facts future work must preserve

Confirm ambiguous platform separately. On greenfield builds without a scaffold, ask once for stack (static HTML/CSS, named framework, or delegated recommendation plus deploy constraints) and record under `## Stack`. Do not ask for aesthetic direction, palette, or typography during init.
</Step>

<Step title="Write PRODUCT.md">
Write confirmed facts and explicitly marked open decisions. Omit irrelevant sections. New files go at `PROJECT_ROOT/PRODUCT.md`; otherwise update the resolved path. Include the provenance stamp verbatim:

```markdown
# Product

<!-- impeccable:product-schema 1 -->

## Platform

web
```

Bare platform values: `web` | `ios` | `android` | `adaptive`. When the recorded platform is native, load `reference/ios.md`, `reference/android.md`, or both before design work (context could not have loaded them before the stamp existed).
</Step>

<Step title="Configure live when useful">
Skip native and non-runnable projects. Leave existing live config untouched. For runnable web apps, follow live first-time setup (`.impeccable/live/config.json`, inject targets, CSP consent). Any CSP source edit still requires explicit consent.
</Step>

<Step title="Verify completion and resume">
**Completion gate:** `PRODUCT.md` must exist at the resolved path with the confirmed product record. Interview notes, planning packets, or design prose are not substitutes. Then resume the original request without rerunning `context.mjs`.
</Step>
</Steps>

### PRODUCT.md section map

| Section | Required content |
|---|---|
| `## Platform` | Bare `web` / `ios` / `android` / `adaptive` |
| `## Stack` | Greenfield only; omit when the codebase already answers |
| `## Users` | Primary users, situation, job |
| `## Product Purpose` | What it does, why it exists, success |
| `## Positioning` | Differentiated mechanism or claim |
| `## Operating Context` | Workflows, tools, materials, rituals |
| `## Capabilities and Constraints` | Functionality, tech constraints, undecided facts |
| `## Brand Commitments` | Name, voice, assets, binding identity; omit if none |
| `## Evidence on Hand` | Real content/data/assets and paths; state absences not to fabricate |
| `## Product Principles` | Three to five strategic principles (not visual recipes) |
| `## Accessibility & Inclusion` | Known needs or standard; omit if none |

Schema constant: `PRODUCT_SCHEMA_VERSION = 1` in `skill/scripts/lib/artifact-schema.mjs`. Stamp readers: `readProductSchemaVersion`, `stampProductSchema`, `productStampLine`.

Deprecated heading `## Register` is no longer read (visitor modes live per surface brief). Doctor/boot may report it; delete when the user agrees rather than carrying it forward.

### What belongs vs does not

| Belongs in `PRODUCT.md` | Does not belong |
|---|---|
| Users, jobs, purpose, positioning, constraints | Visual worlds, palettes, type, components |
| Platform, a11y needs, evidence, brand commitments | Visitor mode, CTA/proof sequence, surface strategy |
| Confirmed voice and assets | Invented testimonials, pricing, or deployment claims |

## Document workflow

Run when you need a portable visual system for agents (or the live design panel). Paths:

| Mode | When | Outputs |
|---|---|---|
| **Scan** (default) | Tokens, components, or rendered UI exist | Full `DESIGN.md` (YAML frontmatter + up to eight sections) and `.impeccable/design.json` (`schemaVersion: 2`) |
| **Seed** | Pre-implementation; no extractable system | Seed `DESIGN.md` with `<!-- SEED: ... -->` marker; minimal frontmatter (`name`, `description`); no sidecar |

Scan extracts from CSS custom properties, Tailwind theme, CSS-in-JS themes, design-token files, component libraries, global styles, and optional browser computed styles. Then confirm qualitative language (north star, color character, elevation and component philosophy) in short structured rounds.

Canonical body sections (omit empty; keep order): Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Frontmatter holds normative tokens (`colors`, `typography`, `rounded`, `spacing`, `components`); shadows, motion, breakpoints, HTML/CSS snippets, and narrative live only in the sidecar.

<Warning>
Do not silently overwrite an existing `DESIGN.md`. Confirm refresh, overwrite, or merge. Seed mode does not authorize replacing a coherent incumbent system; route identity replacement through new-work.
</Warning>

`DESIGN.md` carries **no** product-schema stamp (external design.md / Stitch compatibility). Sidecar version constant: `DESIGN_SIDECAR_SCHEMA_VERSION = 2`.

## Context resolution and boot directives

`context.mjs` path order (first match wins):

1. Active project root (`PRODUCT.md` / `DESIGN.md`; `--target` selects monorepo child or nearest owner)
2. Active project `.agents/context/`, then `docs/`
3. Repo root fallback for nested monorepo apps
4. `$IMPECCABLE_CONTEXT_DIR` when defaults are empty
5. Active project root as empty default

Platform parse: first non-empty line under `## Platform`. Valid: `web`, `ios`, `android`, `adaptive`. A line naming both native targets (for example `ios, android`) becomes `adaptive`. Unrecognized values fall back to `web` and emit a `WARNING` naming the bad value.

Key directives when product context is missing:

| Directive | Meaning |
|---|---|
| `NO_PRODUCT_MD` | No product file; init/teach/shape/new surface require `reference/init.md` |
| `PRODUCT_INIT_REQUIRED` | No product or visual authority; builds need init then new-work |
| `BUILD_INIT_REQUIRED` | Shape / new-surface / redesign must capture product first |
| `SCOPED_EXISTING_ALLOWED` | Narrow refinements may use code as authority and offer init later |
| `EXISTING_VISUAL_SYSTEM` | Code/assets are design authority; missing `DESIGN.md` is documentation gap |
| `INCUMBENT_WORLD_UNDOCUMENTED` | Product exists, design missing, code has visual decisions |
| `WORLD_DISCOVERY_REQUIRED` | Product exists; no design file and no visual implementation |

After init writes `PRODUCT.md`, resume without rerunning `context.mjs`. Init loads native platform references itself for `ios` / `android` / `adaptive`.

## Completion gates and verification

<Check>
**Init complete when:** resolved `PRODUCT.md` exists, includes `<!-- impeccable:product-schema 1 -->`, records bare `## Platform`, and holds confirmed product sections (not empty placeholders for required truths).
</Check>

<Check>
**Document (scan) complete when:** root `DESIGN.md` follows canonical section order with normative frontmatter tokens, and `.impeccable/design.json` has `schemaVersion: 2` with extensions and component snippets as applicable.
</Check>

<Check>
**Document (seed) complete when:** seed marker is present, world invariants are committed without fake tokens, and the user is told to re-run document once code exists.
</Check>

Optional follow-up check: `node <skill>/scripts/context.mjs` in a **new** session should print `# PRODUCT.md` content (and design / native refs when present) without `NO_PRODUCT_MD`. For schema/config drift later, use doctor; do not repair drift as a side effect of design work unless the finding is severity `auto`.

## Recommended next actions after init

| Project state | Next command |
|---|---|
| Empty or early | Natural build request, or `/impeccable shape <surface>` for a confirmed brief |
| Coherent UI, no `DESIGN.md` | `/impeccable document` (optional, independent of a build) |
| Existing surface needing work | Scoped refine/evaluate command for that target |
| Web project, live configured | `/impeccable live` |

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Agent designs without `PRODUCT.md` | Scoped command path; init not required for narrow polish | Explicit `/impeccable init` before new surfaces/redesigns |
| Platform refs missing after first init | Session resumed without native load | Init must load `ios.md` / `android.md` when platform is native |
| Unrecognized platform treated as web | Typo or toolchain name (`flutter`, etc.) | Set bare design-language value: `web` / `ios` / `android` / `adaptive` |
| Init offered `DESIGN.md` | Incorrect flow | Init never writes design; use document or new-work |
| Live inject fails / CSP | Config missing or CSP blocks localhost | First-time live setup + CSP consent (`cspChecked`) |
| Seed without product | Seed requires product truth | Finish init first |
| Duplicate product files | Nested monorepo writes | Use context-resolved path; confirm shared vs app-specific scope |

## Related pages

<CardGroup>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md, DESIGN.md, design.json, surface briefs, stamps, and resolution order.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Visitor modes and platform values, native refs, web-only live/detect bounds.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live config, poll contract, inject, and carbonize cleanup.
  </Card>
  <Card title="Doctor" href="/doctor">
    Schema, config, and truth-drift findings for product and design artifacts.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    First successful session from install through init and a scoped command.
  </Card>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, craft-floor gate, and when init is required vs optional.
  </Card>
</CardGroup>

---

## 09. Run design commands

> Invoke evaluate and refine commands (audit, critique, polish, harden, layout, typeset, and related) with targets, expected artifacts, and verification signals.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/09-run-design-commands.md
- Generated: 2026-08-05T07:36:44.223Z

### Source Files

- `skill/SKILL.src.md`
- `skill/scripts/command-metadata.json`
- `skill/reference/audit.md`
- `skill/reference/critique.md`
- `skill/reference/polish.md`
- `skill/reference/new-work.md`
- `skill/scripts/critique-storage.mjs`

---
title: "Run design commands"
description: "Invoke evaluate and refine commands (audit, critique, polish, harden, layout, typeset, and related) with targets, expected artifacts, and verification signals."
---

Design work under `/impeccable` is command-driven: Setup loads project context once, the matching `skill/reference/<command>.md` playbook owns the run, and evaluate commands produce scored reports while refine/enhance/fix commands edit UI and hand off to a final polish pass. Invocation is always `/impeccable <command> [target]` (or a pin shortcut such as `/audit`).

## Prerequisites

| Requirement | Role |
|---|---|
| Skill installed in a supported harness | Hosts the single `impeccable` skill and sub-command router |
| Project cwd at the user repo | `context.mjs` and artifacts resolve relative to the project, not the skill install |
| `PRODUCT.md` (preferred) | Product truth; missing it does not block narrow refinement of existing code, but blocks new-surface / replacement-world work until init |
| `DESIGN.md` (preferred) | Visual system for refine commands; missing file alone is not greenfield |
| Optional: running web dev server | Critique browser overlays; live mode; URL-based inspection |

<Note>
Live mode and the bundled HTML detector are **web-only**. On `ios` / `android` / `adaptive`, do not lead with live or `detect.mjs`; use native audit/adapt variants and platform references instead.
</Note>

## Session setup (every design command)

Setup is non-optional for skill runs. Order is fixed in `skill/SKILL.src.md`:

<Steps>
  <Step title="Load context once">
    Run `node <skill-scripts>/context.mjs` once per session (optionally `--target <path>` for a named surface). Follow its directives; do not re-run it for the next command in the same session.
  </Step>
  <Step title="Load the command playbook">
    For an explicit or clearly implied sub-command, load `skill/reference/<command>.md`. On native platforms, prefer native variants when the Commands table lists them (`audit.native.md`, `adapt.native.md`). For a new surface or replacement visual world, load `new-work.md` instead.
  </Step>
  <Step title="Inspect the target">
    Resolve a concrete file, route, or URL, and at least one representative source of incumbent visual truth (tokens, theme, CSS, component, asset) before editing.
  </Step>
  <Step title="Load the craft floor before UI edits">
    Load `skill/reference/craft-floor.md` immediately before editing UI. Skip it for planning-only evaluate runs (critique/audit report generation).
  </Step>
</Steps>

**Refinement vs redesign:** refinement preserves incumbent identity, behavior, copy, and out-of-scope areas. Redesign keeps product truth and function but replaces the visual world via new-work and a new `DESIGN.md`. Do not smuggle a redesign through polish.

## Command map (evaluate and improve)

User-facing categories come from the skill Commands table. Metadata categories in `scripts/lib/skill-categories.js` (create / evaluate / refine / simplify / harden / system) are for harness menus and differ slightly in naming.

### Evaluate (report only; do not fix)

| Command | What it scores | Primary artifact |
|---|---|---|
| `critique [target]` | UX / design review: Nielsen heuristics, design specificity, cognitive load, personas, detector evidence | Chat report + `.impeccable/critique/<timestamp>__<slug>.md` |
| `audit [target]` | Technical quality: a11y, performance, theming, responsive, implementation integrity (web) or native dimensions | Chat report with P0–P3 findings and recommended commands |

### Refine / enhance / fix (edit, then polish)

| Command | Intent | Typical detector scope |
|---|---|---|
| `polish [target]` | Final shipping quality pass; consumes latest critique snapshot as backlog | Full path judgment + hook/context detector when active |
| `harden [target]` | Errors, overflow, i18n, empty/edge data | Manual stress tests |
| `bolder` / `quieter` / `distill` | Amplify, calm, or strip complexity inside the incumbent world | Visual judgment |
| `onboard [target]` | First-run, empty states, activation | Flow completeness |
| `layout [target]` | Spacing, rhythm, hierarchy | `detect.mjs --json --scope layout` |
| `typeset [target]` | Type roles, measure, hierarchy | `detect.mjs --json --scope type` |
| `colorize` / `animate` / `delight` / `overdrive` | Color, motion, personality, ambitious craft | Command-specific verify lists |
| `clarify [target]` | UX copy, labels, errors | Copy walkthrough |
| `adapt [target]` | Responsive / multi-context (native: `adapt.native.md`) | Viewport / platform checks |
| `optimize [target]` | UI performance | Measure before/after |

Most improve commands end with a handoff to `/impeccable polish` when the targeted change holds.

## How to invoke

<CodeGroup>

```bash title="Evaluate UX"
/impeccable critique src/pages/settings.tsx
```

```bash title="Technical audit (web)"
/impeccable audit src/components/Checkout
```

```bash title="Final polish with target"
/impeccable polish src/pages/settings.tsx
```

```bash title="Scoped enhance"
/impeccable layout src/components/Dashboard
/impeccable typeset src/pages/docs
```

</CodeGroup>

Pin shortcuts (`/audit`, `/polish`, …) resolve to the same playbooks when created with `pin.mjs`. No-argument `/impeccable` never auto-runs a command; it presents a context-aware menu from `routing.md` and optional `context-signals.mjs` / detector hits.

### Target resolution

| User phrasing | Resolve to |
|---|---|
| "the homepage" | Primary source file (e.g. `index.html`, `app/page.tsx`) preferred over a fragile dev-server URL |
| "the settings modal" | Primary component file |
| "this page" | Current URL **or** source file; prefer path when both name the same surface |
| Git-dirty surface | Scope audit/polish to changed markup/style files when signals expose them |

Vague or project-root targets may still run critique/audit, but critique **skips snapshot persistence** when the slug helper cannot derive a stable slug.

## Evaluate: critique

`critique` is dual-assessment UX review. Chat is the primary deliverable; disk snapshots are archive/backlog for later polish.

### Flow

```text
Resolve target → slug check → read ignore.md (optional)
        │
        ├─ Assessment A: design review (no detector)
        └─ Assessment B: detect.mjs + optional browser overlay
        │
   Synthesize report (chat)
        │
   Persist snapshot → trend line → ask user → recommend commands
```

**Hard rules (from `critique.md`):**

- Assessment A and B run as **two isolated sub-agents** when a sub-agent/Task tool exists. Inline single-context is degraded and must open with `⚠️ DEGRADED: single-context (<reason>)`.
- A skipped detector is a failed critique unless `detect.mjs` is missing or crashes after a real attempt.
- Detector findings must not enter synthesis until A is finished.
- Viewable targets use browser inspection when automation is available; local servers started only for critique must be stopped before the final report unless the user keeps them.

### Detector CLI used in Assessment B

```bash
node <skill-scripts>/detect.mjs --json [target]
```

- Pass markup files/directories; do not pass CSS-only paths as the sole target.
- For URLs, skip CLI scan and use browser visualization.
- Exit `0` = clean, `2` = findings (non-advisory).
- Optional browser path injects live-server `detect.js` into a **fresh** tab labeled `[Human]` when mutation is available.

### Report shape (chat)

1. Provenance header: `Method: dual-agent (...)` or degraded banner  
2. Design Health Score (Nielsen 10 heuristics, 0–4; n/a allowed on some Persuade/Experience heuristics; total over applicable max, e.g. `/40` or `/32`)  
3. Design Specificity Verdict (LLM + deterministic scan + overlays)  
4. Overall impression, what’s working, priority issues (P0–P3), persona red flags, minor observations, questions  
5. Trend line after persistence  
6. User questions (or skip with reason) → recommended `/impeccable …` actions, ending with polish when fixes are planned  

### Persistence: `critique-storage.mjs`

Snapshots live under `.impeccable/critique/`. Filenames: `<UTC-stamp>__<slug>.md`.

| Subcommand | Purpose | Exit notes |
|---|---|---|
| `slug <resolved-target>` | Print stable slug from path/URL | Non-zero → skip persistence for this run |
| `write <slug-or-target> <body-file>` | Write snapshot; meta via `IMPECCABLE_CRITIQUE_META` JSON | Prints absolute path written |
| `latest <slug-or-target>` | Print latest snapshot body | Exit `2` if none |
| `trend <slug-or-target> [limit]` | Last N frontmatter rows as JSON (default 5) | — |

Meta keys written by critique:

```json
{
  "target": "<user phrasing>",
  "total_score": 28,
  "max_score": 40,
  "na_heuristics": "7,10",
  "p0_count": 1,
  "p1_count": 2
}
```

Optional prior input: `.impeccable/critique/ignore.md` (plain markdown; matching findings dropped silently). No `ignore` subcommand exists on the helper.

Only **polish** auto-reads the latest matching snapshot as a fix backlog. Other commands do not.

## Evaluate: audit

`audit` is a **technical** code-level report, not UX critique. It documents issues for other commands; it does not apply fixes.

### Web (`audit.md`) — five dimensions, 0–4 each

| # | Dimension | Focus |
|---|---|---|
| 1 | Accessibility | Contrast, motion, ARIA, keyboard, semantics, forms |
| 2 | Performance | Layout thrash, expensive effects, assets, re-renders |
| 3 | Theming | Tokens vs hard-coded colors, dark mode |
| 4 | Responsive | Fixed widths, touch targets, overflow, breakpoints |
| 5 | Implementation integrity | Bundled detector findings verified in context |

**Audit Health Score** total `/20`. Rating bands: 18–20 Excellent, 14–17 Good, 10–13 Acceptable, 6–9 Poor, 0–5 Critical.

Issues use **P0–P3** severity with location, category, impact, standard, recommendation, and a **suggested command** from the available command list. Recommended actions should end with polish when any fixes are proposed. Re-run audit after fixes to rescore.

### Native (`audit.native.md`)

Used when platform is `ios` / `android` / `adaptive`. No browser tooling and no `detect.mjs`. Dimensions become: Accessibility (VoiceOver/TalkBack), Performance, Appearance & Theming, Platform Conformance, Adaptivity — still `/20` with the same report skeleton.

## Refine and enhance: common loop

<Steps>
  <Step title="Establish the system">
    Read `DESIGN.md`, tokens, shared components, and neighboring flows. Classify drift (missing token, one-off, conceptual mismatch, local defect) before editing.
  </Step>
  <Step title="Gather evidence">
    Use the feature at representative sizes and states. For polish, optionally load prior critique:
    `node <skill-scripts>/critique-storage.mjs latest "<resolved target>"` (exit 0 = body; exit 2 = none). Perform an independent pass either way.
  </Step>
  <Step title="Two assessments when the playbook requires it">
    Layout and typeset run a design assessment and a mechanical scan in isolation when sub-agents exist, then synthesize before editing. Do not let detector output anchor the first assessment.
  </Step>
  <Step title="Apply the minimal correct fix">
    Stay inside the incumbent world and named scope. Amplify/calm/distill commands must not invent a new identity; that routes to new-work.
  </Step>
  <Step title="Verify with evidence">
    Answer the playbook’s verify checklist with rendered or source evidence, rerun scoped detect when used, then hand off to polish.
  </Step>
</Steps>

### Polish triage order

1. Broken tasks, data loss, misleading state, inaccessible paths  
2. Missing loading / empty / error / success / disabled / permission states  
3. Flow, hierarchy, responsive, design-system drift  
4. Visual and motion inconsistencies  
5. Code and asset cleanup  

Ship only when the full path is functionally complete and consistent. Bounded verification: one batched inspect (desktop + mobile), one fix batch, at most one confirm round—not open-ended self-QA loops.

### Layout and typeset mechanical scans

```bash
node <skill-scripts>/detect.mjs --json --scope layout [files-or-dirs]
node <skill-scripts>/detect.mjs --json --scope type [files-or-dirs]
```

`--scope` filters detector rules by design domain (`layout`, `type`, and other rule-declared scopes). A clean scan is a floor, not proof of good hierarchy or typography.

Live-mode signature params (when generating live variants for these commands): layout uses coarse `density` → `var(--p-density, 1)`; typeset uses `scale` → `var(--p-scale, 1)`. Full live protocol is out of scope here.

### Harden focus areas

- Extreme inputs (long/short/RTL/CJK/emoji, large lists, empty data)  
- Error and network scenarios  
- i18n expansion (~30–40% text budget), logical CSS properties, `Intl` formatting  
- Overflow: truncation, line-clamp, `min-width: 0` on flex/grid children  

### Craft floor (edit-time)

Before UI edits, craft-floor enforces contrast, spacing rhythm, type measure, motion restraint, control states, themed browser chrome, product copy, and bans on common AI-default scaffolds (identical card grids, kickers on every section, gradient text as emphasis, hard offset shadows outside neobrutalist worlds, and related habits). A pinned brief or committed world overrides the floor when it explicitly earns an exception; model habit does not.

## Expected artifacts and verification signals

| Command | User-visible output | On-disk / side effects | “Done” signals |
|---|---|---|---|
| `critique` | Full structured report in chat; optional questions + command plan | `.impeccable/critique/<ts>__<slug>.md`; trend line | Dual-agent (or explicit degraded) header; scores + P0/P1 counts; snapshot path or skip reason |
| `audit` | Health table `/20`, P0–P3 findings, recommended commands | None required | Dimension scores, integrity verdict, prioritized next commands |
| `polish` and other improve commands | Code/UI diffs in project sources | May consume critique snapshot; no new critique file unless critique re-run | Verify checklist answered with evidence; unexplained detector findings cleared; optional re-critique/re-audit scores improve |
| Scoped layout/typeset | Source edits | Detector JSON during run | Squint/role hierarchy holds; scoped scan clean |

Detector exit codes during mechanical steps: **0** clean, **2** findings. Critique storage `latest` exit **2** means no prior snapshot (not a product failure).

## Recommended sequencing

```text
init / document (once per project)
        │
   critique  ──►  layout | typeset | colorize | clarify | …
        │                    │
   audit (parallel or after) │
        │                    ▼
        └────────────►  polish
                              │
                     re-critique / re-audit (scores)
```

- Start evaluate when you need a backlog; start a named enhance/fix when the defect is already known.  
- End multi-command fix trains with polish.  
- Re-run critique/audit to measure movement; trend lines only work when targets resolve to stable slugs.

## Troubleshooting

| Symptom | Likely cause | Action |
|---|---|---|
| Critique opens with degraded banner | No sub-agent tool, user declined, or spawn failed | Accept sequential run only when declared; prefer dual-agent when available |
| No snapshot written | Unstable slug (root/vague target) or `slug` exit non-zero | Resolve a concrete path/URL; re-run slug |
| Polish ignores prior critique | Slug mismatch or no snapshot for that target | Use the same resolved path; check `latest` exit code |
| Detector skipped / unavailable | Native platform, missing `detect.mjs`, CSS-only target | Use native audit; pass markup; browser path for URLs |
| Audit recommended wrong commands | Recommendations must stay inside available command list | Map findings to evaluate→improve mapping above |
| Redesign attempted via polish | Wrong world-change semantics | Stop; run new-work / replace DESIGN.md intentionally |
| Live or detect suggested on native | Platform is ios/android/adaptive | Use `audit.native` / platform refs; skip HTML detector |
| Hook re-scans after every edit | Design hook enabled | Act on findings; do not add an extra full detect pass in polish when context says the hook already covers it |

## Next

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, no-argument menu, craft-floor gate, and native variants.
  </Card>
  <Card title="Skill commands reference" href="/skill-commands-reference">
    Full sub-command catalog with argument hints and categories.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    In-browser variants after evaluate/improve plans are clear.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, scopes, and finding shape used by critique and scoped scans.
  </Card>
  <Card title="Initialize product context" href="/init-and-document">
    Write PRODUCT.md and DESIGN.md before first critique or polish.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    `.impeccable/` layout, surface briefs, and context resolution.
  </Card>
</CardGroup>

---

## 10. Live browser iteration

> Start live mode, poll contract, generate/accept/discard/steer/manual-edit events, carbonize cleanup, roots resolution, and web-only platform constraints.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/10-live-browser-iteration.md
- Generated: 2026-08-05T07:35:50.980Z

### Source Files

- `skill/reference/live.md`
- `skill/reference/live-setup.md`
- `skill/scripts/live.mjs`
- `skill/scripts/live-server.mjs`
- `skill/scripts/live/roots.mjs`
- `skill/scripts/live-wrap.mjs`
- `skill/scripts/live-accept.mjs`
- `docs/adr-live-variant-mode.md`

---
title: Live browser iteration
description: Start live mode, poll contract, generate/accept/discard/steer/manual-edit events, carbonize cleanup, roots resolution, and web-only platform constraints.
---

Live mode lets you pick an element in a running web page, choose a design action, and review AI-generated HTML+CSS variants hot-swapped through the app’s own HMR (or a no-HMR source fallback). Variants are written into real source files so Accept is a source mutation, not a DOM patch.

## What you get

Three parties share one session:

| Role | Responsibility |
|------|----------------|
| **Browser overlay** (`live.js`) | Element picker, action bar, variant cycler, Steer/Apply controls, SSE + POST to the helper |
| **Live helper server** (`live-server.mjs`) | Localhost HTTP on `127.0.0.1` (port from **8400** upward), `/poll`, `/events`, `/source`, session journal |
| **Agent** | Boot via `live.mjs`, long-poll via `live-poll.mjs`, wrap/write variants, carbonize after Accept |

Design context for generation uses this precedence: **DESIGN.md** for visual decisions, **PRODUCT.md** for product and voice, surface brief for that surface’s strategy. Missing DESIGN.md does not mean “no identity”: extract tokens and sibling rhetoric from the live element.

## Web-only constraint

Live mode and the HTML detector overlay are **web-only**. When project platform is `ios`, `android`, or `adaptive`, routing must not lead with live: the browser inject path and HTML rule engine do not apply to native app sources. Use web projects (or web surfaces of a multi-platform product) only.

## Prerequisites

- A runnable web app with a dev server that supports HMR (Vite, Next, Nuxt, SvelteKit, Astro, TanStack, plain HTML, etc.), **or** a static HTML page open in the browser.
- `PRODUCT.md` and `DESIGN.md` present (boot fails with `context_missing` and points at `init` / `document` otherwise).
- One-time `.impeccable/live/config.json` (and CSP consent when needed).
- Prefer probing the app’s default URL before spawning a second dev server if the default port is busy.

Do not confuse **`serverPort`** with the app URL. The helper serves `/live.js` and `/poll`; open the origin that serves a configured page file.

## Architecture

```mermaid
sequenceDiagram
  participant User
  participant Browser as Browser overlay
  participant Server as live-server
  participant Agent as Agent + live-poll

  User->>Browser: Pick element, action, Go
  Browser->>Server: POST /events generate
  Agent->>Server: GET /poll (long-poll)
  Server-->>Agent: generate event + scaffold
  Agent->>Agent: wrap + write variants
  Agent->>Server: POST /poll done --file
  Server-->>Browser: SSE done
  Browser->>Browser: HMR or /source inject
  User->>Browser: Accept / Discard / Steer
  Browser->>Server: POST /events
  Server-->>Agent: next poll event
```

**Source modification, not DOM-only patching.** Accept keeps the winning markup in source. SSE (server→browser) + fetch POST (browser→server) avoid a WebSocket dependency. Agent traffic is HTTP long-poll so any harness that can run a shell command can participate.

Helper endpoints (selected):

| Path | Role |
|------|------|
| `GET /live.js` | Injected browser script (token embedded) |
| `GET/POST /events` | SSE stream + browser events |
| `GET/POST /poll` | Agent long-poll and replies |
| `GET /source` | Raw file for no-HMR fallback |
| `/manual-edit-stash`, `/manual-edit-commit`, `/manual-edit-discard` | Staged browser copy edits |
| `GET /status`, `GET /health` | Recovery / health |
| `GET /stop` | Graceful shutdown |

Session state lives under `<appRoot>/.impeccable/live/` (`server.json`, `roots.json`, `sessions/`, inject journal). The append-only journal is canonical for recovery after helper restarts or chat interruptions.

## Roots resolution

Every live CLI calls `enterLiveRoot()` so ambient `cwd` cannot fork session state.

| Root | Meaning |
|------|---------|
| `appRoot` | Dev-served app; inject targets, session state, preview modules |
| `repoRoot` | Git boundary (or `appRoot` outside git) |
| `contextRoot` | Nearest dir up to `repoRoot` with PRODUCT/DESIGN |
| `sessionRoot` | `<appRoot>/.impeccable/live` |

`appRoot` is detected from dev-server config markers (`vite.config.*`, `next.config.*`, `svelte.config.*`, `astro.config.*`, `nuxt.config.*`, …) or an existing live config, not monorepo branding. Nested `website/` with Vite wins over a root that only has `package.json`. Manifest is written to `<appRoot>/.impeccable/live/roots.json`; when `repoRoot ≠ appRoot`, a pointer at `<repoRoot>/.impeccable/live/app-root.json` helps helpers started from elsewhere. Multi-app repos: pass `--target <path>` or run from the child app; ambiguous multi-app state is warned on stderr.

**Svelte preview modules** are published under `node_modules/.impeccable-live/` (not under `.impeccable/`) so Vite/SvelteKit `server.fs.allow` can load them.

## First-time setup

Required when boot returns `config_missing` / `config_invalid`, when `configDrift` needs a decision, or when `cspChecked` is absent.

### Live config

Create `.impeccable/live/config.json` (path reported by boot):

```json
{
  "files": ["index.html"],
  "exclude": [],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

| Field | Role |
|-------|------|
| `files` | HTML/templates the browser actually loads (paths or globs), not necessarily “tracked source” |
| `exclude` | Optional globs skipped after expand |
| `insertBefore` / `insertAfter` | Injection anchor |
| `commentSyntax` | `html` or `jsx` |
| `cspChecked` | CSP consent already handled |

Hard excludes (cannot override): `**/node_modules/**`, `**/.git/**`.

| Framework | Typical `files` | `commentSyntax` |
|-----------|-----------------|-----------------|
| Vite / plain SPA | `index.html` | `html` |
| Next App Router | `app/layout.tsx` | `jsx` |
| Next Pages | `pages/_document.tsx` | `jsx` |
| Nuxt | `app.vue` | `html` |
| SvelteKit | `src/app.html` | `html` |
| TanStack Start | `src/routes/__root.tsx` | `jsx` (`insertBefore`: `<Scripts`) |
| Multi-page | e.g. `public/**/*.html` | `html` |

SvelteKit, Nuxt, and TanStack Start use dedicated inject adapters (dev-only root component / client plugin / generated root component). Inject journal: `.impeccable/live/inject-journal.json`.

**Config drift:** boot may report `configDrift.orphans` (HTML under `public/`, `src/`, `app/`, `pages/` not covered by `files`). Tell the user once; never auto-edit config.

### CSP (first time)

Run `detect-csp.mjs`. If shape is `null`, set `cspChecked: true`. Auto-patchable shapes (`append-arrays`, `append-string`) add a **dev-only** `http://localhost:8400` allowance to `script-src` and `connect-src` after explicit consent. Middleware/meta-tag shapes need a manual allowance, then still mark `cspChecked: true`. On “no”, mark checked anyway and expect live to fail until the user allows the origin.

## Start a session

```bash
node <scripts_path>/live.mjs
# monorepo / nested app:
node <scripts_path>/live.mjs --target <app-or-file-path>
```

Boot order: resolve roots → require PRODUCT/DESIGN → check config → start or reuse helper → inject script → optional drift scan → print one JSON blob.

Success shape (fields of interest):

| Field | Meaning |
|-------|---------|
| `ok` | `true` when ready to poll |
| `serverPort` / `serverToken` | Helper only |
| `pageFiles` | Resolved inject targets |
| `projectRoot` / `roots` | App and related roots |
| `product` / `design` / `surfaceBrief` | Inlined context |
| `configDrift` | Orphans advisory or `null` |
| `_instructions` | Authoritative next steps for this boot |

Then open the **app** URL for a `pageFile`, and enter the poll loop.

### Poll loop

```text
LOOP:
  node <scripts_path>/live-poll.mjs    # default long timeout; do not use short --timeout=
  dispatch on event.type
  reply when required
  LOOP until exit
```

Default event lease is long (~600s). Do not pass a short `--timeout=`. The global bar’s Impeccable mark dims with a pulsing amber dot when nothing is polling `/poll`.

Harness policy:

| Harness | Poll style |
|---------|------------|
| Claude Code | Background poll (harness notifies) |
| Cursor | One-shot background poll + restart; **not** `--stream` |
| Codex | One-shot foreground poll; keep servicing the exec session |
| Others | One-shot foreground unless incremental stdout is reliable |

Every tool output may include `_instructions` with concrete ids and paths. When it conflicts with static docs, **`_instructions` wins**.

Events that need an agent reply: `generate`, `steer`, `manual_edit_apply`, `carbonize_cleanup`, `variant_mount_failed`. Accept/discard are mostly handled by the poll script itself.

## Events

Browser/client types (wire vocabulary) include: `generate`, `accept`, `discard`, `steer`, `prefetch`, `manual_edits`, `variant_mounted`, `variant_mount_failed`, `exit`, plus progress types (`agent_phase`, `checkpoint`, …). Agent-facing poll types also include `timeout`, `manual_edit_apply`, and completion payloads.

### `generate`

Replace mode (default): element + action (`impeccable` freeform or a named action such as `bolder`, `polish`, `typeset`, …) + optional annotations (`screenshotPath`, `comments`, `strokes`).

Insert mode (`mode: "insert"`): net-new content at an anchor; requires freeform prompt or annotations; no `action`.

Agent path:

1. Reuse `event.scaffold` when present (do not re-run wrap).
2. Else run `live-wrap.mjs` / `live-insert.mjs` with separate `--element-id`, `--classes`, `--tag`, `--text` flags (`--text` disambiguates siblings).
3. Plan **three** variants within identity (default) or departure only on explicit redesign language.
4. Write complete HTML replacements + colocated CSS per `cssAuthoring` / `styleMode` (atomic single edit preferred).
5. Optional 0–4 parameters per variant (`range` / `steps` / `toggle`).
6. Reply: `live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH`.

On generation failure after the UI shows GENERATING: `--reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` to abort generation (browser bar never clears).

**Svelte component path:** preview under `node_modules/.impeccable-live/<id>/`; edit `v1.svelte`… in place; params in `params.json`; accept merges mechanically into the real route.

**Fallback (`fallback: "agent-driven"`):** wrap refused generated/untracked files. Preview in the served file; on Accept write true source yourself; strip the temporary wrapper.

### `accept`

Poll already ran `live-accept.mjs` and may attach `_acceptResult` and `_completionAck`.

| Result | Agent action |
|--------|----------------|
| `handled: true, carbonize: false` | Done; poll again |
| `handled: true, carbonize: true` | Required carbonize cleanup, then `live-complete.mjs --id EVENT_ID` |
| `handled: false, mode: "fallback"` | Persist to true source; remove temp wrapper |
| `handled: false, mode: "error"` | Do not hand-edit; retry lock or check `live-status` (`source_locked`, `accept_receipt_conflict`) |

Accept refuses generated files. Param values arrive as sibling comments; carbonize bakes them.

### Carbonize cleanup

When Accept stitches the winner with helper markers so the browser never flashes empty, the stitch is temporary. Before the next poll:

1. Find `impeccable-carbonize-start/end` and optional `impeccable-param-values`.
2. Move CSS into the project’s real stylesheet.
3. Bake params: keep chosen `steps`/`toggle` branches; substitute `range` values; collapse `@scope` / `data-p-*` to semantic rules.
4. Unwrap variant/carbonize wrappers and `data-impeccable-*` attrs.
5. Delete inline style, markers, leftover non-accepted scopes.

Then:

```bash
node <scripts_path>/live-complete.mjs --id SESSION_ID
```

Completion refuses with `error: "source_dirty"` while markers, `data-p-*`, or unbaked `--p-*` remain (`--force` only for false positives). Verify `phase: "completed"` before polling again.

### `discard`

Poll restores original and acknowledges. If `_completionAck.ok !== true`, run `live-complete.mjs --id EVENT_ID --discarded`, then poll.

### `steer`

Page-level direction from the global bar (no element, no variants). Edit or answer, then `--reply EVENT_ID steer_done ["toast"]` or `error`. No pickup ack.

### `prefetch`

Speculative route pre-read on first selection. No reply; poll again after reading.

### `manual_edit_apply`

User already clicked Apply on staged copy edits. Do not re-ask or redirect to Go. Delegate to the manual-edit applier agent when available (it must not poll/reply). Reply once with structured JSON:

```bash
node <scripts_path>/live-poll.mjs --reply EVENT_ID done --data \
  '{"status":"done","appliedEntryIds":["8hexid"],"failed":[],"files":["src/page.html"],"notes":[]}'
```

Use `status: "partial"` or `"error"` with `failed[]` when needed. If `repair` is set, fix current source; do not roll back yourself.

### `variant_mount_failed`

Published variant failed to render. Fix sources, `--reply EVENT_ID done --file <manifest-or-source>`; browser retries.

### `timeout` / `exit`

`timeout` → poll again. `exit` → cleanup (below). Closing the tab drops SSE; poll returns `exit` after a short grace period (~8s).

## Recovery

```bash
node <scripts_path>/live-status.mjs
node <scripts_path>/live-resume.mjs --id SESSION_ID
node <scripts_path>/live-complete.mjs --id SESSION_ID
```

Journal under `.impeccable/live/sessions/` is durable. After helper restart, start server again and poll; unacknowledged work is requeued. Fall back to non-live direct edits only when resume reports **no** active session.

## Exit and cleanup

```bash
node <scripts_path>/live-server.mjs stop
# keep inject for a quick restart:
node <scripts_path>/live-server.mjs stop --keep-inject
```

Stop removes the injected script (unless `--keep-inject`). Config persists. Sweep leftover `impeccable-variants-start` and `impeccable-carbonize-start` blocks from source.

## Troubleshooting

| Symptom | Check |
|---------|--------|
| Boot `config_missing` | Create config per setup; re-run `live.mjs` |
| Overlay never loads | CSP blocking `localhost:8400`; clear `cspChecked` and re-run CSP flow |
| Amber dimmed mark | No active poll; restart `live-poll.mjs` |
| Accept leaves markers | Finish carbonize; `live-complete` until clean |
| Wrong monorepo app | Rerun with `--target` or from child cwd |
| `element_ambiguous` / generated file | Agent-driven fallback; never accept into generated output |
| Generation stuck on dots | `--reply EVENT_ID error "…"` (not accept discard) |
| Multi-app warning | Explicit `--target` to the intended `appRoot` |

## Related pages

<CardGroup cols={2}>
  <Card title="Modes and platform" href="/modes-and-platform">
    Web-only live/detect boundaries and platform defaults.
  </Card>
  <Card title="Live framework recipes" href="/live-framework-recipes">
    Copy-paste live config shapes for Vite, Next, Nuxt, SvelteKit, TanStack, Astro, multipage, CSP fixtures.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md, DESIGN.md, surface briefs, and `.impeccable/` layout.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Live config.json fields and path excludes.
  </Card>
  <Card title="Plugin agents" href="/plugin-agents">
    Manual-edit applier and related bundled agents.
  </Card>
  <Card title="Build and test" href="/build-and-test">
    Opt-in live-e2e suite and framework fixtures.
  </Card>
</CardGroup>

---

## 11. Design hook

> Provider-native edit hooks that scan writes for detector findings, intentional-finding workflow, quiet/disabled controls, and native-platform skip behavior.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/11-design-hook.md
- Generated: 2026-08-05T07:35:38.101Z

### Source Files

- `skill/reference/hooks.md`
- `skill/scripts/hook.mjs`
- `skill/scripts/hook-before-edit.mjs`
- `skill/scripts/hook-lib.mjs`
- `plugin/hooks/hooks.json`
- `docs/HARNESSES.md`
- `cli/lib/impeccable-config.mjs`

---
title: "Design hook"
description: "Provider-native edit hooks that scan writes for detector findings, intentional-finding workflow, quiet/disabled controls, and native-platform skip behavior."
---

The design hook is a provider-native edit-time gate that runs Impeccable’s anti-pattern detector on UI file writes. Install and update wire a harness-specific manifest that invokes either `hook.mjs` (post-edit + Stop) or `hook-before-edit.mjs` (Cursor pre-write deny). Shared scan logic lives in `skill/scripts/hook-lib.mjs`; project lifecycle is managed through `/impeccable hooks` → `hook-admin.mjs` and `.impeccable/config.json` / `config.local.json`.

The hook is **web-only**. When `PRODUCT.md` sets `## Platform` to `ios`, `android`, or `adaptive`, both entry points skip scanning (`skipped: 'native-platform'`). Manual `npx impeccable detect` is separate: `hook.enabled` does not turn CLI scans off.

## Runtime surface

| Piece | Path / role |
|---|---|
| Post-edit + Stop entry | `skill/scripts/hook.mjs` → `runHook` / `runStopHook` |
| Cursor pre-write gate | `skill/scripts/hook-before-edit.mjs` |
| Shared library | `skill/scripts/hook-lib.mjs` |
| Admin CLI for the skill | `skill/scripts/hook-admin.mjs` (via `/impeccable hooks`) |
| Manifest emitters | `scripts/lib/transformers/hooks.js` |
| Plugin package hooks | `plugin/hooks/hooks.json` (`${CLAUDE_PLUGIN_ROOT}`) |
| Detector | `cli/engine/detect-antipatterns.mjs` (or skill-bundled `detector/detect-antipatterns.mjs`) |

**Contract:** hooks always exit `0` and must not break an agent turn. Detector throws, malformed stdin, missing files, and unsupported Node versions degrade to allow / silence (with optional audit log).

```text
Harness edit event
        │
        ├─ Cursor preToolUse ──► hook-before-edit.mjs
        │                         allow | deny (permission JSON)
        │
        └─ PostToolUse/postToolUse ──► hook.mjs (runHook)
              immediate-tier findings → additionalContext
              clean / pending acks (unless quiet)
              session cache under .impeccable/hook.cache.json
                        │
                        ▼ (Claude / Codex / Grok Stop only)
                   runStopHook — full rule set on touched UI files
```

## Supported harnesses

| Harness | Event | Script | Manifest | Behavior |
|---|---|---|---|---|
| Claude Code | `PostToolUse` + `Stop` | `hook.mjs` | `.claude/settings.local.json` (preferred; gitignored) or shared `settings.json` | After Edit/Write/MultiEdit; deep pass on Stop |
| Codex | `PostToolUse` + `Stop` | `hook.mjs` | `.codex/hooks.json` | Matcher `Edit\|Write\|apply_patch`; requires `/hooks` trust |
| Grok Build | `PostToolUse` + `Stop` | `hook.mjs` | `.grok/hooks/impeccable.json` | Claude matchers alias to Grok tools; needs `/hooks-trust` or `--trust` |
| GitHub Copilot | `postToolUse` only | `hook.mjs` | `.github/hooks/impeccable.json` (committed) | Full per-edit rules (no Stop context channel); matcher `edit\|create\|apply_patch` |
| Cursor | `preToolUse` only | `hook-before-edit.mjs` | `.cursor/hooks.json` | Denies bad proposed writes; silent allow on clean |

Other harnesses ship the skill without a documented hook surface. When no automatic hook is active, `context.mjs` can emit `MANUAL_DETECTOR_REQUIRED` so the agent runs a detector pass at session end.

### Install and consent

`npx impeccable install` / `update` installs the skill payload and, unless `--no-hooks`, offers to wire the design hook (default yes). Consent is stored per developer as `hook.consent` (`accepted` | `declined`) in gitignored `.impeccable/config.local.json`.

| Platform step | Requirement |
|---|---|
| Codex | Approve the project hook via `/hooks` after install/update (re-prompt possible when the manifest changes) |
| Cursor | Hooks enabled under Settings → Hooks; restart if reload fails |
| Grok | Project folder trust (`/hooks-trust` or `--trust`) |
| Copilot CLI | Commit `.github/hooks/impeccable.json` on the default branch; trust the folder |
| Node runtime | Node **22+** on the hook shell’s PATH (manifest probe exits 0 and may emit a one-shot `systemMessage` on Claude/Codex when too old) |

Plugin installs use `plugin/hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` (Grok aliases that to `GROK_PLUGIN_ROOT`).

## What gets scanned

Built-in extensions:

`.tsx` `.jsx` `.html` `.htm` `.vue` `.svelte` `.astro` `.css` `.scss` `.sass` `.less` `.ts` `.js`

- Clean/pending **acks** fire only for UI-ish extensions (`ACK_EXTS`); plain `.ts` / `.js` stay quiet unless findings exist.
- Add server templates via `detector.extensions` (no admin subcommand; edit config directly), e.g. `{ "ext": ".blade.php", "engine": "html" }`. Match is suffix-based (supports double extensions). `engine` is `html` or `text` (default `html`).
- Hard skips (not configurable): sensitive paths (`SENSITIVE_PATH`), generated/build/lock paths (`GENERATED_PATH`), path traversal, files outside the project root, files over `limits.maxFileBytes` (default 131072).

## Two-tier rules

Default `hook.perEditRules` is `"immediate"`. Per-edit PostToolUse only surfaces **immediate-tier** rules; remaining findings wait for the Stop deep pass.

**Immediate tier (`IMMEDIATE_TIER_RULES`):**  
`broken-image`, `text-overflow`, `clipped-overflow-container`, `body-text-viewport-edge`, `low-contrast`, `gray-on-color`, `tiny-text`, `gradient-text`, `dark-glow`, `design-system-font`, `design-system-color`, `design-system-radius`, `design-system-font-size`.

**Stop deep pass (`runStopHook`):** full detector set over UI files touched this session, deduped against per-edit cache, max `STOP_MAX_FILES` (20), timeout 30s. Silent when nothing new. Skips when Claude sets `stop_hook_active: true` (prevents consecutive-block loops).

Tiering is **off** for Cursor and GitHub Copilot (`perEditTieringActive` returns false) so non-immediate rules are not silently dropped. Set `hook.perEditRules: "all"` to restore full rules on every edit for harnesses that support Stop.

Advisory rules (e.g. `em-dash-overuse`) are **excluded** from the hook unless `detector.advisoryRules: "include"`.

## Emission kinds (post-edit)

| Kind | When | Output shape (Claude/Codex/Grok) |
|---|---|---|
| `fresh` | New findings not already in session cache | `[impeccable@1] Design hook findings...` + fix/ignore guidance via `hookSpecificOutput.additionalContext` |
| `pending` | Known unresolved findings still present | Re-nudge listing known issues |
| `clean` | No immediate findings; once per file per session | Short ack + steer line (UI extensions only) |
| `suppression` | Edit count for the file exceeds `EDIT_COUNT_THRESHOLD` (6) | Stops further per-file hints; points at audit |

- **Quiet mode** (`hook.quiet` or `IMPECCABLE_HOOK_QUIET`): no clean/pending acks; findings still emit.
- **Cursor:** deny JSON `{ permission: "deny", user_message, agent_message }` when findings exist; after the same finding signature is denied more than 6 times, allow with a loop-break warning.
- **GitHub payload:** top-level `additionalContext`.
- Caps: `limits.maxFindings` (default 5), `limits.maxChars` (default 8000).

## Native platform skip

`resolveProjectPlatform(cwd)` loads the same product context as the skill (`loadContext` + `extractPlatform`). If platform is `ios`, `android`, or `adaptive`, the hook returns without scanning. Native apps still use the same file extensions the hook watches; skipping avoids web HTML/CSS findings that contradict native platform guidance.

## Configuration

Shared (committed) `.impeccable/config.json` and local (gitignored) `.impeccable/config.local.json` merge; local overrides shared for the same keys. Malformed files are ignored.

### `hook` keys

| Key | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | boolean | `true` | Automatic hook execution only |
| `quiet` | boolean | `false` | Suppress clean/pending acks |
| `auditLog` | string path \| null | `null` | NDJSON log path |
| `perEditRules` | `"immediate"` \| `"all"` | `"immediate"` | Per-edit rule set |
| `consent` | `"accepted"` \| `"declined"` | (local) | Install consent, recorded by CLI / `hooks on` |
| `limits.maxFindings` | number | `5` | Cap findings in the prompt |
| `limits.maxChars` | number | `8000` | Cap message size |
| `limits.maxFileBytes` | number | `131072` | Skip larger files |

### `detector` keys used by the hook

| Key | Meaning |
|---|---|
| `ignoreRules` | Suppress rule ids project-wide |
| `ignoreFiles` | Suppress all rules for matching globs |
| `ignoreValues` | Value- and file-scoped suppressions |
| `extensions` | Extra template/source suffixes + engine |
| `designSystem.enabled` | Design-system drift checks (default on) |
| `advisoryRules` | `"exclude"` (default) or `"include"` |

Legacy env overrides (win over config when set):

| Variable | Effect |
|---|---|
| `IMPECCABLE_HOOK_DISABLED` | Skip all hook work (`1`/`true`/`yes`/`on`) |
| `IMPECCABLE_HOOK_QUIET` | Quiet acks |
| `IMPECCABLE_HOOK_LOG` | NDJSON audit path |
| `IMPECCABLE_HOOK_DEPTH` / `CLAUDE_HOOK_DEPTH` | Re-entrancy guard |
| `IMPECCABLE_HOOK_DEBUG` | stderr on unexpected errors |
| `IMPECCABLE_HOOK_HARNESS` | Force harness id for payload shape |

Session state: `.impeccable/hook.cache.json` (dedupe, edit counts, touched files for Stop). Cursor may use pending/denial tracking in the same cache family.

## Manage with `/impeccable hooks`

Routes to `node …/hook-admin.mjs <action>`. Prefer this over hand-editing config (except `detector.extensions`).

| Action | Effect |
|---|---|
| `status` (default) | Enabled state, config paths, ignores, env override, cache path |
| `on` | `hook.enabled: true`, local consent `accepted`, repair provider manifests |
| `off` | `hook.enabled: false` |
| `ignore-rule <id>` | Append to `detector.ignoreRules` (`overused-font` needs `--all-values`) |
| `ignore-file <glob>` | Suppress every rule on matching files |
| `ignore-value <id> <value> [--shared\|--local] [--reason] [--file]` | Narrowest value/file suppressions |
| `reset` | Remove project hook config, cache, Cursor pending queue |

Example config shape:

```json
{
  "hook": {
    "enabled": true,
    "quiet": false,
    "perEditRules": "immediate",
    "auditLog": null
  },
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": [],
    "ignoreValues": [],
    "extensions": [{ "ext": ".blade.php", "engine": "html" }],
    "designSystem": { "enabled": true },
    "advisoryRules": "exclude"
  }
}
```

## Intentional findings workflow

The hook **never** writes ignore config. Persist exceptions only after the user confirms a finding is intentional, via `hook-admin.mjs` (or `npx impeccable ignores`).

Prefer narrowest first:

1. Exact `ignore-value` command printed next to a value-specific finding (fonts, easing, etc.).
2. `ignore-value <id> "*" --file <path>` for a single rule on one still-reviewable surface.
3. `ignore-file <path>` only when the whole file is out of design scope (fixture, generated, deliberate slop demo).
4. `ignore-rule <id>` only for project-wide rule suppression when the user asks.
5. Inline comments only when the waiver must travel with a standalone export: `impeccable-disable <rule>`, `impeccable-disable-line`, `impeccable-disable-next-line` (optional reason after `:` or `--`). Honored by the detector unless `--no-inline-ignores` / `--no-config`.

```bash
node skill/scripts/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
node skill/scripts/hook-admin.mjs ignore-value design-system-font-size "*" --file "src/overlay/widget.js" --reason "Widget owns its type scale"
node skill/scripts/hook-admin.mjs ignore-file "src/legacy/Card.tsx"
```

Do not “fix” intentional design solely to silence the hook, and do not add inline disables to skip real defects.

## Operational checklist

<Steps>
  <Step title="Install skill and hook">
    Run `npx impeccable install` (or provider plugin install). Accept hook consent or pass `--no-hooks`. Complete harness trust (Codex `/hooks`, Grok `/hooks-trust`, Cursor Hooks on).
  </Step>
  <Step title="Verify Node and status">
    Ensure Node 22+ is on the agent shell PATH. Run `/impeccable hooks status` (or `node skill/scripts/hook-admin.mjs status`) and confirm `state: enabled` with no unexpected `IMPECCABLE_HOOK_DISABLED`.
  </Step>
  <Step title="Edit a UI file">
    After Edit/Write on a scanned extension, expect either findings context, a clean ack (unless quiet), or Cursor deny. Set `hook.auditLog` or `IMPECCABLE_HOOK_LOG` if you need NDJSON traces.
  </Step>
  <Step title="Handle findings">
    Fix real issues, or after explicit user confirmation persist the narrowest ignore. For full taste/copy rules deferred under tiering, wait for Stop or run `npx impeccable detect` / `/impeccable audit`.
  </Step>
</Steps>

## Failure modes and skips

| Situation | Hook behavior |
|---|---|
| `hook.enabled: false` or `IMPECCABLE_HOOK_DISABLED` | No scan |
| Native platform | No scan |
| Missing/unsupported Node | Guarded command exits 0; Claude/Codex may show one `systemMessage` |
| Detector missing / throws | Allow / silent; audit may record `detector-missing` / `detector-threw` |
| Malformed config JSON | File ignored; defaults + remaining config used |
| >6 edits on same file (post-edit) | Suppression notice once, then quiet for that file this session |
| No automatic hook in harness | Skill may require a manual detector run at end |

## Relation to CLI detect

| | Design hook | `npx impeccable detect` |
|---|---|---|
| Trigger | Harness edit/Stop events | Explicit CLI |
| Controlled by `hook.enabled` | Yes | No |
| Shares detector ignores / designSystem | Yes | Yes (unless `--no-config`) |
| Blocks writes | Cursor only | No (exit codes for CI) |

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Install paths, provider selection, and hook consent on install/update.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Hook capability matrix and trust steps per AI harness.
  </Card>
  <Card title="Manage detector ignores" href="/manage-detector-ignores">
    ignoreRules, ignoreFiles, ignoreValues, and inline disable comments.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Full `.impeccable/config.json` and config.local.json keys.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    IMPECCABLE_HOOK_* and related env overrides.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Native platform values that skip the design hook.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule registry, categories, and finding shape.
  </Card>
  <Card title="Detect in CI" href="/detect-in-ci">
    Non-interactive detect without relying on the edit hook.
  </Card>
</CardGroup>

---

## 12. Pin shortcuts

> Create and remove standalone harness shortcuts (for example `/audit`) that redirect to `/impeccable <command>` across discovered skill directories.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/12-pin-shortcuts.md
- Generated: 2026-08-05T07:35:43.678Z

### Source Files

- `skill/scripts/pin.mjs`
- `skill/SKILL.src.md`
- `skill/scripts/command-metadata.json`
- `scripts/lib/utils.js`
- `tests/pin.test.mjs`

---
title: "Pin shortcuts"
description: "Create and remove standalone harness shortcuts (for example `/audit`) that redirect to `/impeccable <command>` across discovered skill directories."
---

`skill/scripts/pin.mjs` creates and removes lightweight standalone skill shims so a design sub-command can appear as its own harness skill (for example `/audit` or `$audit`) while still executing the full `/impeccable <command>` or `$impeccable <command>` workflow. The Impeccable skill routes pin requests through this script; it is not an `npx impeccable` CLI sub-command.

## What a pin is

A pin is a one-file skill directory named after a valid design sub-command:

```text
<project-root>/<harness>/skills/<command>/SKILL.md
```

That file is a redirect shim, not a second implementation of the command. When the harness loads the pinned skill, the model is instructed to invoke `impeccable <command>` with the same arguments and follow that workflow.

| Property | Value |
|---|---|
| Source script | `skill/scripts/pin.mjs` (shipped into each provider skill tree as `…/impeccable/scripts/pin.mjs`) |
| Metadata source | Sibling `command-metadata.json` (`description`, `argumentHint`) |
| Safety marker | `<!-- impeccable-pinned-skill -->` |
| Scope | Project root only; every discovered harness that already has Impeccable installed |
| Not pinnable | Utility routes such as `doctor` and `hooks` (they are not in `VALID_COMMANDS`) |

## Prerequisites

1. Impeccable is installed under at least one harness skills directory as `impeccable` or the legacy prefixed name `i-impeccable`.
2. The process runs from (or under) a project root that has `package.json`, `.git`, or `skills-lock.json` (the script walks up from `cwd` to find one).
3. Node can execute the installed script path.

If no harness directory contains Impeccable, pin prints `No harness directories with impeccable installed found.` and exits `0` without writing files.

## Usage

### Via the skill (agent path)

SKILL source instructs the agent:

```bash
node <scripts_path>/pin.mjs <pin|unpin> <command>
```

`<scripts_path>` is the provider-local path to the installed skill scripts (for example `.claude/skills/impeccable/scripts` or `.cursor/skills/impeccable/scripts`). After the agent runs the script, it should report the script result concisely and relay stderr verbatim on error.

### Direct invocation

From a project that already has Impeccable installed under one or more harness dirs:

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
node .claude/skills/impeccable/scripts/pin.mjs unpin audit
```

Any copy of the script under an installed harness works; the script discovers **all** eligible harnesses from the project root, not only the harness that owns the script path.

### Arguments

| Argument | Required | Values |
|---|---|---|
| action | yes | `pin` or `unpin` |
| command | yes | One of `VALID_COMMANDS` (see below) |

Missing arguments, an unknown action, or an unknown command exit with code `1` and print usage or the available command list.

## Pinnable commands

`VALID_COMMANDS` in `pin.mjs` (23 names):

| Build / setup | Evaluate | Refine | Enhance | Fix | Iterate |
|---|---|---|---|---|---|
| `craft`, `init`, `extract`, `document`, `shape` | `critique`, `audit` | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` | `clarify`, `adapt`, `optimize` | `live` |

These are the design sub-commands under the single `impeccable` skill. Maintenance utilities (`doctor`, `hooks`, pin itself) are intentionally excluded so they do not expand the harness skill menu.

Descriptions and `argument-hint` values for pinned frontmatter come from `skill/scripts/command-metadata.json`. If a key is missing there, the generated description falls back to `Shortcut for <prefix>impeccable <command>.` and the hint falls back to `[target]`.

## Harness discovery

`HARNESS_DIRS` scanned under the project root:

```text
.claude  .cursor  .gemini  .codex  .agents  .agent  .github  .grok
.trae  .trae-cn  .pi  .opencode  .kiro  .rovodev  .vibe  .qoder
```

For each harness, the script only acts when:

```text
<harness>/skills/impeccable
```

or

```text
<harness>/skills/i-impeccable
```

exists. Empty harness folders without Impeccable are ignored.

### Command prefix per harness

| Harnesses | Prefix written into the pin body |
|---|---|
| `.codex`, `.agents` | `$` (for example `$impeccable audit`) |
| All other harnesses in the list | `/` (for example `/impeccable audit`) |

`tests/pin.test.mjs` asserts this split when pinning `audit` into `.claude`, `.cursor`, `.agents`, and `.codex`.

## Pin behavior

For each eligible `…/skills` directory:

1. Build `SKILL.md` from metadata and the harness command prefix.
2. If `<skills>/<command>/` already exists and its `SKILL.md` does **not** contain the pin marker, log `SKIP: … (non-pinned skill already exists)` and leave it alone.
3. Otherwise create the directory and write (or overwrite) the pinned `SKILL.md`.
4. Log `+ <skillDir>` for each write.

When at least one location is written:

```text
Pinned '<command>' as a standalone shortcut in N location(s).
Use the pinned command directly in each harness.
```

Re-pinning an already pinned skill is allowed: the marker identifies it as owned by Impeccable, so the file is rewritten with current metadata.

### Generated pin shape

```yaml
---
name: audit
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. …"
argument-hint: "[area (feature, page, component...)]"
user-invocable: true
---

<!-- impeccable-pinned-skill -->

This is a pinned shortcut for `/impeccable audit`.

Invoke /impeccable audit, passing along any arguments provided here, and follow its instructions.
```

On Codex / Agents harnesses the body uses `$impeccable audit` instead of `/impeccable audit`.

## Unpin behavior

For each eligible harness:

1. Require `<skills>/<command>/SKILL.md` to exist.
2. Require the pin marker in that file; otherwise log `SKIP: … (not a pinned skill)` and do not delete.
3. Remove the entire skill directory recursively.
4. Log `- <skillDir>`.

Outcomes:

| Case | Message | Exit |
|---|---|---|
| One or more pins removed | `Unpinned '<command>' from N location(s).` | `0` |
| Nothing removed | `No pinned '<command>' shortcut found.` | `0` |

## Exit codes and messages

| Situation | Exit | Notes |
|---|---|---|
| Missing action/command | `1` | Prints usage and available commands |
| Unknown action | `1` | `Unknown action: … Use 'pin' or 'unpin'.` |
| Unknown command | `1` | Lists `VALID_COMMANDS` |
| Pin with no Impeccable harnesses | `0` | Message only; no files written |
| Pin success | `0` | Even if some dirs were skipped as non-pinned |
| Unpin with nothing to remove | `0` | Message only |

## Workflow

<Steps>
  <Step title="Install Impeccable into the harnesses you use">
    Install or link the skill so at least one of `<harness>/skills/impeccable` or `…/i-impeccable` exists in the project.
  </Step>
  <Step title="Pin a frequent command">
    Ask the agent to pin (or run the script directly), for example:

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
```

  </Step>
  <Step title="Verify the shim">
    Confirm `<harness>/skills/<command>/SKILL.md` exists, contains `<!-- impeccable-pinned-skill -->`, and names the correct `<prefix>impeccable <command>` redirect.
  </Step>
  <Step title="Use the shortcut">
    In the harness command menu, invoke the short name (`/audit`, `$audit`, and so on). The agent should load the pin and then run the full Impeccable sub-command with your arguments.
  </Step>
  <Step title="Unpin when finished">
```bash
node .claude/skills/impeccable/scripts/pin.mjs unpin audit
```
    Only directories that still carry the pin marker are removed.
  </Step>
</Steps>

## Safety and constraints

- **User skills are preserved.** Pin never overwrites a pre-existing skill directory whose `SKILL.md` lacks the pin marker. Unpin never deletes such a directory.
- **No global install scan.** Only project-root harness trees are considered.
- **No design logic in the pin.** The pin file does not load `reference/<command>.md`; it only redirects to the main skill.
- **Menu cost.** Each pin adds another top-level skill entry in every eligible harness. Prefer pinning high-frequency commands rather than every sub-command.
- **Not a package CLI.** `npx impeccable pin` is not defined; use the skill script path.

## Maintainer notes

When adding a new design sub-command that should be pinnable:

1. Add the command to the router / skill surface (`skill/SKILL.src.md`, `IMPECCABLE_SUB_COMMANDS` or related build lists as required by the new-command checklist).
2. Add metadata to `skill/scripts/command-metadata.json`.
3. Add the name to `VALID_COMMANDS` in `skill/scripts/pin.mjs`.
4. Keep `doctor` and similar maintenance tools out of `VALID_COMMANDS` unless product intent changes.

Regression coverage lives in `tests/pin.test.mjs` (provider command-prefix rendering for pin content).

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `No harness directories with impeccable installed found.` | Skills not installed under any listed harness | Install/link Impeccable into the project harnesses you use |
| `SKIP: … (non-pinned skill already exists)` | A real skill already owns that name | Rename or remove the conflicting skill, or choose a different pin |
| `Unknown command: …` | Name not in `VALID_COMMANDS` | Use a design sub-command from the table above |
| Pin created but harness still shows only `/impeccable …` | Harness cache or skill discovery lag | Restart the harness / reload skills for that project |
| `$` vs `/` mismatch | Expected: `.codex` / `.agents` use `$` | Use the prefix for that harness; do not hand-edit pins across providers |
| Unpin left a skill behind | File lacked the pin marker | Inspect `SKILL.md`; if it is user-authored, remove it manually only if intentional |

## Related pages

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Single `/impeccable` skill, sub-command table, and Setup load order that pins redirect into.
  </Card>
  <Card title="Skill commands reference" href="/skill-commands-reference">
    Catalog of pinnable sub-commands, argument hints, and reference files.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Harness directories, install aliases, and command-prefix differences across providers.
  </Card>
  <Card title="Installation" href="/installation">
    Install paths that place `impeccable` under harness `skills/` trees pin.mjs discovers.
  </Card>
  <Card title="Contributing" href="/contributing">
    Checklist for adding commands, including updating `VALID_COMMANDS` in `pin.mjs`.
  </Card>
</CardGroup>

---

## 13. Manage detector ignores

> Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config, including value scoping, reasons, and inline disable comments.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/13-manage-detector-ignores.md
- Generated: 2026-08-05T07:35:36.733Z

### Source Files

- `cli/bin/commands/ignores.mjs`
- `cli/lib/impeccable-config.mjs`
- `cli/engine/shared/inline-ignores.mjs`
- `skill/scripts/hook-lib.mjs`
- `tests/cli-ignores.test.js`
- `tests/inline-ignores.test.mjs`

---
title: "Manage detector ignores"
description: "Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config, including value scoping, reasons, and inline disable comments."
---

Detector ignores live under the `detector` key in `.impeccable/config.json` (shared) and `.impeccable/config.local.json` (per-developer). `npx impeccable detect` and the design hook both load the merged config; `npx impeccable ignores` is the CLI CRUD surface for the same keys. Inline `impeccable-disable*` comments suppress findings inside a single file without writing config.

## Ignore kinds

| Config key | Effect | Typical use |
|---|---|---|
| `ignoreRules` | Drop every finding for listed rule ids project-wide | Rule is never relevant for this product |
| `ignoreFiles` | Skip matching paths entirely (all rules) | Fixtures, generated assets, deliberate slop demos |
| `ignoreValues` | Drop findings for a rule when the extracted value matches; optional `files` globs scope the entry | Brand fonts, intentional motion, one noisy rule in one file |

```json
{
  "detector": {
    "ignoreRules": ["side-tab"],
    "ignoreFiles": ["src/legacy/**", "tests/fixtures/**"],
    "ignoreValues": [
      {
        "rule": "overused-font",
        "value": "inter",
        "createdAt": "2026-04-01T12:00:00.000Z",
        "reason": "Brand font"
      },
      {
        "rule": "side-tab",
        "value": "*",
        "files": ["**/TopicCard.jsx"],
        "createdAt": "2026-04-01T12:05:00.000Z",
        "reason": "CSS triangle decoration"
      }
    ]
  }
}
```

<Info>
Legacy builds stored the same arrays under `hook.*`. Readers still accept that layout, but every write migrates detector keys into `detector` and strips them from `hook`.
</Info>

## Shared vs local scope

| File | Default for writes | Intended ownership |
|---|---|---|
| `.impeccable/config.json` | Yes (`--shared`) | Team-reviewed, commit with the repo |
| `.impeccable/config.local.json` | `--local` | Personal exceptions |

`config.local.json` is added to `.git/info/exclude` on first local write (`# impeccable-config-ignore-start` … `# impeccable-config-ignore-end`). Merged reads apply shared first, then local: arrays union; `ignoreValues` dedupe on `rule` + normalized `value` + sorted `files`.

| Flag | Where it applies |
|---|---|
| `--shared` | Shared config only (default for add) |
| `--local` | Local config only |
| `--all` | Shared **and** local; remove and clear only |

## CLI: `impeccable ignores`

```bash
npx impeccable ignores <action> [options]
# alias: npx impeccable ignore ...
```

### Actions

| Action | Aliases | Arguments |
|---|---|---|
| `list` | `status`, `ls` (default) | none |
| `add-rule` | `ignore-rule` | `<rule>` [`--all-values`] |
| `add-file` | `ignore-file` | `<glob>` |
| `add-value` | `ignore-value`, `update-value` | `<rule> <value>` [`--file <glob>`…] [`--reason <text>`] |
| `remove-rule` | `rm-rule` | `<rule>` |
| `remove-file` | `rm-file` | `<glob>` |
| `remove-value` | `rm-value` | `<rule> <value>` [`--file <glob>`…] |
| `clear` | | none (clears all three arrays in the selected scope) |

### Value and rule options

<ParamField body="--file" type="string">
Scope an `add-value` / `remove-value` entry to one or more globs. Repeatable. Empty globs and flag-looking values (for example `--file --reason`) are rejected.
</ParamField>

<ParamField body="--reason" type="string">
Optional documentation stored on the `ignoreValues` entry. On re-add with the same key, updates the stored reason. Accepted on `add-rule` for symmetry but not stored on `ignoreRules`.
</ParamField>

<ParamField body="--all-values" type="boolean">
Required to put `overused-font` into `ignoreRules`. Without it the CLI refuses and points at `add-value`.
</ParamField>

### Value normalization

Stored and compared values are normalized: trim, strip wrapping quotes, `+` → space, collapse whitespace, lowercase. `design-system-color` also matches equivalent colors across hex / `rgb()` / `hsl()` forms.

Value-bearing rules for extraction and ignore matching:

- `overused-font`
- `bounce-easing`
- `design-system-font`
- `design-system-color`
- `design-system-radius`
- `design-system-font-size`

Rules without an extractable value (for example `side-tab`) only match a value ignore when the entry is a file-scoped wildcard (`value: "*"` plus `files`).

### Wildcard policy

A bare `add-value <rule> "*"` is refused. Scope it:

```bash
npx impeccable ignores add-value side-tab "*" --file "components/TopicCard.jsx"
```

Project-wide rule silence uses `add-rule`, not an unscoped wildcard. Existing unscoped wildcards on disk can still be removed with `remove-value` (removal allows unscoped `*`).

### Examples

```bash
# List merged + per-file views
npx impeccable ignores list

# Ignore a whole path tree (shared)
npx impeccable ignores add-file "src/legacy/**"

# Brand font (shared, with reason)
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

# One rule, one file only
npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"

# Personal exception
npx impeccable ignores add-value overused-font Roboto --local --reason "Sandbox prototype"

# Broad rule suppress (overused-font needs the flag)
npx impeccable ignores add-rule overused-font --all-values

# Remove and clear
npx impeccable ignores remove-value overused-font Inter
npx impeccable ignores remove-file "src/legacy/**" --all
npx impeccable ignores clear --local
```

### List output shape

```text
Impeccable detector ignores
  shared file: .impeccable/config.json
  local file:  .impeccable/config.local.json

Merged:
  ignoreRules:  ...
  ignoreFiles:  ...
  ignoreValues: overused-font=inter - Brand font, side-tab=* [**/TopicCard.jsx]
  designSystem: enabled

Shared:
  ...

Local:
  ...
```

`ignoreValues` lines print as `rule=value`, optional `[file, …]`, optional `- reason`.

## Prefer the narrowest exception

| Situation | Prefer |
|---|---|
| Confirmed brand font / motion / token value | `add-value <rule> <value>` |
| One non-value rule noisy in one file | `add-value <rule> "*" --file <glob>` |
| Entire path out of design review | `add-file <glob>` |
| Rule never applies product-wide | `add-rule <id>` (and `--all-values` for `overused-font`) |
| Waiver must travel with an exported standalone file | Inline `impeccable-disable*` comment |

<Warning>
`ignoreFiles` silences **every** current and future rule for matching paths. Prefer a file-scoped `ignoreValues` entry when the surface should still be reviewed for other issues.
</Warning>

## Design hook path

The skill’s hooks admin writes the same `detector` keys. Prefer the dedicated CLI for bulk CRUD; use the hook flow when confirming an intentional finding from an edit-time scan.

```bash
# Skill-invoked admin (same config files)
node <scripts_path>/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
node <scripts_path>/hook-admin.mjs ignore-value side-tab "*" --file "src/components/TopicCard.jsx"
node <scripts_path>/hook-admin.mjs ignore-file "src/legacy/**"
node <scripts_path>/hook-admin.mjs ignore-rule overused-font --all-values
```

The hook never auto-writes ignores. Persist only after explicit confirmation that the finding is intentional.

## Inline disable comments

Config is the default for repo policy. Inline directives cover waivers that belong **in the file** (exported HTML, emailed docs, snippets scanned out of context).

| Directive | Scope |
|---|---|
| `impeccable-disable <rule>[, <rule>...]` | Whole file |
| `impeccable-disable-line <rule>...` | Same line |
| `impeccable-disable-next-line <rule>...` | Following line |
| bare `impeccable-disable` or `impeccable-disable *` | Every rule |

Reasons are optional after eslint-style `--` or biome-style `:` and are discarded at scan time (they only keep free text out of the rule list). Keyword match is case-insensitive. Comment syntax is ignored: `//`, `/* */`, `<!-- -->`, `#`, `{/* */}`, `{# #}` all work; trailing closers are stripped.

```css
/* impeccable-disable overused-font -- exported brand doc */
.brand { font-family: Inter; }

.a { font-family: Inter; } /* impeccable-disable-line overused-font */

/* impeccable-disable-next-line bounce-easing: intentional playful affordance */
.ball { animation: bounce-ball 1s; }
```

```html
<!-- impeccable-disable overused-font -- standalone export -->
```

Findings without a line number (common for static HTML page-level rules) only match whole-file directives.

### Engine integration

`detectText` and `detectHtml` apply inline directives after rule evaluation unless disabled:

| Detect flag | Behavior |
|---|---|
| (default) | Load project config + honor inline directives |
| `--no-inline-ignores` | Keep config filters; ignore inline comments |
| `--no-config` | Skip project ignores **and** inline directives |

```bash
npx impeccable detect src/
npx impeccable detect --no-inline-ignores src/widget.css
npx impeccable detect --no-config --json src/   # raw scan
```

After per-file detection, the CLI runs `filterDetectionFindings` (rules + values) and skips paths matched by `ignoreFiles` before scanning.

## Glob matching

`ignoreFiles` and per-entry `files` support `*`, `**`, `?`, and `{a,b}` alternation. Matching tries the raw path, absolute path, path relative to the project root, and for value scopes each path suffix (so `**/TopicCard.jsx` and `TopicCard.jsx` can both match `components/TopicCard.jsx`).

## Verify

```bash
npx impeccable ignores list
npx impeccable detect --json path/to/file.tsx
# Expect: suppressed findings absent; exit 0 when no non-advisory findings remain
npx impeccable detect --no-config --json path/to/file.tsx
# Expect: same issues return if only config was suppressing them
```

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| `Wildcard value ignores must be scoped with --file` | `add-value … "*"` without `--file`; use `--file` or `add-rule` |
| `overused-font is value-specific by default` | Used `add-rule overused-font` without `--all-values` |
| `--file` / `--reason` errors | Empty glob, or a flag consumed as a glob; pass a non-empty glob string |
| Remove reports “No matching…” | Scope mismatch (`--local` vs shared), different `files` set, or value not normalized the same way |
| Local file missing from git status | Expected: local config is exclude-listed under `.git/info/exclude` |
| Inline comment not honored | Typo in directive name; or scan used `--no-inline-ignores` / `--no-config` |
| Line-scoped directive missed a page-level finding | Line-less findings only match whole-file `impeccable-disable` |

## Related pages

<CardGroup>
  <Card title="Design hook" href="/design-hook">
    Edit-time scans, intentional-finding workflow, and quiet/disabled controls that share these ignores.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full `detect` / `ignores` flags, JSON output, and exit codes.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Complete `.impeccable/config.json` and `config.local.json` schema.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, categories, and finding shape used in ignore keys.
  </Card>
  <Card title="Detect in CI" href="/detect-in-ci">
    Non-interactive detect with project ignores and exit code 0 vs 2.
  </Card>
</CardGroup>

---

## 14. CLI reference

> Commands for detect, ignores, install, link, update, check, and help: flags, defaults, exit codes, JSON output, URL scanning, and detect shorthand targets.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/14-cli-reference.md
- Generated: 2026-08-05T07:51:10.991Z

### Source Files

- `cli/bin/cli.js`
- `cli/engine/cli/main.mjs`
- `cli/bin/commands/skills.mjs`
- `cli/bin/commands/ignores.mjs`
- `README.npm.md`
- `package.json`

---
title: "CLI reference"
description: "Commands for detect, ignores, install, link, update, check, and help: flags, defaults, exit codes, JSON output, URL scanning, and detect shorthand targets."
---

The npm package `impeccable` ships a Node CLI (`bin`: `cli/bin/cli.js`, Node `>=22.18.0`) that routes top-level commands to the detector engine, the ignores manager, and the skills installer. Invoke it as `npx impeccable …` or a global `impeccable` install. The package also exports the detector as a library (`main` / `exports["."]` → `cli/engine/detect-antipatterns.mjs`; `exports["./browser"]` → the browser bundle).

## Command router

```text
impeccable <command> [options] [args…]
```

| Command | Handler | Role |
|---|---|---|
| `detect` | `cli/engine/cli/main.mjs` (`detectCli`) | Scan files, dirs, stdin, or URLs |
| `ignores` / `ignore` | `cli/bin/commands/ignores.mjs` | Manage detector ignore config |
| `help` | `cli/bin/commands/skills.mjs` | List skill commands from the API |
| `install` | skills module | Download/copy compiled skills |
| `link` | skills module | Symlink skills from a local checkout |
| `update` | skills module | Refresh installed skills |
| `check` | skills module | Report whether project skills need update |
| `skills <sub>` | skills module | Legacy namespace for help/install/link/update/check |

Global flags on the root binary:

| Flag | Behavior |
|---|---|
| `--help` / `-h` / no args | Print command list and exit `0` |
| `--version` / `-v` | Print `package.json` version and exit `0` |

**Detect shorthand.** If the first argument is not a known command but looks like a detect target (flag, `http(s)://` URL, path-shaped string containing `/`, `\`, or `.`, or an existing path such as extension-less `Dockerfile`), the router rewrites argv and runs `detect`. Bare unknown words fail with exit `1` instead of being statted as paths.

**Prompt abort.** Interactive skill prompts can throw `IMPECCABLE_PROMPT_ABORT`; the root catcher prints `Aborted.` and exits `130`.

```bash
npx impeccable --help
npx impeccable --version
npx impeccable src/                 # shorthand → detect
npx impeccable detect --json src/
npx impeccable skills install -y    # legacy namespace
```

## `detect`

```text
impeccable detect [options] [file-or-dir-or-url…]
```

Default target when none is given and stdin is a TTY: `process.cwd()`. Non-TTY stdin with no targets reads stdin (hook-style JSON with `tool_input.file_path`, or raw text as `<stdin>`).

### Flags

<ParamField body="--json" type="boolean" default="false">
Pretty-print findings as a JSON array on stdout. Empty scan writes `[]`.
</ParamField>

<ParamField body="--quiet" type="boolean" default="false">
Text mode only: print the primary findings summary (and advisory count note) on stderr; omit per-finding detail.
</ParamField>

<ParamField body="--scope" type="string">
Comma-separated design domains. Valid values today: `type`, `layout`. Bare `--scope` or unknown names exit `1`. Empty list means no filtering.
</ParamField>

<ParamField body="--viewport" type="WxH" default="1280x800">
Browser viewport for URL scans, e.g. `--viewport 390x844`. Format: two integers 2–5 digits joined by `x`. Invalid form exits `1`.
</ParamField>

<ParamField body="--no-config" type="boolean" default="false">
Skip project detector config, ignore lists, inline ignore comments, and DESIGN.md / design-system loading.
</ParamField>

<ParamField body="--no-inline-ignores" type="boolean" default="false">
Do not honor in-file `impeccable-disable*` comments (still loads project config unless `--no-config`).
</ParamField>

<ParamField body="--no-design-system" type="boolean" default="false">
Do not load per-target DESIGN.md / `.impeccable/design.json` context.
</ParamField>

<ParamField body="--no-advisory" type="boolean" default="false">
Drop advisory findings before output and exit-code math.
</ParamField>

<ParamField body="--help" type="boolean">
Print detect usage and exit `0`.
</ParamField>

Deprecated flags (accepted, ignored, note on stderr):

| Flag | Note |
|---|---|
| `--fast` / `-fast` | Full scan always runs; regex-only path no longer used |
| `--gpt`, `--gemini` | Generated-UI tells run by default |

Aliases: `-json` → `--json`.

### Detection modes

| Target | Engine | Notes |
|---|---|---|
| `.html` / `.htm` | Static HTML/CSS (`detectHtml`) | Resolves linked CSS; design system per file project root |
| Other scannable files | Regex text (`detectText`) | CSS, SCSS/SASS/LESS, JS/TS/JSX/TSX, Vue, Svelte, Astro, Blade |
| Directory walk | Both per extension | Skips `node_modules`, `dist`, `build`, `__pycache__`, and most hidden dirs (except `.vitepress`, `.vuepress`, `.storybook`) |
| `http://` / `https://` | Puppeteer (`detectUrl`) | Optional dependency `puppeteer`; design system not loaded for remote hosts |
| `file://` | Puppeteer | Local path used for design-system resolution when mappable |

Directory scans build an import graph and may attach `importedBy` basenames on findings. When not in `--json`/`--quiet`, framework config detection can suggest scanning `http://localhost:<port>` for more accurate results. Interactive TTY scans of >50 files prompt to continue; declining exits `0`.

### Project config applied by default

Unless `--no-config`:

- `.impeccable/config.json` and `.impeccable/config.local.json` → `detector.ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem.enabled`
- Inline comments: `impeccable-disable`, `impeccable-disable-line`, `impeccable-disable-next-line` (rule ids comma-separated, or `*` / omit for all)

### Finding shape (JSON)

Each finding includes at least:

| Field | Type | Meaning |
|---|---|---|
| `antipattern` | string | Rule id |
| `name` | string | Display name |
| `description` | string | Human description |
| `severity` | string | Default `warning` |
| `category` | string \| null | e.g. slop / quality |
| `file` | string | Path or URL label |
| `line` | number | Line when known; `0` otherwise |
| `snippet` | string | Short evidence |
| `advisory` | boolean | Present only when `true` |
| `importedBy` | string[] | Optional; basenames of importers |

### Advisory findings

Rules marked advisory (currently `em-dash-overuse`) list in a separate dimmed text section, carry `"advisory": true` in JSON, and **never** contribute to the failure count or non-zero exit. `--no-advisory` removes them entirely.

### Exit codes (`detect`)

| Code | When |
|---|---|
| `0` | No primary findings (including advisory-only scans, empty scan, help) |
| `2` | One or more non-advisory findings |
| `1` | Invalid `--scope` / `--viewport` (and other hard parse failures) |

URL scan failures for a single target write `Error: …` to stderr and continue; inaccessible path targets warn and skip.

### Examples

```bash
npx impeccable detect src/
npx impeccable detect index.html styles.css
npx impeccable detect https://example.com
npx impeccable detect file:///abs/path/to/page.html
npx impeccable detect --json --quiet --scope type,layout src/
npx impeccable detect --viewport 390x844 --no-advisory https://localhost:3000
npx impeccable detect --no-config --no-design-system dist/index.html
```

<RequestExample>
```bash
npx impeccable detect --json src/Button.tsx
```
</RequestExample>

<ResponseExample>
```json
[
  {
    "antipattern": "overused-font",
    "name": "Overused font",
    "description": "…",
    "severity": "warning",
    "category": "slop",
    "file": "/project/src/Button.tsx",
    "line": 12,
    "snippet": "font-family: Inter"
  }
]
```
</ResponseExample>

## `ignores`

```text
impeccable ignores <action> [options]
impeccable ignore <action> …   # alias
```

Writes detector ignore fields under `.impeccable/config.json` (shared, default) or `.impeccable/config.local.json` (`--local`). Default action with no args: `list`.

### Actions

| Action | Aliases | Arguments |
|---|---|---|
| `list` | `status`, `ls` | None |
| `add-rule` | `ignore-rule` | `<rule>` `[--all-values]` |
| `add-file` | `ignore-file` | `<glob>` |
| `add-value` | `ignore-value`, `update-value` | `<rule> <value>` `[--file <glob>]…` `[--reason <text>]` |
| `remove-rule` | `rm-rule` | `<rule>` |
| `remove-file` | `rm-file` | `<glob>` |
| `remove-value` | `rm-value` | `<rule> <value>` (same value flags as add) |
| `clear` | — | Scope flags only |

### Scope flags

| Flag | Meaning |
|---|---|
| `--shared` | Target shared config (default) |
| `--local` | Target `config.local.json` |
| `--all` | Remove/clear both scopes only |

Only one of `--shared`, `--local`, `--all` may be set.

### Value-ignore rules

- Wildcard value `*` requires `--file <glob>` on add (project-wide `*` is rejected).
- `overused-font` cannot be whole-rule ignored without `--all-values`; prefer `add-value overused-font <font>`.
- Empty or flag-shaped globs for `--file` are rejected.
- `list` prints merged, shared, and local `ignoreRules` / `ignoreFiles` / `ignoreValues` and design-system enabled state.

```bash
npx impeccable ignores list
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"
npx impeccable ignores remove-value overused-font Inter --all
npx impeccable ignores clear --local
```

## Skills: `install`, `link`, `update`, `check`, `help`

These are first-class top-level commands and also work under `impeccable skills <sub>`. Bundle download URL: `https://impeccable.style/api/download/bundle/universal`. Override with env `IMPECCABLE_BUNDLE_PATH` (directory or zip) for offline/local bundles.

### Provider aliases

Install targets map friendly names to harness folders, including: `claude` → `.claude`, `cursor` → `.cursor`, `codex`/`agents` → `.agents`, `gemini` → `.gemini`, `github`/`copilot` → `.github`, `grok`/`xai` → `.grok`, `opencode`, `pi`, `kiro`, `qoder`, `trae`, `trae-cn`, `rovodev`/`rovo-dev`, `antigravity`/`agent` → `.agent`, `vibe`.

Default when nothing is detected: `.claude` + `.agents`. Global skill path overrides: Pi → `~/.pi/agent/skills`, OpenCode → `$OPENCODE_CONFIG_DIR` or `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`, Antigravity global → `~/.gemini/config/skills`.

### `install`

```text
impeccable install [flags]
```

| Flag | Meaning |
|---|---|
| `-y` / `--yes` | Non-interactive: use detected/default providers; scope defaults to **project** unless scoped explicitly; hooks install-by-default when undecided |
| `--providers=<list>` | Comma-separated provider names or folder names |
| `--scope=project\|global` (also `--project`, `--local`, `--user`, `--home`, `--global`, `--install-scope`) | Install root: project cwd tree vs home |
| `--force` | Reinstall/refresh even if already present |
| `--no-hooks` | Skip design-hook manifests |

Behavior summary:

1. Resolve providers (explicit → project harness dirs → global harness hints → defaults).
2. Resolve scope (explicit → interactive prompt → `-y` forces project).
3. Download universal bundle (or local override), copy per-provider skill variants (never cross-provider symlink), optional agents, optional hooks.
4. Hooks: prompt once (default yes) on TTY; consent stored in `.impeccable/config.local.json`; declined consent skips hooks; non-interactive defaults to install without recording consent.

```bash
npx impeccable install -y --providers=claude,codex --scope=project
npx impeccable install --no-hooks --providers=cursor
npx impeccable install --force --scope=global --providers=claude
```

### `link`

```text
impeccable link [--source=<path>] [--providers=<list>] [-y|--yes] [--force]
```

| Flag | Default / meaning |
|---|---|
| `--source` | `.impeccable` relative to project root (git root if found) |
| Bundle resolution | Prefer `<source>/dist/universal`, else provider `*/skills` under source |
| `--force` | Replace existing skill folders with symlinks |
| `-y` / `--yes` | Skip confirmation |

Fails if source has no compiled skills, nothing links (existing dirs without `--force`), or targets cannot be resolved.

```bash
npx impeccable link --source=.impeccable --providers=claude,cursor -y
```

### `update`

```text
impeccable update [flags]
```

| Flag | Meaning |
|---|---|
| `-y` / `--yes` | Non-interactive confirm; on dual project+user installs, defaults to **project** |
| `--project` / `--user` (and other scope aliases) | Force which install to update |
| `--force` | Passed through to hook merge/replace paths |
| `--no-hooks` | Do not install/update hook manifests |

Linked (submodule) providers are skipped with guidance to `git submodule update --remote` + re-`link`. Copied installs refresh from the downloaded bundle when file hashes differ.

### `check`

```text
impeccable check
```

Checks the **project** install only. Exit `0` if not installed (with install hint), or after reporting up-to-date / updates-available. Exit `1` if the bundle download/compare fails.

### `help`

```text
impeccable help
```

Fetches `https://impeccable.style/api/commands` and prints `/command` rows. Network failure exits `1`.

## Exit codes (skills and router)

| Code | Typical cause |
|---|---|
| `0` | Success, abort after user decline (some paths), `check` not installed / up to date, help list OK |
| `1` | Unknown command/subcommand, download/install/update failure, link nothing written, invalid scope/providers |
| `130` | Interactive prompt aborted (`IMPECCABLE_PROMPT_ABORT`) |
| `2` | **`detect` only** — primary findings present |

## Requirements and runtime notes

- **Node** `>=22.18.0`.
- **URL scanning** needs optional `puppeteer` (declared under `optionalDependencies`). Prefer `node` over Bun for HTML-heavy local scans if using the detector outside the packaged path.
- **CI**: use `detect --json` and/or `--quiet`; exit `2` means findings. See related CI guidance for ignores and Puppeteer setup.
- Skills install/update need network access to `impeccable.style` unless `IMPECCABLE_BUNDLE_PATH` is set.

## Related pages

<CardGroup>
  <Card title="Detect in CI" href="/detect-in-ci">
    Non-interactive detect, exit codes 0/2, ignores, optional URL scans.
  </Card>
  <Card title="Manage detector ignores" href="/manage-detector-ignores">
    ignoreRules, ignoreFiles, ignoreValues, scopes, and inline disable comments.
  </Card>
  <Card title="Installation" href="/installation">
    install/link/update paths, provider selection, project vs global, hooks consent.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    `.impeccable/config.json` and local override keys for detector and hooks.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, categories, advisory flag, engines, finding shape.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    IMPECCABLE_* and related env vars including bundle and OpenCode config dirs.
  </Card>
</CardGroup>

---

## 15. Skill commands reference

> Catalog of `/impeccable` sub-commands with argument hints, categories, reference files, and native variants for audit and adapt.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/15-skill-commands-reference.md
- Generated: 2026-08-05T07:36:04.539Z

### Source Files

- `skill/scripts/command-metadata.json`
- `skill/SKILL.src.md`
- `scripts/lib/utils.js`
- `scripts/lib/skill-categories.js`
- `skill/reference/audit.native.md`
- `skill/reference/adapt.native.md`
- `skill/reference/doctor.md`

---
title: "Skill commands reference"
description: "Catalog of `/impeccable` sub-commands with argument hints, categories, reference files, and native variants for audit and adapt."
---

Impeccable exposes **one** user-invocable skill (`impeccable`) with **23** design sub-commands. Invocation is `{{command_prefix}}impeccable <command> [args]` (for example `/impeccable audit hero`, `$impeccable polish`). The command prefix is provider-specific (`/` vs `$`). Each design command loads a playbook under `skill/reference/<command>.md` after Setup runs `context.mjs`.

Canonical sources:

| Surface | Path | Role |
|---|---|---|
| Router table | `skill/SKILL.src.md` → `## Commands` | Human-facing command list, router categories, reference paths, native variants |
| Metadata | `skill/scripts/command-metadata.json` | `description` + `argumentHint` per command (pin + build) |
| Transformer categories | `scripts/lib/skill-categories.js` | `SKILL_CATEGORIES` / `CATEGORY_ORDER` for generated argument-hint grouping |
| Suggestion list | `scripts/lib/utils.js` → `IMPECCABLE_SUB_COMMANDS` | Names expanded into `{{available_commands}}` in skill text |
| Pin allowlist | `skill/scripts/pin.mjs` → `VALID_COMMANDS` | Commands that may be pinned as standalone shortcuts |

Two utility routes sit **outside** the 23 and are **not** design commands: `hooks` and `doctor`. Pin/unpin is a script, not a sub-command in the table.

## Invocation and routing

| Case | Behavior |
|---|---|
| No argument | Load `reference/routing.md`; present a context-aware menu; **never auto-run** a command |
| Explicit or clearly implied command | Load that command’s reference (native variant when `setup.platform` is native) and follow it |
| Ambiguous between two commands | Ask once |
| Otherwise | Treat as general design work: missing PRODUCT.md on a new surface or replacement world goes through `init` then `new-work`; narrow refinement of existing code proceeds on the incumbent implementation |

Aliases and specials:

| Name | Status | Notes |
|---|---|---|
| `teach` | Alias of `init` | Not a separate catalog entry |
| `craft` | Deprecated compatibility alias | No extra behavior; ordinary new-work uses the same flow as a natural build/redesign request |
| `shape` | Active | Owns task discovery; enters new-work only for visual-world / surface-concept decisions |

Parent skill frontmatter argument shape (after build substitution):

```text
[{{command_hint}}] [target]
```

`{{command_hint}}` is filled from `command-metadata.json` keys grouped by `SKILL_CATEGORIES` order (`create · evaluate · refine · simplify · harden · system`), joined with `|` inside a group and ` · ` between groups. Commands missing a `SKILL_CATEGORIES` entry (today: `craft`) stay out of that generated hint group but still route.

## Two category taxonomies

Do not conflate them.

### Router categories (`SKILL.src.md` table)

Used in the skill’s Commands table and no-argument menu grouping:

| Router category | Commands |
|---|---|
| Build | `craft`, `shape`, `init`, `document`, `extract` |
| Evaluate | `critique`, `audit` |
| Refine | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` |
| Enhance | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` |
| Fix | `clarify`, `adapt`, `optimize` |
| Iterate | `live` |

### Transformer categories (`SKILL_CATEGORIES`)

Used by the provider build to group the parent skill’s `argument-hint` and related harness metadata:

| Category | Commands |
|---|---|
| `create` | `shape` (parent skill name `impeccable` also maps here; not a sub-command) |
| `evaluate` | `critique`, `audit` |
| `refine` | `typeset`, `layout`, `colorize`, `animate`, `delight`, `bolder`, `quieter`, `overdrive` |
| `simplify` | `distill`, `clarify`, `adapt` |
| `harden` | `polish`, `optimize`, `harden`, `onboard` |
| `system` | `init`, `document`, `extract`, `live` |
| *(unmapped)* | `craft` — deliberately omitted so it stays out of the generated argument-hint while still routing |

`CATEGORY_ORDER`: `create`, `evaluate`, `refine`, `simplify`, `harden`, `system`.

## Full command catalog

Argument hints and long descriptions come from `skill/scripts/command-metadata.json`. Router category and reference path come from the Commands table in `skill/SKILL.src.md`. Empty `argumentHint` means the command takes no positional args in metadata (scope is still often supplied conversationally).

### Build

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `craft` | `[feature description]` | `reference/craft.md` | Deprecated alias for ordinary new-work; do not require users to invoke it |
| `shape` | `[feature to shape]` | `reference/shape.md` | Multi-round discovery interview → confirmed design brief before code |
| `init` | *(none)* | `reference/init.md` | Writes PRODUCT.md (including Platform); may offer DESIGN.md / live pre-config |
| `document` | *(none)* | `reference/document.md` | Generate DESIGN.md from code (Stitch-compatible) |
| `extract` | `[target]` | `reference/extract.md` | Pull repeated patterns/tokens into the design system |

### Evaluate

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `critique` | `[area (feature, page, component...)]` | `reference/critique.md` | UX review, scoring, personas, anti-pattern signal |
| `audit` | `[area (feature, page, component...)]` | `reference/audit.md` · **native:** `reference/audit.native.md` | Technical quality (a11y, perf, theming, responsive, anti-patterns); report only, no auto-fix |

### Refine

| Command | Argument hint | Reference |
|---|---|---|
| `polish` | `[target]` | `reference/polish.md` |
| `bolder` | `[target]` | `reference/bolder.md` |
| `quieter` | `[target]` | `reference/quieter.md` |
| `distill` | `[target]` | `reference/distill.md` |
| `harden` | `[target]` | `reference/harden.md` |
| `onboard` | `[target]` | `reference/onboard.md` |

### Enhance

| Command | Argument hint | Reference |
|---|---|---|
| `animate` | `[target]` | `reference/animate.md` |
| `colorize` | `[target]` | `reference/colorize.md` |
| `typeset` | `[target]` | `reference/typeset.md` |
| `layout` | `[target]` | `reference/layout.md` |
| `delight` | `[target]` | `reference/delight.md` |
| `overdrive` | `[target]` | `reference/overdrive.md` |

### Fix

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `clarify` | `[target]` | `reference/clarify.md` | UX copy, labels, errors, microcopy |
| `adapt` | `[target] [context (mobile, tablet, print...)]` | `reference/adapt.md` · **native:** `reference/adapt.native.md` | Responsive / device / platform adaptation |
| `optimize` | `[target]` | `reference/optimize.md` | UI performance (load, render, animation, images, bundle) |

### Iterate

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `live` | *(none)* | `reference/live.md` | Browser variant mode; **web-only**; needs a running dev server |

## Native command variants

When PRODUCT.md platform resolves to `ios`, `android`, or `adaptive`, Setup step 2 routes these commands to the **native** file **instead of** the web file (one variant covers all three native platforms; OS specifics stay in `reference/ios.md` / `reference/android.md`).

| Command | Web reference | Native reference | Web file guard |
|---|---|---|---|
| `audit` | `reference/audit.md` | `reference/audit.native.md` | First lines redirect native readers to the native file |
| `adapt` | `reference/adapt.md` | `reference/adapt.native.md` | Same pattern |

Behavior differences (verified in the native playbooks):

| Concern | Web `audit` / `adapt` | Native variants |
|---|---|---|
| Inspection surface | Browser/HTML tooling, `detect.mjs` when applicable | Source-level (SwiftUI/UIKit/Compose/RN/Flutter); **no** browser tooling or `detect.mjs` |
| Scoring / standards | Web a11y, responsive, theming, anti-patterns | Platform refs: VoiceOver/TalkBack, Dynamic Type / sp, 44 pt / 48 dp targets, size classes, Material/HIG idioms |
| Report shape | `audit.md` skeleton | `audit.native.md` mirrors the same skeleton; keep both in sync when editing dimensions |
| Adaptation model | Breakpoints, fluid layouts, touch targets (incl. mobile web) | Restructure for size class / window class / foldable / platform idioms — not scale-and-stretch |

Commands such as `animate` and `layout` have **no** separate `.native.md`; platform refs loaded by Setup already cover their divergence. Do not add in-file web→native translation notes to those playbooks (native runs would pay for unused web content).

`live` and the bundled detector are **web-only**. No-argument routing must not lead with them when `setup.platform` is native.

## Utilities outside the 23

These are documented in SKILL.src.md after the Commands table. They are **not** in `IMPECCABLE_SUB_COMMANDS`, `command-metadata.json`, `SKILL_CATEGORIES`, or the design menu count.

### Pin / unpin (script)

```bash
node <scripts_path>/pin.mjs pin <command>
node <scripts_path>/pin.mjs unpin <command>
```

Creates or removes a standalone harness shortcut (for example `/audit`) that redirects to `/impeccable <command>` in discovered skill roots. `VALID_COMMANDS` matches the 23 design commands (includes `craft` and `live`).

### Hooks

```text
{{command_prefix}}impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>
```

Load `reference/hooks.md`. Manages the design detector hook for the project (config under `.impeccable/config.json` / `config.local.json`).

### Doctor

```text
{{command_prefix}}impeccable doctor
```

Load `reference/doctor.md`. Maintenance only: schema/config/proxy truth-drift report and auto fixes. Typical script entry:

```bash
node <scripts_path>/doctor.mjs --json
node <scripts_path>/doctor.mjs --fix   # apply severity: auto only
```

Do not run doctor unasked when a design command is in flight. `CONTEXT_STALE` at boot is the cheap subset of the same report.

## Shared playbooks (not sub-commands)

Loaded by Setup or by specific commands; not pinned as design menu entries:

| File | Role |
|---|---|
| `reference/new-work.md` | New surface or replacement visual world |
| `reference/craft-floor.md` | Quality floor / absolute bans immediately before UI edits |
| `reference/operate.md` | Deeper Operate / Read mode guidance |
| `reference/routing.md` | No-argument context-aware menu |
| `reference/ios.md` / `reference/android.md` | Platform conventions (also inlined by `context.mjs` for native platforms) |
| `reference/live-setup.md` | Live pre-config helpers used from init / live setup paths |
| `reference/hooks.md` / `reference/doctor.md` | Utility command playbooks |
| `reference/visualize.md` | Supporting visual-probe material (not a router table command) |

## Suggestion list vs full catalog

`IMPECCABLE_SUB_COMMANDS` (what `{{available_commands}}` expands to for next-step suggestions in skill text) is a **subset** of the 23:

```text
adapt, animate, audit, bolder, clarify, colorize, critique, delight,
distill, document, harden, layout, onboard, optimize, overdrive,
polish, quieter, shape, typeset
```

Omitted from that suggestion list (still real commands): `craft`, `init`, `extract`, `live`.

## Metadata schema

Each key in `skill/scripts/command-metadata.json`:

```json
{
  "<command>": {
    "description": "string — used for pinned shortcut skills and tooling",
    "argumentHint": "string — may be empty"
  }
}
```

There are **23** keys, matching the router table names. Adding a design command requires updating at least: `reference/<name>.md`, the Commands table in `SKILL.src.md`, `IMPECCABLE_SUB_COMMANDS` (if it should appear in suggestions), `VALID_COMMANDS` in `pin.mjs`, `command-metadata.json`, and usually `SKILL_CATEGORIES` (unless deliberately unmapped like `craft`).

## Platform and web-only constraints (command-relevant)

| Constraint | Applies to |
|---|---|
| Native variant replaces web reference | `audit`, `adapt` when platform is `ios` / `android` / `adaptive` |
| Skip live + detector in routing | Any native platform |
| Design hook skips native projects | Hook scan on native PRODUCT.md platforms (web file types only) |
| After `init` writes PRODUCT.md | Resume without re-running `context.mjs`; init itself loads native platform refs when it recorded a native platform |

## Quick invocation examples

```text
/impeccable
/impeccable init
/impeccable document
/impeccable critique pricing
/impeccable audit src/components/Hero.tsx
/impeccable polish checkout
/impeccable adapt dashboard mobile
/impeccable live
/impeccable doctor
/impeccable hooks status
```

Pin example (after skills are installed in the project):

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
# then use /audit as a redirect to /impeccable audit
```

## Related pages

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, no-argument menu, craft-floor gate, and when native variants replace web references.
  </Card>
  <Card title="Run design commands" href="/run-design-commands">
    How to invoke evaluate/refine commands with targets, expected artifacts, and verification signals.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Visitor modes and platform values that change which references load.
  </Card>
  <Card title="Pin shortcuts" href="/pin-shortcuts">
    Create and remove standalone harness shortcuts for any of the 23 commands.
  </Card>
  <Card title="Doctor" href="/doctor">
    Utility doctor pass: findings, severities, auto fix, and opt-out of boot staleness.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live command contract, roots, accept/discard, and web-only boundaries.
  </Card>
</CardGroup>

---

## 16. Detector rules

> Deterministic rule registry: ids, slop vs quality categories, advisory rules, scopes, engines (jsdom, browser, regex), and finding shape for CLI and extension.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/16-detector-rules.md
- Generated: 2026-08-05T07:38:17.381Z

### Source Files

- `cli/engine/registry/antipatterns.mjs`
- `cli/engine/rules/checks.mjs`
- `cli/engine/detect-antipatterns.mjs`
- `cli/engine/findings.mjs`
- `cli/engine/engines/static-html/detect-html.mjs`
- `cli/engine/engines/regex/detect-text.mjs`
- `tests/detect-antipatterns-fixtures.test.mjs`

---
title: Detector rules
description: Deterministic rule registry — ids, slop vs quality categories, advisory behavior, scopes, engines, and finding shape for CLI and extension.
---

The detector is a deterministic anti-pattern registry plus pure checks, wired into three scan engines (static HTML, regex source, and browser/URL) and packaged for the CLI, Chrome extension, and design hook. Rule metadata lives in one place; check logic and adapters stay separate.

## Source of truth

| Surface | Role |
|---|---|
| `cli/engine/registry/antipatterns.mjs` | Canonical `ANTIPATTERNS` array, scopes, advisory set, engine capability tags |
| `cli/engine/rules/checks.mjs` | Pure `checkXxx` functions plus DOM/static adapters |
| `cli/engine/findings.mjs` | Builds the shared finding object from a rule id |
| `cli/engine/detect-antipatterns.mjs` | Public facade re-exporting registry, engines, and helpers |
| `cli/engine/engines/static-html/detect-html.mjs` | Default path for `.html` / `.htm` |
| `cli/engine/engines/regex/detect-text.mjs` | Source/CSS/JSX path and page-level text analyzers |
| `cli/engine/engines/browser/detect-url.mjs` | Puppeteer URL scans via injected browser bundle |
| `cli/engine/engines/visual/screenshot-contrast.mjs` | Pixel contrast fallback for `low-contrast` |
| `cli/engine/detect-antipatterns-browser.js` | Generated browser bundle (`bun run build:browser`) |
| `extension/detector/` | Generated extension detector + `antipatterns.json` (`bun run build:extension`) |

Do not edit generated browser or extension detector files by hand. Change the registry and checks, then rebuild.

## Architecture

```mermaid
flowchart LR
  CLI["impeccable detect"] --> Main["cli/engine/cli/main.mjs"]
  Main -->|".html / .htm"| Static["static-html engine"]
  Main -->|"other scannable files"| Regex["regex engine"]
  Main -->|"http(s) / file URLs"| Browser["browser engine"]
  Static --> Checks["rules/checks.mjs"]
  Regex --> Checks
  Browser --> Bundle["detect-antipatterns-browser.js"]
  Bundle --> Checks
  Browser --> Visual["visual contrast"]
  Checks --> Finding["findings.mjs"]
  Finding --> Registry["registry/antipatterns.mjs"]
  Finding --> Out["text / JSON findings"]
```

Pure checks return lightweight hits `{ id, snippet }` (sometimes with per-finding `severity`). `finding(id, filePath, snippet, line)` expands each hit with registry metadata.

## Registry entry shape

Each rule in `ANTIPATTERNS` is a plain object:

| Field | Required | Meaning |
|---|---|---|
| `id` | yes | Stable kebab-case rule id (used in CLI output, ignores, and JSON) |
| `category` | yes | `slop` or `quality` |
| `name` | yes | Short human title |
| `description` | yes | What was found and what to do instead |
| `scopes` | no | Domain tags: `type`, `layout` (used by `--scope`) |
| `severity` | no | Default finding severity: `warning` (default), `error`, or `advisory` |
| `advisory` | no | When `true`, finding is partitioned as non-failing advisory |
| `skillSection` | no | Optional skill-doc section label |
| `skillGuideline` | no | Optional skill-doc guideline phrase |

Helpers exported with the registry:

- `getAntipattern(id)`
- `getRulesForCategory(category)`
- `isAdvisoryRule(id)` / `ADVISORY_RULE_IDS`
- `filterByScopes(findings, scopes)`
- `RULE_SCOPES` — currently `type` and `layout`
- `RULE_ENGINE_SUPPORT` — which engine phases each engine claims

## Categories

| Category | Intent | Count (current registry) |
|---|---|---|
| `slop` | Recognizable AI-generated UI or copy tells | 32 |
| `quality` | Design, legibility, a11y, or correctness issues | 27 |

**Total: 59 rules.** Counts are whatever `ANTIPATTERNS.length` is in source; do not hard-code them in feature PRs if the registry has moved.

### Slop rules

`side-tab`, `border-accent-on-rounded`, `overused-font`, `flat-type-hierarchy`, `gradient-text`, `ai-color-palette`, `cream-palette`, `nested-cards`, `monotonous-spacing`, `bounce-easing`, `pulsing-dot`, `blinking-cursor`, `shape-assembled-illustration`, `dark-glow`, `radial-halo`, `radial-spotlight-glow`, `marquee`, `icon-tile-stack`, `italic-serif-display`, `hero-eyebrow-chip`, `kicker-above-heading`, `numbered-section-labels`, `em-dash-overuse`, `marketing-buzzword`, `aphoristic-cadence`, `oversized-h1`, `extreme-negative-tracking`, `gpt-thin-border-wide-shadow`, `repeating-stripes-gradient`, `codex-grid-background`, `theater-slop-phrase`, `image-hover-transform`

### Quality rules

`broken-image`, `script-error`, `content-hidden-at-rest`, `edge-flush-cards`, `text-occlusion`, `first-viewport-column-overflow`, `gray-on-color`, `low-contrast`, `layout-transition`, `line-length`, `cramped-padding`, `body-text-viewport-edge`, `tight-leading`, `skipped-heading`, `heading-rhythm`, `justified-text`, `tiny-text`, `undersized-ui-text`, `all-caps-body`, `wide-tracking`, `text-overflow`, `repeated-container-text`, `clipped-overflow-container`, `design-system-font`, `design-system-color`, `design-system-radius`, `design-system-font-size`

## Severity vs advisory

Two separate registry fields. Do not collapse them.

### `severity` (label)

Default is `warning` when omitted.

| Value | Typical use |
|---|---|
| `warning` | Most rules |
| `error` | Hard failures: `script-error`, `content-hidden-at-rest` |
| `advisory` | Soft label on several generated-UI / design-system rules (still **can** count as failures unless also `advisory: true`) |

Rules with `severity: 'advisory'` today include: `blinking-cursor`, `shape-assembled-illustration`, `numbered-section-labels`, `design-system-color`, `design-system-radius`, `design-system-font-size`, `gpt-thin-border-wide-shadow`, `repeating-stripes-gradient`, `codex-grid-background`, `theater-slop-phrase`, `image-hover-transform`.

Checks may **promote** severity per finding (for example a pulsing status dot in a header/nav landmark), overriding the registry default on that finding only.

### `advisory: true` (non-failing partition)

Only rules with `advisory: true` are treated as automation-safe notes:

- Listed under a separate “Advisory (not counted as failures)” section in text output
- Excluded from the failure count that drives exit code
- Carry `"advisory": true` in JSON
- Skipped by the design hook unless the project sets `detector.advisoryRules: "include"`
- Hidden entirely with CLI `--no-advisory`

Current registry member: **`em-dash-overuse` only**.

```bash
# Advisory-only findings still exit 0
impeccable detect path/to/file.html

# Hide advisory notes completely
impeccable detect --no-advisory .
```

## Scopes

Optional `scopes` tags on rules enable CLI filtering:

```bash
impeccable detect --scope type src/
impeccable detect --scope layout,type .
```

| Scope | Domain |
|---|---|
| `type` | Typography / copy hierarchy rules |
| `layout` | Spacing, containers, overflow, column balance |

Rules without `scopes` never match `--scope` filters (they are dropped when any scope is requested). Empty scope list means no filtering.

Valid values come from `RULE_SCOPES`. Unknown values error the CLI.

## Engines

`RULE_ENGINE_SUPPORT` documents engine phases, not a per-rule matrix:

| Engine | Phases | When it runs |
|---|---|---|
| `regex` | `source`, `page-analyzer` | Non-HTML scannable files; also style blocks / CSS-in-JS / text analyzers |
| `static-html` | `element`, `page` | `.html` / `.htm` via custom cascade (not a live browser layout) |
| `browser` | `element`, `page`, `layout` | `http(s)://` and `file://` targets via Puppeteer |
| `visual` | `visual-contrast` | Browser URL path: contrast candidates + optional screenshot pixel check |

### Target routing (CLI)

| Target | Engine |
|---|---|
| `.html`, `.htm` | `detectHtml` (static-html) |
| Other scannable extensions | `detectText` (regex) |
| URL | `detectUrl` (browser + optional visual) |

Scannable extensions include: `.html`, `.htm`, `.css`, `.scss`, `.sass`, `.less`, `.jsx`, `.tsx`, `.js`, `.ts`, `.vue`, `.svelte`, `.astro`, `.blade.php`.

### Engine capabilities in practice

**Static HTML**

- Parses HTML, collects local CSS, builds a static style map
- Runs element rules (borders, colors, glow, motion, icon tiles, quality, and related)
- On full pages: typography, kickers, numbered labels, layout, cream palette, HTML pattern scans, and text-content analyzers
- Line numbers are generally absent; whole-file inline disables still apply
- Falls back to regex if parser imports fail

**Regex**

- Line and block matchers for classes, CSS, Tailwind, CSS-in-JS
- Extracts `<style>` blocks from Astro/Vue/Svelte and CSS-in-JS templates
- Page analyzers on full-page markup for selected rules (for example flat type hierarchy, em-dash, buzzwords, dark-glow)
- Preserves line numbers for ignore-line comments

**Browser**

- Injects the generated browser bundle and calls `window.impeccableDetect`
- Layout-dependent rules (occlusion, edge-flush cards, first-viewport column overflow, true computed layout)
- `script-error` from `pageerror` events
- `content-hidden-at-rest` after a reveal sweep
- Visual contrast fallback when computed color analysis is insufficient

**Deprecated CLI flags**

- `--fast` is accepted but ignored (full scan is the only path)
- `--gpt` / `--gemini` are ignored; generated-UI tells run by default

## Finding shape

Every consumer (CLI text/JSON, hook, tests) uses the same base object from `finding()`:

<ResponseField name="antipattern" type="string">
Rule id from the registry.
</ResponseField>

<ResponseField name="name" type="string">
Registry display name.
</ResponseField>

<ResponseField name="description" type="string">
Registry remediation-oriented description.
</ResponseField>

<ResponseField name="severity" type="string">
`warning` by default, or registry / per-finding override (`error`, `advisory`, …).
</ResponseField>

<ResponseField name="category" type="string | null">
`slop` or `quality`.
</ResponseField>

<ResponseField name="file" type="string">
File path or URL scanned.
</ResponseField>

<ResponseField name="line" type="number">
1-based line when known; `0` when unknown (common for static-html).
</ResponseField>

<ResponseField name="snippet" type="string">
Short evidence string; fixture tests often quote a heading inside straight double quotes.
</ResponseField>

<ResponseField name="advisory" type="boolean">
Present only when `true` (registry `advisory: true`).
</ResponseField>

Optional extras some paths attach:

- `ignoreValue` — value-scoped ignore token from browser serialization
- `importedBy` — import-graph note when a finding is attributed via imports

### Example JSON finding

```json
{
  "antipattern": "side-tab",
  "name": "Side-tab accent border",
  "description": "Thick colored border on one side of a card — the most recognizable tell of AI-generated UIs. Use a subtler accent or remove it entirely.",
  "severity": "warning",
  "category": "slop",
  "file": "src/components/Card.tsx",
  "line": 42,
  "snippet": "border-left: 4px solid #7c3aed"
}
```

Advisory example (`em-dash-overuse`):

```json
{
  "antipattern": "em-dash-overuse",
  "name": "Em-dash overuse",
  "description": "Em-dash saturation in body copy is an AI cadence tell. ...",
  "severity": "warning",
  "category": "slop",
  "file": "index.html",
  "line": 0,
  "snippet": "12 em-dashes in body text",
  "advisory": true
}
```

### Text output shape

```text
path/to/file.html
  line 12: [side-tab] "Feature Card" — thick left border
    → Thick colored border on one side of a card …

2 anti-patterns found.

── Advisory (not counted as failures) ──
path/to/file.html
  [em-dash-overuse] 9 em-dashes in body text
    → Em-dash saturation in body copy …

1 advisory note. Suppress with --no-advisory.
```

### Exit codes

| Code | Meaning |
|---|---|
| `0` | No non-advisory findings (advisory-only still exits 0) |
| `2` | One or more non-advisory findings |
| `1` | CLI usage / argument errors |

## Design-system rules

When DESIGN.md / `.impeccable/design.json` is loaded (default; disable with `--no-design-system` or config):

| Id | Severity | Notes |
|---|---|---|
| `design-system-font` | warning | Font not declared in DESIGN.md |
| `design-system-color` | severity advisory | Color outside palette/ramps |
| `design-system-radius` | severity advisory | Radius outside scale |
| `design-system-font-size` | severity advisory | Size off type ramp |

These are quality-category design-system drift checks, not the non-failing `advisory: true` partition (unless a future registry change sets that flag).

## Browser-only or layout-heavy rules

Some quality rules need real layout or runtime behavior and primarily appear on URL scans:

| Id | Why browser |
|---|---|
| `script-error` | Uncaught page errors during load |
| `content-hidden-at-rest` | Opacity/visibility after reveal sweep |
| `text-occlusion` | Overlapping painted text |
| `edge-flush-cards` | Scroller edge clipping |
| `first-viewport-column-overflow` | Multi-column fold imbalance |
| `low-contrast` (visual path) | Screenshot / visual fallback when computed contrast is incomplete |

Static HTML still covers many quality rules that only need computed style from the cascade (for example `tiny-text`, `cramped-padding`, `skipped-heading`).

## Extension packaging

`bun run build:extension` regenerates:

- `extension/detector/detect.js` — browser detector logic
- `extension/detector/antipatterns.json` — registry metadata for the DevTools panel UI

The extension panel loads `antipatterns.json` for names/descriptions; scan logic uses the same rule ids as the CLI.

## Check implementation pattern

Rules follow a fixed TDD shape (see contributing docs for the full order):

1. Fixture under `tests/fixtures/antipatterns/{rule-id}.html` with should-flag / should-pass columns
2. Fixture assertions in `tests/detect-antipatterns-fixtures.test.mjs` (snippet-substring via quoted headings)
3. Registry entry in `ANTIPATTERNS`
4. Pure `checkXxx(opts)` returning `[{ id, snippet }]`
5. Two adapters: DOM (`getComputedStyle` / geometry) and static/jsdom-style (explicit CSS dimensions; no layout)
6. Wire both adapters into **both** element loops (browser bundle path and static-html path)

Reference implementations in `checks.mjs`: `side-tab` (border), `low-contrast` (color), `icon-tile-stack` (sibling), `flat-type-hierarchy` (page-level), `kicker-above-heading` (heading-anchored).

After rule changes:

```bash
bun run build && bun run build:browser && bun run build:extension && bun run test
```

Fixture suite (Node, not Bun for the jsdom-era HTML fixtures):

```bash
node --test tests/detect-antipatterns-fixtures.test.mjs
```

## CLI usage related to rules

```bash
# Full tree scan
impeccable detect src/

# Domain filter
impeccable detect --scope type components/

# Machine-readable findings (single array; advisory flagged in place)
impeccable detect --json --quiet .

# Drop advisory partition
impeccable detect --no-advisory src/

# Bypass config, DESIGN.md, and inline disables
impeccable detect --no-config page.html

# Live page (requires puppeteer)
impeccable detect --viewport 390x844 https://example.com
```

Ignores (project config and inline comments) filter by rule id and optional value tokens. See the ignores and configuration pages for `ignoreRules`, `ignoreFiles`, `ignoreValues`, and `impeccable-disable*` comments.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| Rule fires in browser but not on static HTML | Needs layout/runtime (occlusion, script errors, reveal state) |
| Rule fires on CSS file but not HTML | HTML path uses different adapters; check static element/page wiring |
| Advisory note still appears but CI is green | Expected for `advisory: true` findings |
| `severity: "advisory"` finding fails CI | Severity label ≠ non-failing partition; only `advisory: true` is excluded |
| Hook silent on em-dash findings | Hook defaults `detector.advisoryRules: "exclude"` |
| `--scope type` drops many findings | Unscoped rules are filtered out when any scope is set |
| URL scan fails with puppeteer missing | Install puppeteer; URL mode is optional for file scans |
| Extension / browser missing new rule | Forgot `build:browser` / `build:extension` after registry change |

## Related pages

<CardGroup cols={2}>
  <Card title="CLI reference" href="/cli-reference">
    detect flags, JSON output, exit codes, and URL scanning.
  </Card>
  <Card title="Manage detector ignores" href="/manage-detector-ignores">
    ignoreRules, ignoreFiles, ignoreValues, and inline disable comments.
  </Card>
  <Card title="Detect in CI" href="/detect-in-ci">
    Non-interactive detect, exit codes 0 and 2, optional Puppeteer.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Per-edit scans, advisory exclusion, and intentional-finding workflow.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    detector.advisoryRules and related config keys.
  </Card>
  <Card title="Contributing" href="/contributing">
    Anti-pattern TDD order and build obligations for new rules.
  </Card>
</CardGroup>

---

## 17. Configuration reference

> `.impeccable/config.json` and `config.local.json` keys for detector, hook, live, update, and staleness settings, plus live config.json fields and hard path excludes.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/17-configuration-reference.md
- Generated: 2026-08-05T07:38:03.914Z

### Source Files

- `cli/lib/impeccable-config.mjs`
- `skill/scripts/lib/impeccable-paths.mjs`
- `skill/reference/live-setup.md`
- `skill/scripts/hook-lib.mjs`
- `skill/scripts/lib/staleness-notice.mjs`
- `tests/lib/impeccable-config.test.js`

---
title: "Configuration reference"
description: "`.impeccable/config.json` and `config.local.json` keys for detector, hook, live, update, and staleness settings, plus live config.json fields and hard path excludes."
---

Impeccable project settings live under `.impeccable/`. Shared team settings go in `config.json`; per-developer overrides go in `config.local.json`. Detector filters, design-hook runtime, update/staleness boot checks, and monorepo `projectRoots` all use that pair. Live mode uses a separate file at `.impeccable/live/config.json` for inject targets and CSP setup state.

## File layout

```text
.impeccable/
├── config.json          # shared (usually committed)
├── config.local.json    # per-developer (gitignored via .git/info/exclude)
├── design.json          # DESIGN.md sidecar (not this page)
├── hook.cache.json      # hook session cache (runtime)
├── hook.pending.json    # Cursor pending findings (runtime)
└── live/
    ├── config.json      # live inject / CSP setup
    ├── server.json      # running live server pid/port
    └── sessions/        # live session state
```

| Path | Role | Typical VCS |
|------|------|-------------|
| `.impeccable/config.json` | Shared project config | Commit |
| `.impeccable/config.local.json` | Local overrides (consent, private ignores, quiet, etc.) | Not committed; writers append `.impeccable/config.local.json` to `.git/info/exclude` |
| `.impeccable/live/config.json` | Live inject targets and CSP flag | Commit when the team shares inject paths |

Malformed JSON is ignored for that file; remaining valid layers and defaults still apply.

## Merge order

Both the CLI (`cli/lib/impeccable-config.mjs`) and the design hook (`skill/scripts/hook-lib.mjs`) read **shared then local**:

1. `.impeccable/config.json`
2. `.impeccable/config.local.json` (wins for scalar / last-write fields)

| Setting type | Merge behavior |
|--------------|----------------|
| Booleans / enums (`hook.enabled`, `hook.quiet`, `hook.consent`, `updateCheck`, `stalenessCheck`, `detector.designSystem.enabled`, `detector.advisoryRules`, `hook.perEditRules`, `hook.auditLog`, `hook.limits`) | Local overwrites shared when present |
| `detector.ignoreRules`, `detector.ignoreFiles` | Union (deduped strings); both files contribute |
| `detector.ignoreValues` | Map-merge by `(rule, value, files)`; local entry with same key replaces shared |
| `detector.extensions` | Merge by extension string; local entry wins per `ext` |
| Legacy detector keys under `hook.*` | Still read for back-compat; canonical `detector.*` wins when both set |

Writes that manage detector ignores (`npx impeccable ignores …`, `hooks ignore-*`) put filters under `detector` and strip legacy filter keys from `hook` while preserving `hook.consent`, `hook.quiet`, and other runtime fields.

## Unified config schema

Canonical shape (shared and/or local):

```json
{
  "updateCheck": true,
  "stalenessCheck": true,
  "projectRoots": ["apps/*", "packages/ui"],
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": [],
    "ignoreValues": [],
    "designSystem": { "enabled": true },
    "advisoryRules": "exclude",
    "extensions": []
  },
  "hook": {
    "enabled": true,
    "quiet": false,
    "consent": "accepted",
    "auditLog": null,
    "perEditRules": "immediate",
    "limits": {
      "maxFindings": 5,
      "maxChars": 8000,
      "maxFileBytes": 131072
    }
  }
}
```

### Top-level keys

<ParamField body="updateCheck" type="boolean" default="true (when unset)">
When `false`, `context.mjs` skips the skill update directive at boot. Local config overrides shared. Also disabled by `IMPECCABLE_NO_UPDATE_CHECK`.
</ParamField>

<ParamField body="stalenessCheck" type="boolean" default="true (when unset)">
When `false`, boot skips `CONTEXT_STALE` collection for PRODUCT/DESIGN/config drift. Local overrides shared. Also disabled by `IMPECCABLE_NO_STALENESS_CHECK=1`.
</ParamField>

<ParamField body="projectRoots" type="string[]">
Optional monorepo project globs relative to the repo root. Takes precedence over package-manager workspace lists for paths they match (including negations). Used by context resolution and doctor diagnostics.
</ParamField>

### `detector` keys

Shared by `npx impeccable detect` (unless `--no-config`) and the design hook. `hook.enabled` does **not** turn off manual CLI scans.

<ParamField body="detector.ignoreRules" type="string[]" default="[]">
Rule ids suppressed project-wide (normalized lowercase). Example: `"side-tab"`. Prefer value-scoped ignores for fonts/motion when a single value is intentional.
</ParamField>

<ParamField body="detector.ignoreFiles" type="string[]" default="[]">
Globs that suppress **all** rules for matching paths. Matches absolute path, basename, and project-relative path. Supports `**`, `*`, `?`, and `{a,b}`.
</ParamField>

<ParamField body="detector.ignoreValues" type="object[]" default="[]">
Per-rule value suppressions. Each entry:

| Field | Type | Notes |
|-------|------|--------|
| `rule` | string | Required; normalized lowercase |
| `value` | string | Required; normalized (trim, collapse space, lowercase). Use `"*"` only with `files` for file-scoped full-rule silence |
| `files` | string[] | Optional globs; omit for project-wide value match |
| `file` | string | Accepted alias for a single path; normalized into `files` |
| `reason` | string | Optional human note |
| `createdAt` | string | Optional timestamp preserved on rewrite |

Value matching: string equality after normalize. For `design-system-color`, hex / `rgb()` / `hsl()` forms that parse to the same RGBA also match. Value-bearing rules include `overused-font`, `bounce-easing`, `design-system-font`, `design-system-color`, `design-system-radius`, `design-system-font-size`. File-scoped `value: "*"` also suppresses rules with no extractable value (for example `side-tab`).
</ParamField>

<ParamField body="detector.designSystem.enabled" type="boolean" default="true">
When `false`, design-system rules are not loaded for CLI or hook scans even if DESIGN.md / sidecar tokens exist.
</ParamField>

<ParamField body="detector.advisoryRules" type="\"include\" \| \"exclude\"" default="exclude">
Advisory rules (for example `em-dash-overuse`) never fail the CLI. The design hook **skips** them unless set to `"include"`.
</ParamField>

<ParamField body="detector.extensions" type="array" default="[]">
Extra markup/template suffixes beyond the built-in list. Config **adds** only; built-ins always apply.

Each entry is `{ "ext": ".blade.php", "engine": "html" }` or a bare string (engine defaults to `html`). `engine` is `html` or `text`. Matching uses **filename suffix** (longest wins), so `.blade.php` and `.html.erb` work. Live wrap/accept also merges these into its template search set.
</ParamField>

### `hook` keys

Runtime for the design edit hook only.

<ParamField body="hook.enabled" type="boolean" default="true">
When `false`, automatic hook scans do not run. Manual `npx impeccable detect` still runs and still honors `detector.*`. Env override: `IMPECCABLE_HOOK_DISABLED` (truthy).
</ParamField>

<ParamField body="hook.quiet" type="boolean" default="false">
When `true`, suppresses clean/pending acks; findings still surface. Env override: `IMPECCABLE_HOOK_QUIET`.
</ParamField>

<ParamField body="hook.consent" type="\"accepted\" \| \"declined\"">
Install / enable decision recorded by the CLI into **local** config. Local always wins over shared. Not a runtime scan filter.
</ParamField>

<ParamField body="hook.auditLog" type="string \| null" default="null">
Optional path for NDJSON audit entries. Env `IMPECCABLE_HOOK_LOG` overrides when set.
</ParamField>

<ParamField body="hook.perEditRules" type="\"immediate\" \| \"all\"" default="immediate">
`immediate` surfaces only the high-urgency rule tier on each edit; the Stop deep pass (where wired) runs the full set. `all` restores full rules on every edit.
</ParamField>

<ParamField body="hook.limits.maxFindings" type="number" default="5">
Cap on findings rendered per emission (must be finite and &gt; 0).
</ParamField>

<ParamField body="hook.limits.maxChars" type="number" default="8000">
Cap on rendered reminder size.
</ParamField>

<ParamField body="hook.limits.maxFileBytes" type="number" default="131072">
Skip scanning a single file larger than this (bundle / generated artifact guard).
</ParamField>

<Note>
Native platforms (`ios` / `android` / `adaptive` in PRODUCT.md) skip the design hook scan entirely. Detector rules are web-shaped; native projects still use native skill references.
</Note>

## Hard path excludes (hook)

These cannot be disabled by config. The hook never scans matching paths:

| Guard | What it skips |
|-------|----------------|
| Sensitive path regex | `.env*`, `.git/…`, key/PEM material, `*secret*` / `*credential*` config-like names |
| Generated path regex | `node_modules`, `dist` / `build` / `out` / `.next` / `.cache` / `coverage`, `generated/` segment, `*.min.*`, `*.d.ts`, lockfiles, `*.generated.*` |

`detector.ignoreFiles` is additive on top of these floors.

## Inline disable comments

Separate from JSON config. In source, comments like:

```text
impeccable-disable <rule>[, <rule>...]
impeccable-disable-line <rule>...
impeccable-disable-next-line <rule>...
```

are honored by default on detect. Bypass with CLI `--no-inline-ignores` or `--no-config`. Prefer config ignores for team-visible waivers; use inline only when the waiver must travel with an exported file.

## Live config (`.impeccable/live/config.json`)

Path resolution (`skill/scripts/lib/impeccable-paths.mjs`):

1. `IMPECCABLE_LIVE_CONFIG` if set (absolute or cwd-relative)
2. Else `.impeccable/live/config.json` if present
3. Else legacy `skill/scripts/config.json` if present when scripts dir is known
4. Else primary path (may not exist yet; setup creates it)

### Fields

```json
{
  "files": ["index.html"],
  "exclude": ["email/**/*.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

<ParamField body="files" type="string[]" required>
Non-empty list of project-root-relative paths or globs for the HTML/shell files the browser loads. Not necessarily source-of-truth components; inject targets are what the browser actually fetches.
</ParamField>

<ParamField body="exclude" type="string[]">
Optional globs subtracted from expanded `files` (fixtures, email templates).
</ParamField>

<ParamField body="insertBefore" type="string">
Required unless `insertAfter` is set. Anchor string for script-tag insertion (usually `</body>`).
</ParamField>

<ParamField body="insertAfter" type="string">
Alternative anchor: insert after a matching line (for example TanStack Start `<Scripts`).
</ParamField>

<ParamField body="commentSyntax" type="\"html\" \| \"jsx\"" required>
Comment markers for inject bookkeeping (`html` vs JSX-style).
</ParamField>

<ParamField body="cspChecked" type="boolean">
Records that the first-time CSP consent step ran. Absent on first setup; set `true` after the user is asked (whether they accept or decline the patch). Delete the key to re-run CSP setup.
</ParamField>

Validation errors from `live-inject.mjs` include missing/empty `files`, missing insert anchor, invalid `commentSyntax`, or non-boolean `cspChecked`.

### Live hard excludes

Always applied; **not** overridable by `exclude` or any other flag:

| Pattern | Reason |
|---------|--------|
| `**/node_modules/**` | Would instrument third-party packages |
| `**/.git/**` | Not a page surface |

User `exclude` is appended after these.

### Framework-oriented examples

| Stack | Typical `files` | Anchor | `commentSyntax` |
|-------|-----------------|--------|-----------------|
| Vite / SPA shell | `["index.html"]` | `</body>` | `html` |
| Next App Router | `["app/layout.tsx"]` | `</body>` | `jsx` |
| Next Pages | `["pages/_document.tsx"]` | `</body>` | `jsx` |
| Nuxt | `["app.vue"]` | `</body>` | `html` |
| SvelteKit | `["src/app.html"]` | `</body>` | `html` |
| TanStack Start | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
| Multipage | `["public/**/*.html"]` | `</body>` | `html` |

Some frameworks route inject through adapters (SvelteKit root component, Nuxt client plugin, TanStack Start root component). `files` remains the detection/CSP hint even when the literal insertion site differs.

## Example configs

### Shared team detector filters

```json
{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": ["src/fixtures/**", "**/*.generated.tsx"],
    "ignoreValues": [
      {
        "rule": "overused-font",
        "value": "Avenir Next",
        "reason": "Brand primary typeface"
      },
      {
        "rule": "side-tab",
        "value": "*",
        "files": ["**/TopicCard.jsx"],
        "reason": "Intentional left accent"
      }
    ],
    "designSystem": { "enabled": true },
    "advisoryRules": "exclude"
  },
  "hook": {
    "enabled": true,
    "perEditRules": "immediate"
  }
}
```

### Local developer overrides

```json
{
  "updateCheck": false,
  "hook": {
    "consent": "accepted",
    "quiet": true
  },
  "detector": {
    "ignoreValues": [
      {
        "rule": "bounce-easing",
        "value": "bounce-ball",
        "reason": "Local playground only"
      }
    ]
  }
}
```

### Blade / server templates

```json
{
  "detector": {
    "extensions": [
      { "ext": ".blade.php", "engine": "html" },
      { "ext": ".html.twig", "engine": "html" }
    ]
  }
}
```

## Managing config without hand-editing

| Goal | Preferred tool |
|------|----------------|
| Detector ignores CRUD | `npx impeccable ignores …` or `/impeccable hooks ignore-*` |
| Hook on/off / status | `/impeccable hooks on\|off\|status` → `hook-admin.mjs` |
| Live inject setup | Live boot + `live-setup` flow writing `.impeccable/live/config.json` |
| Schema / drift repair | `/impeccable doctor` (and `doctor --fix` for auto severities) |

Hand-edit is fine for rare fields with no admin action (`detector.extensions`, top-level `projectRoots`, `updateCheck`, `stalenessCheck`). Keep JSON valid; prefer admin scripts for ignore lists so normalization and exclude markers stay consistent.

## Environment overrides (summary)

Full list lives on the environment variables page. Config-adjacent vars:

| Variable | Effect |
|----------|--------|
| `IMPECCABLE_NO_UPDATE_CHECK` | Disable update check regardless of config |
| `IMPECCABLE_NO_STALENESS_CHECK` | Disable staleness boot check |
| `IMPECCABLE_STALENESS_CACHE` | Override `~/.impeccable/staleness-check.json` path |
| `IMPECCABLE_UPDATE_HOST` / `IMPECCABLE_UPDATE_CACHE` | Update poll host and cache file |
| `IMPECCABLE_LIVE_CONFIG` | Override live config path |
| `IMPECCABLE_HOOK_DISABLED` / `IMPECCABLE_HOOK_QUIET` / `IMPECCABLE_HOOK_LOG` | Override hook enabled / quiet / audit log |
| `IMPECCABLE_CONTEXT_DIR` | Alternate context root for PRODUCT/DESIGN resolution |

## Troubleshooting

| Symptom | Check |
|---------|--------|
| Local ignores not applied | Confirm `.impeccable/config.local.json` is valid JSON; shared+local both merge for lists |
| Hook still quiet after config change | Env `IMPECCABLE_HOOK_QUIET` or `IMPECCABLE_HOOK_DISABLED` overrides config |
| CLI finds issues the hook does not | `hook.enabled: false` only affects the hook; compare `perEditRules` / advisory / designSystem; Stop deep pass may own deferred rules |
| Live inject misses pages | Expand `files` or globs; `configDrift.orphans` on boot lists uncovered HTML under common roots |
| Live blocked by CSP | Delete `cspChecked` and re-run live setup; ensure `localhost:8400` is allowed in dev CSP |
| Consent / local file committed | Writers use `.git/info/exclude`, not tracked `.gitignore`; ensure exclude marker block is present |

## Related pages

<CardGroup>
  <Card title="Manage detector ignores" href="/manage-detector-ignores">
    Add, list, and remove ignoreRules, ignoreFiles, and ignoreValues in shared or local config.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Provider edit hooks, quiet/disabled controls, and native-platform skip behavior.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live mode lifecycle, roots, and poll contract.
  </Card>
  <Card title="Live framework recipes" href="/live-framework-recipes">
    Copy-paste live config shapes for Vite, Next, Nuxt, SvelteKit, and more.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    IMPECCABLE_* overrides for context, update, live, hook, and telemetry.
  </Card>
  <Card title="Doctor" href="/doctor">
    Schema and config drift findings, auto fixes, and staleness opt-out.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    detect, ignores, and related flags including --no-config.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md, DESIGN.md, sidecar, and the rest of `.impeccable/`.
  </Card>
</CardGroup>

---

## 18. Environment variables

> Documented IMPECCABLE_* and related env vars for context dir, update host/cache, live config, hook quiet/disable/depth/log, telemetry opt-out, and OpenCode config dirs.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/18-environment-variables.md
- Generated: 2026-08-05T07:38:16.368Z

### Source Files

- `skill/scripts/context.mjs`
- `skill/scripts/hook-lib.mjs`
- `skill/scripts/lib/impeccable-paths.mjs`
- `skill/scripts/lib/staleness-notice.mjs`
- `cli/bin/commands/skills.mjs`
- `skill/scripts/concept-seed.mjs`

---
title: "Environment variables"
description: "Documented IMPECCABLE_* and related env vars for context dir, update host/cache, live config, hook quiet/disable/depth/log, telemetry opt-out, and OpenCode config dirs."
---

Runtime and install code reads environment variables for path overrides, network hosts, hook behavior, telemetry, and provider config directories. Most day-to-day settings belong in `.impeccable/config.json` or `config.local.json`; env vars are session overrides, power-user escapes, and CI/test knobs. Truthy string values for hook switches match `/^(1|true|yes|on)$/i`.

## Precedence overview

| Concern | Env var | Config key | Precedence |
|---|---|---|---|
| Disable design hook | `IMPECCABLE_HOOK_DISABLED` | `hook.enabled: false` | Env skips the hook for this process; config is project-persistent |
| Quiet clean/pending acks | `IMPECCABLE_HOOK_QUIET` | `hook.quiet: true` | Env or config either enables quiet |
| Hook audit NDJSON | `IMPECCABLE_HOOK_LOG` | `hook.auditLog` | Env wins when set |
| Skill update check | `IMPECCABLE_NO_UPDATE_CHECK` | `updateCheck: false` | Either disables boot network check |
| Staleness boot notice | `IMPECCABLE_NO_STALENESS_CHECK` | `stalenessCheck: false` | Either disables; local config overrides shared when both set |
| Live config path | `IMPECCABLE_LIVE_CONFIG` | (file location only) | Env overrides `.impeccable/live/config.json` and legacy script path |
| PRODUCT/DESIGN location | `IMPECCABLE_CONTEXT_DIR` | (filesystem layout) | Used only when default discovery finds no artifacts |

<Note>
Prefer project config for durable choices (`hooks off`, quiet mode, audit path). Use env vars for one-shell overrides, sandboxes, and CI.
</Note>

## Context directory

`context.mjs` resolves `PRODUCT.md` / `DESIGN.md` in a fixed order: active project root, then `.agents/context/` and `docs/`, then monorepo/repo-root inheritance. Only if those yields are empty does it consult the env override.

<ParamField body="IMPECCABLE_CONTEXT_DIR" type="string">
Absolute path or path relative to the process cwd. Trimmed; blank/whitespace is ignored. When set and defaults are empty, `PRODUCT.md` / `DESIGN.md` (case variants) are looked up in that directory. Relative values resolve with `path.resolve(cwd, trimmed)`.
</ParamField>

```bash
# Artifacts live outside the usual project root
export IMPECCABLE_CONTEXT_DIR=/path/to/brand-docs
node skill/scripts/context.mjs
```

## Update check (boot)

On session boot, `context.mjs` may append an `UPDATE_AVAILABLE` directive after a throttled poll (at most once per day; same version re-notified at most weekly). Failures are silent and never block context output.

<ParamField body="IMPECCABLE_UPDATE_HOST" type="string" default="https://impeccable.style">
Base URL for the latest-skill version poll. Trailing slashes are stripped.
</ParamField>

<ParamField body="IMPECCABLE_UPDATE_CACHE" type="string" default="~/.impeccable/update-check.json">
JSON cache path for `lastCheck`, `latestVersion`, and anti-nag stamps. Lives under the user home by default so clones do not share dismissals.
</ParamField>

<ParamField body="IMPECCABLE_NO_UPDATE_CHECK" type="string">
Any non-empty value skips the update check entirely for that process. Equivalent project config: `"updateCheck": false` in `.impeccable/config.json` or `config.local.json` (local wins when both define the key).
</ParamField>

```bash
# Offline / test harnesses that assert on other boot directives
export IMPECCABLE_NO_UPDATE_CHECK=1
export IMPECCABLE_NO_STALENESS_CHECK=1
```

## Staleness boot notice

Tier-1 schema findings can emit one `CONTEXT_STALE` directive at boot. Mention/route findings are throttled to about once per week per project; `auto` findings are not user-facing.

<ParamField body="IMPECCABLE_NO_STALENESS_CHECK" type="string">
Any non-empty value disables the boot staleness pass. Project config alternative: `"stalenessCheck": false`. `doctor` still runs on demand when the boot check is off.
</ParamField>

<ParamField body="IMPECCABLE_STALENESS_CACHE" type="string" default="~/.impeccable/staleness-check.json">
Throttle state path (alongside the update cache under `~/.impeccable/`). Useful for sandboxed tests that must not touch the real home cache.
</ParamField>

## Live config path

Live mode resolves its config through `resolveLiveConfigPath` in `skill/scripts/lib/impeccable-paths.mjs`.

| Priority | Location |
|---|---|
| 1 | `IMPECCABLE_LIVE_CONFIG` (absolute, or cwd-relative) |
| 2 | `.impeccable/live/config.json` if present |
| 3 | Legacy `<scriptsDir>/config.json` if `scriptsDir` is provided and the file exists |
| 4 | Default path `.impeccable/live/config.json` (even if missing yet) |

<ParamField body="IMPECCABLE_LIVE_CONFIG" type="string">
Override path for live `config.json`. Trimmed; blank is ignored.
</ParamField>

```bash
export IMPECCABLE_LIVE_CONFIG=./fixtures/live-config.json
```

Additional live-only knobs (defaults shown):

| Variable | Default | Role |
|---|---|---|
| `IMPECCABLE_LIVE_DEBUG_EVENTS` | off | `1`/`true`/`yes` logs manual-edit debug events in the live server |
| `IMPECCABLE_LIVE_COPY_AGENT_TIMEOUT_MS` | `120000` | Copy-edit agent timeout for manual-edit commit |
| `IMPECCABLE_LIVE_APPLY_EVENT_HARD_TIMEOUT_MS` | `150000` | Hard timeout for apply-event work |
| `IMPECCABLE_LIVE_APPLY_EVENT_SOFT_DEADLINE_MS` | `120000` | Soft deadline for apply-event work |
| `IMPECCABLE_LIVE_SVELTE_COMPONENT` | on | Set to `0`/`false`/`no` to disable Svelte component injection path |

## Design hook

Hook runtime settings prefer `.impeccable/config.json` → `hook.*`, with these env overrides still honored. `hook-admin.mjs status` prints the current `IMPECCABLE_HOOK_DISABLED` env state.

### Disable, quiet, log

<ParamField body="IMPECCABLE_HOOK_DISABLED" type="string">
Truthy (`1`, `true`, `yes`, `on`) skips PostToolUse, Stop, and Cursor pre-edit hooks for this process (`skipped: env-disabled`). Prefer `/impeccable hooks off` for a durable project disable (`hook.enabled: false`).
</ParamField>

<ParamField body="IMPECCABLE_HOOK_QUIET" type="string">
Truthy silences clean and pending acks on the per-edit path. Findings still emit. Config alternative: `hook.quiet: true`.
</ParamField>

<ParamField body="IMPECCABLE_HOOK_LOG" type="string">
Path for one NDJSON line per hook invocation. Env wins over `hook.auditLog`. Supports `~/…`, absolute paths, and project-relative paths (resolved against the edited project root when known).
</ParamField>

```bash
# One-shot quiet + audit for this shell
export IMPECCABLE_HOOK_QUIET=1
export IMPECCABLE_HOOK_LOG=~/.impeccable/hook.ndjson
```

### Depth, debug, harness

<ParamField body="IMPECCABLE_HOOK_DEPTH" type="string">
Re-entrancy guard. `hook.mjs` snapshots the parent env, then sets `IMPECCABLE_HOOK_DEPTH` (default `1`) for descendants. If the inherited env already has depth set (`1`/`true`/`yes`/`on` or a positive integer), the hook returns immediately as reentrant. `CLAUDE_HOOK_DEPTH` is checked the same way.
</ParamField>

<ParamField body="IMPECCABLE_HOOK_DEBUG" type="string">
When set, unexpected hook errors write a short message to stderr (exit code remains 0 so the agent turn is not broken).
</ParamField>

<ParamField body="IMPECCABLE_HOOK_HARNESS" type="string">
Force harness identity: `cursor`, `github`, or `claude`/`codex`. Otherwise the event shape is inferred.
</ParamField>

## Telemetry and concept seed

Choice telemetry is a fire-and-forget POST to the roll API’s `/chosen` endpoint when a dealt world is selected. It does not run for non-API seeds and never fails the caller.

<ParamField body="IMPECCABLE_NO_TELEMETRY" type="string">
Any truthy presence disables the choice ping.
</ParamField>

<ParamField body="DO_NOT_TRACK" type="string">
Standard opt-out; same effect as `IMPECCABLE_NO_TELEMETRY` for the choice ping.
</ParamField>

Related concept-seed networking and catalog vars:

| Variable | Default | Role |
|---|---|---|
| `IMPECCABLE_CATALOG_DIR` | skill scripts dir | Local catalog root (`concept-ingredients.json`, reviews, compositions) for private repos, evals, tests |
| `IMPECCABLE_API_URL` | `https://impeccable.style/api` | Roll/chosen API base |
| `IMPECCABLE_API_TIMEOUT` | `4000` | Shared deadline (ms) for all API calls in one seed run |
| `IMPECCABLE_CARD_BASE` | `https://impeccable.style/worlds/cards` | World card image base URL |
| `IMPECCABLE_CONCEPT_SEED` | random 4-byte hex | Deterministic deal key when not passed explicitly |
| `IMPECCABLE_COMPOSITIONS` | off | Set to `1` to include compositions in rendered deals (catalog development) |

```bash
export IMPECCABLE_NO_TELEMETRY=1
# or
export DO_NOT_TRACK=1
```

## Skills install: OpenCode and bundles

Global OpenCode skills are **not** installed under `~/.opencode`. The CLI resolves OpenCode’s config directory as:

1. `$OPENCODE_CONFIG_DIR` if set  
2. else `$XDG_CONFIG_HOME/opencode`  
3. else `~/.config/opencode`  

Global skills land in `<that-dir>/skills`. Project scope remains `.opencode/skills`.

<ParamField body="OPENCODE_CONFIG_DIR" type="string">
OpenCode config root override. Skills install uses `join(OPENCODE_CONFIG_DIR, 'skills')` for the global target.
</ParamField>

<ParamField body="XDG_CONFIG_HOME" type="string">
When `OPENCODE_CONFIG_DIR` is unset, OpenCode global config is `$XDG_CONFIG_HOME/opencode`.
</ParamField>

<ParamField body="IMPECCABLE_BUNDLE_PATH" type="string">
Local universal skill bundle (directory or zip) for `npx impeccable` install/update instead of downloading from the network. Used by smoke tests and offline install.
</ParamField>

Other install/CLI environment notes:

| Variable | Role |
|---|---|
| `NO_COLOR` | When defined, skills CLI color output is disabled (also when `TERM=dumb` or stdout is not a TTY) |
| `CI` | URL detect launches Chromium with `--no-sandbox`; `serve-question` treats the session as headless unless forced |

## Question UI and image generation

| Variable | Role |
|---|---|
| `IMPECCABLE_QUESTION_DISABLED` | `serve-question` exits 2 and tells the agent to use the structured question tool |
| `IMPECCABLE_QUESTION_FORCE` | Serve browser questions even in CI/SSH/headless Linux (no `DISPLAY`/`WAYLAND_DISPLAY`) |
| `OPENAI_API_KEY` | Enables API fallback for `generate-image.mjs`; boot may emit `IMAGE_GEN_AVAILABLE` when set |
| `IMPECCABLE_IMAGE_GEN_FAKE` | Offline fake PNG/SVG for tests (no API call) |
| `IMPECCABLE_PALETTE_SEED` | Same as `palette.mjs --from`; deterministic palette pick for evals |
| `IMPECCABLE_CRITIQUE_META` | Optional meta payload for critique storage |

## Test and CI suite knobs

These are for repository tests and maintainers, not product configuration:

| Variable | Suite / tool | Role |
|---|---|---|
| `IMPECCABLE_E2E_ONLY` | live-e2e | Fixture name filter |
| `IMPECCABLE_E2E_DEBUG` | live-e2e | Dump DOM / dev-server tail on failure |
| `IMPECCABLE_E2E_AGENT` | live-e2e | `fake` (default) or `llm` |
| `IMPECCABLE_E2E_LLM_PROVIDER` / `_MODEL` / `_EFFORT` | live-e2e LLM agent | Provider and model overrides |
| `IMPECCABLE_E2E_CONSOLE` | live-e2e | Capture browser console |
| `IMPECCABLE_E2E_ARTIFACT_DIR` | live-e2e | Artifact root |
| `IMPECCABLE_SKILL_BEHAVIOR_MODELS` | skill-behavior | Restrict provider ids |
| `IMPECCABLE_SKILL_BEHAVIOR_VERBOSE` | skill-behavior | Dump per-scenario traces |
| `IMPECCABLE_CLI_REMOTE_E2E` | skills remote E2E | Opt-in remote install tests |
| Provider API keys | skill-behavior / live LLM | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, etc.; missing keys skip cleanly |

## Common setups

```bash
# CI / offline session: no network nags, no telemetry
export IMPECCABLE_NO_UPDATE_CHECK=1
export IMPECCABLE_NO_STALENESS_CHECK=1
export IMPECCABLE_NO_TELEMETRY=1

# Debug the design hook for one shell
export IMPECCABLE_HOOK_LOG=/tmp/impeccable-hook.ndjson
export IMPECCABLE_HOOK_DEBUG=1
# optional: export IMPECCABLE_HOOK_QUIET=1

# Point context at nonstandard docs
export IMPECCABLE_CONTEXT_DIR=./brand

# Offline skill install from a local universal bundle
export IMPECCABLE_BUNDLE_PATH=./dist/universal.zip
npx impeccable skills install
```

## Troubleshooting

| Symptom | Check |
|---|---|
| Hook still fires after “disable” | Confirm `IMPECCABLE_HOOK_DISABLED` is truthy (`1`/`true`/`yes`/`on`), or use project `hooks off`. Non-matching strings do not disable. |
| Update banner every session | Cache unwritable under `~/.impeccable/`; set `IMPECCABLE_UPDATE_CACHE` to a writable path or disable with `IMPECCABLE_NO_UPDATE_CHECK` / `updateCheck: false`. |
| `IMPECCABLE_CONTEXT_DIR` ignored | Env is only used when no PRODUCT/DESIGN was found via project, fallback dirs, or monorepo inheritance. |
| OpenCode install missing skills | Ensure install targeted `$OPENCODE_CONFIG_DIR` / XDG / `~/.config/opencode`, not `~/.opencode`. |
| Choice pings still sent | Set `IMPECCABLE_NO_TELEMETRY` or `DO_NOT_TRACK`; pings only fire for API-dealt rolls. |
| serve-question exits 2 in CI | Expected without a browser; set `IMPECCABLE_QUESTION_FORCE=1` only if you intentionally need the HTTP UI. |

## Related pages

<CardGroup>
  <Card title="Configuration reference" href="/configuration-reference">
    `.impeccable/config.json` keys for hook, detector, live, update, and staleness.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Provider hooks, quiet/disabled behavior, and intentional-finding workflow.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md / DESIGN.md discovery order and `.impeccable/` layout.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live mode roots, config, and web-only constraints.
  </Card>
  <Card title="Doctor" href="/doctor">
    On-demand staleness and schema repair when boot checks are opted out.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Install, update, detect, and skills commands that honor bundle and provider paths.
  </Card>
</CardGroup>

---

## 19. Plugin agents

> Bundled finish-reviewer, documenter, asset-producer, and manual-edit-applier agents, plugin manifest contract, and hooks packaged for Claude Code and Grok plugin installs.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/19-plugin-agents.md
- Generated: 2026-08-05T07:37:54.269Z

### Source Files

- `skill/agents/impeccable-finish-reviewer.md`
- `skill/agents/impeccable-documenter.md`
- `skill/agents/impeccable-asset-producer.md`
- `skill/agents/impeccable-manual-edit-applier.md`
- `plugin/hooks/hooks.json`
- `scripts/lib/validate-plugin-manifest.js`
- `.claude-plugin/plugin.json`

---
title: "Plugin agents"
description: "Bundled finish-reviewer, documenter, asset-producer, and manual-edit-applier agents, plugin manifest contract, and hooks packaged for Claude Code and Grok plugin installs."
---

The committed `plugin/` subtree is the slim package Claude Code marketplace and Grok Build plugin installs load: one skill (`skills/impeccable/`), four subagents under `plugin/agents/*.md`, and design-hook wiring in `plugin/hooks/hooks.json`. Canonical agent prompts live in `skill/agents/`; `bun run build:release` emits provider-native copies and copies the Claude Code agents into `plugin/agents/`. The Claude plugin manifest must **omit** an `agents` key so the loader auto-discovers `plugin/agents/*.md` (PR #494).

## Package layout

```text
plugin/
├── .claude-plugin/plugin.json   # Claude marketplace / plugin loader
├── .grok-plugin/plugin.json     # Native Grok plugin metadata
├── agents/                      # Four markdown agents (auto-discovered)
│   ├── impeccable-finish-reviewer.md
│   ├── impeccable-documenter.md
│   ├── impeccable-asset-producer.md
│   └── impeccable-manual-edit-applier.md
├── hooks/
│   └── hooks.json               # PostToolUse + Stop → hook.mjs
└── skills/
    └── impeccable/              # SKILL.md, reference/, scripts/
```

Marketplace entry (repo root) points at this subtree:

| File | Role |
|------|------|
| `.claude-plugin/marketplace.json` | `plugins[0].source: "./plugin"` |
| `.claude-plugin/plugin.json` | Root version/description source (skills path `./.claude/skills/` for non-plugin layouts) |
| `plugin/.claude-plugin/plugin.json` | Installed plugin manifest: `skills: "./skills/"` only; **no** `agents` key |
| `plugin/.grok-plugin/plugin.json` | Grok dual manifest (name, version, description, author, keywords); no component paths |

Grok install uses the slim package explicitly:

```bash
grok plugin install pbakaus/impeccable#plugin --trust
```

Claude Code:

```text
/plugin marketplace add pbakaus/impeccable
```

then install **impeccable** from the plugin UI.

Project-scoped skill installs (`npx impeccable install`) still write harness dirs such as `.claude/skills/` or `.grok/skills/` plus project hooks; those are separate from marketplace plugin unpack.

## The four agents

Source of truth: `skill/agents/<name>.md`. Shared frontmatter fields:

| Field | Purpose |
|-------|---------|
| `name` | Harness agent id (hyphenated) |
| `codex-name` | Codex TOML id (underscores) |
| `description` | Loader / auto-delegation summary |
| `tools` | Allowed tools (Claude/Grok emitted frontmatter) |
| `model` | Usually `inherit` |
| `effort` | `high` or `medium` |
| `max-turns` | Hard turn ceiling (emitted as `maxTurns` for Claude-format agents) |
| `nickname-candidates` | Codex nicknames only |

| Agent | Id / Codex id | Tools | Effort / max-turns | When the skill spawns it |
|-------|---------------|-------|--------------------|--------------------------|
| Finish reviewer | `impeccable-finish-reviewer` / `impeccable_finish_reviewer` | Read, Bash, Glob, Grep (no Write/Edit) | high / 30 | End of craft/new-work finish: reviews screenshots + artifact against direction contract, approved comp, QUALITY BAR, craft floor |
| Documenter | `impeccable-documenter` / `impeccable_documenter` | Read, Write, Bash, Glob, Grep | medium / 30 | After finish review closes: writes `DESIGN.md` + sidecar from the **built** artifact |
| Asset producer | `impeccable-asset-producer` / `impeccable_asset_producer` | Read, Write, Edit, Bash, Glob, Grep | medium / 24 | Media inventory / visualize / craft: clean production rasters from approved mocks; also decision-card sketch mode |
| Manual edit applier | `impeccable-manual-edit-applier` / `impeccable_manual_edit_applier` | Read, Write, Edit, Bash, Glob, Grep | medium / 12 | Live mode `manual_edit_apply`: leased batch → source files; returns canonical JSON only |

Invocation names in skill references:

| Harness | How parents name the agent |
|---------|----------------------------|
| Claude Code / Grok | `impeccable-<role>` (plugin or `.grok/agents/`) |
| Codex | `impeccable_<role>` TOML nested under skill `agents/` |
| Cursor | `/impeccable-<role>` when agents are installed under `.cursor/agents/` |
| GitHub Copilot | Phrase: "Use the impeccable-\<role\> agent" |

### Finish reviewer

Read-only finishing gate. No browser, server, or second detector pass. Parent supplies screenshots, paths, direction contract (THESIS, OWN-WORLD, STORY, FIRST VIEWPORT, FORM), PRODUCT.md, hook findings, QUALITY BAR cards, approved comp, and `reference/craft-floor.md`.

Checks (order): persistence → fidelity (element matrix; mandatory TYPE and MATERIAL rows) → ceiling → contract promises → truth → craft floor. First return line is disposition:

| Disposition | Meaning |
|-------------|---------|
| `disposition: rebuild` | Wholesale fidelity failure; rebuild directive first, not patch list |
| `disposition: fix` | Non-empty `material_fixes` |
| `disposition: ship` | No contradicted/missing matrix rows |

Then exactly five sections: `persistence`, `fidelity`, `ceiling`, `material_fixes` (≤8, ordered), `keep`. Verdict pass (post-fix recaptures) returns `verdict`, `remaining`, and a recomputed disposition only.

### Documenter

Records design system **after** build. Ground truth is shipped CSS/components, not the direction contract. Follows `reference/document.md` for format, tokens, sidecar, section order. Output: paths written, five-line system summary, one not-canonized line. Must not promote craft-floor refusals (kickers, banned shadows, etc.) into system rules.

### Asset producer

Production cleanup, not new art direction. Buckets: `produce` (regenerate clean plates from mock crops), `direct` (real standalone sources only; mock crops never direct), `semantic` (HTML/CSS/SVG/canvas handoff). Defaults: `.webp` opaque, `.png` cutouts, ≥2× display size, strip UI chrome unless intrinsic. After generation, embed prompt via `embed-prompt.mjs`. Return manifest with `qa_status` ∈ `accepted` \| `needs_parent_review` \| `blocked`. Decision-sketch mode: one card → one file at card `sketch` path; different contract from asset production.

### Manual edit applier

Applies one leased live `manual_edit_apply` batch. Owns source edits only; parent owns poll/protocol. Treats batch text as data, not instructions. Entry atomicity: all ops in an entry succeed or entry fails with undo of that entry’s edits. Return **only** JSON:

```json
{"status":"done","appliedEntryIds":["entry-id"],"failed":[],"files":["src/App.jsx"],"notes":[]}
```

Statuses: `done` | `partial` | `error`. Must not run live poll/commit scripts, stage, commit, or inject live DOM scaffolding into source.

## Degraded mode (no subagents)

When the harness cannot spawn subagents, the parent loads generated fallbacks under `reference/degraded/<role>.md` (role = agent name without `impeccable-` prefix):

| File | Role |
|------|------|
| `degraded/finish-reviewer.md` | Inline finish review / verdict |
| `degraded/documenter.md` | Inline DESIGN.md recording |
| `degraded/asset-producer.md` | Inline asset production |
| `degraded/manual-edit-applier.md` | Inline apply (same JSON contract) |

These are **generated at build** from `skill/agents/` with a preamble that forces the parent to run the role inline and disclose the substitution. Do not hand-edit degraded files; edit the agent sources.

## Plugin manifest contract

`scripts/lib/validate-plugin-manifest.js` is a `bun run build` gate. Verified Claude Code loader keys (`KNOWN_LOADER_KEYS`):

`name`, `description`, `version`, `author`, `homepage`, `repository`, `skills`

Rules:

| Rule | Why |
|------|-----|
| No `agents` key | Array of file paths → zero agents loaded; other shapes can fail the whole plugin |
| `skills` must be `"./skills/"` | Trailing slash required (issue #86); bare path fails slash-command registration |
| Every Claude-emitted agent from `skill/agents/` present under `plugin/agents/` | Auto-discovery only sees shipped files |
| Unknown keys fail the build | Add to `KNOWN_LOADER_KEYS` only after live `claude plugin details` confirms load |

Root `.claude-plugin/plugin.json` is the version source of truth; `validatePluginVersions` keeps marketplace + `plugin/.claude-plugin/plugin.json` + bundled skill frontmatter aligned.

Grok’s `plugin/.grok-plugin/plugin.json` is dual metadata (no `skills` path). Grok also accepts `.claude-plugin/`; both are written so marketplace and `grok plugin validate` stay happy when Claude compat is disabled.

## Packaged hooks

`plugin/hooks/hooks.json` is built by `buildClaudePluginHooksManifest()`:

| Event | Matcher | Timeout | Status message |
|-------|---------|---------|----------------|
| `PostToolUse` | `Edit\|Write\|MultiEdit` | 5s | Checking UI changes |
| `Stop` | (session stop) | 30s | Design deep pass |

Command shape:

1. Skip if `hook.mjs` missing under `${CLAUDE_PLUGIN_ROOT}` (or Grok’s `GROK_PLUGIN_ROOT` alias).
2. Require Node ≥ 22 on PATH; on failure, optional one-shot `systemMessage` notice via `~/.impeccable/node-unsupported`, then exit 0.
3. Else `node …/skills/impeccable/scripts/hook.mjs`.

Marketplace/plugin installs get PostToolUse + Stop without merging project settings. Project-scoped CLI installs still write harness-specific manifests (for example `.claude/settings.json`, `.grok/hooks/impeccable.json`).

## Source, emission, and install paths

```text
skill/agents/*.md          # author here
        │
        ▼  provider transformers (agentFormat)
dist/<provider>/…/agents/  # + skill-nested Codex TOML + degraded refs
        │
        ▼  build:release root sync
.claude/agents/  .grok/agents/  .cursor/agents/  …
        │
        ▼  plugin package (Claude agents copy)
plugin/agents/*.md + hooks/hooks.json + skills/impeccable/
```

| Delivery | Agents | Hooks |
|----------|--------|-------|
| Claude marketplace → `./plugin` | Auto-discover `plugin/agents/*.md` | `plugin/hooks/hooks.json` |
| Grok `…#plugin` | Same markdown agents | Same hooks file (`CLAUDE_PLUGIN_ROOT` → `GROK_PLUGIN_ROOT`) |
| Project `npx impeccable install --providers=grok` | `.grok/agents/` | `.grok/hooks/impeccable.json` |
| Codex skills install | TOML inside skill `agents/` | Project `.codex/hooks.json` (trust step) |
| Cursor / Copilot | Provider agent formats when emitted | Separate project hook manifests |

Agents may set frontmatter `providers:` to limit emission; default is all providers with an `agentFormat`.

## Lifecycle in craft finish

Typical new-world handoff (skill references `new-work` / craft):

1. Parent captures desktop + mobile screenshots; may run `detect.mjs --json` if no design hook ran.
2. Spawn **finish reviewer** with full input packet (`fork_turns: 0` on Codex so review is not poisoned by build transcript).
3. On `rebuild` disposition: rebuild named regions/assets; re-verdict. On `fix`: apply material fixes, recapture, verdict pass. Budget: two unattended rounds unless the user funds more.
4. Spawn **documenter** to write DESIGN.md from the final artifact.
5. Asset producer runs earlier whenever media must ship; manual-edit applier only during live Apply events.

## Verification

| Check | Command / signal |
|-------|------------------|
| Manifest shape | `bun run build` → `collectPluginManifestFindings` empty |
| Real loader inventory | `bun run test:plugin-e2e` (needs `claude` on PATH; skips otherwise) |
| E2E expectations | Skills (1) `impeccable`; Agents = count of `plugin/agents/*.md`; Hooks (2) PostToolUse + Stop |
| Unit guard | `tests/validate-plugin-manifest.test.js` — no `agents` in `KNOWN_LOADER_KEYS` |
| After agent source edits | `bun run build:release` so `plugin/agents/` and harness agents stay in sync |

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Agents missing after marketplace install | Manifest declared `agents` as file paths | Omit key; ship files under `plugin/agents/`; re-release |
| Zero slash commands | `skills` without trailing slash | Must be `"./skills/"` |
| Agents present in repo but not in plugin | Skipped release sync | `bun run build:release` |
| Hook errors every edit | Node &lt; 22 on hook PATH | Install Node 22+ or remove hook |
| Reviewer softens findings | Parent reviewed in-thread or forked transcript | Fresh spawn with input packet only; use degraded path only when subagents impossible |
| DESIGN.md invents tokens | Documenter ran from intention, not build | Re-run documenter against shipped styles only |

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Marketplace, Grok `#plugin`, and project-scoped provider installs including hook consent.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Harness directories, agent formats, and hook capability matrix across tools.
  </Card>
  <Card title="Design hook" href="/design-hook">
    PostToolUse and Stop detector behavior shared by plugin and project hooks.
  </Card>
  <Card title="Live mode" href="/live-mode">
    Manual edit apply events that drive the manual-edit-applier agent.
  </Card>
  <Card title="Build and test" href="/build-and-test">
    Release sync of `plugin/`, plugin-e2e, and build gates for manifest shape.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    DESIGN.md and sidecar written by the documenter after finish review.
  </Card>
</CardGroup>

---

## 20. Live framework recipes

> Copy-paste live config shapes and adapter notes for Vite, Next.js, Nuxt, SvelteKit, TanStack, Astro, multipage, and CSP-aware fixtures under tests/framework-fixtures.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/20-live-framework-recipes.md
- Generated: 2026-08-05T07:37:47.651Z

### Source Files

- `skill/reference/live-setup.md`
- `skill/scripts/live/frameworks/index.mjs`
- `skill/scripts/live/frameworks/sveltekit.mjs`
- `skill/scripts/live/frameworks/nextjs.mjs`
- `skill/scripts/detect-csp.mjs`
- `tests/framework-fixtures/README.md`
- `tests/live-e2e.test.mjs`

---
title: "Live framework recipes"
description: "Copy-paste live config shapes and adapter notes for Vite, Next.js, Nuxt, SvelteKit, TanStack, Astro, multipage, and CSP-aware fixtures under tests/framework-fixtures."
---

Live mode injects a browser client into the HTML (or document shell) your dev server actually serves. The project file is `.impeccable/live/config.json`. On inject, `live-inject.mjs` resolves a framework from `skill/scripts/live/frameworks/` (first match wins), then either inserts a marker-wrapped `<script src>` tag or runs a framework adapter that server-renders the document. Fixtures under `tests/framework-fixtures/` are the canonical config shapes and CSP patch references.

## Config shape

Write config at the path boot reports (default `.impeccable/live/config.json`):

```json
{
  "files": ["<path-or-glob>", "..."],
  "exclude": ["<optional-glob>", "..."],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

<ParamField body="files" type="string[]" required>
Paths or globs for the HTML/shell the browser loads (not always “source”). Project-root-relative, forward slashes.
</ParamField>

<ParamField body="exclude" type="string[]">
Optional globs to skip files that a `files` glob would otherwise include (email templates, demo HTML).
</ParamField>

<ParamField body="insertBefore" type="string">
Anchor string; inject runs immediately before the first match. Prefer an anchor present in every listed file.
</ParamField>

<ParamField body="insertAfter" type="string">
Alternative to `insertBefore`: inject after the matching line.
</ParamField>

<ParamField body="commentSyntax" type="'html' | 'jsx'" required>
`html` → `<!-- … -->`. `jsx` → `{/* … */}` for layouts written as JSX/TSX.
</ParamField>

<ParamField body="cspChecked" type="boolean">
Records that the one-time CSP setup step has run. Absent on first setup; set `true` after the agent asks (even if the user declines the patch).
</ParamField>

<Warning>
Hard-excluded paths (not overridable): `**/node_modules/**` and `**/.git/**`.
</Warning>

**Glob syntax:** `**` any segments (including zero), `*` within a segment, `?` one character.

## Detection and inject kinds

Registry priority (do not reorder without updating inject behavior):

| Priority | `name` | Inject kind | Typical shell |
|---:|---|---|---|
| 1 | `sveltekit` | `adapter` | `src/app.html` (hint); real mount via `+layout.svelte` + generated root component |
| 2 | `nuxt` | `adapter` | `app.vue` (hint); real load via generated `.client.ts` plugin |
| 3 | `tanstack-start` | `adapter` | `src/routes/__root.tsx` + generated `ImpeccableLiveRoot` component |
| 4 | `astro` | `tag` | Root layout `.astro` (`is:inline` on script) |
| 5 | `nextjs` | `tag` | `app/layout.*` or `pages/_document.*` |
| 6 | `vite-generic` | `tag` | `index.html` |
| 7 | `static-html` | `tag` (fallback) | multipage / generator HTML |

**Tag inject** writes a marker-wrapped script into each resolved `files` entry.

**Adapter inject** still uses `files` as a detection/CSP hint, but the live client is loaded by generated or patched framework-owned artifacts. Inject state is journaled in `.impeccable/live/inject-journal.json` so the next inject/remove can heal crash leftovers.

Source traits (preview mode, comment syntax for wrap/accept) resolve by **file extension**, not project name. Svelte (`.svelte`) uses `preview: 'component'` under `node_modules/.impeccable-live/`; Astro (`.astro`) uses `styleMode: 'astro-global-prefixed'` and `injectScriptAttrs: 'is:inline '`.

## Framework recipes

Copy the `config` object into `.impeccable/live/config.json`. Paths match the fixtures; adjust to your tree (`src/app/...`, monorepo app dirs, etc.).

### Vite / SPA shell (React, plain HTML, TanStack Router SPA)

Tag inject into the tracked HTML entry.

```json
{
  "files": ["index.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

| Fixture | Notes |
|---|---|
| `vite-react/` | Baseline shell + `src/App.jsx` |
| `tanstack-router-vite/` | Same shell path; no Start adapter |
| `vite8-https/` | Dev over HTTPS; client still loads from live server |
| `vite8-react-base-path/` | `base: '/app/'` — open the app under `/app/` |
| `vite8-react-csp-meta/` | CSP via `<meta http-equiv>`; not auto-patched |

Nested app at repo root with no Vite config at root:

```json
{
  "files": ["**/index.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

Use a glob when static unit checks resolve from the repo root and E2E resolves from `runtime.appDir` (see `monorepo-nested-vite/`). Literal `"index.html"` only works when cwd is already the app root.

### Next.js

Tag inject into the root layout (App Router) or document (Pages). `commentSyntax` is `jsx`.

<Tabs>
<Tab title="App Router">

```json
{
  "files": ["app/layout.tsx"],
  "insertBefore": "</body>",
  "commentSyntax": "jsx",
  "cspChecked": true
}
```

Also valid: `app/layout.jsx`, `src/app/layout.tsx`, etc. Fixtures: `nextjs-app/`, `nextjs-app-router/`.

</Tab>
<Tab title="Pages Router">

```json
{
  "files": ["pages/_document.tsx"],
  "insertBefore": "</body>",
  "commentSyntax": "jsx",
  "cspChecked": true
}
```

</Tab>
<Tab title="Monorepo app">

```json
{
  "files": ["apps/web/app/layout.tsx"],
  "insertBefore": "</body>",
  "commentSyntax": "jsx",
  "cspChecked": true
}
```

Fixture: `nextjs-turborepo/`. Patch CSP on the **app’s** `next.config.*`, not only the shared helper.

</Tab>
</Tabs>

Next has no dedicated inject adapter: the root layout already owns `<html>` / `<body>`, so the generic tag strategy is enough.

### Nuxt

Config lists `app.vue` (or your app-dir equivalent) as the shell hint. A raw `<script>` in `app.vue` is compiled as Vue DOM and **does not execute**. The `nuxt` adapter creates a marked dev-only client plugin, e.g. `plugins/impeccable-live.client.ts` or `app/plugins/impeccable-live.client.ts` when `srcDir` / Nuxt 4 `app/` layout applies, and removes it on stop.

```json
{
  "files": ["app.vue"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

| Fixture | Notes |
|---|---|
| `nuxt-vite7/` | Static inject/wrap checks; documents that script-in-`app.vue` is wrong |
| `nuxt-csp/` | `routeRules` CSP string → `append-string` patch |

If `plugins/impeccable-live.client.ts` already exists and lacks the Impeccable marker, inject returns `nuxt_plugin_conflict`.

### SvelteKit

Config lists `src/app.html`. The adapter patches the root layout and creates `src/lib/impeccable/ImpeccableLiveRoot.svelte` so the client runs under SSR. Variants use **component preview** (not in-route markup HMR).

```json
{
  "files": ["src/app.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

| Fixture | Notes |
|---|---|
| `sveltekit/` | Shell + route wrap → `node_modules/.impeccable-live/...` preview |
| `vite8-sveltekit/` / `vite8-sveltekit-stateful/` | Runtime E2E; stateful list needs collection props across preview boundary |
| `sveltekit-csp/` | `kit.csp.directives` → `append-arrays` |

Preview modules must live under `node_modules/.impeccable-live` so Vite’s `server.fs.allow` can serve them (SvelteKit restricts FS to `src`, `.svelte-kit`, and `node_modules`).

### TanStack

<Tabs>
<Tab title="Router SPA (Vite)">

Same as Vite shell — no Start adapter:

```json
{
  "files": ["index.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

Fixture: `tanstack-router-vite/`. Multi-route heroes often need `preActions` in E2E (navigate before pick).

</Tab>
<Tab title="Start (SSR)">

No static `index.html`. Inject targets the root document and mounts a generated React root component:

```json
{
  "files": ["src/routes/__root.tsx"],
  "insertBefore": "<Scripts",
  "commentSyntax": "jsx",
  "cspChecked": true
}
```

Fixture: `tanstack-start/`. Detection requires the Start project shape (`detectTanStackStartProject`); plain Router SPA stays on `vite-generic`.

</Tab>
</Tabs>

### Astro

Tag inject into the root layout. Scripts get `is:inline` so Astro does not rewrite `src`. Preview CSS uses global-prefixed rules instead of `@scope`.

```json
{
  "files": ["src/layouts/Layout.astro"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

Fixtures: `astro/`, `astro-vite7/`. Point `files` at your actual root layout path.

### Multipage and generators

Serve HTML under a build output (or `public/`) with a glob so new pages are covered:

```json
{
  "files": ["dist/**/*.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html",
  "cspChecked": true
}
```

Fixture `multipage-with-generator/`:

```json
{
  "files": ["dist/index.html", "dist/docs/one.html"],
  "insertBefore": "</body>",
  "commentSyntax": "html"
}
```

`dist/**` is treated as **generated**. Wrap refuses to edit those files (`element_not_in_source`); accept still lands true source via the fallback flow. Inject into generated HTML only survives until the next rebuild — re-run inject after each build if you rely on the shell tag.

### Quick matrix

| Framework | `files` example | `insertBefore` | `commentSyntax` | Inject |
|---|---|---|---|---|
| Vite / SPA | `["index.html"]` | `</body>` | `html` | tag |
| Next App Router | `["app/layout.tsx"]` | `</body>` | `jsx` | tag |
| Next Pages | `["pages/_document.tsx"]` | `</body>` | `jsx` | tag |
| Nuxt | `["app.vue"]` | `</body>` | `html` | adapter (plugin) |
| SvelteKit | `["src/app.html"]` | `</body>` | `html` | adapter (layout + root) |
| TanStack Router SPA | `["index.html"]` | `</body>` | `html` | tag |
| TanStack Start | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` | adapter |
| Astro | `["src/layouts/Layout.astro"]` | `</body>` | `html` | tag + `is:inline` |
| Multipage | `["public/**/*.html"]` or `["dist/**/*.html"]` | `</body>` | `html` | tag |

## CSP recipes

First-time setup runs when `cspChecked` is missing:

```bash
node <scripts_path>/detect-csp.mjs
```

Stdout: `{ "shape": "...", "signals": ["..."] }`. Shape is the **patch mechanism**, not the framework name. Priority: `append-arrays` > `append-string` > `middleware` > `meta-tag` > `null`.

| Shape | Auto-patch | Typical sources | Fixture |
|---|---|---|---|
| `null` | none | no CSP | most plain fixtures |
| `append-arrays` | yes (with consent) | Next monorepo `additionalScriptSrc` / `additionalConnectSrc`; SvelteKit `kit.csp.directives`; nuxt-security | `nextjs-turborepo/`, `sveltekit-csp/` |
| `append-string` | yes (with consent) | Next `headers()` CSP string; Nuxt `routeRules` CSP header | `nextjs-inline-csp/`, `nuxt-csp/` |
| `middleware` | no | `middleware.ts` `headers.set('Content-Security-Policy', …)` | (detect only) |
| `meta-tag` | no | `<meta http-equiv="Content-Security-Policy">` | `vite8-react-csp-meta/` |

Live needs `http://localhost:8400` on both **`script-src`** and **`connect-src`**.

### append-arrays

Declare once, spread into directive arrays (dev-only):

```ts
const __impeccableLiveDev =
  process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
```

- **Next monorepo helper:** edit the app’s `next.config.*` and append to `additionalScriptSrc` / `additionalConnectSrc` (reference: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`).
- **SvelteKit:** `svelte.config.js` → `kit.csp.directives['script-src']` and `['connect-src']` with `...__impeccableLiveDev` (reference: `sveltekit-csp/expected-after-patch.js`).
- Idempotent if `__impeccableLiveDev` already exists: mark `cspChecked: true` without rewriting.

### append-string

Declare a leading-space token and interpolate into both directives:

```ts
const __impeccableLiveDev =
  process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
```

- Next inline `headers()` in `next.config.*` → `nextjs-inline-csp/expected-after-patch.js`
- Nuxt `routeRules['/**'].headers['Content-Security-Policy']` → `nuxt-csp/expected-after-patch.ts`

### middleware / meta-tag

Show detected paths; ask the user to allow `http://localhost:8400` on `script-src` and `connect-src` manually; then set `cspChecked: true`. Do not invent an auto-edit.

### Consent and re-ask

On decline: skip the patch, warn that live will fail until CSP allows the origin, still set `cspChecked: true`. To re-open the prompt, delete `cspChecked` from config and re-run live boot.

## Config drift

On boot, HTML under common roots (`public/`, `src/`, `app/`, `pages/`) not covered by the resolved `files` list appears as `configDrift.orphans`. Offer once per session to add paths or switch to a glob. Never auto-write the config.

## Fixture catalog (recipes-relevant)

| Fixture | Role |
|---|---|
| `vite-react/`, many `vite8-react-*` | SPA shell + styling variants (Tailwind, CSS modules, Emotion, …) |
| `nextjs-app/`, `nextjs-app-router/` | App Router inject + wrap |
| `nextjs-turborepo/`, `nextjs-inline-csp/` | CSP `append-arrays` / `append-string` |
| `sveltekit/`, `vite8-sveltekit*`, `sveltekit-csp/` | Adapter, component preview, CSP arrays |
| `nuxt-vite7/`, `nuxt-csp/` | Plugin inject shape + CSP string |
| `tanstack-router-vite/`, `tanstack-start/` | Tag SPA vs Start adapter |
| `astro/`, `astro-vite7/` | Layout inject + Astro script attrs |
| `multipage-with-generator/` | Generated HTML + `element_not_in_source` |
| `monorepo-nested-vite/` | `appDir: "website"`, roots resolution |
| `vite8-react-csp-meta/` | Manual CSP meta shape |
| `vite8-https/`, `vite8-react-base-path/` | TLS and base path edge cases |

Layout of each fixture:

```text
tests/framework-fixtures/<name>/
  files/           # staged project tree
  fixture.json     # config + wrap/CSP/runtime expectations
  gitignore.txt    # becomes .gitignore in tmp
  expected-after-patch.*   # CSP references (optional)
```

Runtime E2E (`bun run test:live-e2e`) only runs fixtures that declare `runtime`. Scope with `IMPECCABLE_E2E_ONLY=<fixture>`.

## Troubleshooting

| Symptom | Check |
|---|---|
| Picker never loads | CSP blocks `localhost:8400`; clear `cspChecked` and re-run CSP step |
| Script in HTML but no `window.__IMPECCABLE_LIVE_INIT__` | Wrong framework path: Nuxt/SvelteKit/TanStack Start need adapters, not only a shell tag |
| `file_not_found` on inject | `files` wrong relative to app root; prefer globs in monorepos |
| Wrap errors `element_not_in_source` | Picked DOM only exists in generated HTML; edit true source or accept fallback |
| Inject vanishes after rebuild | Multipage generator output recreated; re-inject after build |
| `nuxt_plugin_conflict` | User-owned file at the plugin path; rename/remove or pick another plugin dir |
| Nested app not detected | Boot from repo root so roots resolution finds `appDir`; set config under the app when E2E uses `runtime.appDir` |

## Next

<CardGroup>
<Card title="Live browser iteration" href="/live-mode">
Start live mode, poll contract, generate/accept/discard, roots, carbonize.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
Full `.impeccable/config.json` and live `config.json` field list.
</Card>
<Card title="Build and test" href="/build-and-test">
`test:live-e2e` triggers and framework-fixture obligations.
</Card>
<Card title="Modes and platform" href="/modes-and-platform">
Live is web-only; native platforms skip live and detect overlays.
</Card>
</CardGroup>

---

## 21. Detect in CI

> Run impeccable detect non-interactively with --json/--quiet/--scope, interpret exit codes 0 and 2, apply project ignores, and wire optional Puppeteer URL scans.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/21-detect-in-ci.md
- Generated: 2026-08-05T07:38:30.205Z

### Source Files

- `cli/engine/cli/main.mjs`
- `cli/bin/cli.js`
- `README.npm.md`
- `package.json`
- `cli/lib/impeccable-config.mjs`
- `scripts/benchmark-detector.mjs`

---
title: "Detect in CI"
description: "Run impeccable detect non-interactively with --json/--quiet/--scope, interpret exit codes 0 and 2, apply project ignores, and wire optional Puppeteer URL scans."
---

`npx impeccable detect` is the non-interactive anti-pattern gate for local automation and CI. It scans HTML, CSS, JS/TS, JSX/TSX, Vue, Svelte, Astro, and related sources under a path, or renders live pages when given `http(s)://` or `file://` URLs. The published CLI package is `impeccable` (Node `>=22.18.0`); Puppeteer is an optional dependency used only for URL scans.

## When to use detect in CI

| Goal | Command shape | Exit signal |
| --- | --- | --- |
| Fail the job on design anti-patterns | `npx impeccable detect --json src/` | `2` if non-advisory findings |
| Log-only gate (no fail) | same, ignore exit `2` | still print JSON on stdout |
| Minimal text noise | `npx impeccable detect --quiet src/` | summary on stderr; `2` still applies |
| Scope to typography or layout rules | `--scope type` or `--scope layout` | filters findings after scan |
| Rendered page (browser rules) | `detect http://localhost:3000` | requires Puppeteer + Chrome |

Static file scans need no browser. URL scans need Puppeteer installed in the job image (see [URL scans with Puppeteer](#url-scans-with-puppeteer)).

## Prerequisites

- Node.js `>=22.18.0`
- Project checkout with the paths you want scanned
- Optional: `.impeccable/config.json` and/or `.impeccable/config.local.json` for detector ignores
- Optional: `puppeteer` (package `optionalDependencies`) for URL targets

## Non-interactive flags

CI should prefer flags that avoid prompts and noisy stderr.

| Flag | Effect in CI |
| --- | --- |
| `--json` | Findings as a JSON array on **stdout**. Clean scan prints `[]`. Skips framework “scan via URL” suggestions and the large-tree confirm prompt. |
| `--quiet` | Text mode only: one line summary on **stderr** (`N anti-pattern(s) found.`). No per-finding detail. Silent when clean. Does not change JSON when combined with `--json`. |
| `--scope <name>` | Comma-separated design domains: `type`, `layout`. Unknown or empty values exit `1`. |
| `--viewport WxH` | Browser viewport for URL scans (default `1280x800`). Example: `--viewport 390x844`. |
| `--no-config` | Ignore project detector config, inline `impeccable-disable*` comments, and DESIGN.md loading. |
| `--no-inline-ignores` | Keep config ignores; ignore in-file disable comments only. |
| `--no-design-system` | Do not load DESIGN.md / `.impeccable/design.json` per target. |
| `--no-advisory` | Drop advisory findings before output and exit-code math. |
| `--fast` | Deprecated no-op; full static scan still runs (stderr note). |

Text findings (non-JSON) write to **stderr**. JSON findings write to **stdout**. That split matters when you capture artifacts with `> findings.json`.

### Argument parsing notes

- `impeccable detect …` and the shorthand `impeccable src/` both route to detect.
- Bare `-json` is accepted as `--json`.
- Default target when none is given: `process.cwd()`.
- Directory walks skip `node_modules`, `dist`, `build`, `__pycache__`, and most hidden dirs (exceptions: `.vitepress`, `.vuepress`, `.storybook`). An explicitly passed hidden path still scans.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | No non-advisory (“primary”) findings. Clean files, empty JSON `[]`, or advisory-only results. |
| `2` | At least one primary finding remains after ignores and scope filters. |
| `1` | CLI usage or runtime error (bad `--scope`, bad `--viewport`, unknown top-level command, uncaught exception). |
| `130` | Interactive prompt abort (`IMPECCABLE_PROMPT_ABORT`); not expected in non-TTY CI. |

Primary vs advisory:

- Registry rules with `advisory: true` (currently `em-dash-overuse`) appear in output but **do not** set exit `2`.
- In text mode they render under a separate “Advisory” section; in JSON each carries `"advisory": true`.
- Use `--no-advisory` to omit them entirely.

<Warning>
Do not treat every non-zero exit as “anti-patterns found.” Exit `1` is a tool/config failure; exit `2` is a findings gate. Wire CI steps accordingly.
</Warning>

## Project ignores and config

Without `--no-config`, detect loads from the current working directory:

1. `.impeccable/config.json` (shared)
2. `.impeccable/config.local.json` (local overlay)

Relevant keys under `detector`:

```json
{
  "detector": {
    "ignoreRules": ["side-tab"],
    "ignoreFiles": ["**/legacy/**", "storybook-static/**"],
    "ignoreValues": [
      { "rule": "overused-font", "value": "roboto" }
    ],
    "designSystem": { "enabled": true }
  }
}
```

| Key | Role at scan time |
| --- | --- |
| `ignoreRules` | Drop all findings for those rule ids |
| `ignoreFiles` | Skip matching files before analysis (globs) |
| `ignoreValues` | Drop value-scoped findings (e.g. one intentional font) |
| `designSystem.enabled` | When not `false`, load per-target DESIGN.md context |

Inline file comments still apply unless `--no-config` or `--no-inline-ignores`:

```html
<!-- impeccable-disable overused-font -- brand doc -->
```

```css
.brand { font-family: Inter } /* impeccable-disable-line overused-font */
```

`hook.enabled` only controls design-hook auto-runs; manual `detect` still runs when the hook is off, but shares the same detector ignore filters.

Manage ignores via `impeccable ignores …` (see related pages) rather than hand-editing CI-only copies unless you need ephemeral overrides with `--no-config`.

## Detection modes

```text
targets[]
  ├─ path → directory walk → HTML: static HTML/CSS engine
  │                      └─ other: regex/text engine
  ├─ path → single file → same split by extension
  └─ http(s):// or file:// → Puppeteer browser engine
```

- **HTML** (`.html`, `.htm`): static HTML/CSS analysis (linked stylesheets included).
- **Non-HTML scannable files**: regex/text path (CSS, JSX, TSX, Vue, Svelte, etc.).
- **URLs**: full browser render; layout and visual rules that need computed style.

Per-file DESIGN.md resolution uses each target’s project root (not always `cwd`). Remote `http(s)` URLs do not load a local design system. Multi-URL runs reuse one browser via `createBrowserDetector`.

## URL scans with Puppeteer

`puppeteer` is optional. Missing install fails URL targets with:

```text
puppeteer is required for URL scanning. Install: npm install puppeteer
```

That error is written to stderr for that target; other targets continue. A failed URL alone does not force exit `2` unless primary findings exist from successful scans.

### CI install patterns

<Tabs>
  <Tab title="npm (optional dep)">
```bash
npm install impeccable
# optionalDependency may install automatically; pin if your install omits optionals:
npm install puppeteer
```
  </Tab>
  <Tab title="npx without lockfile">
```bash
# Prefer a committed package.json that lists puppeteer when URL scans run in CI
npx impeccable detect --json https://staging.example.com
```
  </Tab>
  <Tab title="explicit chrome needs">
```bash
# Puppeteer downloads Chromium on first use; ensure the job can download
# or cache browsers. Windows prefer system Chrome (channel: chrome) when available.
npx impeccable detect --viewport 1280x800 --json http://127.0.0.1:4173
```
  </Tab>
</Tabs>

Typical pattern: start the app or preview server, wait for health, then scan the URL.

```bash
npm run build && npm run preview -- --host 127.0.0.1 --port 4173 &
# wait-for-port helper of your choice
npx impeccable detect --json --viewport 1280x800 http://127.0.0.1:4173
```

`file:///absolute/path/to/page.html` uses the same browser path for local static artifacts when you need computed styles without a server.

## JSON finding shape

Each finding is an object roughly:

| Field | Type | Notes |
| --- | --- | --- |
| `antipattern` | string | Rule id (e.g. `side-tab`) |
| `name` | string | Display name from registry |
| `description` | string | Rule description |
| `severity` | string | Usually `warning` |
| `category` | string \| null | e.g. `slop` / `quality` |
| `file` | string | Path or URL target |
| `line` | number | `0` when unknown |
| `snippet` | string | Locating text (often quote-wrapped labels) |
| `advisory` | true \| omitted | Present only when advisory |
| `importedBy` | string[] \| omitted | Basename importers when multi-file graph applies |

Clean JSON mode:

```json
[]
```

## Minimal CI recipes

### GitHub Actions (static paths)

```yaml
name: design-detect
on: [push, pull_request]
jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - name: Detect anti-patterns
        run: npx --yes impeccable@latest detect --json --quiet src/
```

- `--json` keeps machine-readable output on stdout; `--quiet` is redundant for detail (JSON wins) but harmless.
- Job fails on exit `2` by default.

### Capture findings without failing

```bash
set +e
npx impeccable detect --json src/ > impeccable-findings.json
code=$?
set -e
if [ "$code" -eq 2 ]; then
  echo "Findings present; see impeccable-findings.json"
  exit 0   # or upload artifact and still pass
fi
if [ "$code" -ne 0 ]; then
  exit "$code"  # real tool failure
fi
```

### Scope-limited gate

```bash
npx impeccable detect --json --scope layout,type components/
```

### Strict raw scan (ignore project waivers)

```bash
npx impeccable detect --json --no-config src/
```

Use sparingly; teams usually want shared `ignoreRules` / `ignoreFiles` honored in CI the same way as local hooks.

## Interactive paths that CI avoids

These only run when stdin is a TTY **and** not `--json`/`--quiet`:

- Framework dev-server suggestions (`Next` / Vite / etc. on localhost ports)
- Confirm prompt when a directory contains more than 50 scannable files

Non-TTY CI skips the confirm and proceeds. Prefer explicit subdirectory targets to keep scan time predictable.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Exit `2` with expected brand fonts | Rule not ignored | Add `ignoreValues` or inline disable; see detector ignores docs |
| Exit `0` but advisory noise in logs | Advisory rules | `--no-advisory` or filter `advisory: true` in JSON |
| Exit `1` on `--scope` | Missing/unknown value | Valid scopes: `type`, `layout` |
| URL scan error, empty/partial results | Puppeteer/Chrome missing | Install `puppeteer`; ensure browser download in the image |
| CI finds harness/vendor noise | Scanning repo root | Target `src/` (or app root); walks already skip many hidden harness dirs |
| Design rules from wrong package monorepo | DESIGN.md root | Design system resolves per file project root; set `--no-design-system` if unwanted |
| Large monorepo timeout | Wide walk | Narrow path args; use `ignoreFiles` |

## Related pages

<CardGroup>
  <Card title="CLI reference" href="/cli-reference">
    Full flag list, shorthand targets, and command inventory for detect and ignores.
  </Card>
  <Card title="Manage detector ignores" href="/manage-detector-ignores">
    ignoreRules, ignoreFiles, ignoreValues, and inline disable comments.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, categories, advisory rules, and engine scopes.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    `.impeccable/config.json` schema for detector and related settings.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Edit-time detection that shares the same ignore filters as CLI detect.
  </Card>
</CardGroup>

---

## 22. Doctor

> Run doctor for schema, config, and proxy truth-drift findings; apply auto fixes; route mention and route severities; opt out of boot staleness checks.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/22-doctor.md
- Generated: 2026-08-05T07:46:45.011Z

### Source Files

- `skill/reference/doctor.md`
- `skill/scripts/doctor.mjs`
- `skill/scripts/lib/staleness.mjs`
- `skill/scripts/lib/staleness-deep.mjs`
- `skill/scripts/lib/staleness-notice.mjs`
- `tests/doctor.test.mjs`
- `tests/staleness.test.mjs`

---
title: Doctor
description: Run doctor for schema, config, and proxy truth-drift findings; apply auto fixes; route mention and route severities; opt out of boot staleness checks.
---

`doctor` is a **maintenance utility**, not one of the 23 design sub-commands. It reports (and optionally repairs) drift between project Impeccable artifacts and what the installed skill version reads: `PRODUCT.md`, `DESIGN.md` and `.impeccable/design.json`, `.impeccable/config.json` / `config.local.json`, surface briefs, the design hook, and monorepo workspace context.

It does **not** redesign UI, open unrelated files, or run other commands as side effects. Findings are not errors: exit code is `0` unless the process itself fails.

## What doctor owns vs what it does not

Three kinds of “out of date” are kept separate:

| Kind | Meaning | Owner |
| --- | --- | --- |
| Tool version | Installed skill older than published | Boot `UPDATE_AVAILABLE` from `context.mjs`; fix with package update (`npx impeccable update`) |
| Schema drift | Older fields, missing stamps, retired paths, unknown config keys | **Doctor** (mechanical; many are fixable) |
| Truth drift | Docs no longer describe the code | Proxy signals only; **`init`** owns `PRODUCT.md`, **`document`** owns `DESIGN.md` |

Do not treat a large commit-count proxy as proof that `DESIGN.md` is wrong.

## Two tiers: boot vs on-demand

```mermaid
flowchart LR
  boot[Session boot via context.mjs] --> tier1[Tier 1 collectBootFindings]
  tier1 --> throttle[Weekly throttle for mention/route]
  throttle --> directive[CONTEXT_STALE directive]
  doctor[impeccable doctor / doctor.mjs] --> tier2[Tier 2 deep checks]
  tier2 --> report[Full findings + workspaces]
  report --> fixopt["--fix applies severity auto only"]
```

| Tier | When | Cost budget | Examples |
| --- | --- | --- | --- |
| **Tier 1** | Every session boot that runs `context.mjs` | Parses markdown already in memory, bounded `stat`s, small JSON already read. No git, no full directory walks for deep work | Deprecated `## Register`, product schema stamp, sidecar path/schema/mtime, unknown config keys, orphaned surface briefs, empty `projectRoots`, root-level native-vs-web mismatch |
| **Tier 2** | `/impeccable doctor` or `node …/doctor.mjs` | Git log, per-workspace sweep, detector rule registry, hook script resolution | `design-md-drift`, `design-md-coverage`, ignore list validation, hook install, legacy live paths, workspace inheritance / native evidence |

Boot emits **one** `CONTEXT_STALE` directive for the whole set. Severity `auto` findings are never throttled and are not meant for the user; `mention` and `route` surface at most **once per week per project** (cache under `~/.impeccable/staleness-check.json`, overridable with `IMPECCABLE_STALENESS_CACHE`).

Skill routing: load doctor when the user invokes it or asks what is stale; act on a boot `CONTEXT_STALE` per that directive, not by launching doctor unasked. Never repair drift as a side quest of a design task, except `auto` migrations the next write would perform anyway.

## Run doctor

### From the skill

Invoke `/impeccable doctor` (provider command prefix may be `/` or `$`). The agent should run the script with JSON output, then act by severity.

### From the script

Path is provider-aware (`{{scripts_path}}` in skill text). From a checkout:

```bash
node skill/scripts/doctor.mjs
node skill/scripts/doctor.mjs --json
node skill/scripts/doctor.mjs --fix
node skill/scripts/doctor.mjs --target apps/mobile
node skill/scripts/doctor.mjs --help
```

<ParamField body="--json" type="boolean">
Emit a machine-readable report (preferred for agents).
</ParamField>

<ParamField body="--fix" type="boolean">
Apply **only** severity `auto` migrations. No judgment calls (platform, truth drift, init/document).
</ParamField>

<ParamField body="--target" type="string">
Select a monorepo workspace, file, or route path. Without it, the report is for the resolved project root (often wrong in monorepos). Also accepts `-t` / `--target=`.
</ParamField>

<ParamField body="--help" type="boolean">
Print usage and exit without running checks.
</ParamField>

**Exit codes:** `0` on success (including when findings exist); non-zero if argument parsing fails or the run throws. Findings are never treated as failures.

### Expected clean outcome

Human text:

```text
Impeccable doctor: .
No drift found. Every artifact matches what this version reads.
```

JSON: `"findings": []`.

## Severity model

Severity is **what should happen**, not how bad it is.

| Severity | Agent / user action |
| --- | --- |
| `auto` | No decision. Run `doctor.mjs --fix` once, report what moved in one line. Do not ask first or after. |
| `mention` | State each finding in a sentence with its offered fix. No blocking decision required now. |
| `route` | Name the owning command and the gap. Run `init` / `document` only if the user asks this turn. |

Report all groups in one pass. Text mode groups as *needs a command* → *worth saying* → *automatic*.

### Deprecated fields are binding

Findings for deprecated PRODUCT sections (today: `## Register`) are not style notes. Treat that field as **absent** for every decision this session, whatever value it holds, and offer deletion. Preserving “just in case” keeps a retired axis steering output.

### Truth-drift restraint

- `design-md-drift` counts commits to visual source dirs (`src`, `app`, `pages`, `components`, `site`, `styles`, `public`) since `DESIGN.md` was last committed. Default threshold: **25** commits. It is a **proxy**: report the number and measurement, do not assert the document is wrong.
- `workspace-context-inherited` is designed inheritance, not a defect. Whether one product record describes several apps is a user judgment.

## Finding shape

Every finding is data shared by boot, doctor text, and JSON:

<ResponseField name="id" type="string">
Stable identifier (e.g. `product-schema-legacy`, `design-sidecar-legacy-path`).
</ResponseField>

<ResponseField name="artifact" type="string">
Logical artifact: `PRODUCT.md`, `DESIGN.md`, `design.json`, `config.json`, `surface brief`, `hook manifest`, `live state`, etc.
</ResponseField>

<ResponseField name="path" type="string | null">
Project-relative path when known.
</ResponseField>

<ResponseField name="severity" type="string">
`auto` | `mention` | `route`.
</ResponseField>

<ResponseField name="summary" type="string">
What was detected.
</ResponseField>

<ResponseField name="fix" type="string">
What to do next.
</ResponseField>

### JSON report envelope

When `--json` is set, stdout is an object with:

| Field | Meaning |
| --- | --- |
| `projectRoot`, `repoRoot`, `isMonorepo` | Resolution context |
| `productPath`, `designPath`, `platform` | Active product/design/platform |
| `ruleRegistryAvailable` | `false` if detector rule ids could not be validated; say so, do not imply ignore lists are clean |
| `findings` | Array of findings |
| `workspaces` | Per-app product/design/platform status in monorepos |
| `fixes` | Present only with `--fix`: `{ applied: string[], skipped: { id, reason }[] }` |

## Checks catalog

### PRODUCT.md (Tier 1 + doctor)

| `id` | Severity | Trigger | Typical fix |
| --- | --- | --- | --- |
| `product-deprecated-<section>` | `mention` | Deprecated section present (e.g. `Register`) | Treat as absent; offer delete |
| `product-schema-legacy` | `route` | No stamp and none of the v4 sections (`Positioning`, `Operating Context`, `Evidence on Hand`, `Product Principles`) | Offer `init` (preserves confirmed answers) |
| `product-schema-outdated` | `route` | Stamp older than current product schema (`1`) | Offer `init` |
| `platform-native-evidence` | `mention` | Resolves to `web` but native evidence exists (Flutter/RN/Expo, `ios/Podfile`, Android gradle, etc.) | Confirm `## Platform` (`ios` / `android` / `adaptive`) |

Schema stamps look like `<!-- impeccable:product-schema 1 -->`. Stamps are **schema** versions, not skill release versions.

### DESIGN.md and sidecar

| `id` | Tier | Severity | Trigger | Typical fix |
| --- | --- | --- | --- | --- |
| `design-sidecar-legacy-path` | 1 | `auto` | Sidecar at `DESIGN.json` (or legacy context path) instead of `.impeccable/design.json` | `--fix` moves when canonical missing |
| `design-sidecar-schema-outdated` | 1 | `route` | Sidecar schema behind current (`2`) | Offer `document` |
| `design-sidecar-stale` | 1 | `mention` | `DESIGN.md` mtime newer than sidecar | Offer `document` |
| `design-md-drift` | 2 | `route` | ≥25 commits to visual dirs since DESIGN last edited | Re-read tokens/components; `document` if truly drifted |
| `design-md-coverage` | 2 | `mention` | Missing required sections (seed: colors/typography; full: + components) | Ask if N/A; else `document` |

### Config and detector ignores

Recognized **top-level** config keys: `hook`, `detector`, `updateCheck`, `stalenessCheck`, `projectRoots`, `$schema`, `version`.

Recognized **`detector`** keys: `ignoreRules`, `ignoreFiles`, `ignoreValues`, `designSystem`, `extensions`.

| `id` | Severity | Trigger |
| --- | --- | --- |
| `config-unknown-keys` | `mention` | Top-level keys nothing reads (typos never applied) |
| `config-unknown-detector-keys` | `mention` | e.g. singular `ignoreRule` instead of `ignoreRules` |
| `config-project-roots-match-nothing` | `mention` | Every positive `projectRoots` glob misses → repo root silently active |
| `detector-ignore-rules-unknown` | `mention` | Ignore rule ids not in live `ANTIPATTERNS` (skipped if registry unavailable) |
| `detector-ignore-files-missing` | `mention` | Non-glob ignore file paths that no longer exist |

### Surface briefs, hook, live

| `id` | Severity | Trigger | Notes |
| --- | --- | --- | --- |
| `surface-brief-orphaned` | `mention` | Primary target path missing (skips `http(s):` and `route:`) | Repoint or delete brief |
| `hook-script-missing` | `mention` | Provider hook manifest points at non-existent script | Reinstall hooks; unresolved placeholders (`${CLAUDE_PLUGIN_ROOT}`, `$(…)`) are **not** reported missing |
| `hook-enabled-conflict` | `mention` | Manifest installed but `hook.enabled: false` | Enable or uninstall manifest |
| `legacy-live-state` | `auto` | `.impeccable-live.json` / `.impeccable-live` present | Current live uses `.impeccable/live/`; **`--fix` does not delete** (avoid killing a running session) |

### Monorepo (doctor)

| `id` | Severity | Trigger | Fix guidance |
| --- | --- | --- | --- |
| `workspace-platform-native-evidence` | `mention` | Workspace has native evidence while product resolves to web (especially when **inheriting** root PRODUCT) | Child `PRODUCT.md` with correct `## Platform` |
| `workspace-context-inherited` | `mention` | One or more workspaces inherit root PRODUCT | Informational; `init` in workspace if inheritance is wrong |

Use the `workspaces` table (`path`, `productStatus`, `designStatus`, `platform`) before proposing structure changes.

## What `--fix` actually does

| Case | Behavior |
| --- | --- |
| `design-sidecar-legacy-path` | `rename` to `.impeccable/design.json` if canonical does not already exist; never overwrite |
| Product stamp | Stamps current schema when PRODUCT has content that is **not** `product-schema-legacy` (legacy needs `init`, not a silent stamp) |
| `legacy-live-state` | Skipped: “delete by hand once no live session is running” |
| All other severities | Skipped: “needs a decision from the user” |

## Opt out of boot staleness only

Doctor still runs fully when boot checks are off. Prefer this when you want reports **only on demand**.

| Mechanism | Scope |
| --- | --- |
| `"stalenessCheck": false` in `.impeccable/config.json` | Project default |
| Same key in `config.local.json` | Overrides shared (last boolean wins across roots scanned) |
| `IMPECCABLE_NO_STALENESS_CHECK=1` | One session / process |
| `IMPECCABLE_STALENESS_CACHE` | Override path for the throttle cache file |

```json
{
  "stalenessCheck": false
}
```

Tests that assert on other boot directives should disable staleness so `CONTEXT_STALE` noise does not flake assertions.

## Workflow

<Steps>
  <Step title="Run the pass">
    Prefer `node <scripts_path>/doctor.mjs --json`. Add `--target <path>` in monorepos. Empty `findings` → say clean and stop.
  </Step>
  <Step title="Apply automatic migrations">
    If any finding has `severity: "auto"`, run once with `--fix`. Report applied lines only.
  </Step>
  <Step title="Surface mention findings">
    One sentence each with the offered fix. Do not expand scope into redesign.
  </Step>
  <Step title="Route command-owned gaps">
    Name `init` or `document` (or hooks reinstall) and the gap. Run only if the user asks this turn.
  </Step>
  <Step title="Honor deprecated fields">
    For deprecated PRODUCT sections, treat values as absent for the rest of the session.
  </Step>
</Steps>

## Troubleshooting

| Symptom | Likely cause | Action |
| --- | --- | --- |
| Boot never mentions drift | Disabled via config/env, or still inside weekly throttle | Run doctor explicitly; check `stalenessCheck` / `IMPECCABLE_NO_STALENESS_CHECK` |
| `ruleRegistryAvailable: false` | Detector engine not resolvable from skill install layout | Do not claim ignore rule ids are valid; reinstall skill or run from full checkout |
| Monorepo always “root” | Empty `projectRoots` matches | Fix globs; use `--target` |
| Native app gets web guidance | Missing/wrong `## Platform` or inherited web PRODUCT | Child PRODUCT + platform value |
| `--fix` did not stamp PRODUCT | `product-schema-legacy` needs interview | Offer `init` |
| Hook “installed” but silent | Broken script path or `hook.enabled: false` | Doctor `hook-*` findings; reinstall or align config |
| Live legacy paths remain after `--fix` | Intentional | Delete `.impeccable-live*` only when no live session runs |

## Implementation map

| Piece | Role |
| --- | --- |
| `skill/reference/doctor.md` | Agent procedure for the utility command |
| `skill/scripts/doctor.mjs` | CLI: collect, render, `--fix` |
| `skill/scripts/lib/staleness.mjs` | Tier 1 checks + `collectBootFindings` |
| `skill/scripts/lib/staleness-deep.mjs` | Tier 2 checks + rule registry load |
| `skill/scripts/lib/staleness-notice.mjs` | Opt-out, throttle, `CONTEXT_STALE` text |
| `skill/scripts/lib/artifact-schema.mjs` | Product/sidecar schema versions and stamps |
| `skill/scripts/context.mjs` | `appendStalenessDirective` on boot |
| `tests/doctor.test.mjs`, `tests/staleness.test.mjs` | CLI and pure-check coverage |

## Related pages

<CardGroup cols={2}>
  <Card title="Project artifacts" href="/project-artifacts">
    PRODUCT.md, DESIGN.md, sidecar, schema stamps, and `.impeccable/` layout.
  </Card>
  <Card title="Initialize product context" href="/init-and-document">
    `init` and `document` own truth rewrites doctor only routes.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    `stalenessCheck`, `projectRoots`, detector, and hook keys.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    `IMPECCABLE_NO_STALENESS_CHECK` and related controls.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Platform values and why native evidence mismatches matter.
  </Card>
  <Card title="Design hook" href="/design-hook">
    Hook install paths doctor validates.
  </Card>
</CardGroup>

---

## 23. Build and test

> Source-first vs release builds, browser and extension bundles, default and opt-in test suites (live-e2e, skill-behavior, plugin-e2e), and suite trigger mapping.

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/23-build-and-test.md
- Generated: 2026-08-05T07:39:55.339Z

### Source Files

- `package.json`
- `scripts/build.js`
- `scripts/run-tests.mjs`
- `scripts/test-suites.mjs`
- `docs/DEVELOP.md`
- `tests/build.test.js`
- `tests/skill-behavior/README.md`

---
title: "Build and test"
description: "Source-first vs release builds, browser and extension bundles, default and opt-in test suites (live-e2e, skill-behavior, plugin-e2e), and suite trigger mapping."
---

The repository builds design skills from `skill/` through `scripts/build.js`, regenerates detector and extension bundles with separate Node scripts, and runs tests through `scripts/run-tests.mjs` against named suites defined in `scripts/test-suites.mjs`. Default development uses a **source-first** build that validates `dist/` without rewriting tracked harness folders; a **release** build additionally syncs root provider skills and the committed `plugin/` subtree.

## Prerequisites

| Requirement | Notes |
|---|---|
| **Bun** | Build orchestration and Bun-runner unit tests |
| **Node.js `>=22.18.0`** | `package.json` engines; CI matrix uses `22.18.0` and `24` |
| **Git** | CI change detection and plugin E2E isolation |
| **Optional: Playwright Chromium** | Live E2E suites (`npx playwright install chromium`) |
| **Optional: Puppeteer Chrome** | Detector browser tests (`bunx puppeteer browsers install chrome`) |
| **Optional: `claude` CLI** | Plugin loader E2E; suite skips when missing |
| **Optional: provider API keys in `.env`** | Skill-behavior and billed opt-in E2E |

## Build commands

| Script | What it does |
|---|---|
| `bun run build` | Source-first skills build (`scripts/build.js --skip-root-sync`), then copies `dist/` → `build/_data/dist` |
| `bun run build:release` | Full skills build **with** root harness + `plugin/` sync, then copies `dist/` → `build/_data/dist` |
| `bun run build:skills` | Skills only, skip root sync |
| `bun run build:skills:release` | Skills only, with root sync |
| `bun run build:browser` | Browser detector IIFE → `cli/engine/detect-antipatterns-browser.js` |
| `bun run build:extension` | Extension detector + `antipatterns.json` + zips under `dist/` |
| `bun run clean` | Remove `dist` and `build` |
| `bun run rebuild` / `rebuild:release` | Clean then source-first or release build |

### Source-first vs release

```text
skill/ + scripts/lib/transformers/*
        │
        ▼
 scripts/build.js
        │
        ├─ always: dist/<provider>/…, dist/universal/, ZIPs, OpenAI plugin stage
        │          gates: counts, plugin versions, manifest shape, prose
        │
        ├─ --skip-root-sync (default for `bun run build`)
        │     no rewrite of .claude/skills, .cursor/skills, …, or plugin/
        │
        └─ root sync (`bun run build:release`)
              mirror skills into provider harness dirs (except .codex)
              sync hook manifests, agents where configured
              rebuild committed plugin/ for marketplace installs
```

- **Source-first (`bun run build`)** is the normal contributor path. Edit `skill/`, `scripts/`, `cli/`, `extension/`, `tests/`. Validate under `dist/` without staging harness churn.
- **Release (`bun run build:release`)** rewrites tracked harness directories (`.agents/skills/`, `.claude/skills/`, `.cursor/skills/`, …) and `plugin/`. Use only when intentionally refreshing installable artifacts (releases, build-system work, or the `sync-generated-output` workflow on `main`).
- Codex provider output stays under `dist/`; it is **not** synced to a root `.codex/` tree.
- After feature work lands on `main`, `.github/workflows/sync-generated-output.yml` runs `bun run build:release` and commits generated harness output separately.

### What the skills build produces

| Output | Role |
|---|---|
| `dist/<provider>/<configDir>/skills/…` | Per-provider transformed skills |
| `dist/universal/` | All provider config dirs assembled for install ZIPs |
| `dist/*.zip` | Individual + universal bundles (`createAllZips`) |
| `dist/openai/` / OpenAI plugin zip | Staged via `stageOpenAIPlugin` on every build |
| Root harness dirs + `plugin/` | Only when root sync is enabled |
| `build/_data/dist` | Copy of `dist` for Cloudflare Pages Functions consumers |

Provider transforms come from `createTransformer` + `PROVIDERS` in `scripts/lib/transformers/`. Placeholders such as `{{model}}`, `{{config_file}}`, `{{command_prefix}}`, and `{{available_commands}}` are substituted per provider from `skill/SKILL.src.md`.

### Build gates (hard fail)

`scripts/build.js` exits non-zero when any of these fail:

| Gate | Checks |
|---|---|
| `validateSkillFrontmatter` | Description length ≤ 1024 |
| `generateCounts` | Command count from skill router table and detector rule count match README / AGENTS / plugin manifests (and site index when present) |
| `validatePluginVersions` | `.claude-plugin/plugin.json`, marketplace, `plugin/` manifest, and bundled skill frontmatter versions agree |
| `validatePluginManifestShape` | Known Claude Code loader contract (`scripts/lib/validate-plugin-manifest.js`; no silent `agents` key) |
| `validateProse` | README surfaces: em dashes, `--` substitute, denylisted marketing phrases (`docs/STYLE.md`) |
| `validateSkillProse` | `skill/**/*.md`: em dashes plus a tighter phrase denylist (technical words like `seamless` allowed in skill text) |

### Browser and extension bundles

After changing detector rules under `cli/engine/`:

```bash
bun run build:browser
bun run build:extension
```

| Command | Generated artifacts |
|---|---|
| `build:browser` | `cli/engine/detect-antipatterns-browser.js` (IIFE around browser-safe modules); optionally mirrors to `site/public/js/…` if that tree exists |
| `build:extension` | `extension/detector/detect.js`, `extension/detector/antipatterns.json`, `dist/extension.zip`, Firefox packaging under `dist/` |

CI rebuilds these when the detector suite is selected, then asserts no unexpected diff in tracked outputs:

```bash
git diff --exit-code -- .agents .claude .cursor .gemini .github/skills plugin \
  cli/engine/detect-antipatterns-browser.js extension/detector
```

Rule changes also need fixture tests under `tests/fixtures/antipatterns/` and both browser and jsdom adapter wiring. See [Contributing](/contributing) and [Detector rules](/detector-rules).

## Test runner

Entry points:

```bash
bun run test                          # default suites
node scripts/run-tests.mjs --list     # suite inventory
node scripts/run-tests.mjs --help
node scripts/run-tests.mjs core live  # named suites
node scripts/run-tests.mjs all        # default + all opt-in
node scripts/run-tests.mjs all-local  # same as default
```

`scripts/run-tests.mjs` expands suite aliases via `expandSuites()` and runs each suite’s command list:

| Runner | Invocation |
|---|---|
| `bun` | `bun test <files…>` |
| `node` | `node --test --test-concurrency=N` (default concurrency **4**), optional `--test-timeout` / `--test-force-exit` |

Some commands inject env (for example `IMPECCABLE_CLI_REMOTE_E2E=1` for remote CLI E2E).

## Default suites

`DEFAULT_SUITES` = `core`, `detector`, `live`, `framework`, `plugin-e2e`.

These run for `bun run test` and the `default` / `all-local` aliases.

| Suite | npm script | Description | Special needs |
|---|---|---|---|
| `core` | `test:core` | Build, transformers, CLI helpers, context, hooks, pin, doctor, release, storage unit tests (Bun + Node file lists) | — |
| `detector` | `test:detector` | Text, jsdom fixtures, Puppeteer browser paths, extension build | Puppeteer Chrome (`needsPuppeteer`) |
| `live` | `test:live` | Fast live-mode unit + local-server tests (not full browser fixture sweeps) | — |
| `framework` | `test:framework` | Static framework-fixture coverage (inject, CSP, wrap, generated-file detection) | — |
| `plugin-e2e` | `test:plugin-e2e` | Install committed `./plugin` into sandboxed Claude Code; assert skills, agents, hooks via `claude plugin details` | `claude` on PATH (else skip); 300s timeout |

**Plugin E2E contract:** unit guards in `validate-plugin-manifest` pin known loader keys; the real-CLI suite catches loader surprises (for example a declared `agents` key that loaded zero agents). Isolation sets `CLAUDE_CONFIG_DIR` / `HOME` into a temp dir so the developer’s real config is never touched.

## Opt-in suites

`OPT_IN_SUITES` (not in the default local `bun run test` sweep unless you pass `all` or name them):

| Suite | npm script | Description | Cost / deps |
|---|---|---|---|
| `cli-remote-e2e` | `test:cli-remote-e2e` | Install/update smoke against impeccable.style | Network |
| `live-e2e` | `test:live-e2e` | Playwright full live cycle across framework fixtures with a deterministic fake agent | ~2 min; real `npm install` per fixture; Playwright Chromium |
| `live-e2e-accept-cleanup` | `test:live-e2e-accept-cleanup` | Provider-backed post-accept cleanup regression | Bills a provider key; Playwright |
| `new-work-e2e` | `test:new-work-e2e` | Playwright offline smoke for concept/serve-question decision UI + fake image generator | Playwright; no API cost |
| `skill-behavior` | `test:skill-behavior` | LLM-backed Setup / routing scenarios against real models | ~5 min; keys in `.env`; bills providers |
| `live-svelte-adapter-deepseek` | `test:live-svelte-adapter-deepseek` | DeepSeek-backed Svelte adapter browser sweep | DeepSeek + Playwright; long timeout |

Additional named suites (not default, not in `OPT_IN_SUITES` expand list for `all` unless listed): `cli-e2e` (local universal-bundle CLI tests), `live-e2e-agent` (insert-mode fake-agent helpers).

### Suite trigger mapping (what change owes which suite)

Canonical triggers live in `scripts/test-suites.mjs` (`triggers` regexes). Every suite also self-triggers when one of its own test files changes.

| Area changed | Suite(s) to run |
|---|---|
| `scripts/` (except detector/extension builders), `skill/SKILL.src.md`, skill scripts/refs, `cli/bin/`, READMEs | `core` |
| `cli/engine/`, `extension/`, detector fixtures, `build-browser-detector` / `build-extension` | `detector` (+ rebuild browser/extension) |
| `skill/scripts/live*`, `skill/reference/live.md`, `tests/live-*` | `live` |
| `tests/framework-fixtures/**`, inject/wrap/CSP helpers | `framework` |
| `plugin/`, `skill/agents/`, `scripts/build.js`, plugin manifest validator | `plugin-e2e` |
| `skill/scripts/live/**`, runtime fixtures, `tests/live-e2e*` | `live-e2e` |
| `live-accept` / `live-browser` / `live-server` / `live-wrap` / SvelteKit adapter | also `live-e2e-accept-cleanup` when verifying accept cleanup |
| `live/sveltekit-adapter.mjs`, `live/svelte-component.mjs` | `live-svelte-adapter-deepseek` |
| `SKILL.src.md` Setup, `context.mjs`, Setup-adjacent refs | `skill-behavior` |
| `serve-question.mjs`, `generate-image.mjs`, `concept-seed.mjs` | `new-work-e2e` |
| `cli/bin/commands/skills.mjs` | `cli-remote-e2e` |

Common infra paths (`package.json`, lockfile, `run-tests.mjs`, `test-suites.mjs`, CI workflow) match every suite that lists them.

### Live E2E controls

```bash
bun run test:live-e2e
IMPECCABLE_E2E_ONLY=vite8-react-modal bun run test:live-e2e
IMPECCABLE_E2E_DEBUG=1 bun run test:live-e2e
IMPECCABLE_E2E_AGENT=llm bun run test:live-e2e   # optional real-model agent; costs money
```

| Env var | Role |
|---|---|
| `IMPECCABLE_E2E_ONLY` | Comma-separated fixture names |
| `IMPECCABLE_E2E_SCENARIOS` | Scenario filter (CI smoke uses `core`) |
| `IMPECCABLE_E2E_DEBUG` | Dump page DOM + dev-server tail on failure |
| `IMPECCABLE_E2E_AGENT` | `fake` (default) or `llm` |
| `IMPECCABLE_E2E_LLM_PROVIDER` / `IMPECCABLE_E2E_LLM_MODEL` | LLM agent selection |
| `IMPECCABLE_E2E_TEST_TIMEOUT_MS` | Per-test timeout override |
| `IMPECCABLE_E2E_ARTIFACT_DIR` | Failure artifact root |

Fixtures with a `runtime` block under `tests/framework-fixtures/` install deps, boot a real framework server, and drive Playwright. Schema notes: `tests/framework-fixtures/README.md`.

### Skill-behavior controls

```bash
bun run test:skill-behavior
IMPECCABLE_SKILL_BEHAVIOR_MODELS=claude-sonnet-5 bun run test:skill-behavior
IMPECCABLE_SKILL_BEHAVIOR_VERBOSE=1 bun run test:skill-behavior
```

Default models (`tests/skill-behavior/providers.mjs`): `claude-sonnet-5`, `gpt-5.6-luna`, `gemini-3.5-flash`, `deepseek-v4-flash`. Missing keys skip that provider cleanly. Assertions key on the tool-call **trace** (context load, reference files, writes), not free-form prose. Scenario baseline tables: `tests/skill-behavior/README.md`.

## CI selection

`.github/workflows/ci.yml` + `scripts/ci-test-plan.mjs`:

| Event | Plan behavior |
|---|---|
| **push / workflow_dispatch** | Force deterministic suites; opt-ins mainly via dispatch or path triggers |
| **pull_request** | Path-triggered suites via `matchesSuiteTriggers` against the PR diff |
| **schedule (nightly)** | Full `live_e2e` matrix; deliberately **does not** enable billed opt-ins (`skill_behavior`, accept-cleanup, deepseek) |

Local without `GITHUB_EVENT_NAME` / `CI_CHANGED_FILES`: plan treats as “no changes” and forces deterministic suite selection for summary purposes.

CI always runs `test:core` and `bun run build` on the Node matrix. Detector / live / framework jobs are conditional on the plan. Detector path also runs `build:browser`, `build:extension`, and `web-ext` lint for the Firefox package. Opt-in jobs include remote CLI E2E, live-e2e smoke groups (fixture subsets), full live-e2e on schedule/dispatch, skill-behavior, accept-cleanup, and DeepSeek Svelte adapter when selected.

## Contributor workflow

<Steps>
  <Step title="Edit source, not harness output">
    Change `skill/`, `scripts/`, `cli/`, `extension/`, or `tests/`. Do not hand-edit generated provider trees under `.claude/skills/` (and siblings) unless the task is a release or build-system sync.
  </Step>
  <Step title="Validate with source-first build">
    Run `bun run build` after skill, transformer, or count-affecting edits. Fix prose, version, and count failures before iterating on tests.
  </Step>
  <Step title="Rebuild detector surfaces when rules change">
    Run `bun run build:browser` and `bun run build:extension`, then `bun run test:detector`.
  </Step>
  <Step title="Run the default suite">
    Run `bun run test` (or scoped `test:core` / `test:live` / …). Include `test:plugin-e2e` when touching `plugin/` or the build’s plugin assembly (already part of default).
  </Step>
  <Step title="Run owed opt-in suites">
    Match the trigger table: live script changes → `test:live-e2e`; Setup/`context.mjs` → `test:skill-behavior`; skills CLI remote path → `test:cli-remote-e2e`.
  </Step>
  <Step title="Release builds only when intentional">
    Use `bun run build:release` when you mean to refresh tracked harness + `plugin/` output. Keep that churn out of ordinary feature PRs.
  </Step>
</Steps>

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Build fails on “stale count” | Router table or `ANTIPATTERNS` count drifted from README / plugin descriptions | Update user-facing counts to match source, or fix the source count claim |
| Build fails on plugin version | Marketplace / `plugin/` / skill frontmatter disagree with `.claude-plugin/plugin.json` | Align versions; run `bun run build:release` when regenerating `plugin/` |
| Build fails on prose / skill prose | Em dash or denylisted phrase | Edit copy per `docs/STYLE.md`; do not bypass the regex |
| Detector tests hang under Bun | jsdom path is slow under Bun | Prefer `node` via `run-tests.mjs` / documented `node --test` paths for fixture suites |
| Live E2E missing browser | Playwright Chromium not installed | `npx playwright install chromium` |
| Plugin E2E skipped | No `claude` CLI | Install Claude Code CLI or accept skip for local runs |
| Skill-behavior all skipped | No provider keys in repo-root `.env` | Set at least one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_CLOUD_API_KEY`, `DEEPSEEK_API_KEY` |
| Unexpected harness diff in CI | Source-first build still regenerated tracked browser/extension outputs, or local dirty harness | Rebuild the surface that owns the file; only stage harness diffs for intentional sync |

## Related pages

<CardGroup>
  <Card title="Contributing" href="/contributing">
    Source-of-truth layout, generated harness policy, anti-pattern TDD order, and component release tags.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Supported harness directories, install aliases, and capability matrix for generated skills.
  </Card>
  <Card title="Plugin agents" href="/plugin-agents">
    Bundled agents, plugin manifest contract, and hooks packaged for Claude Code / Grok installs.
  </Card>
  <Card title="Live framework recipes" href="/live-framework-recipes">
    Fixture layouts and live config shapes exercised by framework and live-e2e suites.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule registry, engines, and finding shape that browser and extension builds package.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Detect and install CLI surfaces validated by core and CLI E2E suites.
  </Card>
</CardGroup>

---

## 24. Contributing

> Source-of-truth layout under skill/, generated harness policy, issue-first PR rules, anti-pattern TDD order, and component release tags (skill-v, cli-v, ext-v).

- Page Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/pages/24-contributing.md
- Generated: 2026-08-05T07:39:45.563Z

### Source Files

- `docs/DEVELOP.md`
- `AGENTS.md`
- `scripts/release.mjs`
- `scripts/lib/transformers/providers.js`
- `cli/engine/registry/antipatterns.mjs`
- `docs/STYLE.md`
- `scripts/lib/validate-plugin-manifest.js`

---
title: "Contributing"
description: "Source-of-truth layout under skill/, generated harness policy, issue-first PR rules, anti-pattern TDD order, and component release tags (skill-v, cli-v, ext-v)."
---

Contributions edit **source** under `skill/`, `scripts/`, `cli/`, `extension/`, and `tests/`. Provider harness trees (`.claude/skills/`, `.cursor/skills/`, `plugin/`, and peers) and browser/extension detector bundles are **generated** and must not be hand-authored in ordinary feature work. Outside contributors are issue-first: open or comment on an issue and wait for maintainer direction before a PR.

## Prerequisites

| Requirement | Detail |
|---|---|
| Runtime | [Bun](https://bun.sh) for build and most tests; Node `>=22.18.0` for CLI packaging |
| Edit surface | Source dirs only (see layout below) |
| Validation | `bun run build` after skill/transformer/count changes; `bun run test` before proposing a merge |
| Issue approval | Required for contributors who are not maintainers `pbakaus` or `abdulwahabone` |

No extra package install is required beyond the repo’s Bun/Node tooling for day-to-day skill and CLI work.

## Source-of-truth layout

```text
impeccable/
  skill/                     # Author here
    SKILL.src.md             # Frontmatter, shared design laws, command router
    reference/               # One <command>.md (+ optional .native.md)
    scripts/                 # context.mjs, live-*, hooks, pin, doctor, …
    agents/                  # Nested agent definitions (documenter, finish-reviewer, …)
  scripts/                   # Build, release, transformers, validators
    build.js
    release.mjs
    lib/transformers/providers.js
    lib/validate-plugin-manifest.js
  cli/                       # npm package `impeccable` + detector engine
    engine/
      registry/antipatterns.mjs
      rules/checks.mjs
      engines/static-html/
      browser/injected/
  extension/                 # Chrome extension source
  tests/                     # Bun + Node suites, fixtures
  plugin/                    # Generated Claude Code plugin (tracked)
  dist/                      # Generated provider output (gitignored)
  .claude/ .cursor/ …        # Generated harness trees (tracked)
```

| Path | Role | Edit? |
|---|---|---|
| `skill/**` | Skill text, references, runtime scripts, agents | Yes (primary) |
| `scripts/**` | Build factory, providers map, release, gates | Yes |
| `cli/**` | CLI, detector registry/rules/engines | Yes |
| `extension/**` | Extension UI and manifest source | Yes |
| `tests/**` | Fixtures and suites | Yes |
| Root harness dirs + `plugin/` | Distribution for GitHub / `npx skills` / marketplace | No (regenerate) |
| `dist/`, `build/` | Intermediate build output | No (gitignored) |

As of the v4 product split, the **public** repo is skill + CLI + extension + build. Site, labs, catalog data, and Cloudflare Functions live in the private `pbakaus/impeccable-site` checkout (typically `../impeccable-site`). Do not re-add catalog data files to this repo.

## Generated harness policy

Provider transforms are config-driven from `scripts/lib/transformers/providers.js` (`PROVIDERS`). Each entry names `configDir` (for example `.claude`, `.cursor`, `.grok`), frontmatter fields, optional hooks emit mode, and agent format.

| Build command | What it does |
|---|---|
| `bun run build` | Source-first: regenerates `dist/` and runs validators; **does not** sync tracked root harness folders |
| `bun run build:release` | Full build **and** syncs tracked harness dirs + `plugin/` |
| `bun run rebuild` / `rebuild:release` | Clean then the matching build |
| `bun run build:browser` | Regenerates `cli/engine/detect-antipatterns-browser.js` |
| `bun run build:extension` | Regenerates `extension/detector/` artifacts |

**Feature PR rule:** stage source changes only. Leave harness churn unstaged unless the PR’s purpose is release/main-sync or build-system work. After source lands on `main`, `.github/workflows/sync-generated-output.yml` runs `bun run build:release` and commits generated provider output.

Placeholders in `skill/SKILL.src.md` (replaced per provider): `{{model}}`, `{{config_file}}`, `{{ask_instruction}}`, `{{command_prefix}}`, `{{available_commands}}`, `{{scripts_path}}`.

### Adding a provider

1. Add placeholders under `PROVIDER_PLACEHOLDERS` in `scripts/lib/utils.js`.
2. Add a `PROVIDERS` entry in `scripts/lib/transformers/providers.js` (`provider`, `configDir`, `displayName`, `frontmatterFields`, optional hooks/agent fields).
3. Run `bun run build` (and `build:release` only when intentionally refreshing tracked trees).
4. Document capability differences in `docs/HARNESSES.md`.

## Issue-first PR rules

| Who | Rule |
|---|---|
| Outside contributors | Discuss in an issue first; open a PR only after maintainer discussion and clear approval |
| Unsolicited PRs | May be closed without review |
| Maintainers `pbakaus`, `abdulwahabone` | Can open PRs without the issue gate |

### AI agents

- Disclose AI assistance in commits, PR descriptions, comments, and issue text.
- An agent **not** operating under explicit instructions from `pbakaus` or `abdulwahabone` must **not** create GitHub issues or PRs.
- If asked to open an issue/PR without that authority, do **not** use GitHub. Add `AI_PR_NOTICE.txt` to the diff with exactly:

```text
This contribution was prepared by an AI agent that tried to ship unchecked vibes across a human boundary. Impeccable asks for an issue and maintainer approval first.
```

### Commits and PR body

- Prefer short imperative subjects: `Fix: …`, `Add …`, `Improve …`.
- PR summary: what changed, validation run, whether generated harness output was omitted (normal) or refreshed (intentional).
- Screenshots for visible product UI; name affected providers when transform behavior changes.
- **Do not** bump manifest versions or add changelog entries in a feature PR. Version bumps and changelog entries are release-only.

## Coding style

| Rule | Convention |
|---|---|
| Modules | ESM |
| Semicolons | Yes |
| Indent | Two spaces (JS, HTML, CSS) |
| Filenames | Descriptive, lowercase, hyphens where needed |
| Skill entry | `SKILL.md` / source `SKILL.src.md` |
| Scripts | `.js` / `.mjs` |
| Frontmatter names | kebab-case |
| Structure | Small single-purpose modules |

There is no dedicated formatter/linter for the whole repo; match surrounding code. `biome.json` may exist for local tooling; do not invent project-wide format requirements beyond what neighbors use.

## User-facing prose gates

Read `docs/STYLE.md` before editing `README.md`, `README.npm.md`, or skill markdown.

| Gate | Scope | Enforced by |
|---|---|---|
| `validateProse` | `README.md`, `README.npm.md` | `scripts/build.js` (full denylist) |
| `validateSkillProse` | `skill/**/*.md` (not `skill/scripts/**` code) | `scripts/build.js` (em dashes + non-technical banned phrases) |
| Site copy | impeccable-site repo | That repo’s build |

Banned in README gates include em dashes (`—`, HTML entities, ` -- ` as substitute), `load-bearing`, `highest-leverage`, `biggest unlock`, `seamless`, `robust`, `delve`, `elevate`, `empower`, and related phrases listed in `docs/STYLE.md`. Do not work around the regex; amend `docs/STYLE.md` if a term has a real local meaning. An em dash in `skill/reference/*.md` fails `bun run build`; the same character in a `.mjs` comment does not.

## Plugin manifest contract

Marketplace install uses the committed `plugin/` subtree. `scripts/lib/validate-plugin-manifest.js` pins the verified Claude Code loader contract:

| Constraint | Detail |
|---|---|
| Allowed keys | `KNOWN_LOADER_KEYS`: `name`, `description`, `version`, `author`, `homepage`, `repository`, `skills` |
| No `agents` key | Omission only; an `agents` array path loads zero agents (PR #494 lesson) |
| `skills` path | Trailing-slash form `./skills/` (bare form fails slash-command registration) |
| Agent files | Emitted `plugin/agents/*.md` must match source agents that ship for `claude-code` |

Unit coverage: `tests/validate-plugin-manifest.test.js`. Live loader inventory: `bun run test:plugin-e2e` (skips if `claude` CLI is absent). Never add a new component key to the plugin manifest without a real install + `claude plugin details` check.

## Anti-pattern rules (TDD order)

Detector source is modular under `cli/engine/`:

| Piece | Location |
|---|---|
| Rule registry | `cli/engine/registry/antipatterns.mjs` (`id`, `category` = `slop` \| `quality`, `name`, `description`, optional `skillSection` / `skillGuideline` / `scopes`) |
| Pure checks + adapters | `cli/engine/rules/checks.mjs` |
| jsdom loop | `cli/engine/engines/static-html/detect-html.mjs` |
| Browser loop | `cli/engine/browser/injected/index.mjs` → `bun run build:browser` |
| Facade | `cli/engine/detect-antipatterns.mjs` |
| Extension artifacts | `bun run build:extension` → `extension/detector/` |

TDD order is non-negotiable:

<Steps>
  <Step title="Fixture">
    Add `tests/fixtures/antipatterns/{rule-id}.html` with two columns (should-flag / should-pass). ≥4 flag cases and ≥5 false-positive shapes. Identify each case with a unique heading. Use **explicit pixel dimensions** in CSS; jsdom does not layout.
  </Step>
  <Step title="Failing test">
    Extend `tests/detect-antipatterns-fixtures.test.mjs` with snippet-substring lists (`SHOULD_FLAG` / `SHOULD_PASS`, regex `/"([^"]+)"/`). Run and confirm failure before implementing.
  </Step>
  <Step title="Registry entry">
    Append to `ANTIPATTERNS` in `cli/engine/registry/antipatterns.mjs`.
  </Step>
  <Step title="Pure check">
    Implement `checkXxx(opts)` returning `[{ id, snippet }]`. No DOM access inside the pure function.
  </Step>
  <Step title="Dual adapters and dual loops">
    Browser: `checkElementXxxDOM(el)` via `getComputedStyle` / `getBoundingClientRect`. jsdom: `checkElementXxx(el, tag, window)` via `parseFloat(style.width)` (and similar). Wire **both** into **both** element loops. Forgetting one loop is the common failure mode (“tests pass, live page silent” or the reverse).
  </Step>
  <Step title="Builds and verify">
    Run `bun run build && bun run build:browser && bun run build:extension && bun run test`. Spot-check the fixture page and homepage for false positives.
  </Step>
</Steps>

**Snippet convention:** wrap identifying heading text in straight double quotes so fixture tests can extract it. Prefer helpers `resolveBackground()`, `resolveGradientStops()`, and `parseGradientColors()` for jsdom background/color quirks. Copy patterns from existing rules such as `side-tab`, `low-contrast`, `icon-tile-stack`, `flat-type-hierarchy`, `kicker-above-heading`.

Run the jsdom fixture suite with **Node** (`node --test tests/detect-antipatterns-fixtures.test.mjs` or via `bun run test`), not a direct `bun test` on that file (can time out).

## Adding a design sub-command

All user design commands remain under the single skill `/impeccable` (do not add standalone skills without a strong reason). Checklist:

1. `skill/reference/<command>.md` (and `.native.md` only if web/native divergence requires it).
2. Sub-command row + command menu entry in `skill/SKILL.src.md`.
3. Name in `IMPECCABLE_SUB_COMMANDS` (`scripts/lib/utils.js`).
4. `VALID_COMMANDS` in `skill/scripts/pin.mjs`.
5. Metadata in `skill/scripts/command-metadata.json`.
6. Category in `scripts/lib/skill-categories.js`.
7. Private impeccable-site: relationships, counts, optional editorial pages.
8. Update documented command counts in `README.md`, plugin descriptions, and related surfaces when the total changes (`generateCounts` in `scripts/build.js` fails on drift).

Utility commands such as `doctor`, `hooks`, and `pin` follow the lightweight reference pattern and are **not** counted in the design command total.

## Component releases (`skill-v`, `cli-v`, `ext-v`)

Three components ship independently. Feature PRs never bump versions.

| Component | Manifest(s) | Tag prefix | Changelog label | Release script | Artifacts / next step |
|---|---|---|---|---|---|
| Skill | `.claude-plugin/plugin.json` + `marketplace.json` | `skill-v` | bare `vX.Y.Z` | `bun run release:skill` | `dist/universal.zip`; site must redeploy for `npx impeccable update` |
| CLI | `package.json` | `cli-v` | `CLI vX.Y.Z` | `bun run release:cli` | Then `npm publish` |
| Extension | `extension/manifest.json` | `ext-v` | `Extension vX.Y.Z` | `bun run release:ext` | `dist/extension.zip` (+ Firefox zip); upload to stores |

Release flow (maintainers):

1. Bump only the component that changed; keep skill marketplace sibling versions in lockstep.
2. Add a changelog entry in impeccable-site `site/pages/changelog.astro` (or sibling checkout path the script searches). Entry markup uses `<span class="cf-version">…</span>` and `<ul class="cf-items">`. User-facing items only; move `cf-entry--current` onto the newest skill entry when applicable.
3. Commit, push to origin so HEAD matches remote.
4. Preview: `node scripts/release.mjs <skill|cli|extension> --dry-run`.
5. Publish: `bun run release:skill` | `release:cli` | `release:ext`.

`scripts/release.mjs` **refuses** when:

- Working tree is dirty
- HEAD is not pushed to `origin`
- Tag already exists locally or on origin
- Changelog header for that label+version is missing
- Skill/extension rebuild (`build:release` / `build:extension`) produces uncommitted diff

Post-release: skill path checks `https://impeccable.style/api/version` and warns if the site still serves an older skills version; CLI and extension print their publish/upload reminders. Fix shipped notes with `gh release edit <tag> --notes-file <md>`.

## Local validation matrix

| Change area | Minimum validation |
|---|---|
| `skill/`, transformers, counts | `bun run build` |
| Rule engine | fixture test + `build:browser` + `build:extension` + `bun run test` |
| `skill/scripts/live-*`, `live/**` | `bun run test:live-e2e` (opt-in; Playwright Chromium) |
| Setup / `context.mjs` / Setup refs | `bun run test:skill-behavior` (opt-in; provider keys in `.env`) |
| `plugin/`, agents, build plugin path | `bun run test:plugin-e2e` (in default suite when `claude` present) |
| Default CI-local bar | `bun run test` |

Canonical suite → path mapping lives in `scripts/test-suites.mjs`. Prefer targeted runs while iterating, then full default suite.

### Sandbox gotchas (agent environments)

- `build:release` rewriting harness trees can hit sandbox filesystem errors (`EFAULT`); rerun outside the sandbox.
- Puppeteer/Chrome browser detector tests can hang in sandbox; run outside for authoritative results.
- GitHub SSH / 1Password agent operations may need a non-sandbox shell.

## Related pages

<CardGroup>
  <Card title="Build and test" href="/build-and-test">
    Source-first vs release builds, default and opt-in suites, suite trigger mapping.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Registry ids, slop vs quality, engines, and finding shape.
  </Card>
  <Card title="Provider harnesses" href="/provider-harnesses">
    Harness directories, frontmatter matrix, and install aliases.
  </Card>
  <Card title="Plugin agents" href="/plugin-agents">
    Bundled agents, plugin manifest contract, and packaged hooks.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    detect, install, update, and other CLI surfaces used after you ship a change.
  </Card>
</CardGroup>

---