Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / skill-commands-and-references

Skill commands and reference guidance

The Impeccable skill turns a design request into a bounded workflow. Command metadata describes the available actions. Executable helpers provide shared support. Reference guides define the design decision, evidence, and handoff rules for work such as onboarding, polishing, shaping, and routing.

This page is a child of Agent design workflows. Related guidance covers live editing sessions, agent hooks and edit interception, design context and critique, and AI provider integration.

Command surface

Command catalogue

The command catalogue is the user-facing map of design work. Command metadata gives hosts a short description and argument hint. The matching reference guide defines the work and its boundary.

CategoryDesign questionCommands
BuildWhat should exist and what direction should it take?craft, shape, init, document, extract
EvaluateWhat quality or experience problems exist?critique, audit
RefineHow should an existing surface improve without changing its purpose?polish, bolder, quieter, distill, harden, onboard
EnhanceWhich visual quality needs focused work?animate, colorize, typeset, layout, delight, overdrive
FixWhich clarity, context, or performance problem needs correction?clarify, adapt, optimize
IterateWhich live or generated alternatives should the user compare?live, generate

The catalogue also records special paths. craft is a deprecated alias for ordinary new work, and teach aliases init. Native targets use native references where available. Web adapt and audit switch to native guidance for native projects. live, generate, and the bundled detector are web-only. Android work follows Material rules and uses emulator or device evidence instead of browser captures.

References: plugin/…/SKILL.md• L43-70 plugin/…/command-metadata.json• L1-94 plugin/…/adapt.md• L1-5 plugin/…/audit.md• L1-5 plugin/…/audit.native.md• L1-4 skill/…/android.md• L1-5 skill/…/android.md• L42-46

Command execution

The launcher is the stable entry point for command support. A session loads project context once from the skill directory. Each selected command then uses that context and its own reference instead of rebuilding the project picture. Executable helpers collect context, store records, detect issues, serve review pages, or manage live sessions. The reference guide remains the authority for design judgment.

The launcher selects a compatible engine for the skill version and platform. It prefers an explicit operator choice or a verified bundled or cached engine. If setup needs network access or a writable cache, the launcher reports that boundary instead of running an unverified engine. A compatible preinstalled engine remains usable when the environment cannot download one.

Live support is a separate local interactive path. It resolves the app root, serves the selected page through a development server or static file, and keeps the browser preview tied to the selected element and session. The agent generates or inserts variants, and the user accepts or discards the result. Accepted work is written to true source; temporary preview state is removed before completion. Session journals and recovery commands protect active work across helper restarts. A failed mount stays visible until retry, a successful mount, or a new cycle.

References: plugin/…/SKILL.md• L17-23 plugin/…/SKILL.md• L80-88 skill/…/impeccable• L76-91 skill/…/impeccable• L109-152 skill/…/impeccable• L154-265 skill/…/impeccable.cmd• L1-23 skill/…/live-browser.js• L16-32 skill/…/live-browser.js• L105-132 skill/…/live-browser.js• L197-218 skill/…/live-browser.js• L233-273 plugin/…/live.md• L3-20 plugin/…/live.md• L72-82 plugin/…/live.md• L277-299 plugin/…/live.md• L327-341

Command routing

Explicit command routing

An explicit command selects one workflow. The agent reads that command's reference and follows its contract. Native targets use a native variant when the platform needs one. If two commands fit, the agent asks once instead of silently combining their scopes.

The routing rules preserve a key boundary: shape owns discovery and enters new-work only for visual-world or surface-concept decisions. A narrow refinement stays on the existing implementation. A new surface or replacement visual world enters new-work.

References: plugin/…/SKILL.md• L72-80 plugin/…/shape.md• L37-39 plugin/…/new-work.md• L1-5

No-argument routing

An invocation with no argument means “what should I do?” The routing guide uses project signals to present two or three useful recommendations and then shows the full command menu. It waits for the user's choice. It never runs the lead recommendation automatically.

The recommendations reflect the current project state. Missing product context can lead to init. Missing design documentation can lead to document. A weak or absent critique can lead to critique or polish. Changed files can narrow the target. A running web server can make live or generate available. Native projects stay out of browser and HTML-detector recommendations.

This diagram shows how a bare invocation becomes a user-selected workflow.

flowchart LR
    A[No-argument request] --> B[Load session context]
    B --> C[Read project signals]
    C --> D[Run useful web detection when allowed]
    D --> E[Recommend focused commands]
    E --> F[Show full menu]
    F --> G[User selects a command]
    G --> H[Load its reference guide]

References: plugin/…/SKILL.md• L72-78 plugin/…/routing.md• L7-24

