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 / agent-design-workflows

Agent-assisted design workflows

Impeccable gives an AI coding agent a guided path for frontend design work. It loads product and visual context, chooses a suitable work mode, builds from a clear direction, checks the rendered result, and records what the shipped design should preserve.

System purpose

The workflow turns a design request into a checked result without allowing a local refinement to become an unapproved redesign. It keeps product truth, visual direction, source edits, quality checks, visual evidence, and final judgment as separate concerns.

The workflow serves product UI, dashboards, forms, landing pages, app shells, native iOS and Android screens, and design systems. The installed impeccable skill is the main entry point. Provider packages adapt the same workflow to supported AI coding clients.

Workflow lifecycle

The lifecycle starts with project context and ends with an independent review of the rendered experience. Each stage gives the next stage a clear basis for action.

Context loading

Context loading gives the agent the product facts and design rules for the target surface. A session uses the product record, design record, matching surface brief, workflow settings, and platform guidance when needed before the agent selects a command or edits the UI.

The records have separate roles:

RecordPurpose
PRODUCT.mdProduct users, purpose, constraints, evidence, and durable commitments
DESIGN.mdShared visual rules and component language
Surface briefStrategy and direction for one route or artifact
.impeccable/config.jsonShared workflow and detector settings
.impeccable/config.local.jsonOne developer's local choices and consent

New-surface planning needs product context. A focused change to an existing surface can use the current code and offer setup afterward. If context loading fails, the agent reports the failure and reads existing records directly. It does not invent missing facts or repair stale context during unrelated work. If the launcher itself is unavailable, it states that before the next tool call and continues with direct context reading.

init can also record the default build path for new landing and showcase surfaces when image generation is available. It configures live mode only when the project is runnable and suitable for browser iteration. These are workflow choices, not product truth.

References: plugin/…/SKILL.md• L17-23 plugin/…/SKILL.md• L80-88 plugin/…/document.md• L64-80

Design planning

Design planning turns a request into a clear scope before implementation. The agent identifies the visitor's job, required proof or content, important states, constraints, and what must remain unchanged. It then chooses one visitor mode: Persuade, Operate, Read, or Experience.

The visitor mode sets the design priority:

  • Persuade: help the visitor understand the offer and act.
  • Operate: help the visitor complete a task with clear structure and controls.
  • Read: help the visitor understand material and move through it with confidence.
  • Experience: let the work itself lead the visit.

New surfaces and replacement visual worlds use a direction contract. The contract records the central idea, visual world, visitor story, first viewport, chosen form, and finish condition. A local extension inherits the existing surface instead of starting a new identity exercise. Refinement preserves the incumbent world and behavior. Redesign replaces the visual world while preserving product truth, function, and constraints.

For open new work, concept-seed creates serious directions and challengers. The user selects one direction or explicitly chooses the standing category-standard option. The selected direction is recorded before code, with its seed reference kept for later review. A selected decision composition can also set the build path when image generation is available.

The brief remains the authority for pinned aesthetics, materials, fonts, and palettes. The workflow does not treat the absence of DESIGN.md as proof that a project has no visual direction, and it does not repair context as a side effect of ordinary design work.

References: plugin/…/SKILL.md• L25-41 plugin/…/new-work.md• L7-28 plugin/…/new-work.md• L44-76

Build paths

After the direction is chosen, the workflow uses either a composition-led path or a code-led path. Project settings supply the default for open visual surfaces, while the session can make a temporary choice. Operate and Read surfaces use the code-led path because their working structure matters more than a pictured composition.

PathDesign basisReview basis
Composition-ledAn approved visual composition and measured regionsRendered output compared with the approved composition
Code-ledThe direction contract and first-viewport promiseRendered behavior compared with the contract and quality bar

In the composition-led path, the approved composition is a measured contract. Ordered gates cover the composition, region specification, visual material, first viewport, remaining sections, motion, and responsive views. A later phase cannot replace an earlier failed gate.

In the code-led path, the direction contract carries the ambition. A selected decision composition can guide finish review, but it is a critique reference rather than an approved page contract. For open Persuade and Experience work, the user can choose the session's build path during the direction round; that choice does not silently change the project default. In both paths, the first viewport must show the product's mechanism instead of only a generic header or mood.

This diagram shows how the two build paths meet at implementation and then move through evidence and review.

