Build with a coding agent and a build kit
A builder can hand each build order to a coding agent instead of a generator. The CLI still does the rest: it talks to Studio, verifies, commits, pushes and reports. A build kit describes the stack the builder builds, for agents and generators alike. The cratis build reference has every option.
This page is the reference for agents and kits. For a complete, working kit to start from, see Build with AI, where the agent writes the code, and Deterministic with AI on top, where a generator in the kit writes the structure and the agent completes it.
Choose an agent
Section titled “Choose an agent”cratis build run --agent claude --verify "dotnet test"--agent |
Agent | How it runs |
|---|---|---|
claude |
Claude Code | Through its own command line. |
codex |
Codex | Over the Agent Client Protocol, through npx -y @zed-industries/codex-acp. |
gemini |
Gemini CLI | Over the Agent Client Protocol, through gemini --experimental-acp. |
copilot |
GitHub Copilot CLI | Over the Agent Client Protocol, through copilot --acp. |
opencode |
OpenCode | Over the Agent Client Protocol, through opencode acp. |
cursor, acp |
Any ACP agent | Over the Agent Client Protocol, through the command you give with --agent-command. |
--agent-command overrides the command for any agent. The agent runs with its own sign-in. cratis build init --agent <agent> records the agent in the project, so run and once use it without --agent.
What an agent gets
Section titled “What an agent gets”- A prompt filled from the order, telling it which slices to build and where to write its outcome. The order itself is in a folder outside the project.
- The Screenplay session guidance, the version Studio pins, unless you add
--no-guidance. - The kit’s instructions and skills, when the project has a kit.
- Tools: Screenplay’s tools on the order’s model, and Studio’s board tools when the organization’s MCP credential is configured.
The agent writes the same outcome a generator does. If it stops without one, the CLI asks it to go on, up to twice.
An agent is never run with its permission checks switched off. It may read the project and the folders handed to it, write only the paths the kit permits, and run only the commands the kit permits and the verification commands. Web fetches are refused. No credential is written into a prompt, a file the agent reads, an outcome or the log.
Give agents Studio’s tools
Section titled “Give agents Studio’s tools”export CRATIS_STUDIO_MCP_SECRET=... # the organization's MCP client secretcratis build connect --studio --organization acme --mcp-client-id <client id>The client id and secret come from Organization settings › MCP in Studio. The secret is read from CRATIS_STUDIO_MCP_SECRET, or asked for in the terminal; it is never taken on the command line. The same credential lets cratis studio fetch export the context of a slice, feature, event model or domain.
Build kits
Section titled “Build kits”Without a kit, a builder builds the backend of every slice type, may write anywhere in the project, and verifies with --verify only. A kit narrows and describes that:
| A kit says | So that |
|---|---|
sliceTypes |
Studio offers the builder only those slice types. |
ui: true |
Studio offers user interface orders too, not only backend ones. |
verify |
Every build runs these commands before committing. |
permissions |
The paths agents may write and the CLI commits, and the commands agents may run. |
git |
The branch and commit message when Studio does not name them. |
instructions, skills, prompt |
What an agent is told. |
scaffold, requires, existingCodebase |
How init sets up a new or existing project. |
Install a kit
Section titled “Install a kit”cratis build init --kit cratis-csharp --agent claude--kit is a kit Studio registers by name (cratis-csharp, node), a Git URL (end it with #<branch, tag or commit> to pin it), or a folder. init validates the kit, checks the commands it requires, scaffolds an empty project, copies the kit to .cratis/build/kit and installs its instructions and skills where the agent reads them. It records what it did in .cratis/build/kit.json; run, once and service install read the kit from there. --kit <path> on run or once uses another kit for one run.
Write a kit
Section titled “Write a kit”A kit is a folder with a build-kit.yaml (or build-kit.json) manifest and the files it names:
kitVersion: "1"name: slice-sheetsversion: 1.0.0description: Writes a Markdown sheet for each slice.sliceTypes: [stateChange, stateView, automation, translation]ui: falseinstructions: ./AGENTS.mdprompt: ./build-slice.mdverify: - test -f slices/{feature}/{slice}.mdgit: branch: "build/{feature}" commit: "Build {slices} ({part})"permissions: paths: ["slices/**"] commands: [ls]kitVersion, name, version, description, sliceTypes, instructions, prompt and verify are required. Paths inside the kit start with ./. Commands, prompts, branch names and commit messages may use these placeholders: {order}, {outcome}, {slice}, {slices}, {sliceId}, {feature}, {featurePath}, {application}, {part}, {attempt} and {conventions}. {slice} and {sliceId} are the order’s first slice; {slices} names them all. In a command, each value is quoted for the shell, so do not quote placeholders yourself.
Check a kit the way Studio and the builder do:
cratis build kit validate ./slice-sheets-kitIt reports each problem with a JSON pointer into the manifest. The Studio documentation describes the kit format in full.