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 / design-foundations-and-taste

Design foundations and taste workflows

These workflows give a project a durable design direction and keep that direction useful to both people and agents. Foundations check whether a project has the basic conditions for a sound product. Taste supplies a person's standing design preferences. Worlds provide a service-backed visual system that the CLI can seed into a project.

This page is a child of Native runtime and CLI. It relates to Rust CLI runtime, Agent protocol services, Account and Pro services, Design seed generation, and Component composition operations.

Workflow relationship

The three workflows serve different levels of design direction. Foundations describe project readiness, taste describes personal preference, and a world supplies a reusable visual language. The native CLI joins them with the account service and the agent context path.

This diagram shows how local project evidence and account guidance reach later design work.

flowchart LR
    A[Project files] --> B[Foundations scan]
    B --> C[Foundation status]
    C --> D[Account health record]
    E[User taste] --> F[Account taste service]
    F --> G[Local taste cache]
    G --> H[Agent context]
    I[World id] --> J[World seed service]
    J --> K[DESIGN.md and design sidecar]
    K --> H
    H --> L[Agent design operation]

Foundations workflow

Foundations are a product-readiness roadmap. The workflow checks the evidence that a project can show for security, accessibility, design consistency, delivery practice, and operational safety without treating missing evidence as a pass.

Foundation roadmap

The roadmap groups common launch, payment, and scale needs into named checks. It gives the user a next item to address instead of turning a scan into an undirected list of findings. crates/…/foundations.rs• L12-105.

The local scan reads project evidence offline through one bounded source. It walks the selected project, limits file reads, and uses tracked files when the project is in a Git work tree. When the command starts inside a repository, it also checks the repository's top-level configuration so readiness can include shared delivery practice. crates/…/local.rs• L1-18, crates/…/local.rs• L28-49, crates/…/local.rs• L86-109, crates/…/local.rs• L112-129.

The check result has three useful meanings:

  • failing means the project shows evidence of a problem.
  • checked means the available scan proved the item.
  • An absent item means the scan could not prove either state.

The CLI can run the roadmap offline. A project with no files receives a clear empty-project result, and a monorepo can pass a path for one application. skill/…/foundations.md• L5-15.

References: crates/…/foundations.rs• L12-18 crates/…/foundations.rs• L254-325 crates/…/local.rs• L1-18 crates/…/local.rs• L28-49 crates/…/local.rs• L86-129 skill/…/foundations.md• L5-15

Foundation account record

When the user has enabled foundations consent, a full scan can send the foundation states to the account service. The upload supports account health and product progress; it does not change the scan's terminal result. crates/…/foundations.rs• L107-127, crates/…/health.rs• L104-125.

The service path is deliberately narrower than the local roadmap. Only a real Git work tree with the required consent contributes foundation data, and an item is not reported as passing when the scan did not judge it. This keeps account progress tied to evidence rather than to an incomplete scan. crates/…/foundations.rs• L117-126, crates/…/health.rs• L57-67.

References: crates/…/foundations.rs• L107-127 crates/…/health.rs• L104-145 crates/…/health.rs• L210-229

Taste workflow

Taste is a user's standing design preference, separate from product facts and project design rules. The workflow makes that preference available to an agent while keeping the user in control of consent, refresh, and removal.

impeccable loop connect can add a marked taste instruction to the connected agent's user-level rule file. The instruction tells the agent to read taste once per design task, apply it where relevant, and record lasting user decisions. crates/…/loop_taste.rs• L1-12.

The block is fixed guidance rather than a copy of the user's rules. It is added only to connected agent files and can be updated or removed without changing text outside its markers. Interactive connects ask once. Explicit flags control non-interactive use, and disconnect removes the block and forgets the recorded answers. crates/…/loop_connect.rs• L1325-1468, crates/…/loop_connect.rs• L1475-1532.

References: crates/…/loop_taste.rs• L9-18 crates/…/loop_taste.rs• L44-93 crates/…/loop_connect.rs• L1325-1468 crates/…/loop_connect.rs• L1475-1532