flowchart LR
    A[Load context] --> B[Plan scope and visitor mode]
    B --> C[Choose direction]
    C --> D{Build path}
    D -->|composition-led| E[Approve and measure composition]
    D -->|code-led| F[Record direction contract]
    E --> G[Build first viewport]
    F --> G
    G --> H[Complete surface and responsive views]
    H --> I[Capture and inspect]
    I --> J[Independent finish review]
    J -->|recapture| I
    J -->|fix| G
    J -->|rebuild| C
    J -->|ship| K[Document the result]

References: plugin/…/new-work.md• L48-50 plugin/…/new-work.md• L80-94 plugin/…/visualize.md• L7-11

Implementation and finish review

Implementation applies the confirmed direction to the target surface. The agent preserves product content and behavior while meeting accessibility, responsive, performance, and platform needs. Before any UI edit, including a small refinement, it loads the craft floor so the work follows the quality floor and absolute bans.

When the app cannot run, the workflow starts with current visual-regression goldens or screenshot fixtures and checks them against current visual truth. It builds the first viewport as the clearest proof of the product's mechanism, then completes the rest of the surface inside the same visual system.

Finish review is an independent last gate. The reviewer reads the supplied request, answers, artifact paths, captures, direction contract, product record, quality bar, build evidence, and relevant findings. It does not browse, render, start a server, take screenshots, or edit source. It first validates the required capture set and persistence records, then judges fidelity, the quality bar, the direction contract, product truth, and the craft floor.

The reviewer returns one of four dispositions:

  • recapture: the evidence is invalid or incomplete.
  • rebuild: fidelity failed at a broad level.
  • fix: apply material fixes as one batch and recapture the same views.
  • ship: the reviewed scope is ready for documentation.

After a fix batch, the reviewer scores the named fixes against the new captures instead of starting a new hunt. A failed recapture or a rebuild request starts the corresponding full review path. The documenter treats the shipped artifact as the source of truth. It records durable rules that the build actually uses. New worlds and approved system changes require DESIGN.md and .impeccable/design.json; ordinary extensions preserve the incumbent system. When the harness has no subagents, the asset producer, finish reviewer, and documenter run inline under degraded contracts and disclose that substitution.

References: plugin/…/SKILL.md• L19-23 plugin/…/new-work.md• L108-124 plugin/…/impeccable-finish-reviewer.md• L9-15 plugin/…/impeccable-finish-reviewer.md• L21-39 plugin/…/impeccable-finish-reviewer.md• L41-43 plugin/…/document.md• L1-3

Component fidelity review

Component fidelity review compares a rendered surface with an approved composition before the page is complete. It gives the user an early check on the production plan and visual material, then gives the assembled first viewport a separate check.

On a composition-led build, the chosen composition becomes a spatial contract. Its regions are measured and raster material is produced before page assembly. The first viewport is then compared with the composition through region evidence. The composition guides structure and material. It does not permit rasterized UI text or an unrelated redesign.

The review remains user-owned. A pending or unavailable review is not approval, so the agent must not submit the page or write an approval receipt for the user. If the user requests a revision, the workflow updates the plan or material and repeats the review with accepted decisions carried forward.

Asset production stays downstream of the approved visual decision. The asset producer creates only the assigned raster material and returns unresolved drift to the parent rather than approving its own work.

References: plugin/…/visualize.md• L7-39 plugin/…/new-work.md• L100-119

Hardening review

Hardening checks whether the design survives real inputs and operating conditions instead of only ideal content. It covers long and short text, empty data, errors, slow or failed networks, permissions, concurrent actions, international text, interrupted gestures, and browser limits.

The hardening pass also checks recovery and access. Users should keep their input after validation errors, understand what failed, retry where useful, and reach core behavior with keyboard and assistive technology. Web audits measure accessibility, performance, theming, responsive behavior, and implementation integrity. Native audits replace browser checks with platform conformance and adaptivity checks.

References: plugin/…/new-work.md• L125-135 plugin/…/SKILL.md• L54-59

Agent interfaces

The workflow reaches an AI coding agent through connected interfaces. The skill defines shared behavior, provider packages adapt it to each client, hooks check direct edits, and live mode supports fast browser-based variation.

Skill commands

