/impeccable (CHAT ONLY)
Why use it: a shared design vocabulary with the agent — audit, critique, polish, harden... — instead of describing everything from scratch each time.
What it produces: code changes in the project, plus artifacts under .impeccable/ (PRODUCT.md, DESIGN.md, surfaces/*.md, critique/*.md).
⚠️ Everything in this file is typed into an AI agent's CHAT, NOT a terminal. The CLI deliberately rejects it:
$ npx impeccable init "init" is not a CLI command. Type /impeccable init in your AI coding agent's chat ... (rc 1)Shell commands are in
01–04. Do not mix the two types.
Start with: /impeccable init (once per project)
/impeccable init
init inspects the project, asks about only genuine gaps in durable product context, and writes PRODUCT.md (users, purpose, operating context, constraints, tone, evidence). If code already exists, it also proposes DESIGN.md (colors, typography, components). It also configures live mode in advance and writes buildPath into .impeccable/config.json.
Every other command reads these two files before working. Skipping init makes all subsequent commands guess the context.
buildPath has two values:
| Value | Meaning |
|---|---|
"comp" |
Generate a full-fidelity comp first, then build to match. Bolder and slower. |
"code" |
Build directly in code, recording the ambition in the surface brief's direction contract. Leaner and faster. |
{ "buildPath": "comp" }
Override it on one machine with .impeccable/config.local.json (for example, if your harness lacks image generation). No need to rerun init to change it: each decision page has a footer toggle, and switching it binds the choice for that session.
23 commands
Counts and descriptions come from plugin/skills/impeccable/scripts/command-metadata.json, rather than from the README table.
Setup and context
| Command | Arguments | What it does |
|---|---|---|
/impeccable init |
— | One-time setup: PRODUCT.md, live configuration, and suggested next steps |
/impeccable document |
— | Generate DESIGN.md from existing code (colors, type, spacing, radii, components), in Google Stitch format |
/impeccable extract |
[target] |
Collect repeated patterns/components/tokens into a design system |
/impeccable shape |
[feature] |
Plan UX/UI before writing code, with multiple interview rounds |
Review and assessment
| Command | Arguments | What it does |
|---|---|---|
/impeccable critique |
[area] |
UX review: hierarchy, information architecture, cognitive load, and emotional resonance |
/impeccable audit |
[area] |
Technical audit: a11y, performance, theming, responsiveness, and anti-patterns. Produces a scored report with P0–P3 priorities |
Fixing and finishing
| Command | Arguments | What it does |
|---|---|---|
/impeccable polish |
[target] |
Final pass: alignment, spacing, consistency, and micro-details |
/impeccable harden |
[target] |
Production readiness: error handling, i18n, text overflow, and edge cases |
/impeccable clarify |
[target] |
Fix UX copy, error messages, microcopy, and labels |
/impeccable optimize |
[target] |
Diagnose and fix UI performance: loading, rendering, and animation |
/impeccable adapt |
[target] [context] |
Responsiveness: breakpoints, flexible layouts, and touch targets |
Aesthetic direction
| Command | Arguments | What it does |
|---|---|---|
/impeccable bolder |
[target] |
Make a safe or bland design more interesting |
/impeccable quieter |
[target] |
Tone down an overly intense design while retaining its intent |
/impeccable distill |
[target] |
Strip it to its core and remove needless complexity |
/impeccable delight |
[target] |
Add moments of delight and personality |
/impeccable overdrive |
[target] |
Push beyond common limits with ambitious techniques |
Specific domains
| Command | Arguments | What it does |
|---|---|---|
/impeccable typeset |
[target] |
Fonts, hierarchy, sizes, weights, and readability |
/impeccable layout |
[target] |
Layout, spacing, and visual rhythm; fix monotonous grids |
/impeccable colorize |
[target] |
Add color strategically to an overly monochrome interface |
/impeccable animate |
[target] |
Purposeful motion and micro-interactions |
/impeccable onboard |
[target] |
Onboarding, first-run flows, and empty states |
Special modes
| Command | Arguments | What it does |
|---|---|---|
/impeccable live |
— | Select an element in the browser, generate HTML+CSS variants, and hot-swap through HMR |
/impeccable craft |
[mô tả] |
Deprecated: compatibility alias for an ordinary new-work request. Adds no behavior |
How to invoke
Most commands accept an optional argument to limit their scope:
/impeccable audit blog # audit trang hub + trang bài blog
/impeccable critique landing # review UX trang landing
/impeccable polish settings # pass cuối trước khi ship
/impeccable harden checkout # error handling + edge case
Or describe the task directly, without a subcommand:
/impeccable làm lại khối hero này
Type /impeccable alone to have the agent list all commands.
Codex uses skills rather than /prompts: — open /skills or type $impeccable. The repository-local installation is at .agents/skills/, and the user-wide installation is at ~/.agents/skills/. GitHub Copilot uses .github/skills/. If a newly installed skill does not appear, restart the tool.
Pin frequently used commands
/impeccable pin audit → tạo shortcut /audit
/impeccable unpin audit
Executed by scripts/pin.mjs in the skill installation.
/impeccable live — requirements for running it
Live mode runs only with a running dev server with HMR (Vite, Next.js, Bun...), or a static HTML file open in a browser.
The connection is recorded in .impeccable/live/config.json (this file is committed). This is the actual file from the Impeccable repository:
{
"files": ["site/layouts/Base.astro"],
"insertBefore": "</body>",
"commentSyntax": "html",
"cspChecked": true
}
The loop (from reference/live.md): the agent boots live.mjs → you open the app URL → the agent polls with live-poll.mjs (a long timeout, 600000 ms) → you select an element and action in the overlay → the agent generates variants → you accept/discard.
A few things to know:
- Do not open the URL of
serverPort. That is the helper's port, not the app. Open the actual app URL servingpageFile. - The Impeccable symbol on the overlay bar dims with a flashing amber dot when no one is polling
/poll— the loop is broken and polling needs to restart. - If interrupted, do not guess. The journal under
.impeccable/live/sessions/is the source of truth; the agent runslive-status.mjsorlive-resume.mjsto replay unacknowledged work. - Behavior differs by harness: Claude Code polls as a background task; Cursor uses one-shot polling in a background terminal (do not use
--stream); Codex uses foreground polling that has yielded.
The end-to-end live flow was not actually run in this survey (it requires a dev server and a real harness); the account above was read from plugin/skills/impeccable/reference/live.md and scripts/live*.mjs.
Self-diagnosis
node .claude/skills/impeccable/scripts/doctor.mjs # báo cáo cho người đọc
node .claude/skills/impeccable/scripts/doctor.mjs --json # cho lệnh trong skill
node .claude/skills/impeccable/scripts/doctor.mjs --fix # chỉ áp các migration máy móc
doctor scans for Impeccable artifact drift in the project: git drift, per-workspace sweeps, ignore-list checks against the current rule registry, and hook script resolution. --fix is deliberately narrow — it runs only automigrations that need no judgment. A finding is not an error: the exit code is 0 unless the run itself fails.