AGENT SKILL

cratis-screenplay-event-modeling

Entry point and router for model-first Cratis work: the short decision rule (model, or code), the nine-step workflow per behavior, the four slice types, the Cratis divergences from the generic method, the quick validation gate, file layout and what parsed-but-not-runnable means, then the phase skill to load next. Use when designing an information system, mapping a business process or information flow, deciding the event vocabulary or stream boundaries, turning a whiteboard model into `.play`, or when a request may change behavior in an application with a Screenplay model. Not for: Screenplay syntax and the compiler alone (use `cratis-screenplay-toolchain`), the lifecycle, verdicts and handoffs (use `cratis-screenplay-modeling-lifecycle`), or rendering a settled model (use `cratis-screenplay-render-and-gap-fill`).

License 许可
MIT
所属仓库
Cratis/Prologue
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
cratis-screenplay-event-modeling
license
MIT
description
Entry point and router for model-first Cratis work: the short decision rule (model, or code), the nine-step workflow per behavior, the four slice types, the Cratis divergences from the generic method, the quick validation gate, file layout and what parsed-but-not-runnable means, then the phase skill to load next. Use when designing an information system, mapping a business process or information flow, deciding the event vocabulary or stream boundaries, turning a whiteboard model into `.play`, or when a request may change behavior in an application with a Screenplay model. Not for: Screenplay syntax and the compiler alone (use `cratis-screenplay-toolchain`), the lifecycle, verdicts and handoffs (use `cratis-screenplay-modeling-lifecycle`), or rendering a settled model (use `cratis-screenplay-render-and-gap-fill`).

02 资源文件 11

03 SKILL.md 正文

<!-- cratis-ai-managed: skills/cratis-screenplay-event-modeling/SKILL.md -->

Event modeling with Screenplay (start here)

Event Modeling is the method: walk a business process left to right and write down every behavior as a command that changes the system, a view that reads it, an automation that runs off it, or a translation of outside data. Screenplay is the artifact: one language that holds that whole model - concepts, commands, events, read models, queries, screens, specifications - in files that compile.

You are a facilitator, not a stenographer. Ask probing questions, challenge assumptions, keep asking "and then what happens?" after every event, every command, every answer. Use business language. Do not discuss databases, APIs, or frameworks during modeling.

Ask only what the step needs: ask the one question that changes the model most; in an unattended run assume visibly, never silently; contradictions, a third review round and missing approvals always stop. Read references/facilitation-stance.md for the full rule, and cratis-screenplay-modeling-lifecycle's references/stop-or-assume.md when information is missing or contradictory, or when deciding whether unattended work may proceed.

Do not cut corners to save tokens or effort. A rule that needs more slices, events, views, translation steps or specifications gets them written; budget is never a reason to delete a modeled behavior, label a gap "accepted debt" or merge translating outside data into our facts into the work that acts on them. Flag a real trade-off to the user instead of resolving it by cutting the model (cratis-screenplay-modeling-lifecycle, references/completeness-self-check.md). Read cratis-screenplay-modeling-lifecycle's references/completeness-self-check.md before every gate and whenever effort or token cost tempts a reduction in modeled behavior.

Start here

1. Decide the level (short form; master copy in cratis-screenplay-modeling-lifecycle). Check first that the method skills are installed; installing them never opts a repository in. Decide opt-in per general.md "Model first"; where cratis-screenplay-modeling-lifecycle is installed, run its scripts/model-first-status.mjs for the decision, model root and drafts. Otherwise stay code-first. Only the entry-point session proposes a model (at most once per session, never for trivial, bug-fix, infrastructure, client, framework or brownfield-maintenance work; unattended: record the recommendation in the final report). Framework repositories and brownfield work that has not opted in stay code-first.

  • Model: change the .play, verify, review, then render or gap-fill.
  • Code is right for infrastructure, clients, Screenplay code attachments and handlers, adapters, and scope Stage cannot render yet (the model stays the contract).
  • Never: use code as a shortcut around the model; change the model to match existing code; edit Stage-managed output; leave a modeled rule living only in code; weaken protection (authorization, pii, rules) so a model compiles or renders.

2. Run the lifecycle. Load cratis-screenplay-modeling-lifecycle for modes, the independent verdicts V1-V5, the P0-P9 phases with their gates, stop-or-assume, identity ownership and handoffs. Then load one phase skill. Small changes enter at the phase where they belong and run the downstream gates for the changed scope.

3. Pick the phase skill.