The installed impeccable skill is the main entry point for design requests. It routes explicit or clearly implied requests to the matching playbook. With no command, it presents a context-aware menu and does not choose an action by itself. A general design request uses the existing implementation for a narrow refinement, while a missing product record routes new work or a replacement visual world through context setup and new-work planning.

GroupPurposeExamples
BuildEstablish context, plan work, or record design knowledgeinit, shape, document, extract, foundations
EvaluateReview design or measurable qualitycritique, audit
RefineImprove an existing result without an unapproved redesignpolish, bolder, quieter, distill, harden, onboard
EnhanceChange one focused quality dimensionanimate, colorize, typeset, layout, delight, overdrive
FixResolve clarity, adaptation, or speed problemsclarify, adapt, optimize
IterateTry visual alternatives in a running browserlive, generate

craft is a deprecated alias for ordinary new work. teach aliases init. doctor reports and repairs drift between project records and the installed workflow. foundations checks a roadmap of common product needs and fixes one selected item without redesigning the product. Commands can also manage hooks and pinned shortcuts. See Skill commands and reference guidance for command scope and playbook rules.

Some commands require a user choice before implementation. audit and critique report findings rather than silently changing source. Refinement commands preserve the product's purpose while changing its fit, first-use path, complexity, or visual intensity. Context drift is reported rather than repaired during another design task, except for findings marked auto that the next write applies.

References: plugin/…/SKILL.md• L43-90 plugin/…/document.md• L64-80

Product foundations

The foundations workflow checks basic product readiness outside the visual design task. It reports the next missing item and can fix one chosen item in the project's own stack, while asking the user before changes that need secrets, accounts, legal text, or product decisions. The roadmap covers areas such as a not-found page, icons, social previews, legal pages, error tracking, readable contrast, reduced motion, dependency and migration health, test-running CI, and infrastructure evidence.

The workflow treats secrets as sensitive evidence: it identifies their location without printing their values. A successful check means the project meets the selected foundation's definition, not that every roadmap item has been checked.

References: plugin/…/foundations.md• L1-21 plugin/…/foundations.md• L23-44

Provider integration

Provider integration delivers the same design workflow in the format each supported AI coding client can load. The package keeps shared skill behavior while adapting command syntax, metadata, agent definitions, and hook support to client needs. Client capabilities can differ, so one provider may support hooks or subagents while another supports only part of the workflow. See AI provider integration for package boundaries and engine delivery.

The installed plugin is version 4.10.0. Its launcher runs the pinned engine version 0.1.23 for the current platform. It checks available candidates and verifies downloaded engines against the matching checksum before use. This keeps a provider from silently running a stale, incompatible, or untrusted workflow engine.

References: plugin/…/SKILL.md• L1-8 plugin/…/VERSION• L1 plugin/…/engine-checksums.txt• L1-9

Edit guardrails

The design hook gives supported clients an automatic check around direct edits to design-relevant files. The per-edit pass surfaces immediate mechanical problems. A stop-time deep pass checks the full rule set over UI files touched in the session when the client can return that context. Clients without a usable stop event keep the full detector per edit.

Hook findings are evidence, not a complete design decision. They do not replace rendered review, component-fidelity gates, hardening, or independent finish review. Shared hook and detector settings belong to the project. Consent and local overrides belong to the developer. See Agent hooks and edit interception for event behavior and finding triage.

Manual detector scans use the same project filters as automatic checks. Live browser scans also resolve project rule, value, and file ignores against the page being inspected, so the live result stays aligned with command-line and edit-time results. If no automatic hook is wired, context asks for one manual detector run at the end.

References: plugin/…/SKILL.md• L82-88 plugin/…/live.md• L54-64 plugin/…/live.md• L313-327

Agent roles

Complex work can use focused agents with clear boundaries. An asset producer creates reusable visual material from an approved reference. A finish reviewer evaluates a completed build without editing it. A documenter records the resulting design system.

Each role receives an input packet and returns a defined result. The parent workflow owns the next step. The asset producer makes only assigned material, the finish reviewer judges supplied evidence without a browser or source edits, and the documenter records rules from the shipped artifact. When a client has no subagent capability, the role runs inline under a degraded contract and must disclose that substitution.

References: plugin/…/new-work.md• L137-152 plugin/…/visualize.md• L41-47 plugin/…/impeccable-finish-reviewer.md• L9-15

