Shapes

Shapes

x new <name> --shape <shape> starts an app from a shape instead of the default dashboard and example slice. One flag, still zero questions. A shape is an overlay over the same scaffold x new writes (packages/cli/src/templates/shapes/): it leaves files out, edits a few, adds its own, and runs the generator that owns a capability it needs. Every guard, every gate step and the 95% coverage floor are the default scaffold's. No shape waives one.

bunx create-ultimate myblog --shape blog
cd myblog && bun run setup && bun run dev

Shape	Writes	Leaves out
none (default)	the dashboard, the post example slice (two actions, a live query, a job, a form island), /admin	—
api	the post slice as an API: createPost, archivePost, the live postList, the reindexPost job; an org API key (apps/web/app/keys/) on a /v1 bearer mount cut by API_KEY_SCOPES; the complete openapi.json (defineApi({ openapi })); MCP mounted; /admin	every page but the error documents and the offline fallback, every island, the shell, the dashboard
dashboard	the default app — dashboard, the post table at /posts (live list, a job), /admin — plus a detail page per row (apps/web/app/posts/[id]/, render: 'ssr', read through a single query, postById) and sign-in, written by x g sign-in --password itself once the files land	nothing of the default; site/ stays a home page, the offline fallback and the error documents
blog	a post entity with no tenant (apps/web/app/post/), two public reads (publishedPosts, publishedPost), an isr index at / and one page per post at /posts/<slug>, both budget: { js: '0kb' }, a seed with one published post and one draft. Posts are written at /admin	app/ pages, every island, the shell, the dashboard

What no shape writes, by rule (axiom 8): no plan, tier or quota; no payment, mail or model provider and no provider SDK; no model id in code. packages/cli/src/templates/shapes/shapes.test.ts refuses a provider name or a model id in any shape's output, and X_NOT_IMPLEMENTED anywhere in it.

What happens next

Each shape's README.md names the shape in one line above the three commands every app starts with (bun run setup, bun run dev, bun run verify). Its CLAUDE.md (and AGENTS.md, the same file) adds exactly one line naming the shape. From there, the generators are the default scaffold's: bunx x g --help.

Shape	Your first feature
api	bunx x g resource invoice: a slice with actions, a query and a job. Add its operations to API_KEY_SCOPES to reach them on /v1
blog	write a post at /admin. A new page: bunx x g route about --surface site
dashboard	bunx x g resource invoice --admin: a table, its form and its /admin screens. A detail page for it: copy apps/web/app/posts/[id]/

Refusals

Code	When	Fix
X_NEW_SHAPE_UNKNOWN	--shape names no shape	bunx @ultimat3/cli help new lists them
X_NEW_SHAPE_CONFLICT	--shape with --no-example	drop --no-example: a shape is its own example
X_NEW_SHAPE_GENERATE_FAILED	a generator the shape runs in the new app (dashboard: x g sign-in --password) refused or failed	the cd … && bunx x g … --json it prints reproduces it; the framework's bug, so bun test packages/cli/src/templates/shapes

The first two refuse before a file is written, --dry-run included. A shape whose capability a generator owns runs that generator after its files land (ShapeOverlay.generate), never a copy of its output: --dry-run lists those runs under data.generate.

Where they are proved

Proof	Where
file set, leave-outs, no provider, every path CLAUDE.md names is written	bun test packages/cli/src/templates/shapes
each shape typechecks, lints and meets the error contract as written	the x new --shape <shape> variants in packages/cli/src/scaffold-fixture.ts, read by emitted-contract, emitted-routes, emitted-suites and scaffold-typecheck.contract
bun run setup && bun run verify green on the first pass, then again over every generator	scaffold-smoke in .github/workflows/ci.yml, one row per shape — scripts/ci-workflow-shape.test.ts refuses a shape with no row

As of 2026-11-06. Five shapes are planned (saas and agent beside these three); a shape is listed here, and accepted by --shape, only once its row gates green. saas waits on a member invite and a billing seam no slice has landed; agent on a model and provider an app names by environment alone, which no shipped seam takes without a provider SDK or a model row the scaffold would have to invent.