v4.1.0: command queues, Aspire E2E testing, mutable reference data and AI skills

.claude/commands/coreex-aspire.md

@@ -0,0 +1,14 @@
+---
+description: "Add or extend .NET Aspire orchestration and end-to-end tests in a CoreEx solution. USE FOR: AppHost wiring for new hosts, service-bus queue/topic topology in Test.Aspire, MockHost stubs for third-party HTTP, OnBeforeStartAsync/OnAfterStartAsync setup, E2E tests across domains. DO NOT USE FOR: non-Aspire hosts (use coreex-scaffold) or per-host integration tests (use coreex-test-api / coreex-test-subscribe / coreex-test-relay)."
+allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
+---
+
+<!--
+  AI workflow asset — dual-audience notice:
+  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
+  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
+    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
+    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
+-->
+
+Read `.github/skills/coreex-aspire/SKILL.md` and follow the instructions in that file.

.claude/commands/coreex-command-publish-e2e.md

@@ -0,0 +1,14 @@
+---
+description: "Add the sending/publishing of a command (not an event) to another domain end-to-end: adapter, transactional call site (outbox vs direct), NamedDestinationProvider queue routing, Service Bus topology, API/Relay tests and Aspire E2E. USE FOR: a domain must instruct another domain to do something. DO NOT USE FOR: publishing an event (use coreex-app-service), receiving a command (use coreex-command-subscribe-e2e), or synchronous request/response calls (use coreex-adapter)."
+allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
+---
+
+<!--
+  AI workflow asset — dual-audience notice:
+  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
+  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
+    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
+    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
+-->
+
+Read `.github/skills/coreex-command-publish-e2e/SKILL.md` and follow the instructions in that file.

.claude/commands/coreex-command-subscribe-e2e.md

@@ -0,0 +1,14 @@
+---
+description: "Add the receiving/handling of a command (not an event) end-to-end: contract, app service, subscriber, dedicated keyed command-queue receiver in the Subscribe host, Service Bus topology, Subscribe tests and Aspire E2E. USE FOR: this domain must act on a command addressed to it. DO NOT USE FOR: subscribing to an event (use coreex-subscriber-e2e), sending a command (use coreex-command-publish-e2e), or subscribing to another domain's command (never valid)."
+allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
+---
+
+<!--
+  AI workflow asset — dual-audience notice:
+  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
+  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
+    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
+    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
+-->
+
+Read `.github/skills/coreex-command-subscribe-e2e/SKILL.md` and follow the instructions in that file.

.claude/commands/coreex-repository.md

@@ -1,5 +1,5 @@
 ---
-description: "Create or modify a CoreEx Infrastructure-layer repository. USE FOR: new repository class, adding CRUD operations, adding a custom query (QueryArgsConfig<TSelf>), bidirectional mapper (BiDirectionMapper), EfDb model accessor, Result<T> pipeline variants. DO NOT USE FOR: Application-layer service logic, domain invariants, typed HTTP clients/adapters (those follow adapter conventions in the infrastructure instructions, not this skill)."
+description: "Create or modify a CoreEx Infrastructure-layer repository. USE FOR: new repository class, adding CRUD operations, adding a custom query (QueryArgsConfig<TSelf>), bidirectional mapper (BiDirectionMapper), EfDb/CosmosDb model accessor, Result<T> pipeline variants. DO NOT USE FOR: Application-layer service logic, domain invariants, typed HTTP clients/adapters (those follow adapter conventions in the infrastructure instructions, not this skill)."
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
 ---
 

.claude/commands/coreex-scaffold.md

@@ -1,5 +1,5 @@
 ---
