@eventmodelers/cli 0.0.1

package/stacks/cratis-csharp/templates/.claude/skills/_shared/cratis-conventions.md

@@ -0,0 +1,251 @@
+# Cratis Conventions — Distilled
+
+> Self-contained distillation of the Cratis way of building software, taken from the shared
+> Cratis AI configuration (cratis.io). The build skills (`build-state-change`, `build-state-view`,
+> `build-automation`) all rely on these conventions. When in doubt, follow the established pattern in
+> the target project over anything written here — **consistency is king**.
+
+## Stack
+
+- .NET / C# 13, ASP.NET Core. **Cratis Arc** for CQRS, **Cratis Chronicle** for event sourcing,
+  **MongoDB** for read models.
+- React + TypeScript (Vite), PrimeReact UI — generated from C# via **proxy generation** on `dotnet build`.
+- Specs: xUnit + **Cratis.Specifications** + NSubstitute, BDD `for_*/when_*/and_*` layout.
+
+## The eight values (apply these when a rule doesn't cover a case)
+
+1. **Lovable APIs** — sane defaults, flexible, overridable.
+2. **Easy to do right, hard to do wrong** — convention over configuration; discovery by naming.
+3. **Events are facts** — immutable, never nullable, never ambiguous, never multipurpose. A nullable
+   property on an event means you need a *second* event.
+4. **High cohesion through vertical slices** — everything for a behavior lives together.
+5. **Full-stack type safety** — C# → proxy generation → TypeScript, no manual sync.
+6. **Specialization over reuse** — dedicated read models per use case, never one shared model.
+7. **Consistency is king** — match the established pattern over local cleverness.
+8. American English spelling everywhere (behavior, color, initialize, modeling, dialog, …).
+
+## Non-negotiable structural rules
+
+- **ONE `.cs` file per slice** holds ALL backend artifacts: `[Command]` records with `Handle()`,
+  validators, constraints, `[EventType]` records, `[ReadModel]` records with static query methods,
+  projections/reducers, reactors, and slice-specific concepts.
+- **Never split by artifact type** — no `Commands/`, `Handlers/`, `Events/` folders.
+- **Commands define `Handle()` directly on the record** — never a separate handler class.
+- **`[EventType]` takes NO arguments** — the type name is the identifier.
+- **Drop the `.Features.` segment from namespaces** — `MyApp.Authors.Registration`, not
+  `MyApp.Features.Authors.Registration`.
+- Complete one slice end-to-end before starting the next.
+- **File header:** match the project. The shipped starter's example slices use **no** header — follow
+  that. (Cratis's own framework repos use a copyright header; only add one if the project's existing
+  `.cs` files already carry it.)
+
+## Folder convention
+
+Slices live in a **module → feature → slice** hierarchy. **Discover the actual top-level folder from an
+existing slice in the project** (the shipped starter uses `SomeModule/SomeFeature/...`; some projects
+use a `Features/` root) — match what's already there. Namespace mirrors the folders and drops any
+`.Features.` segment: `<Root>.<Module>.<Feature>.<Slice>` (the starter's `<Root>` is `CratisApp`).
+
+```
+<Module>/<Feature>/
+├── <Feature>.tsx              ← composition page (layout, buttons, dialogs, tables)
+├── index.ts                   ← barrel: export * from './<Feature>'
+├── <Concept>.cs               ← shared concepts for this feature (ConceptAs<T>)
+└── <Slice>/
+    ├── <Slice>.cs             ← ALL backend artifacts in ONE file
+    ├── <Proxy>.ts             ← GENERATED by dotnet build — never hand-edit (marked // @generated)
+    ├── <Component>.tsx        ← React component(s) using the co-located generated proxy
+    ├── index.ts               ← barrel export
+    └── when_<behavior>/       ← integration specs (state-change slices)
+        ├── and_<scenario>.cs
+        └── ...
+```
+
+**Proxies are generated next to the source.** The starter `.csproj` sets
+`CratisProxiesUseSourceFileAsOutputFile=true`, so `dotnet build` writes each TypeScript proxy beside its
+`.cs` file (`Register.ts` next to `Registration.cs`). Frontend imports the proxy from the **same folder**
+(`import { Register } from './Register'`). Never edit a `// @generated` file. (Some projects instead
+generate into a separate `api/` folder — follow whatever the existing slices do.)
+
+## Concepts — `ConceptAs<T>` (never raw primitives in domain models)
+
+```csharp
+public record AuthorId(Guid Value) : ConceptAs<Guid>(Value)
+{
+    public static readonly AuthorId NotSet = new(Guid.Empty);
+    public static implicit operator Guid(AuthorId id) => id.Value;
+    public static implicit operator AuthorId(Guid value) => new(value);
+    public static implicit operator EventSourceId(AuthorId id) => new(id.Value.ToString());
+    public static AuthorId New() => new(Guid.NewGuid());
+}
+```
+
+- Positional `record` inheriting `ConceptAs<T>` (value equality + immutability for free).
+- Add implicit conversion **to** `T`. Add a `static readonly NotSet` sentinel instead of `null`.
+- `Guid` identity concepts: add `static New()` and an implicit conversion to `EventSourceId`.
+- One concept per file, in the feature folder it belongs to (shared between features → `Features/` root).
+
+## Events — `[EventType]`
+
+```csharp
+[EventType]
+public record AuthorRegistered(AuthorName Name);
+```
+
+- **No attribute arguments** — never `[EventType("some-guid")]`.
+- Past-tense names: `AuthorRegistered`, `BookReserved`, `AddressChanged`.
+- Never nullable properties; one purpose per event.
+
+## Commands — `[Command]` with `Handle()` on the record
+
+```csharp
+[Command]
+public record RegisterAuthor(AuthorName Name)
+{
+    public AuthorRegistered Handle() => new(Name);
+}
+```
+
+- `[Command]` from `Cratis.Arc.Commands.ModelBound`; required for discovery.
+- `Handle()` returns: single event, `(eventSourceId, event)` tuple (Arc returns the id as
+  `CommandResult<T>.response`), `IEnumerable<object>` for multiple events, `Result<TSuccess,TError>`,
+  or `void`.
+- Imperative name — `RegisterAuthor`, not `RegisterAuthorCommand`.
+- Event source resolved from a `[Key]` parameter, an `EventSourceId`-convertible concept, or
+  `ICanProvideEventSourceId`.
+- Inject services / constraints / read models as `Handle()` parameters — DI provides them. A read-model
+  parameter gives you current Chronicle-derived state for **DCB** business rules.
+
+### Validation
+```csharp
+public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
+{
+    public RegisterAuthorValidator() =>
+        RuleFor(c => c.Name).NotEmpty().WithMessage("Name is required").MaximumLength(100);
+}
+```
+- Extend `CommandValidator<T>` (not `AbstractValidator<T>`) — auto-discovered, runs client-side and
+  via the auto-generated `/validate` endpoint.
+
+## Read Models — `[ReadModel]` + static query methods
+
+```csharp
+[ReadModel]
+public record AuthorListItem(AuthorId Id, AuthorName Name, int BookCount)
+{
+    public static async Task<IEnumerable<AuthorListItem>> AllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => await collection.Find(_ => true).ToListAsync();
+
+    public static ISubject<IEnumerable<AuthorListItem>> ObserveAllAuthors(
+        IMongoCollection<AuthorListItem> collection)
+        => collection.Observe();
+}
+```
+
+- `[ReadModel]` required. Query methods are **`public static`** on the record — the method name becomes
+  the TypeScript query proxy class name. No controller, no `IReadModels` injection.
+- Observable (real-time) queries return `ISubject<T>` directly — never `Task<ISubject<T>>`.
+- Prefer model-bound projection attributes; AutoMap is **on by default** (`.From<EventType>()` directly).
+- **Projections join events, never read models.** One read model per use case.
+
+### Projection (declarative mapping)
+```csharp
+public class AuthorListItemProjection : IProjectionFor<AuthorListItem>
+{
+    public void Define(IProjectionBuilderFor<AuthorListItem> builder) => builder
+        .From<AuthorRegistered>(from => from.Set(m => m.Name).To(e => e.Name))
+        .From<BookAdded>(from => from.Add(m => m.BookCount).With(_ => 1));
+}
+```
+
+### Model-bound shorthand
+```csharp
+[ReadModel]
+public record AuthorInfo(
+    [Key] Guid Id,
+    [FromEvent<AuthorRegistered>] string Name);
+```
+
+### Reducer (running aggregates — balances, counts, sums)
+```csharp
+public class BalanceReducer : IReducerFor<Balance>
+{
+    public Balance Deposited(FundsDeposited @event, Balance? current, EventContext context)
+        => (current ?? new(0m)) with { Amount = (current?.Amount ?? 0m) + @event.Amount };
+}
+```
+Return the complete new state; never mutate `current` (`null` on first event). Projections/reducers
+are discovered automatically — no registration.
+
+## Reactors — `IReactor` (automation + translation slices)
+
+```csharp
+public class StockKeeping(IStockKeeper stock, ICommandPipeline commands) : IReactor
+{
+    public async Task BookReserved(BookReserved @event, EventContext context) =>
+        await commands.Execute(new DecreaseStock(@event.Isbn, await stock.GetStock(@event.Isbn)));
+}
+```
+
+- `IReactor` is a **marker interface** — dispatch is by the **first parameter type** of each public
+  method. Method name is for readability only. Signature: `Task Method(TEvent @event, EventContext context)`.
+- Reactors *do things* (side effects); they never build read-model state.
+- To write new events, inject `ICommandPipeline` and `Execute` a command — **never** use `IEventLog`
+  directly from a reactor.
+- **Design for idempotency** — a reactor may run more than once (replay/recovery). Use event data
+  directly; never read the read model back inside a reactor. Keep reactors stateless.
+- **Translation** = a reactor that adapts an event by triggering a command in its own slice.
+
+## Specs — BDD with Cratis.Specifications
+
+```csharp
+public class when_registering : Specification
+{
+    RegisterAuthor _command;
+    AuthorRegistered _event;
+
+    void Establish() => _command = new(new AuthorName("John"));
+    void Because() => _event = _command.Handle();
+
+    [Fact] void should_carry_the_name() => _event.Name.Value.ShouldEqual("John");
+}
+```
+
+- Inherit `Specification`. `Establish()` = setup, `Because()` = the **one** action, `[Fact] should_*()`
+  = one assertion each (no blank lines between facts). Fields `private`/`protected`, `_camelCase`.
+- Shared setup → `given/` contexts (`all_dependencies` → `a_<sut>`). Mock with NSubstitute.
+- Folder/file names read as English: `for_<Type>/when_<behavior>/and_<condition>.cs`.
+- Chronicle integration specs live in the slice's `when_<behavior>/` folder and run against a real
+  event store using `Given<context>` + `ChronicleOutOfProcessFixture`; assert with
+  `Context.ShouldHaveAppendedEvent<T>(...)`.
+
+## React (frontend) — only relevant once `dotnet build` has generated proxies
+
+- Import the generated command/query proxy from the slice's `../api/...` path.
+- Commands: `const [command] = MyCommand.use();` → set props → `await command.execute()` →
+  check `result.isSuccess` / `result.response`.
+- Queries: `MyQuery.use()` (snapshot) or `MyQuery.useWithPaging(pageSize)`.
+- Dialogs: `CommandDialog` from `@cratis/components/CommandDialog`, `Dialog` from
+  `@cratis/components/Dialogs`. **Never** import `Dialog` from `primereact/dialog`.
+- PrimeReact CSS variables for colors (no hard-coded hex). No `any` — use `unknown` + type guards.
+  Full descriptive names (`event`, not `e`; `index`, not `idx`).
+
+## Build / test / sequencing
+
+- **`dotnet build`** compiles the backend AND regenerates the TypeScript proxies. The frontend cannot
+  reference a slice's proxy until the backend compiles — so the order is strict:
+  **Backend → `dotnet build` → Frontend.** Backend and frontend of the same slice never run in parallel.
+- Zero warnings, zero errors — warnings are treated as errors.
+- `dotnet test` (filter to the slice while iterating:
+  `dotnet test --filter "FullyQualifiedName~<SliceName>"`).
+- Slice-by-slice order: Backend → Specs → `dotnet build` → Frontend → Composition page → Routes.
+
+## Final verification against `slice.json` (the JSON is the source of truth)
+
+- Every `commands[]` field → a Command record property. No invented fields, none missing.
+- Every event in `events[]` → an `[EventType]` record; names match exactly; no invented fields.
+- Every read model field → a `[ReadModel]` property fed by a projection/reducer mapping.
+- Every specification / GWT scenario in the slice → an executable spec.
+- No business rule appears in `Handle()` that is not in the slice `description`/`comments`.
+- If a field is not in `slice.json`, it is not in the code.

package/stacks/cratis-csharp/templates/.claude/skills/build-automation/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: build-automation
+description: >
+  Implement automation and translation slices the Cratis way — an IReactor that observes events and
+  produces side effects, triggering further writes via ICommandPipeline. Use when: (1) implementing a
+  new automation / reactor in a Cratis project, (2) a slice.json has a non-empty processors[] section
+  or sliceType === "TRANSLATION", (3) the user provides an Event Modeling artifact or description of an
+  event-driven reaction and asks to implement it, (4) the user says "implement", "create", "add" an
+  automation, reactor, translation, or event-to-command flow in a Cratis Arc / Chronicle project.
+---
+
+# Cratis — Automation / Translation Slice
+
+An automation *reacts* to events and *does things* (side effects). A translation adapts an event by
+triggering a command in its own slice. Both are implemented with an **`IReactor`**.
+
+```
+event  →  IReactor method (dispatch by first param type)  →  side effect / ICommandPipeline.Execute(command)
+```
+
+> **Read first:** [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md). Everything
+> below assumes those rules.
+
+## Step 0 — Discover conventions
+
+Read `CLAUDE.md` and one existing reactor. Confirm the namespace root, how reactors are placed within a
+slice, which services are available for side effects, and how existing translations call
+`ICommandPipeline`. Resolve slice `comments` when done (see the state-change skill's Step 0).
+
+## Step 1 — Understand the input (`slice.json` is the source of truth)
+
+| Element | What to extract |
+|---|---|
+| **Trigger event(s)** | Which event(s) the reactor observes (the method's first parameter type) |
+| **Reaction** | The side effect — notify, call a service, or trigger a command |
+| **Target command** | For translation: which command to `Execute`, and how its fields map from the event |
+| **Idempotency** | The reaction must be safe to run more than once (replay/recovery) |
+| **Specifications** | Each scenario → an executable spec |
+
+If a command field has no source in the trigger event or an injected service, do not invent it.
+
+## Step 2 — Write the reactor in the slice `.cs` file
+
+`<Module>/<Feature>/<Slice>/<Slice>.cs` — namespace `<Root>.<Module>.<Feature>.<Slice>` (mirror the folders; drop any `.Features.`).
+
+### Automation — side effect
+```csharp
+public class ProjectRegisteredNotifier(INotificationService notifications) : IReactor
+{
+    public async Task ProjectRegistered(ProjectRegistered @event, EventContext context) =>
+        await notifications.Notify($"Project '{@event.Name}' was registered.");
+}
+```
+
+### Translation — event → command via ICommandPipeline
+```csharp
+public class StockKeeping(IStockKeeper stock, ICommandPipeline commands) : IReactor
+{
+    public async Task BookReserved(BookReserved @event, EventContext context) =>
+        await commands.Execute(new DecreaseStock(@event.Isbn, await stock.GetStock(@event.Isbn)));
+}
+```
+
+**Critical rules:**
+- `IReactor` is a **marker interface** — dispatch is by the **first parameter type**. Method name is
+  for readability only. Signature: `Task Method(TEvent @event, EventContext context)` (`EventContext`
+  optional).
+- To write new events, inject `ICommandPipeline` and `Execute` a command — **never** use `IEventLog`
+  directly from a reactor.
+- **Design for idempotency** — a reactor may run more than once. Use event data directly; never query
+  the read model back inside a reactor. Keep the reactor stateless (constructor-injected deps only).
+- One focused concern per reactor class; multiple handler methods are fine if they serve that concern.
+
+If the translation's target command doesn't exist yet, implement it first with the
+**build-state-change** skill, then reference it here.
+
+## Step 3 — Build
+
+`dotnet build` from the project root — zero warnings / errors.
+
+## Step 4 — Specs
+
+Write specs proving the reactor reacts correctly — for translations, assert the expected command was
+executed (mock `ICommandPipeline` with NSubstitute and verify `Execute` was called with the mapped
+command); for automations, assert the side-effect service was invoked. Cover idempotency where the
+slice calls for it. One spec per scenario. Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`.
+See [references/patterns.md](references/patterns.md).
+
+## Final verification — does the implementation match `slice.json`?
+
+- [ ] The reactor observes exactly the trigger event(s) named in the slice.
+- [ ] For translation: the executed command and its field mapping match the slice; the command exists.
+- [ ] No new events written via `IEventLog` — only via `ICommandPipeline`.
+- [ ] The reaction is idempotent; the reactor is stateless.
+- [ ] Every scenario → an executable spec; `dotnet build` clean; specs pass.
+
+## References
+- [references/patterns.md](references/patterns.md) — full reactor/translation code and reactor specs.
+- [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md) — the Cratis conventions.

package/stacks/cratis-csharp/templates/.claude/skills/build-automation/references/patterns.md

@@ -0,0 +1,115 @@
+# Automation / Translation Patterns — Cratis Arc + Chronicle
+
+Complete code for automation and translation slices. The reactor lives in the slice's single
+`<Module>/<Feature>/<Slice>/<Slice>.cs` (the shipped starter uses `SomeModule/SomeFeature/...` — match
+whatever the existing slices use). The example slices use no file header (match the project); namespace
+mirrors the folders and drops any `.Features.`. Examples below use short illustrative names; mirror your
+project's actual module/feature layout instead.
+
+---
+
+## 1. Automation — react with a side effect
+
+```csharp
+// Features/Projects/RegistrationNotifications/RegistrationNotifications.cs
+namespace MyApp.Projects.RegistrationNotifications;
+
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Reactors;
+
+public class ProjectRegisteredNotifier(INotificationService notifications) : IReactor
+{
+    /// <summary>Sends a notification when a project is registered.</summary>
+    public async Task ProjectRegistered(ProjectRegistered @event, EventContext context) =>
+        await notifications.Notify($"Project '{@event.Name}' was registered.");
+}
+```
+
+---
+
+## 2. Translation — event → command via ICommandPipeline
+
+```csharp
+// Features/Inventory/StockKeeping/StockKeeping.cs
+namespace MyApp.Inventory.StockKeeping;
+
+using Cratis.Arc.Commands;
+using Cratis.Chronicle.Events;
+using Cratis.Chronicle.Reactors;
+
+public class StockKeeping(IStockKeeper stock, ICommandPipeline commands) : IReactor
+{
+    /// <summary>Decreases stock when a book is reserved.</summary>
+    public async Task BookReserved(BookReserved @event, EventContext context) =>
+        await commands.Execute(new DecreaseStock(@event.Isbn, await stock.GetStock(@event.Isbn)));
+}
+```
+
+The `DecreaseStock` command lives in its own slice (build it with the build-state-change skill first if
+it doesn't exist). The reactor only triggers it.
+
+---
+
+## 3. Multiple handlers in one reactor (same concern)
+
+```csharp
+public class OrderFulfillment(ICommandPipeline commands) : IReactor
+{
+    public Task OrderPlaced(OrderPlaced @event, EventContext context) =>
+        commands.Execute(new ReserveInventory(@event.OrderId, @event.Items));
+
+    public Task PaymentCaptured(PaymentCaptured @event, EventContext context) =>
+        commands.Execute(new ShipOrder(@event.OrderId));
+}
+```
+
+---
+
+## 4. Idempotency
+
+A reactor may be invoked more than once for the same event (replay, recovery, redelivery). Use only the
+event's own data, keep the reactor stateless, and make the triggered command/side effect safe to repeat
+(e.g. the target command is itself idempotent, or carries a key that de-duplicates). Never read the read
+model back inside the reactor to "check if already done".
+
+---
+
+## 5. Reactor spec (translation — assert the command was executed)
+
+```csharp
+namespace MyApp.Inventory.StockKeeping.for_StockKeeping.when_a_book_is_reserved;
+
+public class and_stock_is_available : Specification
+{
+    IStockKeeper _stock;
+    ICommandPipeline _commands;
+    StockKeeping _reactor;
+
+    void Establish()
+    {
+        _stock = Substitute.For<IStockKeeper>();
+        _stock.GetStock("123").Returns(Task.FromResult(5));
+        _commands = Substitute.For<ICommandPipeline>();
+        _reactor = new StockKeeping(_stock, _commands);
+    }
+
+    async Task Because() => await _reactor.BookReserved(new BookReserved("123"), EventContext.Empty);
+
+    [Fact] void should_decrease_stock() =>
+        _commands.Received(1).Execute(Arg.Is<DecreaseStock>(c => c.Isbn == "123" && c.Quantity == 5));
+}
+```
+
+For automations, mock the side-effect service (e.g. `INotificationService`) and assert it was called.
+Match the project's existing reactor-spec harness (`IReactorInvoker` / `ReactorHandler`) for full
+event-store-driven specs — discover it from an existing reactor's specs.
+
+---
+
+## Checklist
+
+- One `.cs` file, namespace without `.Features.` (no file header unless the project uses one).
+- `IReactor` marker; dispatch by **first parameter type**; `Task Method(TEvent, EventContext)`.
+- New writes only via `ICommandPipeline.Execute(...)` — never `IEventLog` from a reactor.
+- Stateless and idempotent; constructor-injected dependencies only.
+- One spec per scenario; `dotnet build` clean; specs pass.

package/stacks/cratis-csharp/templates/.claude/skills/build-state-change/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: build-state-change
+description: >
+  Implement Event Sourcing write slices the Cratis way — using Cratis Arc (CQRS) + Cratis Chronicle
+  (event sourcing) in a .NET / C# project. A write slice is: Command → Handle() → Event(s), with
+  optional validators, constraints, and DCB business rules. Use when: (1) implementing a new write
+  slice / command in a Cratis project, (2) a slice.json has a non-empty commands[] / events[] section,
+  (3) the user provides an Event Modeling artifact, specification, or natural-language description of a
+  command and asks to implement it, (4) the user says "implement", "create", "add" a write slice,
+  command, or state change in a Cratis Arc / Chronicle project.
+---
+
+# Cratis — Write Slice (State Change)
+
+A write slice mutates state by recording events. In Cratis Arc the whole path lives in **one `.cs`
+file**:
+
+```
+[Command] record + Handle()  →  validator/constraint  →  [EventType] record(s)  →  dotnet build  →  specs
+```
+
+> **Read first:** [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md) — the
+> non-negotiable Cratis rules. Everything below assumes them.
+
+## Step 0 — Discover the target project's conventions
+
+Before writing code, read the project's `CLAUDE.md` and **at least one existing slice** (the starter
+ships one under `SomeModule/SomeFeature/`). Confirm:
+
+- The namespace root (read the `.csproj` `<RootNamespace>` and existing `.cs` files — never
+  hard-code it; the namespace mirrors the folders and drops any `.Features.` segment).
+- How existing commands return results (single event / tuple / `Result<,>` / `void`).
+- How `ConceptAs<T>` identity types are declared and where they live.
+- Whether existing `.cs` files use a file header (the starter uses none).
+
+> **Comments & description:** each slice element carries a `comments: string[]` array and a
+> `description`. Use them as implementation hints. When done, resolve each used comment:
+> `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`
+> (get IDs first via GET on the same path).
+
+## Step 1 — Understand the input (`slice.json` is the source of truth)
+
+Extract, regardless of input format:
+
+| Element | What to extract |
+|---|---|
+| **Command** | Name (imperative), fields, which field is the event source / `[Key]` |
+| **Events** | Names (past tense), fields, which events this command appends |
+| **Business rules** | Preconditions, invariants, idempotency — from `description` / `comments` only |
+| **State needed for rules** | Which read model must be inspected (DCB) to evaluate a rule |
+| **Specifications** | Each GWT / scenario maps 1:1 to an executable spec |
+
+**If a field is not in `slice.json`, it does not go in the code.** If requirements are unclear, ask
+the user before proceeding.
+
+### Determine the trigger
+If unclear how the command is dispatched, ask:
+> - **UI / REST** — exposed automatically by Arc; add a React component + integration spec.
+> - **Automation only** — dispatched internally by a reactor (no UI). The command still exists; no `.tsx`.
+
+## Step 2 — Create concept types (if needed)
+
+For any new identity / value, add one `ConceptAs<T>` per file in the feature folder. Use the canonical
+Guid-identity pattern (with `NotSet`, `New()`, and the `EventSourceId` conversion) — see the shared
+conventions doc and [references/patterns.md](references/patterns.md).
+
+## Step 3 — Write the slice `.cs` file
+
+`<Module>/<Feature>/<Slice>/<Slice>.cs` — ALL backend artifacts in this one file; namespace
+`<Root>.<Module>.<Feature>.<Slice>` (no file header unless the project uses one).
+
+### Events first
+```csharp
+[EventType]                                   // NEVER any arguments
+public record AuthorRegistered(AuthorName Name);
+```
+Past tense, no nullable properties, one purpose each. If the context's events already exist elsewhere,
+reuse them — don't redefine.
+
+### Command with `Handle()` on the record
+```csharp
+[Command]
+public record RegisterAuthor(AuthorName Name)
+{
+    public AuthorRegistered Handle() => new(Name);   // Arc appends the returned event
+}
+```
+
+Pick the return shape that matches the slice:
+- **single event** → `EventName Handle()`
+- **generate + return a new id** → `(NewId, EventName) Handle()` (Arc returns the id as
+  `CommandResult<T>.response`)
+- **multiple events** → `IEnumerable<object> Handle() => [ new A(...), new B(...) ];`
+- **success/error** → `Result<TSuccess, TError> Handle()`
+- **side-effect only** → `void Handle()`
+
+Event source: a `[Key]` parameter, an `EventSourceId`-convertible concept, or `ICanProvideEventSourceId`.
+
+### Business rules (DCB) — inject the read model
+When a rule depends on event-sourced state, take the read model as a `Handle()` parameter; Arc injects
+current state. Throw / return an error for violations:
+```csharp
+[Command]
+public record RegisterAuthor(AuthorName Name)
+{
+    public Result<AuthorRegistered, RegistrationError> Handle(AuthorByName existing) =>
+        existing is not null
+            ? RegistrationError.NameAlreadyTaken
+            : new AuthorRegistered(Name);
+}
+```
+Only encode rules that appear in the slice `description` / `comments`. See
+[references/patterns.md](references/patterns.md) for the full DCB and constraint patterns.
+
+### Validation (optional but recommended)
+```csharp
+public class RegisterAuthorValidator : CommandValidator<RegisterAuthor>
+{
+    public RegisterAuthorValidator() =>
+        RuleFor(c => c.Name).NotEmpty().WithMessage("Name is required").MaximumLength(100);
+}
+```
+Extend `CommandValidator<T>` — auto-discovered, no registration. One `RuleFor` per validation in the slice.
+
+## Step 4 — Build
+
+From the project root: `dotnet build`. Fix ALL warnings and errors before continuing (warnings = errors).
+This also regenerates the TypeScript proxies the frontend depends on.
+
+## Step 5 — Write specs (one per scenario in `slice.json`)
+
+Put integration specs in `<Module>/<Feature>/<Slice>/when_<behavior>/and_<scenario>.cs`. Cover, from the
+slice's specifications:
+- **Happy path** — command succeeds, correct event appended.
+- **Each validation failure** — one spec per rule.
+- **Each DCB business-rule violation** — one spec per read-model condition in `Handle()`.
+- **Each constraint violation.**
+
+Use the Cratis BDD pattern (`Specification`, `Establish` / `Because` / `[Fact] should_*`). For
+Chronicle integration specs use `Given<context>` + `ChronicleOutOfProcessFixture` and assert with
+`Context.ShouldHaveAppendedEvent<T>(...)`. See [references/patterns.md](references/patterns.md).
+
+Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`. Fix all failures.
+
+## Step 6 — Frontend (only if the command is UI-triggered)
+
+After `dotnet build` generated the proxy (co-located next to the `.cs`), add
+`<Module>/<Feature>/<Slice>/<Component>.tsx` importing the proxy from `./`, using `CommandDialog` /
+inline form. Add a barrel `index.ts`. Register it in the feature's composition
+page. See the shared conventions doc's React section and [references/patterns.md](references/patterns.md).
+
+## Final verification — does the implementation match `slice.json`?
+
+- [ ] Every `commands[]` field → a Command record property (no invented, none missing).
+- [ ] Every `events[]` entry → an `[EventType]` record; names match exactly; fields match.
+- [ ] Every specification / GWT scenario → an executable spec.
+- [ ] No business rule in `Handle()` that is absent from the slice `description` / `comments`.
+- [ ] `dotnet build` is clean (0 warnings / 0 errors); slice specs pass.
+
+## References
+- [references/patterns.md](references/patterns.md) — full command/event/validator/constraint/DCB code,
+  integration specs, and the React command UI patterns.
+- [../_shared/cratis-conventions.md](../_shared/cratis-conventions.md) — the Cratis conventions.