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-seed-generation

Design seed generation

Design seed generation turns product context into a small set of visual directions or surface structures for a target-project workflow. It creates a repeatable decision round, adds guidance for the work mode, and records enough local state to connect the choice to later briefs, builds, and choice reports.

This page is a child of Rust CLI runtime. The wider native workspace is described in Native runtime and CLI, while Agent protocol services covers the service boundary and Component composition operations covers later build work.

Seed lifecycle

Product gate

The seed process starts only when the target project has product truth in PRODUCT.md. Product facts keep each direction tied to the real product, so a missing product file stops a normal roll instead of allowing an ungrounded visual result. crates/…/concept_seed.rs• L742-745

References: crates/…/concept_seed.rs• L742-745

Roll inputs

Each roll combines a seed key with a scope and optional workflow controls. The key makes the hand repeatable. The scope selects a direction round or a surface round. A re-roll selects a new round from the same key. A register can steer a direction re-roll toward a safer or bolder range. Mode, composition grain, platform, and candidate count further narrow the hand when the workflow supplies them. crates/…/concept_seed.rs• L388-401, crates/…/concept_seed.rs• L436-475

The CLI exposes this system through impeccable concept-seed, which the native command dispatcher routes to the context runtime. crates/…/main.rs• L57-70

References: crates/…/concept_seed.rs• L388-401 crates/…/concept_seed.rs• L436-475 crates/…/main.rs• L57-70

Candidate sources

The system first tries a valid local catalog of approved concepts and compositions. If that catalog is not usable, it asks the roll service for candidates. If neither source can provide challengers, it still produces a degraded text-only hand grounded in the project. The result states which source supplied the hand. crates/…/concept_seed.rs• L501-589

Local catalog material enters a hand only after its catalog and review checks pass. Approval state, review coverage, mode limits, and inspiration tiers then shape the available candidates. crates/…/catalog.rs• L186-230, crates/…/catalog.rs• L246-435

References: crates/…/concept_seed.rs• L501-589 crates/…/catalog.rs• L186-230 crates/…/catalog.rs• L246-435

The following flow shows how project truth becomes a decision hand and then a build-facing record.

flowchart LR
    A[PRODUCT.md and target context] --> B[Validate roll inputs]
    B --> C{Candidate source}
    C -->|valid local catalog| D[Select approved candidates]
    C -->|roll service| D
    C -->|no catalog or service| E[Degraded grounded hand]
    D --> F[Render direction or surface guidance]
    E --> F
    F --> G[Serve decision page]
    G --> H[Record roll and choice state]
    H --> I[Surface brief or build workflow]

Decision scopes

Direction rounds

A direction round chooses a visual world and its first-surface expression as one decision. The roll assigns one product-grounded direction and can show challengers beside it. A challenger wins only when its result improves audience identification and product clarity. Its useful discipline may inform the assigned direction without copying its surface style. crates/…/seed_text.rs• L4-14

The assigned direction guides the build workflow. It is not a user-facing ranking label. The user can accept it, choose a permitted alternative, choose the canon exit, or request a re-roll through the decision page. crates/…/seed_text.rs• L4-8, crates/…/serve_question.rs• L123-146

References: crates/…/seed_text.rs• L4-14 crates/…/serve_question.rs• L123-146

Surface rounds

A surface round chooses the structure for a specific task while preserving the committed visual identity. It deals three structural candidates, marks one as the lead, and lets the user lock one composition. Composition seeds can make the proposed structure visible before implementation. crates/…/seed_text.rs• L6-14, crates/…/seed_text.rs• L91-93

The hand can favor a grain such as product, flow, view, or region and can filter for web, iOS, or Android work. It preserves family variety before filling remaining slots, so the decision challenges habitual layout without becoming arbitrary. crates/…/roll_selection.rs• L8-9, crates/…/roll_selection.rs• L282-388

Composition candidates are included in the rendered seed only when composition support is enabled. This keeps a surface decision explicit about whether it has visual composition inputs or only structural guidance. crates/…/concept_seed.rs• L592-619

References: crates/…/seed_text.rs• L6-14 crates/…/seed_text.rs• L91-93 crates/…/roll_selection.rs• L8-9 crates/…/roll_selection.rs• L282-388 crates/…/concept_seed.rs• L592-619

Re-roll registers

Re-rolls exclude candidates shown in earlier rounds and derive a new hand from the same key. A safer round suspends the assignment and offers a small familiar lineup. A bolder round puts the dealt challengers first and lets the first dealt challenger lead. These registers are user steering rather than an agent-selected preference. crates/…/seed_text.rs• L39-43, crates/…/serve_question.rs• L144-146

References: crates/…/seed_text.rs• L39-43 crates/…/serve_question.rs• L144-146

Mode guidance

Mode rules

The supported modes are persuade, operate, read, and experience. A mode supplies separate guidance for directions and compositions through its Directions and Comps sections. experience uses the persuade rule file. The other modes use their matching files. A missing file or section does not stop the roll. Instead, the result tells the workflow to read the unavailable guidance before writing directions or compositions. crates/…/catalog.rs• L18, crates/…/concept_seed.rs• L24-30, crates/…/concept_seed.rs• L54-67

Mode guidance has priority over shared seed guidance for the current surface. An explicit user or brief decision still wins. This gives the target project a stable task posture without overriding product truth or a confirmed choice. crates/…/seed_text.rs• L12-20

References: crates/…/catalog.rs• L18 crates/…/concept_seed.rs• L24-30 crates/…/concept_seed.rs• L54-67 crates/…/seed_text.rs• L12-20

Build path guidance

