Codegen Add Entity
Table of Contents
1. When to use this skill
When the user asks to "add a new entity", "create entity X", or any
equivalent. A regular ORE Studio entity requires all layers listed
below — skipping any layer requires explicit user approval. This skill
orchestrates the sub-skills in dependency order via TaskCreate tasks.
2. How to use this skill
2.1. Step 1 — Confirm or create the org model
Confirm a model file exists under projects/ores.<component>/modeling/
with #+type: ores.codegen.entity (or ores.codegen.junction for
association tables). If it does not exist, scaffold it with
compass add entity_org ... before proceeding. See
ORE Studio Codegen for the model schema.
The model also carries the entity's summary capability in the ** Presentation
drawer: collection_name, key_field, and the *** Columns and
*** Detail fields tables. The C++ presentation facets read that drawer.
2.2. Step 2 — Create one task per layer
Use TaskCreate to register a task for each layer. Execute them in
the order shown. Do not skip a layer unless the user explicitly says
it is out of scope for this entity.
| # | Layer | Sub-skill | Codegen |
|---|---|---|---|
| 1 | Domain · SQL · repository · service · protocol · generator | domain-type-creator | --address ores.cpp (SQL via compass-codegen-add-sql-schema) |
| 2 | HTTP REST endpoints | compass-codegen-add-surface-entity | ❌ GAP |
| 3 | CLI commands | cli-entity-creator | ❌ GAP |
| 4 | Shell REPL commands | compass-codegen-add-surface-entity | ❌ GAP |
2.3. Step 3 — Gap protocol
When a layer is marked ❌ GAP:
- Do not hand-code the layer.
- Raise a sprint story: "Implement codegen profile for {layer}."
- Reference Entity lifecycle§"Codegen gaps" for what the profile must cover.
- Link the story to the entity task before marking the layer done.
- Once the profile exists, regenerate and discard any hand-written interim code.
Until the gap is resolved the layer is incomplete. The entity is not "done" while gap layers remain open.
2.4. Step 4 — Tests and diagrams
After all layer tasks are green, create two more tasks:
- Tests: invoke unit-test-writer for domain, repository, and service layers.
- Diagrams: invoke plantuml-class-modeler and plantuml-er-modeler.
2.5. Step 5 — PR strategy
Each layer produces one or more PRs (see the layer skill for PR titles
and phase boundaries). Use feature-branch-manager between phases and
pr-manager to open each PR.
3. Recipes
- Entity lifecycle — canonical file checklist, template inventory, layer diagram.
4. Reference
- ORE Studio Codegen — model schema, physical-space graph,
codegen.shusage. - Entity lifecycle — complete file checklist; links to every layer skill and pattern doc.