Build with AI
A coding agent can build a slice from its build order: read the specifications, write the code and the tests, and run them until they pass. The Cratis CLI starts the agent, keeps it to the files and commands you permit, and runs your checks itself before anything is committed. You describe your stack once, in a build kit, and the agent follows it on every slice.
This is the way to choose when you want the most code for the least effort, on any stack. Its quality depends on two things you control: the instructions the agent gets, and the checks that catch what it gets wrong. For how it compares with the other ways to build, see Build a builder.
Quick start with a registered kit
Section titled “Quick start with a registered kit”Studio registers reference kits by name, such as node for TypeScript on the Cratis Chronicle client and cratis-csharp for .NET on Cratis Arc and Chronicle. See Registered kits.
-
In an empty Git repository for the application, install the kit for the agent you use:
Terminal window cratis build init --kit node --agent claudeThe CLI checks that the kit’s tools are installed, scaffolds the project, copies the kit to
.cratis/build/kit, and writes the kit’s instructions where the agent reads them:CLAUDE.mdfor Claude Code,GEMINI.mdfor Gemini CLI,AGENTS.mdfor the others. -
Commit what
initwrote. A build starts from a clean project. -
Connect the machine once, and start building:
Terminal window cratis build connect --studio --organization <your organization>cratis build runrunuses the kit and the agent thatinitrecorded. See Run it as a builder.
To try it without Studio, save the example backend order as order.json beside the project and run cratis build once --order ../order.json --outcome ../outcome.json in the project.
Choose the agent
Section titled “Choose the agent”Name the agent with --agent, on init (it is recorded for later builds), run, once or service install:
--agent |
Agent | How the CLI talks to it |
|---|---|---|
claude |
Claude Code | Runs claude directly, with the kit’s permissions as its allowed tools |
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 |
Copilot CLI | Over the Agent Client Protocol, through copilot --acp |
opencode |
OpenCode | Over the Agent Client Protocol, through opencode acp |
cursor, acp |
Cursor, or any other agent | Over the Agent Client Protocol, through the command you give with --agent-command |
--agent-command also replaces the command for a known agent, for example to run a particular installation. The agent must be installed and signed in on the machine: it builds with your own account and plan.
What the agent gets, and what it may do
Section titled “What the agent gets, and what it may do”For every order, the CLI writes the order and its Screenplay documents to a folder outside the project, and starts the agent in the project with:
- the kit’s instructions and skills, as the agent’s own instructions,
- the Screenplay guidance and a Screenplay tool server for the order’s model, so the agent can read the model and run its specifications,
- the kit’s prompt, with its placeholders filled from the order, followed by the rules for the outcome document: where to write it and what it may hold.
The agent works inside the kit’s permissions, and the CLI answers every request it makes:
- It may read the project and the order’s folder.
- It may write only the files that match
permissions.paths, and its outcome file. It never writes inside.git. - It may run only the commands that start with an entry of
permissions.commandsor averifycommand, followed by a space or nothing. A command that chains, pipes, redirects or substitutes another (&&,;,|,>,`,$() is refused, whatever it starts with. - It never commits, pushes or switches branches. The CLI does that after verification.
An agent is never run with its permission checks switched off, and Claude Code runs without your own user settings, hooks and plugins, so a build behaves the same on every machine. An agent that stops without writing an outcome, as Copilot CLI does when a request is refused, is asked twice to go on.
Sample: a kit of your own
Section titled “Sample: a kit of your own”This sample is a small kit for slices in plain TypeScript on Node.js, tested with Vitest, with no framework. It shows every part a kit needs. Make a folder ts-vitest beside your projects, with these files:
ts-vitest/├── build-kit.yaml # the manifest├── AGENTS.md # the stack instructions├── build-slice.md # the prompt for one build order└── scaffold/ # the files of a new project ├── .gitignore ├── package.json └── tsconfig.jsonThe manifest
Section titled “The manifest”kitVersion: "1"name: ts-vitestversion: 1.0.0description: Plain TypeScript slices on Node.js, specified with Vitest.sliceTypes: [stateChange, stateView]scaffold: path: ./scaffold commands: - npm installinstructions: ./AGENTS.mdprompt: ./build-slice.mdverify: - npx tsc --noEmit - npx vitest run src/{feature}git: commit: "Build {slices}"permissions: paths: ["src/**"] commands: - npx tsc --noEmit - npx vitest runrequires: - command: node version: ">=22" - command: npm| Lines | What they do |
|---|---|
kitVersion, name, version, description |
Identify the kit. name is lowercase words joined by hyphens |
sliceTypes |
The kit builds state changes and state views. The CLI refuses an order for an automation or a translation with a failed outcome, before the agent starts |
scaffold |
Copies the scaffold folder into a new, empty project and runs npm install there |
instructions, prompt |
The stack instructions the agent always reads, and the prompt for one order |
verify |
Run by the CLI after the agent, in the project: the type check, then the tests of the feature. {feature} is filled from the order. Vitest fails when it finds no tests, so a slice without tests is never committed |
git.commit |
The commit message, here Build PayInvoice |
permissions.paths |
The agent writes only under src. It cannot change the package, the scaffold or the kit |
permissions.commands |
The agent may run the type check and the tests, and nothing else. It may not install a package |
requires |
init refuses to install the kit unless Node.js 22 or later and npm are on the machine |
The instructions
Section titled “The instructions”The instructions say how code is written in this stack: where a slice goes, what it is named, and how a specification becomes a test. Keep them about the stack; what to build comes from the order.
# TypeScript slices
This project is a set of event-sourced slices in plain TypeScript on Node.js, with no framework.
- Each feature is a folder under `src/`, named exactly like the feature: `src/Invoicing/`.- Each slice is one file named after the slice, `src/Invoicing/PayInvoice.ts`, with its tests beside it in `src/Invoicing/PayInvoice.test.ts`.- Events and commands are TypeScript types. An event has a `type` field with its name, such as `{ type: 'InvoicePaid', invoiceId: string, amount: number }`.- A state change slice exports one function named after its command in camel case: `payInvoice(history: Event[], command: PayInvoice): Event[]`. It returns the events the command appends, or throws an `Error` when the history rejects it. It does no I/O.- A state view slice exports one function named after its read model in camel case, which folds the events into the read model: `openInvoices(events: Event[]): OpenInvoices`.- Each specification in the build order becomes one Vitest test, named exactly like the specification: its `given` events are the history, its `when` is the command, and its `then` is what the test expects. Add a test for every other rule you write, such as a rejection.- Strict TypeScript, no `any`, no new packages.The prompt
Section titled “The prompt”The prompt is the task for one order. The CLI fills {slices}, {part}, {feature}, {application}, {order} and {attempt}, and adds the rules for the outcome document after it.
# Build {slices}
Build the {part} of {slices} in the feature `{feature}` of `{application}`. The build order is at `{order}`; this is attempt {attempt}.
1. Read the build order. Its `specifications` for these slices are the acceptance criteria: build what they describe, nothing more. `context.hints` holds each slice's description, the summary of what it is supposed to do; follow it. `context.feedback` comes from people on the board, and `context.previousFailure` says why the last attempt failed.2. Work in the folder `src/{feature}/`. When a slice's file is already there, change it in place.3. Write each slice to `src/{feature}/<slice name>.ts` and its tests to `src/{feature}/<slice name>.test.ts`, as the instructions describe. Where the order does not say something, such as a field, decide it sensibly and list it as an assumption.4. Run `npx tsc --noEmit`, then `npx vitest run src/{feature}`, until both pass. Run one command at a time: chained or piped commands are refused.5. Report the result of each specification as `passed` or `failed`, from its test. Write the outcome with your file editing tool.The scaffold
Section titled “The scaffold”The files of a new project: the packages, the TypeScript settings and what Git ignores.
{ "name": "slices", "private": true, "type": "module", "scripts": { "typecheck": "tsc --noEmit", "test": "vitest run" }, "devDependencies": { "typescript": "^7.0.0", "vitest": "^5.1.0" }}{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "noEmit": true, "skipLibCheck": true }, "include": ["src"]}node_modules/Validate and try the kit
Section titled “Validate and try the kit”-
Check the kit. The CLI validates the manifest, checks that every file it names is there and not empty, and that every placeholder is one it fills:
Terminal window cratis build kit validate ./ts-vitest -
Create a project and install the kit in it:
Terminal window mkdir shop && cd shop && git initgit commit --allow-empty -m "Start the shop"cratis build init --kit ../ts-vitest --agent claudegit add . && git commit -m "Install the ts-vitest kit" -
Save the example backend order as
../order.json, and build it:Terminal window cratis build once --order ../order.json --agent claude --outcome ../outcome.json -
Read
../outcome.json, and look at the commit withgit show. The agent wrotesrc/Invoicing/PayInvoice.tsandsrc/Invoicing/PayInvoice.test.ts, the CLI ran the type check and the tests, and committed both files asBuild PayInvoice.
The outcome lists the files, the result of each specification, and the decisions the agent made where the order was silent. Studio shows those assumptions on the slice, so a person can confirm them or add what was missing to the model:
{ "contractVersion": "1", "orderId": "6f0c3d5e-2b1a-4f7e-9a51-0d2c8e4b7a10", "kind": "built", "files": ["src/Invoicing/PayInvoice.ts", "src/Invoicing/PayInvoice.test.ts"], "specifications": [{ "id": "8e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "result": "passed" }], "assumptions": [ "PayInvoice identifies an invoice by invoiceId.", "PayInvoice pays the full outstanding amount; partial payments are not supported." ], "commit": "3c9c782223c92da32371b49d5985dc7f6e93080b", "branch": "main"}The code differs from run to run: an agent is not deterministic. What does not change is what the CLI checks. When you want parts of the code to come out the same every time, generate them: see Deterministic with AI on top.
Write good instructions
Section titled “Write good instructions”- Point at the specifications. Every specification in the order is an acceptance criterion. Ask for one test per specification, named like it, so the outcome’s results mean something and a reviewer can find them.
- Be concrete about the layout. Name the folder, the file and the function, with an example. An agent asked for “a slice in the feature folder” picks a folder of its own; one shown
src/{feature}/<slice name>.tswrites it there. - Let the checks decide. Put the type check and the tests in
verify, and tell the agent to run the same commands until they pass. The CLI runs them again afterwards, and only their result counts. - Permit little. Permit the paths the slices live in and the commands the agent needs to check its work. Leave out package installs and anything that reaches the network.
- Ask for one command at a time. Chained and piped commands are refused, and an agent that keeps asking for them wastes its turns. Ask it to write the outcome with its file editing tool rather than a shell command.
- Ask for assumptions. Where the order is silent, a listed assumption is better than a silent decision: it comes back to the slice in Studio.
- Use
{conventions}for existing code. A kit that builds into a project it did not scaffold learns the project’s conventions once and passes them to every build. See Existing codebases.
Related
Section titled “Related”- Deterministic with AI on top: a generator writes the structure and the agent completes it.
- Use the reference builder: every member of the kit manifest, and the placeholders.
- Build orders and outcomes: what the agent reads, and what it answers with.