Hooks

The detector rules run in two tiers. The per-edit hook surfaces only the immediate tier: mechanical, unambiguous problems worth interrupting an edit for, such as broken images, overflowing or clipped content, contrast and legibility failures, gradient text, glow shadows, and design-system drift. Everything else (copy cadence, palette and typography taste, layout rhythm) is deferred to a deep pass on the Stop hook event, which runs the full rule set over every UI file touched in the session and surfaces the remaining findings once, deduplicated against what the per-edit pass already reported. A session with nothing left to report stops silently. Set hook.perEditRules to "all" in .impeccable/config.json to restore the full rule set on every edit. The Stop deep pass is wired for Claude Code, Codex, and Grok Build, which dispatch a native Stop hook event. Cursor does not get one (its stop hook is not consistently dispatched; the pre-write gate covers it), and GitHub Copilot’s stop-style events do not feed context back to the model, so they keep the full detector per edit. Grok also fires an observe-only Stop with reason: "shutdown" after end_turn; skip that one, scan only end_turn.

Every hook is a mechanical pass. The reflexes no scanner catches live in craft-floor.md, which the skill loads before it edits UI, so they apply whether or not a hook is wired. A session with no automatic hook gets one MANUAL_DETECTOR_REQUIRED directive from impeccable context asking for a single detector run at the end.

This command toggles the hook per project by editing .impeccable/config.json (the unified Impeccable config; hook runtime settings live under its hook key, and shared detector ignores live under detector). Per-developer overrides, including the install consent decision (hook.consent) the CLI records, live in the gitignored .impeccable/config.local.json. Set hook.enabled: false to turn the hook off, hook.quiet: true to silence the clean/pending acks, or hook.auditLog to a file path for an NDJSON log. The legacy IMPECCABLE_HOOK_DISABLED, IMPECCABLE_HOOK_QUIET, and IMPECCABLE_HOOK_LOG env vars are still honored and override these config values when set.

Declare server-side template extensions under detector.extensions when the project uses Blade, Twig, ERB, or Handlebars files; the hook skips them otherwise because they sit outside the built-in extension list. One entry per extension, { "ext": ".blade.php", "engine": "html" }. engine picks the analyzer (html for markup templates, text for JS/TS/CSS-like files) and defaults to html. Match against the end of the filename, so double extensions like .blade.php and .html.erb work. Config only adds extensions; the built-in list always applies.

Manual npx impeccable detect scans use the same project filter config by default: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled. hook.enabled only controls automatic hook execution, not manual CLI scans. Use npx impeccable detect --no-config ... for a raw detector run that ignores project config/context. Use npx impeccable ignores ... for direct CLI CRUD on the same detector ignores.

Supported harnesses: Claude Code (.claude/settings.local.json in the project, which is gitignored so the hook stays machine-local; a hook you move into the shared settings.json is honored in place too), Codex (.codex/hooks.json in the project), Cursor (.cursor/hooks.json in the project), Grok Build (.grok/hooks/impeccable.json in the project; requires /hooks-trust or --trust), and GitHub Copilot (.github/hooks/impeccable.json in the project, a team-shared committed file that both the Copilot CLI and the cloud agent read). For the Copilot CLI, repo-level hooks fire once .github/hooks/impeccable.json is committed to the repository’s default branch.

On Cursor, preToolUse checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.

Routing

The first argument is the action. Defaults to status.

Flow

1. Resolve the action from the user’s argument. If no action was given, default to status.

2. Invoke the admin script and pass the user’s output through verbatim:

   bashCopy

   "<skill-base-dir>/scripts/impeccable" hooks <action> [args...]

3. If <action> is off, follow up with a one-line note: “Done. New edits will not trigger the design hook in this project until you run /impeccable hooks on.”

4. If <action> is on, follow up with: “Done. The design hook will fire after the next Edit/Write on a UI file.”

5. If <action> is ignore-value, ignore-file, or ignore-rule, just print the script output. The default scope is shared .impeccable/config.json; add --local only when the user explicitly asks for a private exception.

6. If <action> is status, just print the script output. Do not add commentary unless the user asked a follow-up question.

Triage findings

The hook itself never writes ignore config; every exception goes through impeccable hooks. Triage each finding into one of three outcomes:

• Real design problem: fix it. Never add an ignore to skip a fix or to push a blocked write through.
• Confident false positive or sanctioned exception: persist the narrowest ignore yourself and disclose it in your reply. The bar is evidence you can name: an intentional demo or fixture, documentation of bad design, literal or domain-appropriate motion (a ball that bounces), or a choice the user already confirmed. Put that evidence in --reason as "<who decided: evidence>"; write “user confirmed” only when the user actually did.
• Unsure: leave the finding standing and ask the user in one line. Ask once; a one-line question costs less than the hook re-firing on every later edit.

Self-serve stops at ignore-value. ignore-file and ignore-rule silence too much to add on your own judgment; ask the user first.

Prefer the narrowest exception:

• If the finding line shows an ignore-value <rule> <value> pair, pass it to impeccable hooks ignore-value with your --reason. This writes shared .impeccable/config.json by default.
• For value-specific findings such as overused-font and bounce-easing, use ignore-value for the specific value. Do not use ignore-rule overused-font for a specific font.
• If the finding has no value-specific command, such as side-tab, scope that one rule to the file: ignore-value <id> "*" --file <path>. Run npx impeccable detect <path> first to see what actually fires there.
• Reach for ignore-file <path> only when the whole file is out of scope for design review: a fixture, a generated artifact, a deliberate slop demo. It silences every rule for that file permanently, including rules that have not been written yet. A real UI surface with one noisy rule wants the file-scoped value ignore above.
• Use ignore-rule <id> only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use ignore-rule overused-font --all-values only when the user asks to ignore overused fonts generally.
• Prefer config ignores (the commands above) by default; they keep suppressions in one reviewable place. Reach for an inline comment only when the waiver must travel with a single file that leaves the repo (a generated/exported standalone document, an emailed HTML file). The supported marker is impeccable-disable <rule> (whole file) or impeccable-disable-line / impeccable-disable-next-line (one line), in any comment syntax, with an optional reason after : or --. The detector honors it by default; --no-inline-ignores or --no-config bypasses it.

Example value-specific exception:

Example self-served exception, with the evidence named:

Example whole-rule font exception:

Example one-rule-in-one-file exception, for a file that is still worth reviewing for everything else:

Example whole-file exception, for a file that is out of scope entirely:

Constraints

• Never modify .impeccable/config.json or .impeccable/config.local.json by hand from this command. Always go through impeccable hooks so writes stay validated and the file shape stays consistent. One exception: detector.extensions has no admin action, so when the user asks to cover a template stack, edit that one field in .impeccable/config.json directly and leave the rest of the file untouched.
• Do not edit the launcher or the binary behind impeccable hook and impeccable hook-before-edit from this flow. Those are skill plumbing.
• Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
• The hook is bundled with the Impeccable skill and installed through project-local manifests: .claude/settings.local.json, .codex/hooks.json, .cursor/hooks.json, and .github/hooks/impeccable.json. On Codex, the user must approve the hook via /hooks the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads .github/hooks/impeccable.json once it is committed to the repository’s default branch, and the cloud agent reads it from the repo directly.

Failure modes

• If .impeccable/config.json or .impeccable/config.local.json is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. impeccable hooks status will show malformed files as ignored.
• If the user asks to “disable the hook” globally, lead with /impeccable hooks off (persistent for this project; writes hook.enabled: false to config). The legacy IMPECCABLE_HOOK_DISABLED=1 env var also works as a one-shot override that follows the shell.