# Overview

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

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## 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>