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 and 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 capable collaborator, but its output is variable: the same request produces different code every run. Project Builder is designed to complement 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, so what the AI produces on Friday does not drift from what it produced on Monday.
• Time and money. A change encoded once runs in milliseconds on every run. You spend no tokens regenerating it and no review cycles re-validating output that should never have changed.

Schematics also 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 such as creating files, editing content, and 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, without the CLI or the disk. That 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.

The machinery (the SDK–engine conversation, instruction records, and the AST story) 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. If it throws before it returns, 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.

Evaluating Project Builder in an existing repository? You can try it without adding the SDK to package.json. See Evaluate without adopting the SDK.