Skip to content

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.

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 failed outcome 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). Report nothingToDo rather than built when nothing changed: an empty commit fails.
  • Verification decides. Every --verify command runs after built or nothingToDo; one that fails turns the outcome into failed. See What every build has in common.
  1. Save the example backend order as order.json, outside the project.

  2. 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
  3. Read outcome.json, and check the commit with git log. Run the same order again: a generator that finds nothing to change reports nothingToDo.

Then run it as a builder with cratis build run --exec "<your command>" --verify "<your test command>", as Build a builder describes.

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.