Coreex Solution Scaffolder

---
name: coreex-solution-scaffolder
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."
argument-hint: "Optional: base solution name, whether this is new or retrofit, required hosts, database choice, messaging needs, and whether to add an Aspire AppHost for local orchestration."
tags: ["coreex", "scaffolding", "retrofit", "template", "hosts", "aspire", "apphost", "orchestration"]
---

<!--
  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.
-->

# 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](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 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](/.github/coreex-ai-workflows.md#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

```text
# 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

# 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 src/Avanade.Product.Books.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)

```text
# 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`/`Extensions.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](/.github/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, 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 so `dbex.yaml` resolves correctly; 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 schema setup as part of scaffolding.

## 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 |