Workflow & Core Tools · pbakaus/impeccable

impeccable

Name: impeccable
Author: pbakaus/impeccable

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author pbakausGitHub pbakaus/impeccable ↗Stars 66816License Apache-2.0（GitHub API spdx Apache-2.0；仓库根 LICENSE 文件为 Apache License Version 2.0, January 2004）Commit cd12f8660e

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Compiled multi-host distribution: skill/ serves as the sole master source (SKILL.src.md + scripts/ + reference/ + agents/). At any given time, the repository contains compiled copies across 20 host directories including .claude/.cursor/.agents/.gemini. These compiled copies expand placeholders ({{scripts_path}}/{{command_hint}}, etc.) into host-specific paths, populate host frontmatter (such as version: 4.3.1, user-invocable, allowed-tools), and strip  consistency comments.

skill/SKILL.src.md

allowed-tools: - Bash(npx impeccable *) - Bash({{scripts_path}}/impeccable *)

Comparing against the first 20 lines of .claude/skills/impeccable/SKILL.md reveals the same section expanded into '.claude/skills/impeccable/scripts/impeccable *' along with 'version: 4.3.1'—a diff confirms both files are verbatim identical aside from placeholder expansions and rule comments.

Session initialization protocol: Every session begins by executing `<skill-base-dir>/scripts/impeccable context` (the launcher is a POSIX shell that locates the self-contained engine binary). The engine reads PRODUCT.md/DESIGN.md/matching surface briefs and feeds instructions (including CONTEXT_STALE and other directives) back to the agent; explicit fallbacks exist if launcher fails—it clearly notifies the user and directly falls back to reading existing PRODUCT.md/DESIGN.md to proceed.

.claude/skills/impeccable/SKILL.md

Run `<skill-base-dir>/scripts/impeccable context` once per session, where `<skill-base-dir>` is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project.

Original fallback protocol: 'On refusal or failure, send a separate message **before the next tool call**: "Context loading did not run; I'll read the existing project context directly."'—launcher failures do not block planning and editing.

The core engine runs on an accompanying binary (not a Node runtime): The launcher resolves the executable sequentially via IMPECCABLE_BIN → sibling directory bin/<os>-<arch>/ → ~/.impeccable/bin → version-pinned cache → impeccable on PATH. As a last resort, it downloads that version's binary from the author's GitHub releases into the user cache with sha256 sidecar verification (fail closed: refuses to run if verification fails or the sidecar is missing).

skill/scripts/impeccable

base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"

Original download clause: 'Last resort: fetch this version's binary for the current platform from the public release channel into the user cache'; Verification clause: 'Fail closed: a freshly downloaded binary runs only after verifying against its .sha256 sidecar.'; Sandboxes without egress can preinstall the binary on PATH (per launcher comments).

Instruction surface covering 23 commands + routing: The core of SKILL.md is a command table (Build/Evaluate/Refine/Enhance/Fix + live iteration). Invocations without parameters surface a context-aware menu only and never run commands automatically; each command maps to an independent playbook under reference/, with rules embedded as  tags in source files for publish-time consistency checks.

.claude/skills/impeccable/SKILL.md

**No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command.

