Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(cli): AST-048 build always recommends a template to start from (#6769)

Joey1ffe66db8549
diff --git a/docs/specs/AST-048-build-recommendation/spec.md b/docs/specs/AST-048-build-recommendation/spec.md
new file mode 100644
index 0000000000..66bb7b0f18
--- /dev/null
+++ b/docs/specs/AST-048-build-recommendation/spec.md
@@ -0,0 +1,210 @@
+---
+schema_version: 4
+template_version: 1
+kind: system-spec
+id: spec:AST-048
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: josephfarina
+approved_at: 2026-09-29
+phase: accepted
+owners: [josephfarina]
+affects_architecture: [architecture:cli-surface]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: [cli]
+---
+
+# Build recommendation system spec
+
+## Intent
+
+A builder, a person or a coding agent, describes the UI they want in words and
+asks `astryx build` where to begin. A page template already carries the frame,
+the spacing, and the section rhythm the system decided on; a page composed from
+components has to rediscover all of that. So build's answer always starts from
+a template: it names one page template to scaffold, the command that scaffolds
+exactly that template, the next best templates, and the blocks and components
+that fill it.
+
+This record owns what build recommends and how the recommendation reads, in
+text and JSON. `spec:AST-017` owns compatibility and response-field rules,
+`spec:AST-042` owns command admission, search owns its own ranking and output,
+and template owners own what each template is.
+
+## Non-goals
+
+- How candidates are ranked. Word matching, weights, thresholds, and the
+ ranking algorithm are implementation; this record states what the
+ recommendation must be and how a reader can act on it.
+- Which templates exist, or how they look.
+- Writing files. Build recommends; `astryx template` scaffolds.
+- New commands, options, or flags. Build's options and exit codes are not
+ changed by this record.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — Always one start.** A build that can return pages MUST name exactly
+ one page template to start from, chosen among the ready page templates the
+ project can scaffold, including the ones its integrations provide. A build
+ narrowed to components or hooks names no start, and neither does a project
+ that offers no page template.
+- **FR2 — A shell when nothing leads.** When no template has the evidence to
+ lead, the start MUST be the neutral app shell, or a blank page template when
+ the project has no shell. The start never falls back to "compose from
+ components".
+- **FR3 — A part starts where it lives.** A request for a part of a page (a
+ control, a state, a widget, a section) MUST start from the page template the
+ request places that part in, when the request gives that page, and from the
+ app shell (FR2) when it gives no page. The blocks and components in the kit
+ carry the part itself.
+- **FR4 — Never an unready start.** A template marked not ready MUST NOT be the
+ start or an alternative. When search matches one directly, the start's
+ reason MUST name it and say the start is the closest ready template or the
+ app shell instead.
+- **FR5 — The start is exact and runnable.** The start and every alternative
+ MUST carry the scaffold command that selects exactly that template in the
+ project where build ran. A template an integration provides in place of a
+ Core one is selected the way `astryx template` addresses it, and the command
+ names the page kind so a block with the same id cannot make it ambiguous.
+- **FR6 — The start says why.** The start MUST carry a basis and a one-line
+ reason. The basis is `direct` when the start is also search's direct match,
+ `closest` when no template is exactly this page, and `fallback` for the
+ shell.
+- **FR7 — The builder can overrule.** Beside every start, build MUST offer the
+ next best page templates, at most two, each with its scaffold command.
+- **FR8 — The kit fills the template.** Build MUST list the blocks that fill
+ the start before the components, and name the always-on frame and
+ foundation components.
+- **FR9 — An existing page is kept.** Build's text output MUST tell a builder
+ who is changing a page they already have to keep it and use only the blocks
+ and components.
+- **FR10 — The recommendation is data.** The JSON response MUST carry the
+ recommendation itself (the start with its name, command, basis, reason, and
+ alternatives), so no caller derives it from other fields.
+- **FR11 — Additive JSON.** Changes to the recommendation MUST keep the build
+ JSON additive under `spec:AST-017`: new data arrives as new fields, and
+ every existing field keeps its shape and meaning. A ranking change may move
+ values (which templates, blocks, or components appear, and in what order);
+ it does not change a field's shape or meaning.
+- **FR12 — Text leads with the start.** Build's text output MUST lead with the
+ start, then the alternatives, then the blocks, then the components. Every
+ response field keeps a text projection as `spec:AST-017` requires: short by
+ default, and whole under `--verbose`.
+- **FR13 — Every agent-facing surface agrees.** The build playbook, the
+ generated agent docs, and the consumer guides that describe building a page
+ MUST describe the same workflow: scaffold the named template, fill it with
+ blocks, and compose only what is left. No surface tells builders to compose
+ a page from primitives first.
+
+### Platform support
+
+- Supported floor: every shell and package manager the CLI already supports.
+ Commands are printed with the project's run prefix in text and without it in
+ JSON, as the CLI does for every command it prints.
+- Unsupported behavior: none; build writes nothing, so there is nothing to
+ degrade.
+- Browser evidence: not applicable; the recommendation is CLI output.
+
+## Current-state impact
+
+Before this record, build named a template to scaffold only when one matched a
+request almost by name. A looser match got a layout skeleton to use as a
+reference, and a request with no page match was told to frame with an app
+shell component and compose from primitives.
+
+When this ships:
+
+- the `build.kit` response gains the start, with its command, basis, reason,
+ and alternatives; every existing field keeps its shape and meaning;
+- build's text leads with the start and the alternatives, then the blocks and
+ the components;
+- the build playbook, the generated agent docs, and the consumer guides that
+ describe building a page start from a template.
+
+`architecture:cli-surface` keeps the command envelope and its rules unchanged.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ---------- | ----------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| FR1, FR2 | Build kit tests | a request that names a template; a loose request; a request no template fits | A page build with no start, or a start that is not a page template |
+| FR3 | Build kit tests | a part placed in a page; a part with no page | A part with no page starting from a page template |
+| FR4 | Build kit tests | search's direct match is not ready | An unready template as the start or an alternative, or a reason that hides it |
+| FR5 | Template integration tests | an integration template that replaces a Core one; a block sharing a page template's id | A start or alternative command that selects another template, or none |
+| FR6, FR7 | Build kit tests | direct, closest, and fallback starts | A start without a basis or reason, or without its alternatives |
+| FR8, FR12 | Text field tests | default and `--verbose` text for a build with every field populated | A response field the text never shows, or text out of the required order |
+| FR9 | CLI text tests | any page build | Text without the keep-your-page line |
+| FR10, FR11 | Response type and build tests | the canonical response type, the response docs, and existing fields on a page build | A missing recommendation field, or an existing field whose shape changes |
+| FR13 | Playbook and agent docs tests | the playbook steps and the generated agent docs block | A surface that tells builders to compose a page from primitives before a template |
+
+## Decision log
+
+### DEC-1 — Start from a template, always
+
+**Reference:** `spec:AST-048/DEC-1`
+**Decider:** `josephfarina`, `2026-09-28`
+
+Templates carry the spacing judgment and a kit of loose parts does not, so the
+recommendation is always a full page template, and blocks and components fill
+it.
+
+Rejected: naming a template only on an exact match and a layout reference
+otherwise, which leaves most builders composing from primitives.
+
+### DEC-2 — A shell when nothing leads
+
+**Reference:** `spec:AST-048/DEC-2`
+**Decider:** `josephfarina`, `2026-09-28`
+
+When no template has the evidence to lead, the start is a neutral app shell,
+so even an unusual request starts from a frame the system decided.
+
+Rejected: no start at all, which hands the builder primitives; and the best
+weak match, which lets one incidental word pick the page.
+
+### DEC-3 — The builder can overrule the pick
+
+**Reference:** `spec:AST-048/DEC-3`
+**Decider:** `josephfarina`, `2026-09-28`
+
+The builder judges meaning better than word matching does, so every start
+comes with the next best templates and their commands.
+
+Rejected: a single pick with no alternatives.
+
+### DEC-4 — A part starts where it lives
+
+**Reference:** `spec:AST-048/DEC-4`
+**Decider:** `josephfarina`, `2026-09-29`
+
+A part is built inside a page. When the request gives that page, its template
+is where the part goes; when it gives none, the app shell is the frame, and the
+blocks and components carry the part.
+
+Rejected: starting a part from whichever page template shares a word with it,
+which scaffolds an unrelated page for a single control; and giving a part no
+start, which breaks DEC-1.
+
+### DEC-5 — The response stays additive
+
+**Reference:** `spec:AST-048/DEC-5`
+**Decider:** `josephfarina`, `2026-09-29`
+
+Callers read build's JSON, so the recommendation arrives as new data beside
+the existing fields, and ranking changes move values rather than shapes. Text
+may change with the recommendation.
+
+Rejected: replacing existing fields with the recommendation, which breaks JSON
+callers for a policy change they did not ask for.
+
+## Open questions
+
+- **OQ1 — How recommendation quality is measured.** Whether changes to what
+ build recommends must report their effect on a checked-in set of
+ representative requests with accepted templates, separately for requests
+ that describe a whole page and requests that describe a part of one.
+ (`human-design`)