claude-foundations/claude/impeccable.md

Impeccable — design skill: install, maintenance, usage

Impeccable (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:

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:

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:

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)

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).