README claims '1 skill, 23 commands'; the command table actually has 23 rows (including the deprecated craft); reference/ holds 35+ playbooks (init/shape/audit/polish/live/hooks/craft-floor...), along with degraded/ and agents/*.md sub-agent prompts.

PRODUCT.md/DESIGN.md dual-document source of truth: init only populates PRODUCT.md (product truth: users/tasks/constraints/platform) without touching the visual domain; document/extract backfills DESIGN.md (design systems/tokens/components) from completed code. Visual directions are finalized during new-work to overwrite DESIGN.md—'visual authority is evidence, not a filename.'

skill/reference/init.md

`init` captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md; [new-work.md](new-work.md) creates or expands one, and [document.md](document.md) records an incumbent one.

The three 'How to design' principles in SKILL.md strictly define rewrite semantics: 'Refinement preserves; redesign replaces.' + 'Visual authority is evidence, not a filename.'; Brief precedence: '**The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning.'

Deterministic linter (61 rules) integrated as host hooks: Once hooks are on, Claude Code/Codex/Copilot run the linter via post-tool-use hooks after every UI file modification and pipe findings back into context; Cursor utilizes preToolUse to intercept bad writes before they hit disk. Configured in .impeccable/config.json (locally overridden by .impeccable/config.local.json).

skill/reference/hooks.md

The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`).

Original Cursor interception semantics: 'Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.'; README states 61 deterministic rules 'run the deterministic rules with no LLM and no API key'; Per-edit triggers + session Stop deep sweeps form a closed 'detector-hook-context' loop.

live browser variant iteration mode: Leverages a local dev server (HMR) to hand selected elements to AI for hot-swapping generated HTML+CSS variants; maintains crash recoverability via an event polling loop (the _instructions field is the authoritative next step) and .impeccable/live/ session journals; explicitly prohibits production site injection or weakening CSP.

skill/reference/live.md

Interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR.

Original boundary: 'Live editing requires a local checkout; injection into deployed production sites (including HTTPS) is unsupported. …Do not disable browser security or weaken production CSP to enable live mode.'

2Core Capabilities

0123-command design vocabulary: craft/shape/init/document/extract (Build), critique/audit (Evaluate), polish/bolder/quieter/distill/harden/onboard (Refine), animate/colorize/typeset/layout/delight/overdrive (Enhance), clarify/adapt/optimize (Fix), live (Iterate)

02Capturing product truth in PRODUCT.md (init: users/tasks/mechanisms/constraints, prohibiting inquiries on visual preferences) + capturing design systems in DESIGN.md (document/extract: reverse-documenting tokens/components from production code)

0361 deterministic lint rules (executed locally without LLMs or API keys, covering AI slop patterns and general design quality) + two-tiered per-edit/Stop hook integrations into hosts

04craft-floor pre-editing prerequisites: quality floor, absolute prohibitions, and reflexes undetected by automated linters

05live browser variant iteration (HMR hot-swapping, event polling, journal-based recovery, forbidden production injection)

06Pattern taxonomy (Persuade/Operate/Read/Experience) + pattern persistence discipline (retained strictly within corresponding surface briefs)

07Versioned self-managed engine: doctor repairs PRODUCT.md/DESIGN.md/config/hook drift; pin/unpin generates standalone shortcut commands; multi-tiered engine lookup + sha256 verified downloads

08Verification budget discipline: bounded passes ceiling covering the entire lifecycle, prohibiting endless self-QA loops

3External Dependencies

Kind	Dependency / Endpoint
cli	impeccable 引擎（自含二进制，随 skill 的 scripts/impeccable launcher 定位/下载；技能通过 Bash 调用）
network	引擎二进制下载通道（仅首次且缺二进制时）：GitHub Releases，engine-v<version> 资产 + .sha256 sidecar
package	npx impeccable（SKILL 授权 Bash(npx impeccable *) 的发布安装路径；README quick start 亦用 npx impeccable install）
network	文档站/知识引用（非运行时调用）：impeccable.style、github.com/pbakaus/impeccable（README/docs 内链接）、google-labs-code/design.md spec（reference/document.md 内引用）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: skill/scripts/impeccable launcher (POSIX sh) → engine binary: context/detect/hooks/live
网络端点: Declares external network access: Initial engine binary download: https://github.com/pbakaus/impeccable/releases/download/engine-v<
本地工作目录: File read/write and artifact output: Within project: PRODUCT.md, DESIGN.md (+sidecar), .impeccable/config.json, and config.local.json

Audit Notes: Attack and integration surface: 1) Egress is unique and predictable—it downloads the engine binary from the author's official GitHub Releases upon first run (sha256 sidecar verified, version pinned, fail-closed, with IMPECCABLE_BIN/offline preinstallation bypasses available), adhering to standard official distribution channels; 2) Local write scope is broad: modifies PRODUCT.md/DESIGN.md/.impeccable configs, writes hook manifests to host configs (.claude/settings.local.json, etc.), and triggers automated lint checks on every UI modification; 3) No credential access or third-party telemetry. Considerations: Engine binary supply chain, automated hook execution surface, and live injection mechanisms require informed consent (activated only after explicit installation/opt-in by the user).

5Second-Pass Verification

[ok] 单一 master 源 + 多宿主编译副本 — diff skill/SKILL.src.md 与 .cursor/.claude 副本：差异仅为占位符展开（{{scripts_path}}→宿主路径）、frontmatter 增删（version/argument-hint/allowed-tools）、 注释剥离；正文结构一致。
[ok] 每会话 context + 降级协议 — 编译副本与 src 均含 Setup 三步与 'Launcher unavailable' 段；引文逐字存在。
[ok] 引擎二进制下载仅首次且 fail-closed — launcher 第 60-200 行精读：候选顺序 IMPECCABLE_BIN→sibling bin→~/.impeccable/bin→version cache→PATH probe→下载；下载后必须 sha256 sidecar 匹配才 chmod+mv+exec，sidecar 不可得/不匹配/空文件均拒绝（exit 127）。
[ok] 61 规则与无 LLM 声明 — README 两处声明一致（'61 deterministic detector rules'、'no LLM and no API key'）；hooks.md 描述 per-edit 与 Stop 深扫两级；规则实体位于引擎二进制内（本仓库 skill 目录不含规则源码，属引擎发布物 [INFERENCE]）。
[ok] 23 命令数 — SKILL.md 命令表逐行计数 = 23（craft 为 deprecated alias 仍列）；与 README '23 commands' 一致。
[ok] hook 安装面与宿主 manifest — hooks.md 列出全部宿主清单路径（.claude/settings.local.json/.cursor/hooks.json/.codex/hooks.json/.github/hooks/impeccable.json/.grok/hooks/impeccable.json）；'reset' 动作会从 on 安装过的 manifest 移除条目。
[ok] live 仅限本地 + journal 恢复 — live.md 明确 'requires a local checkout'、'injection into deployed production sites (including HTTPS) is unsupported'；.impeccable/live/sessions/ journal 与 live-status/resume 流程存在。
[ok] 无凭证读取 — skill 目录（src/scripts/reference/agents + 编译副本）无 API key/token/secret/.env 读取代码；引擎行为以 README『no API key』声明 + 引文为据（引擎二进制内部未逐一审计 [INFERENCE]）。

6Verdict & Scenarios

Engineers 'design quality' into deterministic linters + host hooks (triggered on edits, preemptive write blocking), moving beyond mere prompt suggestions.

Dual-document authority model + rewrite semantics (brief wins / refinement preserves / redesign replaces) prevent the agent from overriding established user direction with its own aesthetic taste, an uncommon rigor among design skills.

Compiled multi-host distribution guarantees consistent skill behavior across 20 hosts, with machine-verifiable rule annotations ensuring release-time consistency and mature engineering governance.

Fail-closed launcher download strategy (sha256 sidecar validation + version pinning + preinstallation workarounds), offering a minimal external surface with self-documented guidance: 'sandboxes without egress preinstall the binary on PATH'.

Engineered failure semantics: launcher fallbacks, live journal recovery, CONTEXT_STALE reporting without automatic mutations, and bounded passes verification budgets provide clear mitigation paths when tools fail or data becomes stale.

Best for: Ideal for AI coding users (Claude Code, Cursor, Codex, etc.) committed to serious frontend design or refactoring who are willing to set up the engine and quality gate hooks; teams using or looking to adopt the PRODUCT.md/DESIGN.md dual-document pattern; engineering workflows requiring deterministic a11y/quality checks with per-edit interception; requires internet access to download the engine binary on first run (unless preinstalled).

Not for: Not suitable for backend-only or non-UI tasks (as stated in the description: 'Not for backend-only or non-UI tasks.'); environments prohibiting local automated hooks or zero-egress sandboxes (can be mitigated via hooks off + manual detect + preinstallation, though with a degraded experience); zero-trust or minimal environments unwilling to accept external engine binaries and author-defined aesthetics; unconstrained creative workflows seeking freeform generation rather than structured design discipline.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload impeccable.tar.gz

sha256: 1467f7553455c007…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit cd12f8660e.