What is Project Builder?

Project Builder gives developers — and the AI agents working alongside them — deterministic code generation. A prompt produces something different every run; a schematic — a typed, testable file-mutation program — produces the same files, byte for byte, every time. You (or your agent) encode the change once, and from then on generation is a program you run, not an output you review.

Built to complement AI

As software craftsmen we want to build quality software — and quality starts with code that is predictable and repeatable. AI is a phenomenal collaborator, but it is inherently variable: the same request produces different code every run. Project Builder is designed as the complement to that variability: let the AI decide what to build, and let a schematic make the how deterministic.

That determinism pays off in two ways:

• Consistency. Every service, component, or module generated by a schematic follows the same structure and conventions — no drift between what the AI produced on Monday and what it produced on Friday.
• Time and money. A change encoded once runs in milliseconds, forever, with no tokens spent re-generating — and no review cycles spent re-validating output that should never have changed.

And it compounds: schematics grow with your codebase and your team. Every pattern you encode becomes a reusable, versioned building block that new teammates — human or agent — can run on day one.

What is a schematic?

A schematic is a small package that lives in your repository. It has three files:

• schema.json — the schematic’s typed inputs, the contract with whoever runs it.
• schema.generated.ts — an Input type generated from the schema, so your code is typed against the contract rather than a hand-written shape.
• factory.ts — your authoring logic: a function that receives the typed input and schedules file mutations — creating files, editing content, scaffolding whole folders of templates.

Once registered, you run it with builder execute <collection>:<schematic>, passing inputs as CLI flags. Because a factory is just a typed function, it can also be executed entirely in memory by the testing harness — no CLI, no disk — which is what makes schematics testable like any other code. See Your first schematic for the end-to-end walkthrough.

The golden rule: never improvise a schematic

A schematic is an automation of code that already works. Have the code running and tested first — then encode it as a schematic. Premature automation spends time and resources on something you may only ever run once: extract a schematic when a pattern has proven itself, never before.

Curious about the machinery — the SDK–engine conversation, instruction records, and the AST story? That has a page of its own.

Design principles you’ll feel as a user

• Idempotency. Factories re-run against already-generated projects, so mutations are written to be safe on repeat: read the tree first, then create or update — and skip the edit when your marker, import, or entry is already present.
• Fail-closed. Verbs that write to a new path (create, rename, move, copy, copyIn, scaffold) reject on a collision with an existing path; overwriting is always a deliberate opt-in via force: true.
• All-or-nothing runs. Nothing touches disk while your factory runs — a thrown error before it returns means nothing is written at all, and your tree is left exactly as it was.

Where next

How it works

The SDK–engine conversation, flush, and the language-agnostic bridge — How it works.

Install it

Get the builder CLI and Bun set up in a couple of commands — Installation.

Build your first schematic

From builder init to a running, idempotent generator — Your first schematic.