Reference guide system

Workflow ownership

Each command guide owns one kind of decision. This keeps a technical audit from becoming a design review, a polishing pass from becoming a redesign, and a context change from becoming simple scaling.

GuideOwnsStops or hands off at
initDurable product contextProduct truth in PRODUCT.md
documentThe current visual system and its reusable guidanceA confirmed DESIGN.md and sidecar, or an honest seed before implementation
onboardFirst value, empty states, and feature discoveryA usable path to the product's first useful moment
shapeDiscovery and a confirmed briefConfirmation before code or persistence
new-workNew surfaces and replacement visual worldsA recorded direction ready for its chosen build path
polishBounded refinement of the incumbent surfaceA finished path with current evidence addressed
distillRemoval of excess while preserving necessary functionA simpler path with required information and access intact
quieterLower visual intensity without losing hierarchy or personalityA restrained surface that remains clear and distinctive
overdriveUser-chosen enhancement to how an interface feelsA verified enhancement with a useful fallback and controlled cost
critiqueIndependent design and evidence assessmentA persisted snapshot, synthesis, and user-directed next step
auditReport-only technical quality reviewFindings routed to commands that can fix them
optimizeMeasured performance improvementA verified change against the observed bottleneck
hardenResilience under real data and failure conditionsEvidence across boundary states and environments
adaptExperience changes for a new context rather than simple scalingVerification on the target device, input, or platform
visualizeComposition options after the world is fixedOne approved composition for the build
hooksProject detector-hook state and finding triageA configured hook or a clear user decision on an exception
doctorDrift between installed artifacts and current skill expectationsMechanical repair, a named truth gap, or a user decision

The guide is the authority for behavior. Executable helpers can collect context, store records, detect issues, or serve a review. They do not replace the guide's design judgment.

References: plugin/…/SKILL.md• L43-70 plugin/…/critique.md• L1-16 plugin/…/audit.md• L1-5 plugin/…/document.md• L1-3 plugin/…/document.md• L64-80 plugin/…/distill.md• L1-3 plugin/…/overdrive.md• L8-20 plugin/…/quieter.md• L1-10 skill/…/audit.md• L1-5 skill/…/doctor.md• L1-12 skill/…/optimize.md• L1-2 plugin/…/visualize.md• L1-5

Design critique

critique separates design judgment from deterministic evidence before it combines them. On web targets it uses an independent design assessment and detector or browser evidence. Native targets use design review only because the web detector does not apply. The command then produces one critique with a design health score, priority issues, persona risks, and questions tied to the findings.

The chat report is the primary result. A target-specific snapshot preserves the assessment for later work, and polish can use its current priority issues. The run closes with targeted user questions when enough issues exist, or with an explicit skipped-questions reason.

References: plugin/…/critique.md• L1-16 plugin/…/critique.md• L31-46 plugin/…/critique.md• L48-63 plugin/…/critique.md• L65-99 plugin/…/critique.md• L101-139 plugin/…/critique.md• L204-240 plugin/…/critique.md• L242-264

Technical audit

audit is a report-only technical review for web projects. It measures accessibility, performance, theming, responsive behavior, and implementation integrity, then scores each dimension and assigns severity to verified findings. Native projects use the native audit path instead of browser or HTML evidence.

The audit does not fix the surface. It records an overall health score, concrete findings with impact and locations, positive findings, systemic patterns, and commands that can address the problems. It saves the report after delivery so later work can use the findings without replacing the user-facing report.

References: plugin/…/audit.md• L1-9 plugin/…/audit.md• L11-22 plugin/…/audit.md• L24-71 plugin/…/audit.md• L73-86 plugin/…/audit.md• L88-113 plugin/…/audit.md• L124-157

Design documentation

document records the visual system that later agents must preserve. In scan mode it extracts real tokens and component patterns, then confirms the descriptive language. The root DESIGN.md carries the normative token layer and canonical visual sections. The .impeccable/design.json sidecar carries extensions such as tonal ramps, motion, breakpoints, component snippets, and narrative that the token format cannot hold. The sidecar extends the frontmatter rather than duplicating its token primitives, and its component snippets are meant to render as self-contained panel examples.

Seed mode is for a project with no visual system to extract. It first requires product context and uses the new-work world choice to write a directional seed. The seed records durable direction with honest unresolved implementation facts; it has no fabricated component tokens or sidecar. A later scan mode run replaces that provisional view with the observed system.

The command must not silently overwrite an existing DESIGN.md. It shows the current file and waits for a refresh, overwrite, or merge choice. On a new seeded world, the first build writes the durable design record from the shipped result rather than defending a pre-build guess.

