Coreex Docs Sync

---
name: coreex-docs-sync
description: "Refresh the full CoreEx AI workflow asset bundle (instructions, skills, prompts, the coreex-expert agent, and the .github/docs/coreex/ docs cache) to the CoreEx.Template release matching the project's installed CoreEx NuGet version. Version-pinned — never fetches unreleased GitHub main content — so the assets that shape AI behaviour and the reference docs they point to always describe the exact same release."
argument-hint: No arguments required. Run to check for or apply a version-pinned refresh.
tags: ["docs", "cache", "sync", "coreex-expert", "template", "versioning"]
---

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

# Sync CoreEx AI Assets

Keeps `.github/instructions/`, `.github/skills/`, `.github/prompts/`, `.github/agents/coreex-expert.agent.md`, `.claude/commands/`, and the `.github/docs/coreex/` docs cache all pinned to **one** `CoreEx.Template` release — the one matching the `CoreEx` NuGet version this project actually references. It does this by re-running `dotnet new coreex-ai --force` at that exact version — it does **not** fetch anything from GitHub `main` directly. Instructions/skills (behaviour) and the docs cache (reference material) are one bundle from one release; they cannot drift apart from each other under this mechanism.

## When to Use

- The `CoreEx` NuGet package version was bumped in the project.
- `coreex-expert` reports the installed AI-asset bundle (`.github/docs/coreex/manifest.txt` → `coreex-version`) no longer matches the project's referenced `CoreEx` version.
- `.github/docs/coreex/manifest.txt` is missing entirely (assets were copied in by hand rather than via `dotnet new coreex-ai`).

## When Not to Use

- In the CoreEx repository itself — the docs are already present at `samples/docs/` and `src/*/AGENTS.md`, and there is no NuGet-referenced version to pin to.
- When you only need one specific doc and are not trying to realign the whole bundle — fetch the GitHub URL for that one file directly instead; do not use this as a substitute for the version-pinned refresh.
- To get unreleased/`main`-branch content ahead of a release — not supported. This skill only ever installs a released `CoreEx.Template` version; there is no "give me the latest main" path, by design (see Rationale below).

## What It Does

