| 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"] |
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
- 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.
- 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.
- 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).
- 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.
- 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).
- 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; 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.
- Reports the refreshed
coreex-version, the files changed (from the step-4 dry run), and any flagged orphans.
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.
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.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."
