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:
failingmeans the project shows evidence of a problem.checkedmeans 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.
Taste consent and agent handoff
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
| Trigger | Consequence | Guard |
|---|---|---|
| A scan cannot judge an item | The account can show a false pass | Omit the item instead of inferring success |
| Foundations consent or the required grant is missing | Local checks still work, but no foundation record is sent | Check the saved sign-in grant before building the upload |
| The local scan runs outside the right project or cannot read its Git view | Foundation results can miss shared repository evidence or lose the tracked-file basis | Keep 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 ready | The agent receives no standing taste guidance | Require a recent ready cache for the expected account |
| A taste grant is revoked during refresh | Old rules can remain active after access is lost | Clear the copy for the same sign-in when the grant is revoked |
| A world seed conflicts with an existing design record | A project can gain two competing visual authorities | Stop before the request or write and use --print for a merge |
| A world response names another world or has an unreadable shape | Later rolls can carry the wrong world identity | Validate the response and require a matching world marker |
| A world write fails after one file is created | A partial seed can look like a complete design system | Create files only when absent and remove files made by the failed attempt |
| Design sync is disabled or its generation changes during upload | Old design content can be sent after the user's choice changed | Recheck consent and generation before sending and caching |
| The service is unavailable during a normal design command | The account view is delayed, but local design work can continue | Keep refresh and sync best effort and bounded |
Key files
| File | Why to read it |
|---|---|
| crates/…/router.rs | Native command routing and detached refresh scheduling |
| crates/…/foundations.rs | Foundation roadmap, scan states, and account handoff |
| crates/…/local.rs | Local project evidence source and bounded repository scan |
| crates/…/loop_connect.rs | Taste consent, agent targets, and disconnect behavior |
| crates/…/loop_taste.rs | Stable taste block and safe rule-file updates |
| crates/…/taste.rs | Account taste refresh, cache state, and grant handling |
| crates/…/taste.rs | Offline cache validation and agent context output |
| crates/…/world.rs | World retrieval, context placement, non-destructive seeding, and write safety |
| crates/…/design.rs | Design record sync and bounded account upload |
| crates/…/health.rs | Consent gates and the relationship between scans and account health |
| skill/…/foundations.md | User-facing foundation roadmap and fix contract |
| skill/…/new-work-world.md | Agent-facing rules for creating and replacing visual worlds |
| docs/design-seed-generation.md | Downstream direction and surface decision workflow |
| docs/agent-protocol-services.md | Related account and agent service boundaries |