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
--directionhandling 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
| Trigger | Consequence | Guard |
|---|---|---|
| PRODUCT.md is missing | The system refuses to produce an ordinary seed because its candidates would lack product facts | Complete product initialization before running a new direction or surface round |
| Local catalog validation fails and the roll service is unreachable | The workflow receives a degraded hand with no challengers or quality-bar boards | Tell the user that the roll is degraded and retry through a network-enabled command path |
A mode file lacks Directions or Comps | The roll continues without mode guidance, so directions and compositions lack the mode contract | Read the named reference file before writing the decision cards |
| Composition support is off | The hand has no composition inputs even when the catalog supplied them | Enable composition support before a comp-led decision round |
| A seed reference has no local ledger | The original roll key cannot be recovered and the choice report is skipped | Re-run with the original key or roll again locally |
Runtime files under .impeccable/ are already tracked by Git | Seed keys, dealt hands, or choices can enter a commit despite the ignore file | Remove tracked runtime paths from the index and keep local files ignored |
| A decision payload omits card identity or challenger catalog identity | The page cannot validate the hand or report the selected source safely | Include the required card kind and catalogId values before serving or updating the page |
Key files
| File | Why to read it |
|---|---|
| crates/…/concept_seed.rs | Main seed lifecycle: input checks, source choice, candidate rendering, presentation guidance, telemetry handling, and record handoff |
| crates/…/seed_text.rs | User-facing contracts for directions, surfaces, registers, mode rules, build paths, and degraded rounds |
| crates/…/roll_selection.rs | Selection model for approved challengers and composition candidates |
| crates/…/catalog.rs | Catalog and review boundary that decides whether local design material is usable |
| crates/…/serve_question.rs | Decision-page payload validation, roll records, answer handling, and runtime-state protection |
| crates/…/telemetry.rs | Seed ledger, round state, opt-out behavior, and choice-report lifecycle |
| crates/…/seed.rs | Shared salted seed-reference and ledger-location rules |
| crates/…/build_phase.rs | Downstream build-state contract that records the seed reference without storing the raw key |