Workflow artifacts

The workflow keeps records that explain why a design was chosen and what later work must preserve. These records supplement source code. They do not replace the implemented surface.

Design context

Design context gives each session a stable frame for its choices. Product context defines users and purpose. The design system defines the shared visual world. A surface brief adds route-level strategy. A direction contract records the selected form and finish condition for new or replacement visual work.

init owns durable product truth and does not create a visual world. document records an existing visual system. doctor handles schema drift and reports truth drift without treating commit counts as proof that a document is wrong. It applies only findings marked auto; other findings remain reported or go to the command that owns the repair.

The context loader can report missing or stale records. It surfaces those signals for the agent to address when the user asks. It does not repair project documentation as an unrequested side effect. See Design context and critique artifacts for record roles and reuse across sessions.

References: plugin/…/document.md• L64-80 plugin/…/SKILL.md• L82-90 plugin/…/new-work.md• L74-90

Critique feedback

Critique and audit provide different kinds of feedback. Critique reviews whether the experience is clear, specific to the product, usable, and coherent. Audit checks measurable quality across accessibility, performance, theming or appearance, responsive or platform behavior, and implementation integrity.

Audit is report-only. It separates verified detector findings from visual judgment, prioritizes findings by severity, and recommends follow-up commands. A critique snapshot can preserve a bounded backlog for a later refinement run, but an old snapshot never becomes current truth without a fresh check. See Design context and critique artifacts for storage, trends, pinned decisions, and stale-context handling.

References: plugin/…/SKILL.md• L52-59 plugin/…/new-work.md• L137-152

Live editing

Live mode supports an interactive browser loop for visual alternatives. A user selects an element in a running local surface, chooses a design action, reviews generated variants, and accepts or discards a result. The user can also steer the page, add annotations, or apply a structured manual edit. Acceptance writes the chosen change through a controlled source path, while discard restores the original.

Live mode is for a local checkout with a running development server or a static page. It does not inject into a deployed production site. The helper resolves the app root and keeps the browser page, source files, and session journal tied to that root. Durable session state lets an interrupted browser, helper, or poll process resume without losing the user's choice.

Live generation supports both replacement and insertion. A source preview can use a temporary wrapper, while supported component targets use temporary previews that preserve route control flow. The accepted result is promoted to real source rather than left in generated preview material. Publication is atomic by default so the browser does not show a partly delivered variant set.

Manual copy edits use a separate structured apply path. A selected element can also be staged for removal through that flow. The element stays hidden in the DOM while removal is staged, which lets undo and discard restore it without depending on framework reconciliation. See Live editing sessions for setup, selection, variant delivery, acceptance, manual edits, removal, and recovery.

References: plugin/…/live.md• L1-30 plugin/…/live.md• L72-82 plugin/…/live.md• L264-337 plugin/…/live-setup.md• L3-45

Change checklist

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

  • Keep shared skill guidance, installed SKILL.md, reference pages, provider metadata, and command behavior aligned. The installed router and packaged workflow must describe the same commands and setup rules.
  • Keep context setup, craft-floor loading, hardening guidance, and finish-review rules aligned. The agent must know when context, edge-case checks, and edit-time quality guidance apply.
  • Keep PRODUCT.md, DESIGN.md, surface briefs, direction contracts, and doctor ownership distinct. A field moved between records can become a second authority or cause a repair to change product truth.
  • Keep visitor modes aligned with direction planning. A change to Persuade, Operate, Read, or Experience can alter the content and structure expected in every direction contract.
  • Keep composition-led phases, direction contracts, measured regions, visual material, component review, and finish-review inputs aligned. A changed phase or artifact field can silently change whether a build advances or whether a reviewer can verify it.
  • Keep provider transformations aligned with the shared skill. A provider change can remove a command, agent, hook, or required path placeholder for one client.
  • Keep hook event support and detector tiers aligned across clients. A client without a usable stop event must retain full per-edit coverage.
  • Keep shared detector settings, local consent, local overrides, and live ignore resolution aligned. A scope mismatch can make manual scans, automatic hooks, and live scans inspect different files or rules.
  • Keep live browser vocabulary, source-preview behavior, session state, event validation, acceptance cleanup, and staged removal restore behavior aligned. A mismatch can leave a variant or hidden removal visible while source or session state says something else.
  • Keep live root resolution, page-file mapping, poll behavior, and recovery journal semantics aligned. A helper started from the wrong app root or without an active poll can attach events to the wrong page or leave a user action unanswered.
  • Keep degraded agent input and output contracts aligned with their parent workflows. Inline execution must disclose its substitution and must not blur asset production, review, source edits, and documentation.
  • Keep the foundations roadmap and its item definitions aligned with the skill command. A changed check can alter what the roadmap calls ready or can turn a safe report into an unapproved product change.
  • Keep VERSION, platform assets, checksum entries, and launchers aligned. A release that updates only one can refuse a valid engine or run an unverified one.