Taste service refresh

After a normal CLI entry point, the runtime may start a quiet refresh when the user is signed in with taste access and the local copy is missing or old. The refresh is detached from the visible command so guidance maintenance does not slow normal CLI work. crates/…/router.rs• L20-42, crates/…/setup_report.rs• L14-32.

The account service returns a small versioned snapshot with a state and bounded rules. A ready snapshot becomes the local cache. Empty, paused, and plan states keep no active rules. The cache belongs to the current account issuer and sign-in, so logout, a changed sign-in, or a lost grant cannot leave old guidance active. crates/…/taste.rs• L30-41, crates/…/taste.rs• L64-115.

The context runtime reads only a recent ready cache. It turns the rules into agent context as data, not as higher-priority instructions. Project PRODUCT.md and DESIGN.md remain authoritative when they disagree with taste. crates/…/taste.rs• L7-12, crates/…/taste.rs• L74-95.

References: crates/…/taste.rs• L16-27 crates/…/taste.rs• L74-115 crates/…/taste.rs• L7-12 crates/…/taste.rs• L74-95

World workflow

A world is a service-managed visual direction that can start a project with a coherent design system. It is more than a palette: the seed carries the visual rules that later agent work should reuse across pages.

World seed

impeccable world <id> asks the account service for a finished seed. The response includes a human-readable DESIGN.md and structured sidecar data. The CLI validates that the response belongs to the requested world before it writes anything. crates/…/world.rs• L1-20, crates/…/world.rs• L88-116, crates/…/world.rs• L201-243.

The seed is placed beside the product context that the native resolver selected. It records the chosen world so later context and design-seed workflows can preserve that direction. The sidecar also records the source world for structured readers. crates/…/world.rs• L41-74, crates/…/world.rs• L575-620.

The --print form returns the seed for an agent or engineer to merge into an existing design system. This supports deliberate adoption without making the world command a destructive redesign tool. crates/…/world.rs• L22-39, crates/…/world.rs• L223-231.

References: crates/…/world.rs• L1-20 crates/…/world.rs• L41-116 crates/…/world.rs• L201-243 crates/…/world.rs• L575-620

Existing design boundary

World seeding stops when the project already has a recognized design system. The CLI checks the resolved context and project root before contacting the service, then points the user to --print for a merge. This protects an existing visual authority and avoids an unnecessary account request. crates/…/world.rs• L118-126, crates/…/world.rs• L168-199.

The same boundary applies in workspaces and fallback context folders. A seed must not hide inherited product truth or create a second design authority in a child project. The user must run from the correct project boundary or save the printed seed where it belongs. crates/…/world.rs• L160-194, crates/…/world.rs• L143-185.

The write is create-only. If a new seed cannot finish, files created by that attempt are removed, while existing files remain unchanged. This keeps a partial service response or a write error from becoming a misleading design system. crates/…/world.rs• L575-620.

References: crates/…/world.rs• L118-126 crates/…/world.rs• L160-199 crates/…/world.rs• L575-620 crates/…/world.rs• L71-125 crates/…/world.rs• L143-185

Design record synchronization

The seeded or existing design system can also support account-side design health. This path sends the design record and selected structured metadata only when the user has enabled the design sync setting and the account grant permits it.

Design contents sync

impeccable health design on|off controls whether DESIGN.md changes can be recorded for the signed-in account. A full detect may then prepare the current design document and selected sidecar metadata, send it within a short bound, and report success separately from detector output. crates/…/design.rs• L9-50, crates/…/design.rs• L61-115.

The sync path is best effort and bounded. It reads only the resolved design record, limits its size, keeps account state and consent stable across the upload, and caches the content digest so unchanged material is not sent again. crates/…/design.rs• L112-170, crates/…/design.rs• L181-249.

This creates a service view of the design system without making the service the project's local authority. The project files remain the source used by context and agent operations. crates/…/design.rs• L351-375, crates/…/health.rs• L145-161.