Phase Skill
P0-P1 intake, timeline, personas, events cratis-screenplay-discovery
P2 commands, read models, screens, field lineage cratis-screenplay-slice-design
P2 stream identity, consistency, evolution cratis-screenplay-streams-and-consistency
P2 reactions, work queues, clocks, captures cratis-screenplay-automations-and-translations
P3 specifications and coverage cratis-screenplay-scenario-coverage
P4-P5 self-check and independent review cratis-screenplay-model-review
Existing system into a model (replaces P1-P2) cratis-screenplay-legacy-extraction
P7-P9 execute, render, fall back, verify cratis-screenplay-render-and-gap-fill
Tools, versions, verdict commands, diagnostics cratis-screenplay-toolchain
Estimate, order or split delivery of an accepted model cratis-screenplay-delivery-planning

4. Nine steps to phase skill. references/nine-steps.md keeps the activities, Screenplay output and facilitation questions of each step:

Step Activity Phase skill
1-3 Goal, brainstorm events, order them cratis-screenplay-discovery
4-6 Wireframes, commands, read models cratis-screenplay-slice-design
7-8 Automations, external integrations cratis-screenplay-automations-and-translations
9 Decompose into vertical slices cratis-screenplay-slice-design
after 9 Specifications, then review cratis-screenplay-scenario-coverage, cratis-screenplay-model-review

Read references/nine-steps.md when facilitating a workflow and needing a step's activities, required output, or questions. Read references/invoicing-example.md when you need a complete worked .play document (RegisterInvoice command and InvoiceList view) to copy the shape from.

Verify

screenplay <model-folder> --warnaserror

