# Quickstart

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

- 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

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