1. **Detects** the `CoreEx` NuGet version this project references, from `Directory.Packages.props`, `*.csproj`, or `Directory.Build.props`. This is the target version — `CoreEx.Template` and `CoreEx` are released from the same repo at the same version number, so the two always match.
2. **Reads** `.github/docs/coreex/manifest.txt` (if present) for the currently-installed `coreex-version`. If it already equals the detected target, **report already in sync and stop** — nothing to do.
3. **Installs the pinned template version explicitly** — `dotnet new install CoreEx.Template::<detected-version>` — never a bare `dotnet new install CoreEx.Template` (which silently resolves to latest and can desync the AI assets from the project's actual CoreEx version).
4. **Dry-runs first.** Runs `dotnet new coreex-ai --dry-run` (and `--app-folder <path>` if this is a monorepo, per the recorded app folder) and shows the "Create"/"Overwrite" file list it reports — `--dry-run` never writes anything, so this is always safe to run first, review it before proceeding. Do **not** rely on omitting `--force` alone: when none of the target files exist yet (e.g. a repo missing most of the bundle), `dotnet new coreex-ai` without `--force` and without `--dry-run` still writes every file for real — it only blocks and lists conflicts when files it would touch already exist and differ.
5. **Confirms, then applies** — re-runs with `--force`. Note: `--force` overwrites every file the template currently emits; it does **not** delete files the template no longer emits (see [Guardrails](#guardrails)).
6. **Flags possible orphans** — compares the skill folder names under `.github/skills/coreex-*/` against the current known skill catalog — both L1 per-capability skills and L2 end-to-end workflow skills — listed in [`coreex-ai-workflows.md`](/.github/coreex-ai-workflows.md); any extra folder is very likely left over from a prior version and should be reviewed for manual removal, not assumed safe. Scoped to the `coreex-` prefix deliberately: `CoreEx.Template` only ever installs `coreex-`-prefixed skill folders, and a consumer repo may have other, unrelated skills installed (its own or from other tooling) that this refresh neither writes nor owns — comparing *all* of `.github/skills/*/` would falsely flag those as CoreEx orphans.
7. **Reports** the refreshed `coreex-version`, the files changed (from the step-4 dry run), any flagged orphans, and — if any skill folder was added, removed, or renamed under `.github/skills/coreex-*/` — a reminder that the running AI client (Copilot CLI, Copilot Chat, etc.) caches its skill catalog at session/app startup and will not see the new set until the client is restarted (a new session/tab alone is not always enough — some clients cache the catalog at the app-process level, not per-session).

## Guardrails

- **Never install an unpinned/latest template version.** Every `dotnet new install CoreEx.Template` must carry an explicit `::<version>` matching the project's referenced `CoreEx` NuGet version. A bare install is how the two mechanisms (code and AI assets) end up on different releases.
- **`--force` is scoped, not destructive, but also not a cleanup tool.** It only overwrites files the template's *current* version emits — verified empirically: unrelated repo content and files outside the template's manifest are untouched. It does **not** prune files an *older* version emitted that the current version no longer does (e.g. a renamed or retired skill) — those are true orphans and need manual review/removal.
- **Always dry-run before `--force`.** Use `dotnet new coreex-ai --dry-run` — it is the only invocation guaranteed never to write anything, regardless of whether the target files already exist. Omitting `--force` (without `--dry-run`) is not equivalent: it blocks and lists conflicts only when existing files would change, but it still creates any missing files for real with no confirmation — so it is not safe to treat as a preview on its own.
- **Hand-edits to template-sourced files do not survive a refresh.** Every file under `.github/instructions/`, `.github/skills/`, `.github/prompts/`, `.github/agents/coreex-expert.agent.md`, and `.claude/commands/` is regenerated by this process — see the header on each file.
- **Never run this inside the CoreEx framework repository itself.**
- **A skill set change requires an AI client restart to take effect.** Files on disk update immediately, but the client's skill catalog is typically loaded once at startup — a new chat/session in the same running app may still show the stale list. If the diff added, removed, or renamed a skill folder, tell the user to fully restart the AI client (not just open a new session) before relying on the updated catalog.

## Rationale — why version-pinned only, no live `main` fetch

`dotnet new coreex-ai` bakes instructions/skills/prompts/agent/docs content **at `CoreEx.Template` pack time** — it is already an atomic, version-pinned snapshot the moment that NuGet package is built. A live fetch from GitHub `main` is a *second, independent* sync mechanism with no version guarantee at all — it could pull docs describing behaviour from a `CoreEx` version newer (or older) than the one actually referenced, while instructions/skills stay pinned to whichever template version was last installed. That drift is exactly the failure mode this skill exists to prevent, so there is deliberately no "fetch unreleased main" path.

## Cache Layout

```
.github/docs/coreex/
  manifest.txt                           # coreex-version — stamped by the CoreEx.Template package at generation time
  local-dev.md
  layers.md
  patterns.md
  contracts-layer.md
  domain-layer.md
  application-layer.md
  infrastructure-layer.md
  hosts-layer.md
  testing.md
  tooling.md
  aspire.md
  application-scaffolding-guide.md
  agents/
    CoreEx.md
    CoreEx.AspNetCore.md
    CoreEx.AspNetCore.NSwag.md
    CoreEx.Azure.Messaging.ServiceBus.md
    CoreEx.Caching.FusionCache.md
    CoreEx.CodeGen.md
    CoreEx.Data.md
    CoreEx.Data.GraphQL.md
    CoreEx.Database.md
    CoreEx.Database.Postgres.md
    CoreEx.Database.SqlServer.md
    CoreEx.DomainDriven.md
    CoreEx.EntityFrameworkCore.md
    CoreEx.Events.md
    CoreEx.RefData.md
    CoreEx.UnitTesting.md
    CoreEx.Validation.md
```

All of the above are shipped and refreshed as part of the `dotnet new coreex-ai --force` bundle — none are fetched independently.

## Manifest Format

```
coreex-version: <the exact CoreEx.Template version that generated this bundle>
```

Stamped directly by the template (via the same `coreex-version` constant symbol the `coreex`/`coreex-api`/`coreex-relay`/`coreex-subscribe` templates already use to pin `Directory.Packages.props`) — never hand-written, never fetched. `referenced-packages` (which `CoreEx.*` packages the project currently uses) is no longer cached; `coreex-expert` reads that live from the project's package references each session since it is cheap to compute and does not need to survive a refresh.

## Re-run Triggers

- `CoreEx` NuGet version bumped in the project (the manifest's `coreex-version` will then differ from the detected version).
- `coreex-expert` reports the manifest is missing.
- `coreex-expert` reports a version mismatch between the manifest and the project's current package version.

There is no age-based ("older than N days") trigger — staleness is defined purely by version mismatch now that refresh means "re-install the matching release," not "re-fetch main and hope it lines up."