Important failure modes

TriggerConsequenceGuard
New work starts without product contextThe agent can invent users, claims, or constraintsRun init and verify PRODUCT.md before new work
A refinement is routed as a redesignThe agent can replace identity, copy, or behavior outside scopeUse the command's refinement boundary and preserve the incumbent world
A decision composition is treated as an approved composition-led contractA code-led build can be judged against a contract it never acceptedUse the approved composition only for composition-led work; treat a decision composition as a critique reference otherwise
A composition-led phase is skipped or advanced out of orderThe build can drift from the approved composition while appearing completeClose each build phase in order
A component review is pending or unavailableThe agent can mistake waiting for approval and build past a user checkpointReport the session as pending and wait for the user's decision
A required capture is missing or malformedFinish review must reject the evidence before it can judge the buildValidate every required capture and recapture the named view
A reviewer returns recapture, rebuild, or fix and the workflow treats it as shipThe build can ship with invalid evidence or unresolved material issuesAct on the disposition word and send the required evidence back for review
A technical audit is treated as a fixerSource changes can happen without user direction and measured findings can be lostTreat audit as report-only and route fixes to the named command
A foundations item is fixed without its user decision or without its definition checkThe workflow can add unsafe placeholders or report a foundation as ready when it is notAsk before user-owned changes and verify the item's stated done condition
A provider package or launcher runs stale or unverified outputOne client can lose workflow features or execute the wrong engineUse the pinned version and matching checksum checks
A live page resolves a different app root or ignore scope from the source checksPreview work can target the wrong source or hide findings that other checks reportUse the resolved root manifest and keep live ignore resolution aligned with project config
A live poll is not serviced after an event or replyThe browser can remain locked while the user's next action waitsKeep one client-appropriate long-running or one-shot poll active and restart it after every event
A live session stops before acceptance cleanupTemporary wrappers or staged edits can remain while the session says work is doneResume or discard through live session state, then complete cleanup canonically
A source preview is accepted without promotion to real sourceThe accepted design can vanish after HMR or regenerationUse the framework's source-promotion path and complete the session gate
A downloaded engine has no matching checksum or fails verificationThe launcher refuses to run the engine or a release cannot start on that platformAdd the exact pinned asset digest and use launcher verification

Key files

FileWhy to read it
plugin/…/SKILL.mdInstalled entry point, setup order, visitor modes, commands, routing, hooks, and finish limits
plugin/…/new-work.mdNew-surface planning, direction contracts, build paths, ordered gates, hardening handoff, and finish review
plugin/…/visualize.mdComposition approval, visual material, asset provenance, and fidelity discipline
plugin/…/document.mdDesign-system recording and the relationship between DESIGN.md and its sidecar
plugin/…/foundations.mdProduct-readiness roadmap, user consent rules, and definitions of done
plugin/…/live.mdBrowser iteration, insertion, acceptance, manual edits, source promotion, and recovery contract
plugin/…/live-setup.mdLive config, framework injection, config drift, and development CSP consent
plugin/…/impeccable-finish-reviewer.mdIndependent evidence, fidelity, quality-bar, contract, and post-fix review rules
Live editing sessionsBrowser iteration, acceptance, manual edits, removal, and recovery
Agent hooks and edit interceptionHook events, detector scope, consent, and finding triage
Design context and critique artifactsProduct and design records, critique snapshots, and stale-context handling
Skill commands and reference guidanceCommand selection and playbook boundaries
AI provider integrationProvider packaging, engine delivery, and client boundaries
plugin/skills/impeccable/scripts/VERSIONInstalled engine version selected by the launchers
plugin/…/engine-checksums.txtTrusted engine digests for each supported release asset