Chronicle

Use this skill when asked to add a Chronicle reactor (automation or translation) to a Cratis-based project. Reactors observe events and produce side effects.

Ship staged or unstaged local changes: create a branch, make logical commits, push to origin, open a PR with the correct description and label, merge it, and delete the branch locally and on origin. Use whenever the user asks to commit, push, create a PR, ship, or land changes.

Use this skill when asked to add a validation rule, business rule, or uniqueness constraint to an existing command in a Cratis-based project.

Use this skill when asked to create a strongly-typed domain identifier or value (such as ProjectId, AuthorName, InvoiceNumber) in a Cratis-based project. Produces a ConceptAs<T> record with the correct conversions and sentinel values.

Use this skill when creating a NEW Cratis documentation page under `Documentation/**` (tutorial, how-to, explanation, reference, or recipe). Handles where the file goes (which product repo), sidebar wiring (toc.yml + Diátaxis bucket), and verifying it renders. Trigger on add/create/write a new docs page, document a new feature, or add a new section to a product's docs.

Use this skill when asked to add a database table, column, relationship, or other schema change via Entity Framework Core in a Cratis-based project.

Use this skill when asked to add a Chronicle projection to a Cratis-based project. Favor model-bound projections by default, and only fall back to declarative/fluent `IProjectionFor<T>` projections when model-bound attributes cannot express the behavior cleanly. Enforces the AutoMap-first rule and Chronicle-specific join semantics.

Use this skill when a read model genuinely needs an IReducerFor<T> — when model-bound projection attributes and fluent IProjectionFor<T> cannot express the state transition. Reducers are the last-resort escape hatch, not a default. Covers the admission checklist, method signatures, nullable-current handling, passivity, and pitfalls.

Use this skill when asked to add OpenTelemetry tracing to a class in a Cratis Chronicle Kernel project. Produces `*Traces.cs` companion files using the `[Span]` source-generator pattern from `Cratis.Traces`, registers `IActivitySource<T>` as a keyed DI service, and injects it into the target class.

Use this skill for authentication, authorization, or identity in a Cratis Arc project — backend, frontend, or both. Covers identity providers (`IProvideIdentityDetails`), protecting commands/queries with authorization attributes, Microsoft Identity Platform, connecting backend identity to React, multi-tenant identity, and local-dev generated principals. Trigger on auth, login, roles, permissions, identity details, user context, or protecting endpoints.

Execute a Cratis Arc command from backend code via ICommandPipeline — the scopeless and scoped overloads, typed Execute<TResult>, pre-flight Validate, and reading CommandResult. Use when a reactor, background job, scheduled task, integration test, or backend service needs to run a command without going through HTTP.

Step-by-step guidance for creating a Cratis Arc command — [Command] record, Handle() method, CommandValidator, proxy generation, and React .use() hook with CommandDialog. Use when adding or creating a command, wiring up a form or button to the backend, working with IEventLog, CommandResult, CommandValidator, CommandDialog, or [Command] attribute.

Reference for Cratis C# coding conventions — formatting, naming, records, nullable handling, exceptions, logging, and DI. Use whenever writing C# in a Cratis project, deciding between record vs class, checking naming rules, applying formatting conventions, handling null safety, creating exception types, or asking "how should this be written?" Also covers CUPID characteristics and domain-based folder structure. Trigger on any C# style or standards question for a Cratis project.

Step-by-step guidance for building a React page in a Cratis Arc application — DataPage lists, CommandDialog toolbar actions, row selection, details components, observable queries, and MVVM. Use when building or modifying a page that lists/displays data, adding a table, wiring Add/Edit/Delete, or connecting a component to a proxy-generated query (standard or observable).

Step-by-step guidance for creating a Cratis Chronicle read model from scratch — defining events, choosing between projection and reducer, [ReadModel] record with static query methods, and the generated TypeScript proxy in React. Use when creating a read model, working with [EventType], [ReadModel], IProjectionFor, IReducerFor, observable queries, or deriving state from events. For adding a projection or reactor to an existing read model, use add-projection instead.

Step-by-step guidance for writing C# specs in Cratis with BDD Specification by Example — the Establish/Because/should_ pattern, for_/when_/and_ folder hierarchy, reusable given/ contexts, NSubstitute mocking, and the in-process scenario family. Use when writing C# unit or integration specs or structuring the for_/when_/and_ hierarchy. For specs tied to a specific vertical-slice command, write-specs is the focused workflow.

Step-by-step guidance for writing TypeScript specs in Cratis using BDD-style Specification by Example — the given()/describe/it pattern, for_/when_/ folder hierarchy, reusable context classes, Sinon mocking, and Chai assertions. Use whenever writing TypeScript specs or tests, creating spec files/folders, using the given() helper, mocking with sinon.createStubInstance or sinon.stub, asserting with Chai .should, or understanding how yarn test runs specs.

Explains how vertical feature slices are structured in a Cratis Chronicle + Arc application — folder layout, the single backend .cs file, the four slice types (State Change/View/Automation/Translation), and how features compose slices. Use when asking how slices work, where files go, or which slice type to choose. To actually build a new slice end-to-end, use new-vertical-slice instead.

Create and maintain Mermaid eventmodeling diagrams (EventModel.md) for a Cratis module or feature. Use when adding, renaming, moving, or deleting modules/features/slices, commands, events, read models, automations, translations, or cross-module event flows — to keep the diagram in sync with the code.