(The standalone tool; cratis screenplay validate <model-folder> --warnings-as-errors is the fallback, and neither names the other's verdict. Versions and commands: cratis-screenplay-toolchain.)

  • [ ] Zero errors and zero warnings. An unrecognized construct inside a slice is only a warning (PLAY0029) and its block is silently dropped - a typo can delete a whole projection while the exit code stays 0.
  • [ ] Every behavior is exactly one slice type, and the whole model validates against the eight Quick gate checks.
  • [ ] Every event is past tense, single-purpose, and carries no event-source id.
  • [ ] Personal data is classified on the concept, with a reason.
  • [ ] Specifications name the rejections, not only the happy path.
  • [ ] Bind with the runtime's compiler; tool versions: toolchain SKILL.md. Read references/parsed-not-runnable.md (section "A CLI and Stage that admit v15") when judging what Stage renders: Translate/captures and refused reactions stay gaps, and mixed effects stay STAGE-ESM-037.

Parsed is not runnable

The compiler accepts far more than anything executes. Between the syntax tree and any runtime sits the executable semantic model (ESM), and it fails closed: what it cannot represent reports PLAY0268 or PLAY0271 and the model does not bind. Keep four states apart when you report on a model: parsed (the screenplay tool), bound (ESM), reference-executed (specifications pass the reference runner) and target-executed (Stage or a rendered application). The independent verdicts V1 to V5 that report them are in cratis-screenplay-modeling-lifecycle.

What binds depends on which tool you ask, so name the tool and its version: Read references/parsed-not-runnable.md (section "What binds depends on which tool") when stating what a tool binds or renders (legacy reads and concurrency fail with PLAY0271; protected command reads opt into v25; persona declarations are report-only; an older bundle reports Slice '<name>' of type '<type>' is not admitted by ESM v1.).

The ESM versions, the full disposition table and the Step 7 clock example's binding result are in references/parsed-not-runnable.md and cratis-screenplay-toolchain (references/executable-subset.md). Read references/parsed-not-runnable.md when determining the required ESM version or interpreting binding dispositions. Read cratis-screenplay-toolchain's references/executable-subset.md when checking binder admission or reference-execution limits. Model the wider language freely when the .play file is the deliverable - documentation, review, a shared description of a system. Never read a clean screenplay run as evidence a construct works downstream. The language is frozen at ESM v1–v28 (the freeze decision): model with it, and report a typed Stage, cratis render or Studio refusal as a platform gap rather than waiting for new constructs.

Locate the model

Look first for the project's existing .play files: the folder holding them is the model; a new model goes under Source/ or src/, else Screenplay/, never under .cratis/. Read references/file-layout.md (section "Locate the model") when the location is unclear or source might be copied between repositories. cratis ai install manages .cratis/ai/, never model files.

Verified product sources

Which tool reports what, and how to read installed versions, live only in cratis-screenplay-toolchain SKILL.md; read it before choosing a tool or reporting a version-dependent verdict. Read references/slice-type-rules.md when deciding if a behavior is an Automation or a Translate slice.

Two phases - discovery, then design

Never jump into detailed workflow design without broad domain understanding. Phase 1 maps the territory (actors, processes, outside systems, the most critical workflow; ask, do not assume; it lands as module, persona and import; protocol in cratis-screenplay-discovery). Phase 2 designs one workflow at a time through all nine steps (nine-steps.md: activities, Screenplay output, questions).

Keep modeling reasoning with its declaration

Read references/modeling-reasoning.md when recording assumptions, boundaries or rejected alternatives on a declaration (description, documentation).

The prime directive: do not lose information

Store what happened (events), not just current state. Events are immutable past-tense facts in business language. Every read-model field must trace back to an event. If a field has no source event, something is missing from the model - it is not an optional column. Every value starts somewhere specific (a person's input, the runtime's context, an allocated id, a view's calculation) and is carried by name from there (slice-design references/field-lineage.md).

The four patterns -> the four slice types

Every behavior is exactly one. An unknown slice type is a compile error: Unknown slice type '<x>' - expected StateChange, StateView, Automation or Translate.

Pattern Slice type Screenplay constructs
Command -> Event StateChange command -> produces -> event, plus validate, authorize, constraint
Events -> Read Model StateView readmodel, projection or reducer, query, screen
Event -> decision -> Command/Event Automation reaction
External data -> Event Translate capture

Read references/parsed-not-runnable.md (section "Trigger reads and event generations") when deciding whether a decided construct (trigger reads, event generations) is implemented. An accepted decision is not necessarily implemented.

Where Cratis diverges from the generic method

Two divergences matter, and getting them wrong produces a model that will not compile or will not be safe. Both are deliberate.

  • A command may read state. The generic method forbids ReadModel -> Command edges. Screenplay ships reads <ReadModel> [as <alias>] [by <property>] so the model shows what a state-dependent decision consulted. Application-root command reads protected admits eligible command reads as v25: absent state rejects and matching decide/commit changes conflict. Read protected reads for the strict shape and paths. Legacy reads remain PLAY0271; concurrency is not protection and cannot combine with protected reads. Stage 4.138.0 renders protected reads as Arc read protection (cratis render gets it from the first CLI that bundles it; CLI 3.75.0 refuses them with STAGE-ESM-044); semantic Host/executor support is not generated-app protection. Write state-dependent rules as reads plus require with an indented message; mark refused shapes as unenforced and name the intended target mechanism. Model uniqueness as a unique constraint. Never copy state into a command input, add an attestation flag, or hide the rule in handler prose. Do not use reads to fetch data the command could carry as input. A reaction trigger declares consulted views with reads, but trigger reads remain unprotected; decide in an invoked command instead.
  • Some validation does belong in the model. The generic method routes format rules to the type system. Screenplay's type system is the concept, and a concept carries its own validate block - so a format rule lives on the concept and travels with every use. A state-dependent rule is not a format rule: it needs the modeled reads + require intent, specifications, and the recorded target-enforcement gap described above.

Naming the primitives is the highest-value work

Name concepts before events, classify personal data at the concept, keep events past tense and single-purpose, and never put the event-source identity in an event payload. Read references/naming-primitives.md when declaring concepts, pii classification, event shapes, identifier, inline events or id "<old name>" pins.

Quick gate - before specifications are called done

Run this after the GWT specifications are written. Do not proceed with gaps. When one is found, ask the user to clarify, create the missing element, re-validate. The full critic pass (evidence, severity, business-question review) is cratis-screenplay-model-review.

  1. Every readmodel property traces to an event (backward trace).
  2. Every event feeds a projection, reaction, or capture target (forward trace).
  3. Every command has documented rejection conditions.
  4. Every reaction has a termination condition and cannot loop forever.
  5. No given/when/then clause references an undefined element.
  6. Every behavior is exactly one slice type.
  7. Read-model fields use collection types where the domain allows concurrent instances - ask "can there be more than one of these at once?" for each field.
  8. No cross-cutting infrastructure is modeled as a Translate slice.

Choose a file layout

Choose the coarsest layout that keeps source and diffs readable; compile the folder, or its root file, as one application, because compiling files individually reports false unknown-type errors (PLAY0165, PLAY0166, PLAY0167). Read references/file-layout.md when choosing or changing the file layout, writing import barrels, or compiling a split model. Read multi-service models when the system is several services with their own event stores: one model folder per service, never one folder over all of them.

Route near misses

The lifecycle, toolchain and phase skills are in "Start here" above. Construct and neighbouring skills:

Read references/neighbouring-skills.md when the need is a construct, authoring, rendering, diagram or Chronicle C# skill.

Lineage

Method lineage, Nebulit material and licenses: references/provenance.md. Read it when checking method lineage, attribution, or adaptation permissions.

04 同仓库更多 Skills

Cratis
Cratis/Prologue

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.

★ 0
Cratis
Cratis/Prologue

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.

★ 0
Cratis
Cratis/Prologue

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.

★ 0
Cratis
Cratis/Prologue

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).

★ 0
Cratis
Cratis/Prologue

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.

★ 0
Cratis
Cratis/Prologue

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.

★ 0