| name | coreex-contract |
| description | Create or modify a hand-authored contract (DTO/entity) in a CoreEx domain. USE FOR: new root entity contract, new subordinate/request contract, modifying an existing contract (add property, add interface, wire ref-data), extracting a shared base class. DO NOT USE FOR: reference-data contracts (generated via coreex-refdata / *.CodeGen), Infrastructure persistence models (generated by *.Database CodeGen). |
| argument-hint | Optional: contract name, domain, root or subordinate, properties, identifier type |
| tags | ["contracts","dto","source-generation","coreex","partial","etag","changelog"] |
CoreEx: Contract
Guides you through creating or modifying a hand-authored contract (DTO/entity) in *.Contracts. Covers root entities, subordinate types, request/response objects, and base class extraction.
When to Use
- New root entity contract — independently identifiable, persisted, has its own API endpoint
- New subordinate, line-item, or request/response contract (accessed via a parent — may still carry its own identifier)
- Adding or changing properties on an existing contract
- Wiring a ref-data navigation property (
[ReferenceData<T>]) on an existing contract
- Extracting a shared base class when ≥2 contracts repeat the same fields
When Not to Use
- Reference data contracts (generated by
*.CodeGen from ref-data.yaml) — use coreex-refdata
- Infrastructure persistence models (generated by
*.Database CodeGen from dbex.yaml)
- Domain aggregates, entities, value objects — see
coreex-domain.instructions.md and the coreex-aggregate skill (DDD domains only)
Quick Reference
Clarifying questions to ask before emitting any code:
0. Resolve from state first. Read the solution-root AGENTS.md Feature Configuration for refdata-enabled (whether [ReferenceData<T>] wiring applies) and check whether a *.Domain project exists (aggregate-mapping context). Only ask for what is unresolved; re-state resolved values for confirmation.
- Root or subordinate? (if not explicit)
- Identifier type? (default
string? — confirm before using any other type)
IETag needed? (default yes for root contracts — omit only on explicit request)IChangeLog needed? (ask for root contracts — add when created/updated audit trail is required)- Sub-folder within
*.Contracts? (default: flat root — only create one if requested)
[Schema] override? (only if user explicitly requests a custom event schema name/version)
Key rules at a glance:
[Contract] + partial on all contract classes by default- Only
[ReferenceData<T>] properties are partial — never make plain properties partial (CS9248)
[ReadOnly(true)] on all server-assigned fields (Id, ETag, ChangeLog, computed/derived)- Every property needs a
<summary> XML doc comment
- Same contract type for both API response and event payload — never split them
For full workflow, decision trees, and code examples see references/workflow.md.
Key References