References: crates/…/design.rs• L9-50 crates/…/design.rs• L61-115 crates/…/design.rs• L181-249 crates/…/design.rs• L351-375

CLI and agent connection

The router exposes the workflows as native commands and schedules only the quiet account refreshes from ordinary context-aware entry points. Visible commands remain local and useful when the account is unavailable; service work adds guidance or records progress without becoming a requirement for design editing. crates/…/router.rs• L20-42, crates/…/router.rs• L66-105.

Agents receive the resulting direction through two paths. Taste enters user-level agent guidance and the context block. A world enters project design records that later design-seed and component workflows resolve as durable visual context. This keeps personal preference, project identity, and route-level choices related but distinct. crates/…/taste.rs• L7-12, crates/…/world.rs• L41-74.

Change checklist

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

  • Keep foundation item names, local scan states, detector evidence, account payloads, and roadmap ordering aligned.
  • Keep the local foundation source's bounded walk, tracked-file view, repository-top configuration, and scan entry points aligned with the shared scan contract.
  • Keep foundation consent and health-scope checks aligned so a local scan never uploads data without the matching grant.
  • Keep taste block wording, MCP method names, connect flags, disconnect cleanup, and context cache semantics aligned.
  • Keep issuer, sign-in, grant, freshness, and opt-out rules aligned across taste refresh and context loading.
  • Keep world response fields, world markers, sidecar provenance, context resolution, existing-design checks, and create-only writes aligned.
  • Keep design sync settings, generation checks, content bounds, digest cache, and service upload behavior aligned.
  • Keep native router verbs and detached worker scheduling separate from visible command output and exit status.

Important failure modes

TriggerConsequenceGuard
A scan cannot judge an itemThe account can show a false passOmit the item instead of inferring success
Foundations consent or the required grant is missingLocal checks still work, but no foundation record is sentCheck the saved sign-in grant before building the upload
The local scan runs outside the right project or cannot read its Git viewFoundation results can miss shared repository evidence or lose the tracked-file basisKeep the selected root and repository-top configuration source distinct, and treat Git failure as unproven evidence
Taste cache is stale, for another issuer, or not readyThe agent receives no standing taste guidanceRequire a recent ready cache for the expected account
A taste grant is revoked during refreshOld rules can remain active after access is lostClear the copy for the same sign-in when the grant is revoked
A world seed conflicts with an existing design recordA project can gain two competing visual authoritiesStop before the request or write and use --print for a merge
A world response names another world or has an unreadable shapeLater rolls can carry the wrong world identityValidate the response and require a matching world marker
A world write fails after one file is createdA partial seed can look like a complete design systemCreate files only when absent and remove files made by the failed attempt
Design sync is disabled or its generation changes during uploadOld design content can be sent after the user's choice changedRecheck consent and generation before sending and caching
The service is unavailable during a normal design commandThe account view is delayed, but local design work can continueKeep refresh and sync best effort and bounded

Key files

FileWhy to read it
crates/…/router.rsNative command routing and detached refresh scheduling
crates/…/foundations.rsFoundation roadmap, scan states, and account handoff
crates/…/local.rsLocal project evidence source and bounded repository scan
crates/…/loop_connect.rsTaste consent, agent targets, and disconnect behavior
crates/…/loop_taste.rsStable taste block and safe rule-file updates
crates/…/taste.rsAccount taste refresh, cache state, and grant handling
crates/…/taste.rsOffline cache validation and agent context output
crates/…/world.rsWorld retrieval, context placement, non-destructive seeding, and write safety
crates/…/design.rsDesign record sync and bounded account upload
crates/…/health.rsConsent gates and the relationship between scans and account health
skill/…/foundations.mdUser-facing foundation roadmap and fix contract
skill/…/new-work-world.mdAgent-facing rules for creating and replacing visual worlds
docs/design-seed-generation.mdDownstream direction and surface decision workflow
docs/agent-protocol-services.mdRelated account and agent service boundaries