-description: "Guide a developer through CoreEx solution shaping after bootstrap, using a short plain-English interview that turns user answers into safe dotnet new template inputs. USE FOR: bootstrap-only repos, deciding API-only vs API plus relay vs API plus subscriber, choosing SQL Server vs Postgres vs no database, choosing refdata/outbox/DDD/ROP options, installing CoreEx.Template, checking current solution shape, adding missing Api/Relay/Subscribe hosts to an existing repo, adding a .NET Aspire AppHost for local multi-host orchestration and dashboard visibility, and optionally preparing a first local runnable state with local dependency assets plus database/code-generation steps. DO NOT USE FOR: unrelated runtime debugging, bootstrap creation, or forcing root re-scaffolding over an existing solution. INVOKES: workspace inspection, ask-questions style interviews, dotnet new install/list, dry-run validation, solution wiring, optional local dependency asset creation, focused build/test validation, and either template generation or manual retrofit work depending on repo shape."
+description: "Guide a developer through CoreEx solution shaping after bootstrap, using a short plain-English interview that turns user answers into safe dotnet new template inputs. USE FOR: bootstrap-only repos, deciding API-only vs API plus relay vs API plus subscriber, choosing SQL Server vs Postgres vs Cosmos vs no database, choosing refdata/outbox/DDD/ROP options, installing CoreEx.Template, checking current solution shape, adding missing Api/Relay/Subscribe hosts to an existing repo, adding a .NET Aspire AppHost for local multi-host orchestration and dashboard visibility, and optionally preparing a first local runnable state with local dependency assets plus database/code-generation steps. DO NOT USE FOR: unrelated runtime debugging, bootstrap creation, or forcing root re-scaffolding over an existing solution. INVOKES: workspace inspection, ask-questions style interviews, dotnet new install/list, dry-run validation, solution wiring, optional local dependency asset creation, focused build/test validation, and either template generation or manual retrofit work depending on repo shape."
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
 ---
 

.claude/commands/coreex-subscriber-e2e.md

@@ -1,5 +1,5 @@
 ---
-description: "Create a complete new event or command subscriber end-to-end in a single guided workflow: event/command DTO contract (if new), subscriber handler, optional application service and repository, and integration tests. USE FOR: adding a brand-new subscriber to an existing CoreEx Subscribe host for any scenario — command handling, event-data-sync replication, or event-driven business-process choreography. DO NOT USE FOR: modifying an existing subscriber (use coreex-subscriber directly), API endpoint work (use coreex-api-e2e), or setting up the Subscribe host itself (use coreex-scaffold)."
+description: "Create a complete new event subscriber end-to-end in a single guided workflow: event DTO contract (if new), subscriber handler, optional application service and repository, and integration tests. USE FOR: adding a brand-new subscriber to an existing CoreEx Subscribe host for event-data-sync replication or event-driven business-process choreography. DO NOT USE FOR: command handling (use coreex-command-subscribe-e2e), sending a command (use coreex-command-publish-e2e), modifying an existing subscriber (use coreex-subscriber directly), API endpoint work (use coreex-api-e2e), or setting up the Subscribe host itself (use coreex-scaffold)."
 allowed-tools: [Read, Glob, Grep, Edit, Write, Bash]
 ---
 

.github/INSTRUCTION_AUTHORING.md

@@ -58,7 +58,7 @@ for every POST") is an invariant and stays; a numbered "detect → confirm → s
 procedure and moves to the skill.
 
 **Project-wide choices live in state, not in prompts.** The solution-root `AGENTS.md` "Feature Configuration"
-records `data-provider`, `rop-enabled`, `refdata-enabled`, `outbox-enabled`, and `messaging-provider`. Whether a Domain layer is present is inferred from the existence of `src/*.Domain/` (added via `dotnet new coreex-domain`). Instructions and skills must **read that recording before asking** and re-state resolved
+records `data-provider` (`SqlServer` / `Postgres` / `Cosmos` / `None`), `rop-enabled`, `refdata-enabled`, `outbox-enabled`, and `messaging-provider`. Whether a Domain layer is present is inferred from the existence of `src/*.Domain/` (added via `dotnet new coreex-domain`). Instructions and skills must **read that recording before asking** and re-state resolved
 values for confirmation rather than re-prompting (the global rule lives in `.github/copilot-instructions.md`).
 
 ---
