Build with a generator
A generator is any program that turns a build order into code the same way every time. The Cratis CLI runs it for every order with --exec, and does everything else a builder does, from talking to Studio to verifying and committing. The same order always gives the same code, so builds are fast, cheap and easy to review. Choose this way when your conventions are fixed and you can describe them as code. For how this compares with building with AI, see Build a builder.
The generator contract
Section titled “The generator contract”cratis build run --exec "<command>" runs your command through the shell (/bin/sh, or cmd.exe on Windows) in the project folder, once for every build order. Three environment variables name the files it works with:
| Variable | What it names |
|---|---|
STUDIO_BUILD_ORDER |
The build order, order.json, in a 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 |
STUDIO_BUILD_PROMPT |
The order written out as a prompt, prompt.md, for a generator that wants to hand it to a language model |
The order is Studio’s build order. The outcome is a JSON object with a kind, and only 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 |
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": ["Amounts are rounded to two decimals"]}Write only kind and its fields. The CLI adds contractVersion and orderId, and the commit and branch once it has committed, then sends the outcome to Studio.
The rest of the contract:
- Exit with 0 when you have written an outcome, whatever its kind. A non-zero exit becomes a
failedoutcome that Studio retries. A command that exits with 0 without writing an outcome is run again, up to twice, before the build fails the same way. - List the files you wrote. After
built, the CLI commits the files you listed that changed (every changed file, when you list none). ReportnothingToDorather thanbuiltwhen nothing changed: an empty commit fails. - Verification decides. Every
--verifycommand runs afterbuiltornothingToDo; one that fails turns the outcome intofailed. See What every build has in common.
Try it offline
Section titled “Try it offline”-
Save the example backend order as
order.json, outside the project. -
In a clean clone of the repository, run the generator once:
Terminal window cratis build once --order ../order.json --exec "<your command>" --verify "<your test command>" --outcome ../outcome.json -
Read
outcome.json, and check the commit withgit log. Run the same order again: a generator that finds nothing to change reportsnothingToDo.
Then run it as a builder with cratis build run --exec "<your command>" --verify "<your test command>", as Build a builder describes.
Start from a sample
Section titled “Start from a sample”Each sample is a complete generator that writes a Markdown sheet with the acceptance criteria of every slice in the order, reports built, nothingToDo or failed, and shows where real code generation goes. They are equivalent: pick the language you like, or port one to any other.
Related
Section titled “Related”- Deterministic with AI on top: let a generator write the structure and a coding agent fill in the rest.
- Build orders and outcomes: every field of the order your generator reads.
- Use the reference builder: the
cratis buildcommands and build kits.