Author a Screenplay model through its AST
Read preferred syntax when writing or reviewing .play.
Prefer the Screenplay MCP tools to text/regex edits: the compiler owns declaration, reference, hierarchy and source evidence for the declarative document set.
Valid source is not necessarily executable. Stage owns rendering/runtime admission. Read the language reference for construct syntax, source-versus-execution states and a complete compiled model.
For screens, read references/screen-authoring-workflow.md; use the
same model root or workspace export for all checks. Syntax: cratis-screenplay-ui-composition.
Record open modeling questions as question notes in committed
.screenplay/notes.json, not chat or description text. Never put secrets or
personal data in notes. Read model notes when
listing, recording or resolving questions: list-model-notes,
propose-model-notes, read-proposal view=notes, refs and orphan review.
Application, Module, Feature and Slice notes anchor before binding; members
still need binding and otherwise substitute their own slice. Inspect
containerIdentities in open-workspace / workspace-state for missing or
ambiguous identities; fix parse/placement errors first. Read the notes reference
for refusals, ambiguous: true, typed targets and every substitutions entry.
Choosing a strategy
Read shop strategies and entropy before
editing concept generation or generated identifier.
When not to
For generation proofs/PLAY0688 repairs, read generation details:
use rules[], not parsed diagnostics (Requires Screenplay 4.173.0,
screenplay --version; older servers omit proofs).
Locate and connect
Use the declared screenplay MCP server (for example open-workspace).
Never ask the user which folder to use before trying open-workspace without
arguments; do not invent a root. Read MCP loop when connecting or switching roots;
it owns fallback discovery, fixed-root limits and the initialization protocol.
Discover tools/list schemas.
Look first for the project's existing .play files: their folder is the model.
Reuse existing model/workspace roots; code-only Source/ or src/ is not a
model root. Otherwise use repository-root Screenplay/, never .cratis/
(root selection and version gates). The source is the single flow model;
explanatory Markdown belongs in repository documentation.
cratis ai install manages .cratis/ai/, never model files. Select the
cratis/screenplay profile in the project's AI configuration. The corpus-owned
mcp-servers.json declares the Screenplay server; supported client registration
is owned by the Cratis CLI, which preserves other servers and user configuration.
The CLI-bundled MCP can be older than the standalone tool: discover schemas. Read MCP loop for supported launch channels; do not substitute a global tool, Docker or copied managed configuration.
If MCP is unavailable, report it; regex edits are not compiler-validated AST
editing. Existing standalone screenplay mcp users may retain that entry point.
Understand before editing
- Start with
describe-applicationcounts and paged logical children. A folder of.playfiles is one application, not independent files. - Use
search-declarations,declaration-details,find-referencesanddependenciesto locate the owning declaration and affected references. Before a property change, read property links:kind: "Property",Owner.member/Owner.generationN.member, direct mappings.complete: falseis incomplete evidence, never a successful empty list. Edit through MCP proposals, not hand-edited text; generation. - Read diagnostics and coverage limitations. Identify subjects by code and typed
arguments, never by parsing message text. Read diagnostic arguments for kinds, PLAY0524 step paths/indices, unknown fields and older responses. Usedependency-graphfor container edges, declared-dependency coverage, cycles and advisory order; the board's dependency-map toggle exposes this evidence visually. Unknown or ambiguous bindings are not an empty, successful dependency graph. - Use
find-fixturesfor value occurrences (including example/override origins and event routes) andfind-assertion-gapsfor authored assertion gaps. Neither executes specifications; userun-specificationsfor that.diagnosticsacceptsscopeand opt-inchecks; skipped completeness checks are not passes. Details:references/mcp-tools.md. - Echo
sourceRevisionon subsequent pages. Restart the query after drift; never combine pages from different snapshots. - For screens, also discover the template (its slots and outlets), form, toolbar and package/icon declarations that provide context. A component binding with no traced data source is not a shortcut; fix the model source.
Scope reads to the relevant container/document, not the whole merged AST. Size-limit refusals require narrower reads, not truncation.
Application modes and described handler intent
Start new models with reaction batches atomic; preserve it through proposals.
Read language admission
for atomic/protected modes and Stage refusals. Read intent inventories
for handler views: executableReady means binding, not an implemented body.
Compare models
Compare with main through semantic-diff worktree path, not two exports.
Read comparison sources for paging
and enum numeric identity for
stored-value risks: implicit reorders can renumber values; stable explicit-number
reorders do not. Static comparison never proves storage or behavioral compatibility.
Make one coherent proposal
One edit strategy. Prefer discovered identity-preserving operations
(propose-rename, propose-repair, propose-extract-inline-event, propose-ast).
Bounded text edits must leave catalog addresses unchanged (descriptions, rule
bodies, existing-member mappings), never a way around an MCP refusal. When .screenplay/identities.json
exists, adding, removing or renaming a declaration, command or read-model property, query,
query argument or specification goes through MCP, and an id pin is not enough for a rename or move. A request naming
a rename, move or removal is the approval: do not ask again at apply. Without MCP, text-rename
with id "<Old>" pins and an identity note; only with identities.json and no MCP, return the
request to the owning session, saying first it is NOT done.
Proposals are connection-local (16 cap); only the owner proposes/applies.
Others send an edit request (MCP loop).
- Apply is not crash-atomic across files: it journals its inverse first. The model root must be trusted and exclusively writable during effects.
open-workspaceobtains workspace/catalog revisions and restores root-local identity state.read-workspacelocates document identities.read-astreturns original occurrence handles and existing semantic IDs. Querysyntax-schemafor exact node members before constructing typed input.- Prefer
propose-renameandpropose-move: they carry identities and notes even on unbound models. Manualpropose-ast/propose-sourcerenames needsemanticRenames; removal needs retirement and reportsorphanedNotes. Never substitute global string replacement for an explicit refusal. - Prefer
propose-propertyfor property add/rename/remove, not hand-composedpropose-astbatches. Inspect the chain and never guess past a refusal: property links. Otherwise usepropose-source(whole text) orpropose-ast(typed edits);proposeis executable-only. Default hand-written source toPreserveExactSource(Requires Screenplay 4.158.0,screenplay --version); readreferences/mcp-loop.mdwhen choosing formatting. - Keep reference policy
Safe. UseDraftonly for deliberately requested unresolved model debt and report that debt; it does not waive structural, identity or binding-protection checks. Batch independent reference removals/additions; unmatched same-text pairs refuse as ambiguous. Preserve moves withpropose-moveor semantic migrations. Stringconflicts[].document/pathlocate refusals: reference continuity and version gate. - Report
summary, inspect severity errors/codes rather than counts (Requires Screenplay 4.156.0,screenplay --version); readreferences/mcp-loop.mdwhen reviewing PLAY0288, comment loss or introduced executable errors. Inspectread-proposalbefore/after bytes and diagnostics, including the identity-state change throughworkspace-state. RevieworphanedNoteson source proposals; reanchor or resolve affected questions before applying (notes and orphan impact). - Run
run-specificationswithproposalIdbefore applying; record V4 separately. PLAY0285 unbinds the whole model. Read the MCP tool guide for candidate paging and the required version. applyonly the reviewed server-produced proposal within the user's requested change. The proposal ID and before revisions are required; stale state rejects. Apply after checks if requested; otherwise show the proposal and ask once.- When the host draws views,
visualize-modelshows the board. It follows the files on disk while open, so after an apply do not re-request it; just say what changed.
Handles are revision-bound, not durable IDs. Modules/features span fragments; after apply fetch fresh handles/revisions.
On refusal, use failureKind, never message text (failures/limits).
After revision/disk/identity drift, reopen and re-propose. For ApplyOutcomeUnknown
or EOF during apply, never retry apply: reconnect, inspect workspace-state
and ask. Never delete .screenplay/pending.json. Limits reject, never truncate.
Choose formatting and disclose dropped comments before apply:
formatting/limits covers
PreserveTrivia, canonical consent and byte preservation.
identityMigrationIssues: read the MCP loop.
Repair or extract before rewriting
Read read-workspace with view: "repairs" at the same revision as diagnostics and pass the repair to propose-repair; use propose-extract-inline-event before adding generations, or let a remove with newGeneration: true extract the inline event itself, as property links describes. PLAY0469 changes the event contract, so ask about stored contracts first. No automatic generation-evolution repair ships. PLAY0479: migrate optionality spelling with PreserveTrivia. eventNeverPersisted: true cannot unfreeze admitted revisions. Differing event pins carry storedName in ESM v16, shared by all generations and unique (PLAY0472). Read references/repairs.md when fixing PLAY0166, PLAY0478, PLAY0516 or PLAY0683, or admitting a release baseline. Read references/destination-intent-repair.md when PLAY0470 needs a repair.
Choose a readable layout
Use recommend-layout for options and review an expand-layout proposal; layout is not application semantics. Use one file per module when modules are simple. Use one file per slice when a large model needs isolated diffs. Each level above the slices is a barrel file. Read references/layout.md when splitting files or writing import barrels.
Preserve state and recover explicitly
Fix binding errors through MCP proposals, not outside MCP: reopening after an
external fix can require reconciliation of a persisted partial catalog.
Commit .screenplay/identities.json with the model; only apply writes it. Never delete or overwrite identity state, mint IDs on restart, or text-rename identity-affecting declarations. A pending journal blocks normal work: inspect workspace-state and use recover-workspace only for the identified interrupted operation. Only apply / recover-workspace write source/catalog. readiness.authoringAccepted says the source is valid Screenplay; executableReady is separate. Read references/state-and-recovery.md for root conflicts, journals and readiness.
Code attachments
Screenplay never compiles/runs opaque code attachments or file constraints;
a screen's file realizes UI instead. Read MCP code attachments
for paths, PLAY0430–PLAY0434 and implementation-requirements views; hashes/maps
are not behavioral evidence.
Verify and report honestly
Require zero source errors; investigate warnings, reference safety, identity continuity and exact intended changes.
Report which of the four states you checked: parsed, bound, reference-executed, target-executed. When distinguishing source validity from execution, read the language reference; it defines them and maps them onto V1 to V5.
screenplay --warnaserrorchecks syntax plus the consistency rules (PLAY0282-PLAY0294) but never binds, so a clean run is not a bound or executable result.Never drop or stub source contracts to bind; the bundled compiler and renderer can be older than the standalone tool. Read references/language-reference.md for the ESM version at which each construct binds.
Unsupported capabilities never justify dropping constructs or inventing stubs. Validate intended execution with the owning downstream runtime.
Model rejection cases as specifications; assertion presence is not execution.
Check installed
tools/list/schemas rather than assuming a remembered tool count.
The ordinary CLI remains useful for whole-folder validation:
cratis screenplay validate <model-folder> --warnings-as-errors
Keep screen transcripts in .ai-work/; check the same source, never an app that
silently drops authored UI. Use the Screenplay-owned canonical
corpus fixture path instead of copying fixtures here.
Never invent syntax or capabilities.
Route near misses
| Need | Skill |
|---|---|
| Discovering the domain and event-modeling method | cratis-screenplay-event-modeling |
| Commands, events, validation and concurrency | cratis-screenplay-command-surface |
| Projections and reducers | cratis-screenplay-projections |
| Read models, queries and screens | cratis-screenplay-read-surface |
| UI composition, bindings, navigation and themes | cratis-screenplay-ui-composition |
| Captures, reactions and triggers | cratis-screenplay-captures-and-reactions |
| Behavioral examples and assertions | cratis-screenplay-specifications |
| Rendering/running an admitted model | cratis-stage-rendering-and-sandbox |
| Lifecycle and model-first decision | cratis-screenplay-modeling-lifecycle |
| Compiler, CLI, MCP and diagnostics | cratis-screenplay-toolchain |
| Event-model diagrams rather than .play source | cratis-event-model-diagram |