The presentation block tells the workflow whether the round is code-led or comp-led. operate and read surfaces are always code-led. persuade and experience surfaces follow the recorded project default. When no default exists, they use the comp-led path when image generation is available. The decision page can flip the path for the current session, but that flip does not silently change the project default. crates/…/concept_seed.rs• L70-105, crates/…/seed_text.rs• L95-99

The path changes what the chosen card must provide. Code-led work uses a first-viewport HTML sketch as the visible composition reference. Comp-led work declares a decision comp and generates it after the page is served. A selected comp is binding for a comp-led build. A code-led build carries its ambition in the direction contract and can use a rendered comp later as a critique reference. crates/…/seed_text.rs• L85-93, crates/…/serve_question.rs• L151-167

References: crates/…/concept_seed.rs• L70-105 crates/…/seed_text.rs• L85-99 crates/…/serve_question.rs• L151-167

Decision presentation

Decision page handoff

Every valid roll ends with instructions for presenting the hand to the user. The workflow writes an options payload, starts or updates serve-question, waits for the user’s answer, and uses the structured question tool only when the decision page cannot serve or wait. A re-roll updates the open page instead of starting a second decision context. crates/…/seed_text.rs• L73-83, crates/…/seed_text.rs• L107

Each card carries its decision identity, such as assigned direction, pick, challenger, grounded direction, or dealt structure. A challenger also carries its catalog identity. These fields let the page validate the hand and let later choice reporting distinguish catalog material from an agent-authored grounded option. crates/…/serve_question.rs• L369-377, crates/…/serve_question.rs• L1184

References: crates/…/seed_text.rs• L73-83 crates/…/seed_text.rs• L107 crates/…/serve_question.rs• L369-377 crates/…/serve_question.rs• L1184

Runtime records

The roll record binds the latest hand to the next decision page. It stores the scope, re-roll number, seed reference, and any dealt worlds. The seed ledger keeps the key behind that reference and, when telemetry is enabled, the API round details needed for one choice report. These are local runtime records under .impeccable/questions/, not project design content. crates/…/serve_question.rs• L380-401, crates/…/serve_question.rs• L470-514, crates/…/telemetry.rs• L205-224

The roll still runs when telemetry is disabled. The remote request is marked as opted out, while API round details and choice reports are not stored or sent. The ledger keeps only the local state needed to reproduce the seed reference. crates/…/concept_seed.rs• L144-177, crates/…/concept_seed.rs• L789-800

Committed workflow records use a salted seed:<16 hex> reference instead of the raw roll key. The reference resolves only on a machine that holds the matching local ledger. A missing ledger requires the original key or a new roll. If no valid salt can be kept, the system records that no reference is available instead of creating an unsalted public hash. crates/…/seed.rs• L1-14, crates/…/seed.rs• L203-281, crates/…/concept_seed.rs• L755-801

References: crates/…/serve_question.rs• L380-401 crates/…/serve_question.rs• L470-514 crates/…/telemetry.rs• L205-224 crates/…/concept_seed.rs• L144-177 crates/…/concept_seed.rs• L789-800 crates/…/seed.rs• L1-14 crates/…/seed.rs• L203-281 crates/…/concept_seed.rs• L755-801

Change checklist

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

  • Keep CLI dispatch, seed input validation, rendered seed text, and decision-page payload fields aligned.
  • Keep local catalog selection and remote roll response fields aligned with the roll record and seed ledger fields.
  • Keep mode rule file names, required section names, and presentation guidance aligned with the installed reference files.
  • Keep composition enablement aligned with the surface payload and the build path that consumes it.
  • Keep seed reference creation, ledger lookup, brief recording, and build-phase --direction handling on the same salted-reference rule.
  • Keep build-path defaults aligned across project config, presentation guidance, decision payloads, and the answer that reports a session-only flip.

Important failure modes

TriggerConsequenceGuard
PRODUCT.md is missingThe system refuses to produce an ordinary seed because its candidates would lack product factsComplete product initialization before running a new direction or surface round
Local catalog validation fails and the roll service is unreachableThe workflow receives a degraded hand with no challengers or quality-bar boardsTell the user that the roll is degraded and retry through a network-enabled command path
A mode file lacks Directions or CompsThe roll continues without mode guidance, so directions and compositions lack the mode contractRead the named reference file before writing the decision cards
Composition support is offThe hand has no composition inputs even when the catalog supplied themEnable composition support before a comp-led decision round
A seed reference has no local ledgerThe original roll key cannot be recovered and the choice report is skippedRe-run with the original key or roll again locally
Runtime files under .impeccable/ are already tracked by GitSeed keys, dealt hands, or choices can enter a commit despite the ignore fileRemove tracked runtime paths from the index and keep local files ignored
A decision payload omits card identity or challenger catalog identityThe page cannot validate the hand or report the selected source safelyInclude the required card kind and catalogId values before serving or updating the page

Key files

FileWhy to read it
crates/…/concept_seed.rsMain seed lifecycle: input checks, source choice, candidate rendering, presentation guidance, telemetry handling, and record handoff
crates/…/seed_text.rsUser-facing contracts for directions, surfaces, registers, mode rules, build paths, and degraded rounds
crates/…/roll_selection.rsSelection model for approved challengers and composition candidates
crates/…/catalog.rsCatalog and review boundary that decides whether local design material is usable
crates/…/serve_question.rsDecision-page payload validation, roll records, answer handling, and runtime-state protection
crates/…/telemetry.rsSeed ledger, round state, opt-out behavior, and choice-report lifecycle
crates/…/seed.rsShared salted seed-reference and ledger-location rules
crates/…/build_phase.rsDownstream build-state contract that records the seed reference without storing the raw key