Skip to content

Build deterministically with a generator for a Cratis Studio builder

A generator is the deterministic way to build: a program of your own that turns a build order into the same code every time, with no coding agent involved. To let an agent build instead, see Build with AI; to combine the two, see Deterministic with AI on top.

The Cratis CLI runs your generator for every build order and does everything else: it talks to Studio, holds the lease, verifies, commits, pushes and reports. Your generator reads one JSON file and writes another, so it can be in any language the shell can start.

cratis build run --exec "<command>" (and cratis build once --exec) runs your command through the shell, /bin/sh -c (or cmd.exe /d /s /c on Windows), in the project folder, once for every build order.

Variable What it names
STUDIO_BUILD_ORDER The build order, order.json, in a fresh folder for the order under the system’s temporary folder, outside the project. The order’s Screenplay documents are written beside it, in a model folder.
STUDIO_BUILD_OUTCOME The file your command writes its outcome to, outcome.json, in the same folder.
STUDIO_BUILD_PROMPT The order written out as a prompt, prompt.md, for a generator that hands it to a language model. A kit’s prompt is used when the project has a kit.
STUDIO_AI_URL, STUDIO_AI_TOKEN With --ai studio: an OpenAI-compatible address on this machine and its token. A generator that wants a model’s help posts chat completions there; Studio runs them on the organization’s providers and counts the tokens. OPENAI_BASE_URL and OPENAI_API_KEY carry the same values for SDKs that read them. See Run the Cratis builder locally.

The order is Studio’s build order: the slices to build, with their type, the feature they belong to, the Screenplay model they live in, each slice’s specifications as acceptance criteria, and the hints and feedback people left. The Studio documentation describes every field, with an example order.

Write a JSON object with a kind, and the fields for that kind:

kind Fields Meaning
built files, specifications, assumptions You wrote code. files lists the paths you wrote, relative to the project; a folder stands for everything under it. specifications lists { "id", "result", "message" }, with result passed, failed or notRun. assumptions lists what you decided where the model was silent.
nothingToDo none The code already matches the order.
blocked reason, questions You cannot build the slices until a person answers the questions.
failed error, retryable Something went wrong. retryable is true unless you say otherwise; Studio offers the slice again while attempts are left.
{
"kind": "built",
"files": ["slices/Invoicing/PayInvoice.md"],
"specifications": [{ "id": "8e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b", "result": "notRun" }],
"assumptions": ["Wrote a slice sheet for each slice; no code was generated."]
}

The CLI keeps only these fields, and adds the order’s id (orderId), the contract version (contractVersion) and, after committing, the commit and branch. Do not write those yourself.

Your command What the CLI reports
Exits with 0 and wrote an outcome Your outcome.
Exits with anything but 0 failed, retryable, whatever you wrote.
Exits with 0 without writing an outcome The CLI runs the command again, up to twice more, then reports failed, retryable.
Wrote something that is not a JSON object, or an unknown kind failed, retryable.

So a generator that knows another attempt would fail the same way writes failed with "retryable": false and exits with 0. A generator that crashes exits with an error, and Studio retries the slice.

After a built or nothingToDo outcome, the CLI runs the kit’s verification commands and then each --verify, in order, in the project. The first that exits with anything but 0 turns the outcome into failed, retryable, with the end of the command’s output as the error. A verification command may use the kit’s placeholders, such as {slice} or {feature}.

For a built outcome in a Git repository, the CLI commits the changed files that are both:

  • listed in files, or under a folder listed there (every change, when files is empty), and
  • permitted by the kit’s permissions.paths (everything, without a kit).

It commits on the branch Studio names, or on the kit’s git.branch, with Studio’s commit message, the kit’s git.commit, or Build <slices> (<part>). run then pushes with your own Git credentials unless you add --no-push; once pushes only with --push. A commit or push that fails turns the outcome into failed, retryable.

Anything left uncommitted after the build, including files you wrote but did not list, is put away in a Git stash named cratis build: left over from order <order id>, never discarded. The repository then goes back to the branch it was on.

Each sample does the same thing: for every slice in the order, it writes a Markdown sheet with the slice’s acceptance criteria to slices/<feature>/<slice>.md, and reports what it wrote. A comment marks where real code generation goes. A sheet that is already in the project with the same content is skipped, so building the same order twice reports nothingToDo and makes no empty commit. A feature or slice name that cannot be a file name is reported as failed, not retryable.

Save the generator outside the application’s repository, in ~/slice-sheets/.

Needs Bash and jq 1.6 or later. Make the script executable with chmod +x ~/slice-sheets/generate.sh.

generate.sh
#!/usr/bin/env bash
# Slice sheets: a generator for `cratis build`. For every slice in the build order it writes
# a Markdown sheet with the slice's acceptance criteria into the project.
set -euo pipefail
order="$STUDIO_BUILD_ORDER"
outcome="$STUDIO_BUILD_OUTCOME"
fail() {
jq -n --arg error "$1" '{ kind: "failed", error: $error, retryable: false }' > "$outcome"
exit 0
}
safe() {
case "$1" in
"" | *[!A-Za-z0-9._\ -]* | .*) return 1 ;;
esac
}
feature=$(jq -r '.scope.feature.name' "$order")
safe "$feature" || fail "The feature name '$feature' cannot be used as a folder name."
files=()
while IFS=$'\t' read -r id name; do
safe "$name" || fail "The slice name '$name' cannot be used as a file name."
file="slices/$feature/$name.md"
# This is where real generation goes: run your code generator or templates for the
# slice here and write the files they produce. This sample writes one sheet per slice.
sheet=$(jq -r --arg id "$id" '
(.scope.slices[] | select(.id == $id)) as $slice
| "# \($slice.name)",
"",
"A \($slice.type) slice in \(.scope.feature.name).",
"",
"## Acceptance criteria",
(.specifications[] | select(.sliceId == $id)
| "", "### \(.name)", "",
"- Given \(if (.given | length) > 0 then .given | join(", ") else "nothing" end)",
"- When \(.when)",
"- Then \(.then | join(", "))")
' "$order")
if [ -f "$file" ] && [ "$(cat "$file")" = "$sheet" ]; then
continue
fi
mkdir -p "$(dirname "$file")"
printf '%s\n' "$sheet" > "$file"
files+=("$file")
done < <(jq -r '.scope.slices[] | [.id, .name] | @tsv' "$order")
if [ "${#files[@]}" -eq 0 ]; then
jq -n '{ kind: "nothingToDo" }' > "$outcome"
exit 0
fi
jq '{
kind: "built",
files: $ARGS.positional,
specifications: [.specifications[] | { id, result: "notRun" }],
assumptions: ["Wrote a slice sheet for each slice; no code was generated."]
}' "$order" --args "${files[@]}" > "$outcome"
Terminal window
cratis build once --order ~/order.json --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices" --outcome ~/outcome.json
  1. Save the example backend order as ~/order.json.
  2. In a clean clone of the repository, run the cratis build once command under the sample. --verify is where your build and tests go, for example dotnet test or npm test.
  3. ~/outcome.json says built and lists slices/Invoicing/PayInvoice.md, and git log shows the commit. Run the command again: the sheet is unchanged, so the outcome is nothingToDo and nothing is committed.

To build for real, swap once --order ~/order.json ... --outcome ~/outcome.json for run, as in Connect and run a builder:

Terminal window
cratis build run --exec "$HOME/slice-sheets/generate.sh" --verify "test -d slices"