CoreEx Scaffold

Guides a repository through the right CoreEx setup path by interviewing the user in simple English and translating the answers into safe CoreEx template commands.

When to Use

• Starting a new CoreEx domain or service from a repository that already contains only the bootstrap AI assets.
• Deciding whether the first cut should create just the API host or also include the outbox relay and/or subscriber hosts.
• Adding missing Api, Relay, or Subscribe hosts to an existing scaffolded CoreEx solution.
• Adding an Aspire AppHost so a solution's hosts can be run and debugged together locally, with a dashboard.
• Converting plain-English project needs into either the matching dotnet new coreex* commands or the safest retrofit path.

When Not to Use

• You are debugging local runtime, container, Aspire, or package restore issues unrelated to project shaping.
• You still need to create the initial bootstrap repository; run dotnet new coreex-ai then /coreex-bootstrap before this skill is used.
• You want architectural guidance for an existing implementation beyond project setup; use CoreEx Expert instead.

Workflow Overview

1. Inspect the workspace shape first.
2. Interview the user in simple English. Ask one short question at a time and turn the answers into template inputs.
3. Validate the naming shape before any template command.
4. Choose the safest implementation path. Prefer dry-runs and stop on layout mismatches.
5. Apply the right shape. Generate only what is missing or explicitly requested.
6. Validate the scaffold. Wire projects into the solution, then choose between shape validation and fully runnable local validation.
7. Summarize the result. Show the derived inputs, commands, validations, and any deferred steps.

For step-by-step guidance, see references/workflow.md.

Interactive Interview Rules

• When mcp_microsoft_git_confirm_options is available, use it for every interview step.
• Each interview turn must contain exactly one editable field plus optional readonly context fields.
• Ask short, plain-English questions. Do not ask the user to supply template flag names.
• The canonical interview order is: base solution name, new vs retrofit, HTTP API, reliable event publishing, event consumption, data storage, messaging provider when needed, reference data, domain layer, and ROP.
• Use a single text field only for the base solution name.
• Use a single select field for every other interview step so the workflow stays multiple-choice and deterministic.
• For yes or no questions, use a select with Yes and No so the default remains visibly preselected.
• Prefer either/or or small-choice questions before any extra freeform follow-up.
• Do not batch multiple scaffold questions into a single assistant message.
• If the user gives a partial or non-canonical name, stop and help them reach [Company].[Product].[Domain] before any template command.
• If the workspace already proves a choice, confirm it instead of asking again.
• Before any real dotnet new command, restate the derived inputs in one compact summary and ask for confirmation when there is any ambiguity.

Default Selection Policy

When the workspace does not already prove a value, preselect the safest default that still keeps the workflow moving:

Question	Default
Base solution name	The workspace root folder name if it is already in [Company].[Product].[Domain] form; otherwise the best canonical guess from workspace hints. If only two parts exist, use Product as a temporary middle segment. The user can override during the interview.
New domain or retrofit	New domain in a bootstrap-only repo
HTTP API	Yes
Reliable event publishing	No
Event consumption	No
Data storage	No local database
Messaging provider	Yes for Azure Service Bus when messaging is needed
Reference data	No
Domain layer	No
Result/ROP style	No
Aspire AppHost	No

Set outbox to true only when the user chose owned persistence and reliable publishing. Otherwise keep it false.

Quick Reference

User answer	Template impact
"I need HTTP endpoints."	Add coreex-api.
"I need to publish events reliably."	Add coreex-relay; use a messaging provider and keep outbox enabled where relevant.
"I need to consume events."	Add coreex-subscribe; use a messaging provider.
"This service stores its own data in SQL Server."	--data-provider SqlServer
"This service stores its own data in Postgres."	--data-provider Postgres
"This service stores its own data in Azure Cosmos DB."	--data-provider Cosmos
"This is a facade. No local database."	--data-provider None
"I need reference data."	--refdata-enabled true
"I want a Domain layer."	Add coreex-domain addon after coreex
"I want Result/ROP style pipelines."	--rop-enabled true
"I want to run everything locally with one command / a dashboard."	Add coreex-aspire after all chosen hosts exist, with --has-api/--has-relay/--has-subscribe matching what was chosen

Prerequisite

Before this skill runs, the repository must already be in one of these states:

• A bootstrap-only shell created by coreex-bootstrap; or
• An existing CoreEx solution that is missing some runtime hosts.

AI assets: If the repository does not yet have .github/instructions/ or .github/agents/, the consumer should run dotnet new coreex-ai at the repo root first (optionally with --app-folder <subfolder> for monorepos), installed from an explicitly pinned CoreEx.Template::<version> (see Version-pin discipline). This skill will remind the user if AI assets appear to be absent.

Naming Rules

