write-specs

Write comprehensive in-process BDD specs for an event-sourced Cratis application slice. Lead with the scenario family; reserve out-of-process Chronicle host specs for the host/transport boundary. Full patterns and assertion catalogs: .ai/rules/specs.scenarios.csharp.md (application profile).

Application-oriented. Most framework / library specs (Chronicle kernel, Arc pipeline, Fundamentals, generators) use the plain Specification base + NSubstitute — see specs.csharp.md. A framework repo reaches for the scenario family only to test the engine it provides (Arc's command pipeline, Chronicle's event/projection/reactor engine) — see specs.scenarios.csharp.md.

Spec placement

Specs live in the same slice folder as the .cs file, each file wrapped in #if DEBUG … #endif (spec code ships only in Debug):

<Feature>/<Slice>/
├── <Slice>.cs
└── when_<verb_phrase>/
    ├── and_<happy_scenario>.cs
    └── and_<failure_scenario>.cs

What to cover for every State Change command

One spec class for each of:

1. Happy path — command succeeds, expected event appended (CommandScenario)
2. Each validation failure — one and_ class per CommandValidator / ConceptValidator rule (CommandScenario)
3. Each business rule violation — one and_ class per DCB condition in Handle() that inspects a read model (CommandScenario)
4. Each constraint violation — one and_ class per IConstraint → use the write-specs-events skill (EventScenario)

Default: CommandScenario<TCommand> (in-process)

Runs authorization, validators, Provide(), and Handle() in-process and exposes the appended events — no HTTP, no fixture.

#if DEBUG
namespace MyApp.Projects.Registration.when_registering;

public class and_name_is_unique : Specification
{
    readonly CommandScenario<RegisterProject> _scenario = new();
    readonly ProjectId _id = ProjectId.New();
    CommandResult _result;

    async Task Because() => _result = await _scenario.Execute(new RegisterProject(_id, "My Project"));

    [Fact] void should_succeed() => _result.ShouldBeSuccessful();
    [Fact] async Task should_have_appended_the_registered_event() =>
        await _scenario.ShouldHaveAppendedEvent<RegisterProject, ProjectRegistered>(_id, e => e.Name == "My Project");
}
#endif