Skip to content

Builders

Builders

Turn ready slices into code in your repository

A builder takes the slices you mark Ready for implementation on the board and turns them into code, then tells Studio what came of it.

Studio keeps the board and the process around it in order. A builder does the building: it takes one slice at a time, builds it with whatever tooling it likes, and reports one outcome. You review what it built on the slice, including the specifications it ran and the assumptions it made.

Studio’s own generation also runs on your machine. The Cratis builder and the Axon builder are packaged, build the application at the Screenplay, Code or Code and AI level, run in Docker, and can send their model calls through Studio so usage is counted and pooled there. See Run a builder locally.

You do not write a builder from scratch. A builder is cratis build from the Cratis CLI, plus whatever writes the code, and there are three ways to write it:

  • With AI. A coding agent, such as Claude Code, Codex, Gemini CLI, Copilot CLI or OpenCode, builds the slice inside the files, commands and checks of a build kit. The most code for the least effort. See Build with AI.
  • Deterministic. A generator of your own, in any language, turns the order into code the same way every time. See Build with a generator.
  • Deterministic with AI on top. Your generator writes the structure, and the agent fills in the parts that need judgment. See Deterministic with AI on top.

Any stack works: the build order describes the slice in Screenplay, with its specifications as acceptance criteria, and what you turn that into is up to you. Build a builder helps you choose.

The CLI does the rest: it connects to Studio, waits for approval, asks for work, keeps the claim on a slice alive, keeps an agent within its permissions, verifies, commits, pushes and reports the outcome. It runs anywhere that can reach Studio over HTTPS, and needs no inbound port.

Studio’s own generation, or a builder you connect

Section titled “Studio’s own generation, or a builder you connect”

Every application has a builder from the start: Studio’s own generation, as static code, static code refined by AI, or AI only (the two that involve AI need an AI provider configured). Until you choose another, that is who builds.

A connected builder runs on a machine you control: a laptop, a build server, a container in another cloud. It dials out to Studio, so it needs no inbound port. A maintainer approves it once, and from then on you can choose it for an application, for the backend or the screens of an application, or for a single slice.

Both go through the same loop and the same statuses, so the built-in path and a builder you connect cannot drift apart.

STUDIO BUILDER failed with attempts left: offered again claim heartbeat outcome OFFERED Slice is ready CLAIMED Build order LEASE Two minutes BUILDING Attempt n REPORTED One outcome SETTLED Status set
Studio runs the loop. A builder only claims, builds and reports.
Piece What it is
Builder Anything that connects to Studio, takes a slice to build, builds it with whatever tooling it likes, and reports what came of it. Studio’s own generation is a builder. So is a coding agent driven by the Cratis CLI, and so is a program a team wrote for its own stack
Build order The JSON document Studio hands a builder: what to build, written in Screenplay, with the specifications as acceptance criteria and the context the builder needs. See Build orders and outcomes
Build outcome The JSON document a builder answers with: built, nothing to do, blocked or failed, with the commit it made, the results of the specifications it ran and the assumptions it made
Build loop Studio’s side of the exchange: offering work, claiming it, holding the claim under a lease, retrying and settling the slice’s status. See The build loop
cratis build The builder in the Cratis CLI. It connects, claims, keeps the lease alive, runs your agent or generator, verifies, commits, pushes and reports. See Use the reference builder
Coding agent Claude Code, Codex, Gemini CLI, Copilot CLI, OpenCode or any Agent Client Protocol agent, run by cratis build with --agent. See Build with AI
Generator Any program that reads a build order and writes code and an outcome, run by cratis build with --exec. See Build with a generator
Build kit A description of a stack for cratis build: a manifest, a scaffold, instructions, permissions and verification commands. What an agent builds with. See Build kits