• The base solution name must be in [Company].[Product].[Domain] form, e.g. Avanade.Bookstore.Books.
• The coreex (solution) template takes the 3-part base name: -n Company.Product.Books. If the current directory is already named Company.Product.Books, -n can be omitted — the template uses the folder name automatically.
• Every addon template — coreex-domain included — takes a 4-part name with its suffix appended:
  • coreex-domain -n Company.Product.Books.Domain
  • coreex-api -n Company.Product.Books.Api
  • coreex-relay -n Company.Product.Books.Relay
  • coreex-subscribe -n Company.Product.Books.Subscribe
  • coreex-aspire -n Company.Product.Books.Aspire
• Addon templates always require -n — the folder name is the 3-part base and cannot supply the addon's suffix automatically.
• coreex-aspire also always requires --has-api/--has-relay/--has-subscribe set explicitly to match whichever hosts this solution actually has — unlike the other host templates, there is no shared parameter it can derive this from.
• Do not pass the 3-part base name to an addon template; doing so causes it to emit into src/Company.Product.Books/ instead of its own suffixed folder, colliding with (or overwriting) sibling addons.
• If the user gives only a two-part name, ask for the missing segment before running any template.
• If the repository already exists with a non-canonical root name (e.g., Avanade.Books), prefer a manual retrofit unless the user explicitly wants to rename the solution first.

Command Patterns

Bootstrap-Only Repository

# Step 1: Run the solution template. If the folder is named Avanade.Product.Books, -n can be omitted.
dotnet new coreex -n Avanade.Product.Books --data-provider SqlServer --messaging-provider ServiceBus --refdata-enabled true --outbox-enabled true --rop-enabled false

# Step 1a (optional): Add the Domain layer when domain complexity warrants DDD.
dotnet new coreex-domain -n Avanade.Product.Books.Domain
dotnet sln Avanade.Product.Books.slnx add src/Avanade.Product.Books.Domain

# Step 2: Add each host template using the 4-part name (base + host suffix).
dotnet new coreex-api        -n Avanade.Product.Books.Api        --data-provider SqlServer --refdata-enabled true --outbox-enabled true
dotnet new coreex-relay      -n Avanade.Product.Books.Relay      --data-provider SqlServer --messaging-provider ServiceBus
dotnet new coreex-subscribe -n Avanade.Product.Books.Subscribe --data-provider SqlServer --messaging-provider ServiceBus --refdata-enabled true

# Step 2a (optional): Add an Aspire AppHost for local orchestration, once the hosts above exist.
dotnet new coreex-aspire -n Avanade.Product.Books.Aspire --has-api true --has-relay true --has-subscribe true --data-provider SqlServer --messaging-provider ServiceBus

# Step 3: Add host and test projects to the solution file.
dotnet sln Avanade.Product.Books.slnx add src/Avanade.Product.Books.Api
dotnet sln Avanade.Product.Books.slnx add tests/Avanade.Product.Books.Test.Api
dotnet sln Avanade.Product.Books.slnx add src/Avanade.Product.Books.Relay
dotnet sln Avanade.Product.Books.slnx add tests/Avanade.Product.Books.Test.Relay
dotnet sln Avanade.Product.Books.slnx add src/Avanade.Product.Books.Subscribe
dotnet sln Avanade.Product.Books.slnx add tests/Avanade.Product.Books.Test.Subscribe
dotnet sln Avanade.Product.Books.slnx add aspire/Avanade.Product.Books.Aspire
dotnet sln Avanade.Product.Books.slnx add aspire/Avanade.Product.Books.Aspire.MockHost
dotnet sln Avanade.Product.Books.slnx add aspire/Avanade.Product.Books.Test.Aspire

# Step 4: Validate the generated solution.
dotnet build Avanade.Product.Books.slnx
dotnet test tests/Avanade.Product.Books.Test.Unit
# Run broader test projects only when their local infrastructure dependencies are available.

Existing Repository Retrofit (Skip Bootstrap)

# If the repo already has a bootstrap or partial scaffold, run only the missing domain/host templates.
# Confirm the canonical three-part base name, then run coreex and/or host templates with the correct suffixes.
dotnet new coreex            -n Company.Product.Books ...
dotnet new coreex-domain     -n Company.Product.Books.Domain    # optional: only when DDD is needed
dotnet new coreex-api        -n Company.Product.Books.Api ...
dotnet new coreex-relay      -n Company.Product.Books.Relay ...
dotnet new coreex-subscribe -n Company.Product.Books.Subscribe ...
dotnet new coreex-aspire    -n Company.Product.Books.Aspire --has-api ... --has-relay ... --has-subscribe ...   # optional: only if the repo needs local orchestration
# Then add new projects to the solution file as in Step 3 above.

Adding an AppHost that already exists: if coreex-aspire output already exists and a new host is being added, do not re-run coreex-aspire --force — it will overwrite any customisation already made to AppHost.cs. Instead, add the missing <ProjectReference> and builder.AddProject<...>(...) line to the existing files by hand.

Adding an API host after CodeGen already ran: when refdata-enabled is true, the *.CodeGen tool only emits the reference-data controller into an *.Api project directory that exists at generation time — it silently skips it (a log warning, not an error) for any coreex-api added afterward. If coreex-api is added to a solution where CodeGen has already been run at least once, re-run dotnet run --project tools/[solution].CodeGen afterward so the new host gets its reference-data controller.