@@ -207,9 +207,9 @@ A development-time console tool. Reads a single `ref-data.yaml` file (validated
 
 The entry point is a one-line `Program.cs` in the `*.CodeGen` project. Templates live in `CoreEx.CodeGen/RefData/Templates/` (embedded in the NuGet package) and are the only place structural changes to the generated shape belong.
 
-### DbEx (`*.Database` project)
+### `*.Database` tooling project
 
-A development-time migration and generation tool. Reads YAML configuration and SQL migration scripts to produce database schema, outbox infrastructure, and EF Core scaffolding.
+For relational domains this is a DbEx-based migration and generation tool that reads YAML configuration and SQL migration scripts to produce database schema, outbox infrastructure, and EF Core scaffolding. For Cosmos domains it is a `CosmosDbConsole` provisioning app that declares containers and imports seed data; there are no SQL migration scripts or `dbex.yaml`.
 
 | Output pattern | What to change instead |
 |---|---|

.github/agents/README.md

@@ -13,13 +13,13 @@ It is defined once in `coreex-expert.agent.md` and works in both tools from the
 
 ## How the agent resolves guidance
 
-The agent relies on a local doc cache rather than making live GitHub fetches on every question. The cache is populated by `/coreex-docs-sync` and stored under `.github/docs/coreex/`.
+The agent prefers the local doc cache installed by `dotnet new coreex-ai` at the pinned `CoreEx.Template` version. `/coreex-docs-sync` refreshes that cache and the entire AI asset bundle together; it does not fetch GitHub `main`.
 
 ```
 Developer asks a CoreEx question
               │
               ▼
-  Read .github/docs/coreex/.manifest
+  Read .github/docs/coreex/manifest.txt
               │
         ┌─────┴─────┐
         │           │
@@ -28,38 +28,38 @@ Developer asks a CoreEx question
         │          └──► offer to run /coreex-docs-sync first
         │                (never runs silently — always asks first)
         │
-  check staleness
+  compare coreex-version with project package references
         │
    ┌────┴────┐
    │         │
- fresh     stale
-   │       (>30 days OR coreex-version in manifest
+ matches   differs
+   │       (coreex-version in manifest
    │        differs from version in project files)
    │         │
    │         └──► recommend running /coreex-docs-sync
    │
    ▼
 Use local cache (always preferred over live GitHub fetches)
    │
-   ├── .github/docs/coreex/*.md           ← 10 architecture docs
+   ├── .github/docs/coreex/*.md           ← 12 architecture/setup docs
    │
    └── .github/docs/coreex/agents/*.md   ← 18 per-package AI guides
               │
-    read manifest referenced-packages
+    inspect project package references
     to distinguish:
       • package already in project  →  guide on current usage
       • package not yet in project  →  recommend adopting it
 ```
 
-The `referenced-packages` field in the manifest lets the agent distinguish between a package the project already uses and one it would need to add — without restricting which guides get synced.
+The manifest records only `coreex-version`. Package adoption is determined from the project's package references, not a `referenced-packages` field or a sync timestamp.
 
 ---
 
 ## The local doc cache
 
-`/coreex-docs-sync` fetches from the CoreEx GitHub repository and writes two folders:
+`CoreEx.Template` packages the documentation at release time. `coreex-ai` installs it; `/coreex-docs-sync` reinstalls the bundle from the release matching the project's CoreEx NuGet version.
 
-**`.github/docs/coreex/`** — 10 architecture docs:
+**`.github/docs/coreex/`** — 12 architecture/setup docs:
 
 | File | Content |
 |------|---------|
@@ -73,17 +73,18 @@ The `referenced-packages` field in the manifest lets the agent distinguish betwe
 | `testing.md` | Unit, integration, API, Subscribe, and Relay test patterns |
 | `tooling.md` | CodeGen and Database project run order, generated-file ownership |
 | `aspire.md` | Aspire orchestration for local distributed development and E2E testing |
+| `local-dev.md` | Local infrastructure, connection strings, and startup sequences |
+| `application-scaffolding-guide.md` | Choosing and composing solution/host templates |
 
-**`.github/docs/coreex/agents/`** — 18 per-package AI usage guides: the base `CoreEx` package plus one per `src/CoreEx.*` package (including `CoreEx.Cosmos`, which is newly published as a preview-quality package — its API surface may still change without following strict semver until it stabilizes). All 18 are synced unconditionally so the agent can guide on any package — including ones the project hasn't adopted yet.
+**`.github/docs/coreex/agents/`** — 18 per-package AI usage guides: the base `CoreEx` package plus one per `src/CoreEx.*` package (including `CoreEx.Cosmos`). All 18 are synced unconditionally so the agent can guide on any package — including ones the project hasn't adopted yet.
 
-**`.github/docs/coreex/.manifest`** — records `synced` date, `coreex-version`, and `referenced-packages`.
+**`.github/docs/coreex/manifest.txt`** — records `coreex-version`, stamped by the installed template release.
 
 ### Staleness triggers
 
 | Trigger | Agent action |
 |---------|-------------|
 | Cache absent | Offers to run `/coreex-docs-sync` before the first GitHub fetch |
-| `synced` date > 30 days | Recommends a refresh |
 | `coreex-version` in manifest ≠ version in project files | Recommends a refresh |
 
 ---
@@ -95,7 +96,7 @@ An earlier design synced only the packages the project already references. This
 - The agent cannot recommend adopting a package (e.g. `CoreEx.Caching.FusionCache`) if it has no knowledge of what that package offers.
 - All 18 guides are small markdown files — the total download is negligible.
 - Syncing all unconditionally removes the need to re-run after adding a new package.
-- The `referenced-packages` manifest field preserves the "in project vs. not yet" distinction without making it a gate on what gets synced.
+- Inspecting project package references preserves the "in project vs. not yet" distinction without making it a gate on which guides get installed.
 
 ---
 
@@ -119,10 +120,10 @@ dotnet new coreex-ai --app-folder <subfolder>
 `dotnet new coreex-ai` installs everything the agent depends on:
 
 - `.github/instructions/` — the scoped, auto-injected instruction files
-- `.github/prompts/` — the `coreex-scaffold` prompt plus one prompt per per-capability (L1) skill
-- `.github/skills/` — the full skill suite (`coreex-docs-sync`, `acquire-codebase-knowledge`, `coreex-scaffold`, `aspire`, and the 15 L1 skills)
+- `.github/prompts/` — 22 wrappers: bootstrap, scaffold, 16 L1 skills and four L2 workflows (`coreex-docs-sync` is a direct skill, without a prompt wrapper)
+- `.github/skills/` — 23 CoreEx skills: bootstrap, scaffold, docs-sync, 16 L1 skills and four L2 workflows; generic `acquire-codebase-knowledge` and `aspire` skills are framework-repository-only
 - `.github/agents/coreex-expert.agent.md` — this agent
-- `.claude/commands/` — the Claude Code equivalents
+- `.claude/commands/` — 24 commands: one for each CoreEx skill plus expert guidance
 - `.github/docs/coreex/` — the local docs cache (architecture docs + per-package guides) the expert reads first, already populated at the pinned version — no separate sync step needed on first install
 
 Later, when the project's `CoreEx` NuGet version is bumped, re-run `/coreex-docs-sync` to refresh the whole bundle (instructions, skills, prompts, this agent, and the docs cache) to the matching `CoreEx.Template` release — the agent recommends this automatically when the cached `coreex-version` no longer matches the project (see the resolution flowchart above).