Attach audit/correlation metadata to every appended Cratis event without polluting event types — via ICanProvideAdditionalEventInformation, plus event tags and the built-in EventContext fields. Use for correlation IDs, tenant/actor context, and other cross-cutting concerns that should travel with events but are not domain payload.

Use this skill to diagnose why a Cratis slice misbehaves — read model not updating, TypeScript proxy missing, command rejected unexpectedly, projection/observer quarantined, AutoMap mismatch, reactor side effects not appended, or specs flaking. Symptom → likely cause → the rule/skill that owns the fix. Use when something "isn't working" and the cause isn't obvious.

Use this skill when asked to wire up a type that needs to enumerate every implementation of an interface (handlers, strategies, filters, validators, formatters, providers) in a Cratis-based C# project. Enforces `IInstancesOf<T>` over `IEnumerable<T>` and removes hand-maintained DI registrations.

Use this skill to change, fix, or improve Cratis documentation whose source is under `Documentation/**` in a product or contributing repo. Docs are split across repos (each product owns its `Documentation/` folder; the `Documentation` repo aggregates), so it finds the real source file, edits, syncs, and verifies. Trigger on edit/fix/reword a docs page, fix a broken link, or correct a code example/outdated page — for any Cratis product.

Design a Cratis event model before writing code — decide stream boundaries, commands, events, read models, automations/translations, compliance subjects, and the spec outline. Use this when behavior, event vocabulary, stream boundaries, or a multi-slice flow is not yet settled, before implementing a slice.

Evolve a Cratis Chronicle event schema without breaking replay — add a new generation and an EventTypeMigration so old stored events upcast into the new shape. Use when an event needs a new required property, a renamed property, or a structural change after events of the prior shape already exist.

Isolate tenants in a Cratis application with Chronicle namespaces — Arc maps the current tenant to a namespace (TenantNamespaceResolver), and each namespace has its own events, projections, reducers, and read models. Use when one deployment must serve multiple tenants with data isolation. Keep it product-neutral — not every Cratis app is multi-tenant.

Use this skill when asked to implement a new feature, command, query, slice, or screen in a Cratis-based project. Guides the full end-to-end workflow: C# backend → Debug+Release build → specs → React frontend → quality gates.

Practical guidance for debugging and exploring Cratis Arc observable queries with cURL or other plain HTTP clients. Use this whenever the user mentions observable queries together with cURL, curl, HTTP GET debugging, waiting for the first payload, Server-Sent Events, SSE, streaming JSON, or long polling. Also use it when the user wants to inspect an observable query without writing frontend code.

Use this skill to visually QA rendered Cratis docs pages after changes under `Documentation/**` — screenshot headless in light AND dark, check diagrams/tables/code blocks render, and diagnose layout-shift ("flicker"/"jump"/"pop") bugs. Trigger on screenshot the docs, check how a page looks, review the docs visually, verify a diagram or table renders, or investigate a flicker/layout-shift on the docs site.

Add server-side paging and sorting to a Cratis read-model query — return IQueryable<T> for one-shot paging, ISubject<IQueryable<T>> for observable + paged results, and consume them from React with useWithPaging. Use when a list query can grow large enough that returning all rows is wasteful, or needs server-side sorting.

Use this skill when asked to review, check, or validate code in a Cratis-based project. Produces a structured review report with blocking issues and suggestions, checked against all project architecture and style standards.

Use this skill when asked to perform a security review or security audit of code in a Cratis-based project. Checks for injection, auth/authz, data exposure, secrets, and event-sourcing-specific vulnerabilities.

Use this skill when asked to create a new feature, section, or page that does not yet exist in a Cratis-based project. Sets up the folder, composition page, routing, and navigation entry before any slices are added.

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Step-by-step guidance for building a multi-step wizard dialog (StepperCommandDialog) in a Cratis Arc application. Use whenever a command requires gathering information across multiple steps, implementing a wizard flow, breaking a complex form into named stages, or using StepperCommandDialog, StepperPanel, validateOnInit, or wizard-style navigation.

Use this skill when asked to add or build a canvas-style icon toolbar using the @cratis/components Toolbar component. Covers Toolbar, ToolbarButton, ToolbarSeparator, ToolbarSection, ToolbarContext, and ToolbarFanOutItem. Use whenever building tool panels, drawing tool selectors, zoom controls, or any icon-button group with active states, context switching, or fan-out sub-panels.

Diátaxis classification and authoring guidance for Cratis docs — decide whether a page is a Tutorial, How-to, Reference, or Explanation and draft its content in that style. For WHERE a new page goes + sidebar wiring use add-cratis-docs-page; to change an existing page use edit-cratis-docs.

Use this skill when asked to write tests or specs for event appending, event log behavior, constraint violations, or concurrency violations using EventScenario in a Cratis-based project. Produces infrastructure-free in-process specs using EventScenario and AppendResult Should* extensions.

Use this skill to write specs for the React/TypeScript surface of a Cratis APPLICATION slice — view models, helpers, and component behavior (Vitest + Mocha-style describe/it + Sinon + Chai .should). The frontend peer to write-specs (backend). For framework @cratis/* package specs use cratis-specs-typescript instead.

Use this skill when asked to write tests or specs for read model projections, reducers, or model-bound projections using ReadModelScenario in a Cratis-based project. Produces infrastructure-free in-process specs using ReadModelScenario<TReadModel>.