Existing Repository Guardrails

• Bootstrap is a prereq: This skill assumes dotnet new coreex-ai has already been run and (for a blank repo) /coreex-bootstrap has generated root guidance files.
• For retrofit work: If the repo already contains a solution, src/, tooling, or tests, do not re-run the root scaffold unless the current shape is still only the bootstrap shell.
• Template identity conflicts: If dotnet new list or template execution reports duplicate CoreEx template identities, warn the user which template source is being selected before continuing.
• Version-pin discipline: If CoreEx.Template needs installing or updating here, never run a bare dotnet new install CoreEx.Template — resolve and pin an explicit ::<version> matching the project's referenced CoreEx NuGet version (see coreex-ai-workflows.md § Version-pin discipline).
• Pre-flight validation: Always run a dry-run with the intended base solution name before any real domain/host template invocation.
• Watch for nested roots: If dry-run output shows paths like src\\Company.Product.Books.Api\\src\\Company.Product.Books.Api\\..., the output root is wrong; stop and change strategy.
• Naming mismatch: If dry-run output shows incorrect project names because the repo uses a non-canonical root name, stop and recommend either renaming the solution first or manually creating the missing hosts.
• Force only for bootstrap replacement: In a confirmed bootstrap-only repo, --force is acceptable only after dry-run validation shows the expected canonical layout. --force overwrites every file the current template version emits but does not delete files an older/superseded template version left behind — treat any such leftover as a manual-review orphan, not a safe-to-ignore artifact.
• No force for mismatches: Do not use --force to push through a naming or layout mismatch. The mismatch itself indicates an unsafe operation.

Validation Rules

• After generation, verify that every expected host and test project exists on disk and has been added to the .slnx.
• Always run dotnet build on the solution as the minimum end-to-end validation step.
• Always run the unit test project when present.
• Run API, relay, or subscriber test projects only when their required local dependencies are available; otherwise skip them and report the reason explicitly.
• Treat missing local infrastructure such as SQL Server, Postgres, Cosmos emulator, Redis, or Service Bus as a validation skip, not as a scaffolding failure, unless the user explicitly asked for full local environment setup.
• Once the scaffolded test projects build and run their initial templated tests, hand off to coreex-test-api, coreex-test-subscribe, or coreex-test-relay for authoring any further domain-specific integration tests — this skill only validates the generated shape, not test content.
• When the user explicitly wants a first local runnable state, create any missing local dependency assets before broader validation, using bundled templates where available.
• When data-provider != None and the user wants runnable local state, run the *.Database tool from its own project directory. For relational providers this ensures dbex.yaml resolves correctly; for Cosmos it provisions the declared containers and imports seed data. Prefer dotnet run -- All for first-run local setup.
• When refdata-enabled is true and the user wants runnable local state, run the *.CodeGen tool from its own project directory so its config file resolves correctly.
• If generated code fails to compile before environment or tool execution becomes relevant, treat that as a template or package-version defect first; prefer fixing the template pack rather than teaching the workflow to hand-patch generated output every time.
• If refdata-enabled is true, call out the *.CodeGen tool as the next step or run it only when the user wants a fully generated local state.
• If data-provider != None, call out the *.Database tool as the next step or run it only when the user wants local persistence setup as part of scaffolding. Relational domains create schema/migrations; Cosmos domains provision containers and seed data.

Shape Selection Guide

Need	Recommendation
Empty repo, own data, expose HTTP only	coreex + coreex-api
Empty repo, own data, expose HTTP, publish reliable events	coreex + coreex-api + coreex-relay
Empty repo, expose HTTP, publish events, consume events	coreex + coreex-api + coreex-relay + coreex-subscribe
Existing repo missing only runtime hosts	Infer current shape, then add only the missing hosts
Facade over another system with no local database	coreex --data-provider None --messaging-provider None and add coreex-api --data-provider None only if an API is needed

Key References

• ../../docs/coreex/application-scaffolding-guide.md.
• ../../docs/coreex/layers.md.
• ../../docs/coreex/patterns.md.
• https://github.com/Avanade/CoreEx/blob/main/src/CoreEx.Template/README.md.

Related Templates

Template	Short name	Purpose
CoreEx AI workflow assets	coreex-ai	Installs the .github/ instructions, skills, prompts, agents, and docs cache, plus .claude/ commands — run at repo root before or after scaffolding
CoreEx Application services	coreex	Scaffolds the implementation layers (Contracts, Application, Infrastructure, etc.)
CoreEx Domain layer	coreex-domain	Adds a Domain project for DDD — run after coreex, wire via dotnet sln add
CoreEx API host	coreex-api	Adds an ASP.NET Core API host
CoreEx Outbox Relay host	coreex-relay	Adds an outbox relay host
CoreEx Subscriber host	coreex-subscribe	Adds an event subscriber host
CoreEx Aspire AppHost	coreex-aspire	Adds an Aspire AppHost orchestrating this solution's own hosts — run after those hosts exist