References: plugin/…/document.md• L1-3 plugin/…/document.md• L43-62 plugin/…/document.md• L64-80 plugin/…/document.md• L96-116 plugin/…/document.md• L253-257 plugin/…/document.md• L305-326 plugin/…/document.md• L352-385

Direction selection

new-work decides whether a surface inherits the current visual world, extends it, or replaces it. A missing DESIGN.md does not by itself mean the project is greenfield. The guide checks the product code, tokens, components, assets, and confirmed brand commitments before it chooses the level of invention. A local addition inherits an established surface instead of starting a new identity exercise.

For a new surface inside an established world, the concept-seed step presents a small set of composition choices. The assigned option is the rolled lead. Other dealt structures and catalog challengers retain clear identities so the decision page and later build steps report the same choice. For a new or replacement visual world, the direction round compares grounded candidates and challengers. The user still chooses the direction.

The direction choice also selects the build route for the session. A code-led route carries its ambition in the direction contract. A comp-led route turns an approved composition into a measured build contract. The route does not change who owns product truth or the user's authority over the direction. Before code, the chosen direction is recorded in a surface brief as a development-only contract. It guides the build and review but never enters source or browser output.

References: plugin/…/new-work.md• L1-17 plugin/…/new-work.md• L30-42 plugin/…/new-work.md• L44-50 plugin/…/new-work.md• L62-68 plugin/…/new-work.md• L70-80

Product onboarding

init captures confirmed product truth in the resolved PRODUCT.md so later work has a durable source for users, purpose, capabilities, constraints, platform, and evidence. It does not create a visual world or write DESIGN.md. It can record a build-path default and configure live mode for a runnable web project. Before later shaping or building resumes, PRODUCT.md must exist at the resolved path and contain the product record.

onboard has a different goal. It moves an existing user to first value through a real product path, using examples, empty states, or small hints where needed. It keeps advanced teaching for later discovery and allows a skip path when possible. A project can need product context, a better first-run path, or both. Neither command should silently take over the other's job.

References: plugin/…/init.md• L1-15 plugin/…/init.md• L17-23 plugin/…/init.md• L25-56 plugin/…/init.md• L58-110 plugin/…/init.md• L112-135 plugin/…/onboard.md• L1-4 plugin/…/onboard.md• L28-57 plugin/…/onboard.md• L168-193

Surface shaping

shape resolves what a surface must do before implementation begins. It asks about the audience, outcome, content, states, scope, interaction, and constraints. It returns the smallest useful brief and waits for confirmation.

The brief is a handoff, not a build artifact. It keeps unresolved product choices out of code. Confirmed work can then continue into new-work or another scoped command without reopening settled discovery.

References: plugin/…/shape.md• L3-14 plugin/…/shape.md• L25-35 plugin/…/shape.md• L41-59

New visual work

new-work protects the boundary between product truth, visual authority, and surface strategy. It records the chosen direction in a development-only contract before code. That contract guides the build and review but must not enter source code or browser-delivered output.

The build path changes how the chosen direction becomes a surface. Comp-led work uses an approved composition as a measured reference and moves through gates for composition, measurement, assets, the first viewport, later sections, motion, and responsive behavior. Code-led work skips the comp round by contract and carries its ambition in the direction contract. Both paths inspect the result and finish with review and documentation. A new or replacement visual world is not complete until its shipped result produces the durable design record.

References: plugin/…/new-work.md• L1-5 plugin/…/new-work.md• L48-50 plugin/…/new-work.md• L62-68 plugin/…/new-work.md• L80-106 plugin/…/new-work.md• L105-125

Composition review

Comp-led work has a human checkpoint before page code exists. When a surface round already showed a locked decision comp, that comp discharges the three-option round. Otherwise visualize produces three composition options after the visual world is fixed. The user approves, revises, combines, rejects, or delegates the choice. The selected comp then becomes the build reference.

This round tests composition, narrative, hierarchy, density, focal use, and image needs. It does not reopen the visual identity. Core text, controls, responsive behavior, accessibility, semantics, and interaction states remain implementation work. After approval, the comp becomes a measured reference rather than a poster to copy.

References: plugin/…/visualize.md• L1-5 plugin/…/visualize.md• L7-23 plugin/…/visualize.md• L25-39

Interface polishing

polish improves an existing interface without replacing its visual world, content, behavior, or out-of-scope areas. It treats rendered use and the real interaction path as evidence. Detector findings and a current critique snapshot help locate work, but neither proves that the surface is good. A critique snapshot is used only while its target remains current; an independent pass still checks the complete path.

