Skip to content

Build a builder

A builder takes slices that are ready to build and turns them into code. You do not write one from scratch: a builder is cratis build from the Cratis CLI, plus whatever writes the code. The CLI talks to Studio, keeps the work inside the limits you set, runs your checks and commits. What writes the code is your choice, and there are three good ways to do it.

WITH AI DETERMINISTIC DETERMINISTIC WITH AI ON TOP BUILD ORDER Ready slices CODING AGENT Writes all the code GENERATOR Writes all the code GENERATOR Structure CODING AGENT Judgment CHECKS Verify GIT Commit
Whatever writes the code, the same checks decide whether it is committed.

With AI

A coding agent such as Claude Code, Codex or Copilot CLI writes the slice from the order, inside the files and commands you permit. Choose it to get the most code for the least effort, on any stack. It needs good instructions and checks that catch what the agent gets wrong.

Deterministic

A generator of your own, in any language, turns the order into code. The same order always gives the same code. Choose it when your conventions are fixed and you want builds that are fast, cheap and repeatable. It writes only what you taught it.

Deterministic with AI on top

Your generator writes the predictable part: files, names, types, wiring and test skeletons. The agent fills in what needs judgment, such as business rules and test data. Choose it for the best of both: your structure every time, and the agent’s effort where it counts.

Not sure? Start with AI and a registered kit: it is the quickest way to see a slice built. When you notice the agent writing the same structure on every slice, move that structure into a generator and keep the agent for the rest.

STUDIO YOUR MACHINE build order outcome order.json outcome.json verifies, commits, pushes writes the code BUILD LOOP Ready slices CRATIS CLI cratis build run YOUR GENERATOR Any language GIT Your application's repository
The CLI holds the conversation with Studio. What writes the code only sees the order, the project and the outcome.
The Cratis CLI Your agent or generator
Registers the machine and waits for a maintainer to approve it Reads the build order
Asks Studio for work, and keeps the claim on a slice alive while you build Writes code into the project
Writes the order to a file, then starts the agent or runs the generator in the project Writes the outcome: built, nothing to do, blocked or failed
Keeps an agent to the files and commands you permit
Runs the verification commands you give it
Commits the files you report, pushes the branch and reports the outcome to Studio

The agent or generator never talks to Studio, never sees a credential and never runs Git.

  • The Cratis CLI. Install it with brew tap cratis/cratis && brew install cratis on macOS or Linux, or dotnet tool install -g Cratis.Cli anywhere .NET runs. See Getting started in the CLI documentation.
  • A clone of the application’s repository, with Git credentials that can push to it. Studio never hands a builder a repository credential.
  • A maintainer of the organization, to approve the builder once. See Connect a builder and approve it.
  • For AI, a coding agent installed and signed in on the machine: Claude Code, Codex, Gemini CLI, Copilot CLI, OpenCode, or any agent that speaks the Agent Client Protocol.

The order is Studio’s build order: the slices to build with their type, the Screenplay model they live in, each slice’s specifications as acceptance criteria, each slice’s description as a hint, and the feedback people left on the slices. The outcome says what came of it: built with the files written, the result of each specification and the assumptions made; nothingToDo; blocked with questions for a person; or failed.

Whichever way you build, the CLI treats the result the same:

  • After built or nothingToDo, verification runs. Every --verify command, and every verify command of a kit, runs in the project, in order. A command that exits with anything but 0 turns the outcome into failed, whatever the agent or generator said.
  • After built, the CLI commits. It commits the files that were reported and changed, on the branch Studio names or the branch you are on, and pushes it with your own Git credentials. With a kit, it commits only files inside the kit’s permitted paths.
  • Nothing is lost. Anything left uncommitted after a build is put away in a Git stash named after the order, and the CLI goes back to the branch it started on.
  • The project must be clean. cratis build run refuses to start in a repository with uncommitted changes, so a build commits only its own work.

A build kit describes a stack once: the instructions and prompt an agent gets, the files it may write and the commands it may run, the checks that must pass, and the files of a new project. A kit is what makes building with AI repeatable, and it works with a generator too. Without a kit, a build covers the backend of every slice type, may write anywhere in the project, and reads version 1 of the build contract.

Install a kit into the project with cratis build init --kit <name|git url|folder>, or pass it to a single build with --kit <folder>. Build with AI shows how to write one.

cratis build once builds one order from a file, without connecting to Studio. It runs your agent or generator, the verification and the commit exactly as a real build does, but does not push.

  1. Save the example backend order as order.json, outside the project.

  2. In a clean clone of the repository, build it once with an agent or with a generator:

    Terminal window
    cratis build once --order ../order.json --agent claude --outcome ../outcome.json
    cratis build once --order ../order.json --exec "<your command>" --verify "<your test command>" --outcome ../outcome.json
  3. Read outcome.json, and check the commit with git log.

once exits with 5 when the outcome is failed, so it also fits in a CI job.

  1. Register the machine with your organization, once:

    Terminal window
    cratis build connect --studio --organization <your organization>

    It prints a code and waits. A maintainer approves it with the code in Studio under Organization settings > Builders. See Connect a builder and approve it.

  2. In the project, start the loop with your agent or your generator:

    Terminal window
    cratis build run --agent claude
    cratis build run --exec "<your command>" --verify "<your test command>"

    After cratis build init --agent <agent>, a plain cratis build run uses the kit and the agent you installed. Add --once to stop after one slice, or --no-push to keep the commits local.

  3. In Studio, choose the builder for the application, its backend, or one slice. See Choose who builds.

Mark a slice Ready for implementation and watch the terminal: the CLI says when it gets work, what the agent or generator does, what it committed and how Studio settled the slice. See Follow a build and troubleshoot.

On macOS and Linux, install the loop as a user service, so the machine stays a builder without a terminal open:

Terminal window
cratis build service install --agent claude
cratis build service status

The service starts when you sign in and restarts when it stops. It takes the same options as run. Each project gets its own service, and cratis build service uninstall removes it. Windows has no supported service manager; run cratis build run there.