cratis-screenplay-model-authoring
Author, inspect, refactor and verify a Cratis Screenplay .play model through its typed AST and MCP workspace tools. Use for creating or changing model elements, navigating large split models, reviewing references/specifications, revision-checked screen/UI authoring proposals, or distinguishing source validity from executable/runtime readiness. Do not use for rendering a model into an application or hand-written Arc/Chronicle code.
- License 许可
- MIT
- 所属仓库
- Cratis/Prologue
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cratis-screenplay-model-authoring
- license
- MIT
- description
- Author, inspect, refactor and verify a Cratis Screenplay .play model through its typed AST and MCP workspace tools. Use for creating or changing model elements, navigating large split models, reviewing references/specifications, revision-checked screen/UI authoring proposals, or distinguishing source validity from executable/runtime readiness. Do not use for rendering a model into an application or hand-written Arc/Chronicle code.
02 资源文件 13
- 许可证LICENSE212 B
- 参考文档references/choosing-generation.md2.7 KB
- 参考文档references/destination-intent-repair.md5.5 KB
- 参考文档references/language-reference.md28.0 KB
- 参考文档references/layout.md1.6 KB
- 参考文档references/mcp-loop.md25.9 KB
- 参考文档references/mcp-tools.md55.7 KB
- 参考文档references/model-notes.md14.4 KB
- 参考文档references/property-links.md13.0 KB
- 参考文档references/release-baseline.md8.5 KB
- 参考文档references/repairs.md3.2 KB
- 参考文档references/screen-authoring-workflow.md15.5 KB
- 参考文档references/state-and-recovery.md3.3 KB
03 SKILL.md 正文
<!-- cratis-ai-managed: skills/cratis-screenplay-model-authoring/SKILL.md -->
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.
New models go in Source/ or src/, else root Screenplay/, never .cratis/
(configuration/shared corpus only). 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, form, toolbar, package/icon and outlet 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.
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 |
04 同仓库更多 Skills
vectorization
Designs, implements, optimizes, and reviews SIMD code in .NET: vectorizing scalar loops with TensorPrimitives, Vector64, Vector128, Vector256, Vector512, or hardware intrinsics, and reviewing existing SIMD code, including the generic Vector type, for contract equivalence, tail handling, memory safety, portability, fallbacks, and measured performance. Use when a .NET loop or SIMD routine is being written or reviewed. Not for performance work unrelated to SIMD.
target-authoring
Canonical patterns for writing custom MSBuild targets: DependsOnTargets versus BeforeTargets and AfterTargets, the Build-to-CoreBuild three-level pattern, and the XxxDependsOn chain-extension pattern. Use when diagnosing or fixing custom-target anti-patterns: Directory.Build.targets redefining SDK targets, targets that replace CompileDependsOn instead of extending it, Outputs versus Returns misuse that returns stale results, missing Inputs/Outputs causing needless rebuilds, or missing FileWrites registration. Not for incremental build tuning or general anti-pattern review (use the msbuild skill), or non-MSBuild build systems.
run-tests
Chooses and runs the repository-compatible .NET test command: classic, VSTest, bridged MTP, or native MTP syntax for MSTest, xUnit, NUnit, and TUnit. Use before running .NET tests or answering with a test command or flags: run the tests, one test, class, category, trait or target framework, combined filters, --filter-query, --no-build, --diag, TRX, coverage collection, crash or hang dumps, filter errors, or unrecognized options. Not for platform identification alone (use platform-detection), writing or debugging test code, interpreting a coverage report (use coverage-analysis), CI investigation, migration, or a persistent hot-reload loop.
profiling
Uses the free official .NET diagnostics CLI tools for profiling and runtime investigation in a repository: CPU, GC pressure, allocation growth, exception storms, lock contention, and slow code. Use when a .NET application needs performance or runtime profiling. Not for replacing realistic performance or load tests with ad-hoc tracing, production heap collection without a pause-risk plan, crash dumps (use dump-collect), or benchmark design (use microbenchmarking).
platform-detection
Identifies a .NET project's test platform, framework, command mode, and SDK-style versus classic project system, resolving global.json, project, packages.config, Directory.Build.props, and Directory.Packages.props precedence for MSTest, xUnit, NUnit, and TUnit. Use when asking "which test platform or framework?", "VSTest or MTP?", or "what runner does this project use?", including bridge settings, UseVSTest opt-outs, and conflicting VSTest/MTP configuration. Not for running or filtering tests, commands, flags, TRX, dumps, or test-command errors (use run-tests), or for hot-reload or migration requests.
orleans
Designs Microsoft Orleans systems from each primitive's purpose and failure model: grains, digital twins, state versus databases, transactions, messaging, streams, timers, reminders, Durable Jobs, stateless workers, grain services, startup, and hosting. Use when a task needs an Orleans design decision: inspect version and topology, choose the primitive, implement, and validate. Not for other actor stacks, batch processing, relational-only CRUD, or advice without an Orleans decision.