Builder

The Builder makes a new brick from a conversation. It interviews you one decision at a time and turns your answers into a typed specification, the BrickSpec. A deterministic engine then generates the brick from that spec.

A language model is used for two narrow jobs: turning free-text answers into small pieces of JSON, and writing the body of one function at a time. Nothing the model writes is accepted until it typechecks and passes the acceptance tests derived from your spec.

Open it at builder.bricowerx.com. Using it currently needs an invite. Browsing the Vault of bricks it has built is open to everyone.

How a brick gets built

1. Interview

   Each question is a card. Every option lists its pros and cons, and one is marked as recommended. Click an option or type your own answer.

2. Specification

   The Spec tab fills in as you answer: purpose, architecture, data model, lifecycles, operations, interface and requirements. Approve spec and build unlocks only when the spec passes strict validation.

3. Build

   The engine scaffolds the brick from templates, asks a model for one function body at a time, and runs every gate. You watch it happen in the Build tab.

4. Use

   The finished brick gets a page with its files and traced requirements, a live preview, an install kit and a zip download.

The interview

The decisions, in order:

Writing operations precisely

Write an operation as a signature, and it is parsed exactly, with no model involved. The model only writes its examples:

markRead(notificationId): sets status to read, fails with NOT_FOUND
archive(notificationId): sets status to archived, fails with NOT_FOUND or ALREADY_ARCHIVED
listUnread(userId, limit): returns the newest unread notifications

What uses no model at all

• clicked choices, and typed answers that clearly match an option;
• the lifecycle, built in the order you declare it;
• the UI component, derived from the data model and operations;
• operations written as signatures.

Other free text goes through one small JSON extraction for that step. The engine fixes the usual small-model mistakes itself: it normalises names to camelCase or PascalCase, coerces loose types ("integer" becomes int), fills in seed rows, and drops examples that still fail. A step that still doesn’t validate after two corrections stays open and tells you exactly what to type.

What the spec must pass

• every operation is covered by a requirement (REQ-1, REQ-2, …);
• every example is checked against the declared types;
• capabilities belong to the host contract;
• domain operations are pure.

The build pipeline

Every build ends in one of three results:

Gates

The live build view

The Build tab streams the engine’s events and shows them as sheets that fill in while it works:

Builds can be replayed. Reload the page, or open /builder?build=<id>, to reconnect and replay a build from the start.

Using a generated brick

The brick has no imports outside its own folder, so the simplest install is to copy it. To put a Builder brick into your own Next.js app:

1. Get the files

   Download the zip from the brick’s page. It contains <name>/ (the brick), host-adapter/, the spec, the build report and an INSTALL.md written for that brick.

2. Install the brick

   Copy <name>/ to src/features/<name>/. Or, to version it, capture it into your Vault and add it with the commands from the install kit:

   brico capture <name> -p src/features/<name> --module-version 0.1.0 -y   # where the brick is
   brico add <name> -y                                                      # in the target app

3. Wire it to your app

   Copy the host-adapter/ files into your own composition folder, such as src/brico/, and connect them to your auth, routing, translations and storage. This is the one file per brick that knows about your app.

4. Verify

   npx vitest run src/features/<name>

   The brick ships its own tests and an in-memory repository, so they pass with no database.

Safety

• Static guard. Model-written code is checked before it runs. Imports, require, process, network access, timers, eval, the clock and randomness are rejected.
• Isolated tests. Tests run in a child process with no API keys in its environment and a hard timeout.
• Staging. Bricks are built outside the app. The app only sees a brick after it has passed every gate.
• No overwrites. An existing brick is never replaced.
• Access and limits. Invite-only access, per-person rate limits and request size checks. The shared public demo allows 3 builds an hour and 40 interview steps every 10 minutes per person.

Running your own Builder

The Builder runs its engine inside a long-lived Next.js server, because builds take minutes and run tsc and vitest. It can’t run on serverless hosting. Locally:

cd apps/workbench
npm install
cp .env.example .env.local      # add at least one provider key
npm run dev                     # http://localhost:3000/builder

Requires Node.js 20 or later. It only uses free model tiers, and any key you add becomes an automatic fallback. A local model through Ollama keeps it working when every cloud tier is rate-limited. All variables are in Configuration.

Current limits

• The Builder creates new bricks only. Editing an existing brick through its spec isn’t supported yet.
• Generated bricks target Next.js.
• Free-tier models vary. An operation the model can’t implement within its budget is left as a typed stub and reported. The brick is then partial, never silently wrong.