# Impeccable — design skill: install, maintenance, usage

[Impeccable](https://impeccable.style/) (GitHub: `pbakaus/impeccable`, Apache 2.0) is a
design vocabulary system for AI agents: 23 design commands, a per-project DESIGN.md
contract, and a deterministic 46-rule anti-slop detector.

## How it is installed here (non-standard — do not "fix")

Two skills in the **user profile** (`~/.claude/skills/`) **and mirrored into every
`~/.claude-*` profile's `skills/` dir** (octopus, octopus-anthropic, oreillyit,
oreillyit-anthropic, oreillyit-minimax — not `-secrets`), deliberately arranged so
the full skill never auto-fires:

| Path | What | Key frontmatter |
|---|---|---|
| `~/.claude/skills/impeccable/` | Full skill (SKILL.md + `reference/` + `scripts/`), copied from repo `.claude/skills/impeccable` | `disable-model-invocation: true` **(added locally — not upstream)** |
| `~/.claude/skills/impeccable-hint/` | Hand-written ~40-line shim carrying Impeccable's original auto-trigger description | `user-invocable: false` |

Rationale: the upstream description is engineered to auto-trigger on almost any
frontend vocabulary, and a full invocation loads ~10–20k tokens (SKILL.md body +
mandatory reference reads). The shim auto-fires instead and merely *suggests*
`/impeccable <command>` to the user (once per session); only the user invokes the
real skill. Idle cost ≈ one description in the skill listing; hint invocation ≈ a few
hundred tokens.

Deliberately **not** installed globally:
- the detector **hook** (`settings.json` → `hook.mjs`) — false-positive-prone on Hugo
  Go-template source (flags `src="{{ … }}"` as broken-image, em-dashes in comments)
- the `impeccable-manual-edit-applier` **agent** — only Live mode uses it, and Live
  mode overlaps hugo-accelerator's editorial widget + branch previews

## Updating to a new upstream version

`npx impeccable install` / the plugin marketplace will NOT maintain this arrangement.
Update manually:

```bash
cd "$(mktemp -d)"
curl -sL https://github.com/pbakaus/impeccable/archive/refs/heads/main.tar.gz | tar xz
rm -rf ~/.claude/skills/impeccable
cp -r impeccable-main/.claude/skills/impeccable ~/.claude/skills/
```

After re-applying the frontmatter edit below, mirror both skill dirs into every
profile:

```bash
for p in ~/.claude-octopus ~/.claude-octopus-anthropic ~/.claude-oreillyit \
         ~/.claude-oreillyit-anthropic ~/.claude-oreillyit-minimax; do
  rm -rf "$p/skills/impeccable" "$p/skills/impeccable-hint"
  cp -r ~/.claude/skills/impeccable ~/.claude/skills/impeccable-hint "$p/skills/"
done
```

Then **re-apply the local edit** — add below `user-invocable: true` in
`~/.claude/skills/impeccable/SKILL.md`:

```yaml
disable-model-invocation: true
```

If upstream's `description:` changed, copy the new text into
`~/.claude/skills/impeccable-hint/SKILL.md` so the shim's trigger surface stays in
sync. If upstream added/renamed commands, refresh the shim's command table.

Installed version: check `version:` in `~/.claude/skills/impeccable/SKILL.md`
(3.9.1 as of 2026-07-22).

## Detector (no skill involvement, plain npx)

```bash
npx impeccable detect <path|url> [--json]        # 46 deterministic rules, no LLM
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
```

- **Output streams:** the human-readable report goes to **stderr**; `--json` goes to
  stdout. In CI, capture with `2>&1 | grep -v 'npm WARN'` — a bare `2>/dev/null`
  silently discards the entire text report.

- Run against **rendered output** (`public/` after a Hugo build), never template
  source — raw Go templates false-positive.
- Staging URLs are Authelia-gated → the detector would score the login page; use a
  local build or port-forward.
- Needs Node ≥ 22.12 per engines; observed working on Node 18 with EBADENGINE
  warnings only. Pin the version in any CI use (no `@latest`).
- Ignores/config live in `.impeccable/config.json` per repo — a template-sync surface
  if adopted fleet-wide (hugo-accelerator `template_consumers.json`).

## Planned integrations (recommendations, 2026-07-22)

- **hugo-ci (M13):** `npx impeccable detect public/ --json` post-render, advisory
  first, gate later.
- **cms-proxy AI edit / M6 drafting:** per-customer DESIGN.md (bootstrap interview or
  `/impeccable document`) injected into the AI edit prompt alongside component schemas.
- **agent-runtimes:** detector as post-task verify step for frontend tasks; full skill
  baked only into design-scoped harness templates (Node 22+ images).