distill is a narrower form of refinement. It removes redundant content, visual noise, excess choices, and cosmetic complexity while preserving the user's primary goal, necessary information, accessibility, and required function. quieter reduces intensity while keeping hierarchy and personality. These paths end by checking that the result remains complete and easier to use.

References: plugin/…/polish.md• L1-5 plugin/…/polish.md• L7-35 plugin/…/polish.md• L37-47 plugin/…/polish.md• L49-83 plugin/…/polish.md• L85-105 plugin/…/distill.md• L1-3 plugin/…/distill.md• L94-111 plugin/…/quieter.md• L5-10 plugin/…/quieter.md• L46-99

Live command setup

live changes an existing local page in an interactive loop. It requires a running development server with HMR or a static local page. The startup path resolves the app root and page to open, can create the common local configuration, and reports missing pages or configuration drift instead of making an unclear change. It never injects into deployed production sites or weakens production CSP.

Live mode is for local work only. The browser selects an element, the agent generates or inserts variants, and the user accepts or discards the result. Accepted work is written back to true source. Temporary wrappers, staged styles, and carbonize blocks are removed before the session is complete. The poll loop handles generation, steering, acceptance, discard, manual edits, mount failures, and exit. Session journals and resume commands make an interrupted session recoverable without asking the user to repeat a choice.

This diagram shows the high-level live loop.

sequenceDiagram
    participant U as User
    participant B as Browser
    participant H as Live helper
    participant S as Project source
    U->>H: Start live session
    H->>B: Mount picker and session bar
    U->>B: Pick element and request change
    B->>H: Send event and context
    H->>S: Stage variants or source preview
    S-->>B: Hot-swap preview
    U->>B: Accept or discard
    B->>H: Resolve choice
    H->>S: Persist accepted source or remove staging

References: plugin/…/live.md• L3-20 plugin/…/live.md• L32-50 plugin/…/live.md• L54-70 plugin/…/live.md• L72-82 plugin/…/live.md• L256-299 plugin/…/live.md• L327-341

Asset and visual provenance

Comp-led work treats the approved composition as a reference for a semantic, responsive, accessible surface. Painted regions become produced assets. Each shipping raster carries its generation prompt or source origin so later review can tell what the asset represents and why it exists.

The reference is never silently flattened into a screenshot. UI text and controls remain live product content. This keeps the visual decision, the user experience, and the final implementation connected without making the comp itself the product.

References: plugin/…/visualize.md• L35-47 plugin/…/new-work.md• L80-106

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the skill command table, metadata, argument hints, aliases, native variants, and pin validation aligned.
  • Keep no-argument recommendations user-controlled. Do not let signal collection or web detection become automatic command execution.
  • Keep live, generate, and detector recommendations out of native routing. Keep browser assumptions out of native guides.
  • Keep document's scan and seed paths distinct. A seed must remain honest about missing implementation tokens and must not overwrite an existing design record without consent.
  • Keep DESIGN.md as the normative token record and .impeccable/design.json as its extension layer. Regenerate them together when the visual system is regenerated.
  • Keep sidecar component examples self-contained and aligned with the frontmatter token names. Do not move sidecar-only extensions into the frontmatter schema.
  • Keep adapt tied to the target context and gesture evidence. Do not let resized screenshots stand in for touch verification.
  • Keep audit's web and native dimensions, report skeleton, severity tags, and command recommendations aligned without mixing their evidence sources.
  • Keep critique's independent assessments, provenance banner, applicable score maximum, snapshot metadata, trend, and final question or skip line aligned.
  • Keep shape planning-only and keep onboard focused on first value rather than product setup.
  • Keep init limited to confirmed product truth and its workflow setup. Require the resolved PRODUCT.md before later shape or build work.
  • Keep the direction contract in the surface brief and out of implementation source or browser-delivered output.
  • Keep comp-led work behind the current plan, asset, and approval gates. A changed spec or replaced comp needs a fresh review round.
  • Keep approved compositions fixed as references. Do not replace semantic text or controls with raster content.
  • Keep live setup tied to served files, development CSP consent, project-root discovery, and config-drift reporting.
  • Keep live accept, discard, carbonize cleanup, and completion acknowledgement in the same session contract.
  • Keep launcher engine compatibility, checksum validation, and platform-specific launcher behavior aligned.
  • Keep polish independent from stale critique snapshots and close only the snapshot whose current findings it clears.

Important failure modes

