cratis-screenplay-toolchain

Screenplay toolchain

Read preferred syntax when writing or reviewing .play.

This skill owns tool selection, verdicts and admission. Modeling method lives in cratis-screenplay-modeling-lifecycle; syntax lives in the construct skills.

Locate the model

Decide opt-in per general.md "Model first"; where cratis-screenplay-modeling-lifecycle is installed, run its scripts/model-first-status.mjs to locate the model root. A folder of .play files is one application: always check the folder, never one file of it.

Tool versions and the contract

Read the installed versions first: screenplay --version, cratis --version, and which -a cratis (an older copy earlier on PATH shadows a newer install). The standalone tool and the compiler bundled in the CLI are different releases, and the bundled one can be older; a construct the standalone tool binds may be refused or unrendered through the CLI. Capabilities that need a minimum release carry a one-line Requires ... note in the reference that teaches them.

Search screenplay-contract.json, not its whole contents, for exact diagnostic code, tool name or cliCommands options. Its version is screenplay-contract.version. Read contract exceptions when a superseded statement needs context; exceptions do not change the contract.

Ground rules

1. Never invent syntax. Copy shapes from references/cheat-sheet.md and the compiled examples it names, or from a compiled documentation example. Construct keywords are closed.
2. Check the folder, warnings as errors. screenplay <folder> --warnaserror or cratis screenplay validate <folder> --warnings-as-errors. Warnings hide defects: PLAY0029 (a misspelt keyword or a type inside a slice) drops a construct silently. A committed screenplay.json at the model root declares the repository's gate (checks, warnings as errors, scope, open questions): run without repeating those flags (confirm with --print-gate before dropping --warnaserror), read it with --print-gate, and treat a refused file as "could not run" (references/verdicts.md).
3. Pick the compiler deliberately and name it. Standalone screenplay for language checks and reference specifications; cratis for rendering and generation. Report both tool and version, rather than transferring a verdict across releases.
4. Know the mode (design, executable, renderable) and write from its subset.
5. Capability is not correctness. The tool you ran decides what is accepted; the domain and the documented semantics decide what is correct. On conflict keep the correct model and record a tool gap; never reshape a model to silence a tool.
6. Never remove pii, secret, authorization, list queries, automations or rules to reach V3 or a render. Report the verdict as blocked with the codes.
7. A clean verdict proves only its own layer. "Not run" with the reason is a valid result. Specifications written or bound are never specifications passing.
8. Let the tool resolve what it can. Revisions, identities and renames come from the tool, never from hand computation; discover tool, version and root once per session and reuse them until the root, the tool or a call changes. Re-resolve only when a value actually needs to change: a failed or stale call, a different model root, a changed tool, version or configuration, or an explicit override.