TriggerConsequenceGuard
The command table, metadata, and shortcut validation disagreeA host exposes a command that does not route or pin correctlyUpdate the command surface and its presentation metadata together
A bare invocation runs its recommendation without user choiceThe session starts with an unconfirmed scopeShow the focused menu and wait for the user's command
Web detection or live mode is offered for a native targetThe menu reports tools that cannot inspect the targetGate browser-only paths by platform
A critique runs both assessments in one context without declaring degradationDesign judgment can be anchored by detector output and the run appears more independent than it wasUse isolated assessments when available and emit the required method or degraded banner
A critique skips the final question or explicit skip lineThe report has no valid close and cannot capture the user's next priorityEnd with targeted questions or Questions skipped: <reason>
A critique snapshot is treated as current after the target changesPolish follows stale findings and may close the wrong backlogRetain and verify the snapshot identity and current content fingerprint
An audit fixes issues instead of reporting themFindings lose their independent evidence and the wrong command boundary owns the changeKeep audit report-only and route fixes to named commands
document treats a missing DESIGN.md as permission to invent a new worldExisting visual identity is lost or a seed claims false implementation factsScan first, use seed mode only when no system exists, and keep seed values provisional
document overwrites an existing design record without askingConfirmed visual guidance is lostShow the current record and wait for refresh, overwrite, or merge choice
A new-world build skips direction choice or writes code before the direction is recordedThe build falls back to an unreviewed category defaultRun concept-seed, record the direction contract, and keep it out of shipped output
A comp-led build starts without approval or a valid comp referenceThe build changes composition while claiming to follow a chosen directionClose the composition gate and record the approved comp before building
adapt treats a context change as a width change onlyTouch, navigation, content, or device constraints fail in the target contextVerify the real input method, device conditions, and custom gestures
A native audit uses browser captures or the web detectorPlatform conformance and device behavior remain untestedUse native audit dimensions and source or device evidence
shape writes code or persists an unconfirmed directionBuilders implement unresolved product decisionsStop at the confirmed brief
A direction contract is copied into source or browser outputPrivate planning data becomes part of the shipped artifactKeep the contract in the surface brief and pass it only to reviewers and documenters
A live session injects into deployed production files or weakens production CSPProduction behavior or security policy changes for a development helperUse local development injection only and use detector or extension paths for production inspection
Live config omits served pages or ignores reported driftSome routes cannot start a live session or receive the helperUse the served-file list or a suitable glob and ask before changing drifted config
A live component mount fails and clears the sessionThe user loses the handle to a server session that is still activeKeep the mount error card persistent and allow retry or a new cycle
Carbonize cleanup is skipped after acceptTemporary wrappers, scoped rules, or markers remain in sourceComplete the cleanup gate before the next poll
A raster lacks prompt or origin provenanceLater review cannot trace the asset's source or intentEmbed the exact generation prompt or source origin and scan shipping asset folders

Key files

FileWhy to read it
plugin/…/SKILL.mdCanonical command table, setup contract, aliases, routing, modes, and live boundary
plugin/…/command-metadata.jsonCompact command descriptions and argument hints used by hosts and pinned shortcuts
skill/scripts/impeccableUnix launcher selection, engine compatibility checks, checksum validation, and download boundary
skill/scripts/impeccable.cmdWindows launcher selection, engine compatibility checks, checksum validation, and download boundary
plugin/…/routing.mdContext-aware no-argument menu and recommendation rules
plugin/…/init.mdProduct truth, workflow defaults, live setup, and the completion gate for later work
plugin/…/critique.mdIndependent assessments, evidence rules, scoring, persistence, synthesis, and close contract
plugin/…/audit.mdWeb technical quality dimensions, scoring, severity, report contract, and saved findings
plugin/…/document.mdVisual-system documentation, token record, sidecar, scan path, seed path, and overwrite boundary
plugin/…/new-work.mdVisual authority, concept direction, build-path choice, direction contract, phased build, and finish handoff
plugin/…/visualize.mdComposition approval, comp-to-build boundary, asset production, and raster provenance
plugin/…/polish.mdEvidence-led refinement, critique snapshot use, whole-path checks, and snapshot closure
plugin/…/live-setup.mdLive config, served-file selection, framework setup, config drift, and development CSP consent
plugin/…/live.mdBrowser live-session contract, event loop, recovery, variant and source-edit handling, and cleanup
plugin/…/adapt.mdWeb context adaptation, device and input concerns, and gesture evidence
plugin/…/audit.native.mdNative audit dimensions, platform conformance, adaptivity, and device boundary
plugin/…/onboard.mdFirst-value, empty-state, and feature-discovery guidance
plugin/…/distill.mdSimplification boundaries and usability checks
plugin/…/quieter.mdRestraint rules that preserve hierarchy and product character
plugin/…/overdrive.mdUser choice, progressive enhancement, and verification for ambitious interaction work