Entity Creator Skills: v1 → v2 Migration

Seven entity-creator skills — domain-type-creator, sql-schema-creator, http-entity-creator, cli-entity-creator, shell-entity-creator, wt-entity-creator, and qt-entity-creator — are all v1 format. Together they span 7,802 lines, 30–52% of which is inline code blocks used as embedded reference material.

The v2 skill contract (doc/meta/document_types.org §skill) targets 50–80 lines per skill: a thin index of When/How/Recipes/Reference that delegates detail to separate recipe and architecture docs. These v1 skills embed everything inline, making them maintenance liabilities that drift from the codebase and from each other.

doc/knowledge/architecture/
  entity_lifecycle.org           ← new: umbrella overview + layer diagram
  sql_entity_schema_patterns.org ← new: naming, idempotency, entity-type catalogue
  http_entity_patterns.org       ← new: REST route patterns, request/response
  cli_entity_patterns.org        ← new: CLI options, parser, command structure
  shell_entity_patterns.org      ← new: REPL command patterns, messaging
  wt_entity_patterns.org         ← new: Wt widget/dialog/integration patterns

doc/knowledge/qt/
  qt_entity_patterns.org         ← new: Qt model/view/dialog/history patterns

doc/recipes/sql/
  how_do_i_create_entity_schema.org   ← new
doc/recipes/http/
  how_do_i_create_entity_endpoints.org ← new
doc/recipes/cli/
  how_do_i_create_entity_commands.org  ← new
doc/recipes/shell/
  how_do_i_create_entity_commands.org  ← new
doc/recipes/wt/                  ← new directory
  how_do_i_create_entity_widgets.org
doc/recipes/qt/                  ← new directory
  how_do_i_create_entity_ui.org

Create doc/knowledge/architecture/entity_lifecycle.org as the umbrella document. It must:

• Explain the seven layers (domain → SQL → HTTP → CLI → shell → Wt → Qt) and the dependency ordering between them.
• Include a PlantUML component or sequence diagram showing how the layers compose for a new entity.
• Cross-link each layer to its future per-layer pattern doc (can be forward references; the docs are created in later phases).
• Reference domain-type-creator as the mandatory first step.
• Carry correct v2 frontmatter (#+type: knowledge, #+version: 2, required fields per doc/meta/document_types.org).

domain-type-creator is the leanest skill (484 lines, 15% inline code) and the prerequisite for all other layers. It is the natural pilot.

• [ ] Read the existing skill end-to-end. Identify any inline content that belongs in a knowledge doc vs. content that is genuinely skill-level guidance.
• [ ] The skill already delegates heavy lifting to ores.codegen; the main v2 task is trimming procedural prose and replacing it with id-links to the codegen component model and any extracted patterns.
• [ ] Rewrite Domain Type Creator Skill to v2:
  • #+type: skill, #+version: 2, required frontmatter fields.
  • Sections: When / How / Recipes / Reference / Artefacts.
  • No #+begin_src blocks in the skill itself.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

sql-schema-creator is the second layer after domain type creation. Its 1457 lines contain reusable SQL naming conventions and idempotency patterns that belong in a permanent knowledge doc, not inside the skill.

• [ ] Create doc/knowledge/architecture/sql_entity_schema_patterns.org (v2, #+type: knowledge) containing:
  • Entity naming conventions (component prefixes, entity-type suffix table).
  • Idempotency patterns for DDL (CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS, etc.).
  • The entity-type catalogue (21 types: history, audit, junction, etc.) with SQL examples.
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/sql/how_do_i_create_entity_schema.org (v2, #+type: recipe) with a walkthrough of the full schema creation workflow for a new entity (tables, indexes, grants, history trigger).
• [ ] Rewrite SQL Schema Creator Skill to v2:
  • Sections: When / How / Recipes / Reference.
  • References: id-link to sql_entity_schema_patterns.org, the new recipe, and the codegen component model.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

• [ ] Create doc/knowledge/architecture/http_entity_patterns.org (v2, #+type: knowledge) containing:
  • REST route structure (list, save, delete, history endpoints).
  • C++ handler skeleton (request parsing, response construction, error handling conventions).
  • Authentication and authorisation hook points.
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/http/how_do_i_create_entity_endpoints.org (v2, #+type: recipe) with a phase-by-phase walkthrough (Phase 1: list + save; Phase 2: delete + history; Phase 3: recipe docs).
• [ ] Rewrite HTTP Entity Creator Skill to v2.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

• [ ] Create doc/knowledge/architecture/cli_entity_patterns.org (v2, #+type: knowledge) containing:
  • CLI options struct layout and Boost.Program_options parser patterns.
  • Command dispatch and application-layer wiring.
  • Import/export/list/delete command structure.
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/cli/how_do_i_create_entity_commands.org (v2, #+type: recipe) with a phase-by-phase walkthrough.
• [ ] Rewrite CLI Entity Creator Skill to v2.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

• [ ] Create doc/knowledge/architecture/shell_entity_patterns.org (v2, #+type: knowledge) containing:
  • REPL command registration patterns.
  • Message-based communication (request/response message types).
  • List, add, history, delete command shapes.
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/shell/how_do_i_create_entity_commands.org (v2, #+type: recipe) with a phase-by-phase walkthrough.
• [ ] Rewrite Shell Entity Creator Skill to v2.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

• [ ] Create doc/knowledge/architecture/wt_entity_patterns.org (v2, #+type: knowledge) containing:
  • Wt list widget structure (model, view, pagination).
  • Detail dialog and form-binding patterns.
  • Application integration points (menu registration, navigation).
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/wt/ directory (new).
• [ ] Create doc/recipes/wt/how_do_i_create_entity_widgets.org (v2, #+type: recipe) with a phase-by-phase walkthrough.
• [ ] Rewrite Wt Entity Creator Skill to v2.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

qt-entity-creator is the largest skill (2375 lines, 52% inline C++). It covers several distinct concerns — client model, list window, detail dialog, history dialog, async fetching, recency highlighting, icon selection — each of which warrants a clear home.

• [ ] Create doc/knowledge/qt/qt_entity_patterns.org (v2, #+type: knowledge) containing:
  • ClientModel pattern (async fetch, exception handling, pagination).
  • List window structure (table model, proxy, toolbar).
  • Detail dialog structure (form layout, save/cancel, field validation).
  • History dialog structure (read-only table, pagination).
  • Recency highlighting pattern.
  • Icon selection guidance (cross-link to icon-guidelines skill).
  • Cross-link to entity_lifecycle.org.
• [ ] Create doc/recipes/qt/ directory (new).
• [ ] Create doc/recipes/qt/how_do_i_create_entity_ui.org (v2, #+type: recipe) with a phase-by-phase walkthrough (Phase 1: list window + client model; Phase 2: detail dialog; Phase 3: history dialog; Phase 4: recipe docs).
• [ ] Rewrite Qt Entity Creator Skill to v2.
  • Target: 60–80 lines.
• [ ] Verify ./projects/ores.codegen/validate_docs.sh passes.

• Push the feature branch.
• PR title: Entity creator skills: v1 → v2 migration.
• PR body must quote the before/after audit numbers: python3 projects/ores.codegen/scripts/doc_version_audit.py
• No "Test plan" section (project convention).

After every phase:

1. ./projects/ores.codegen/validate_docs.sh — must pass.
2. python3 projects/ores.codegen/scripts/doc_version_audit.py — v1 count decreases by the number of skills ported in that phase.

Final check before PR:

1. All seven skills report #+version: 2 and are under 100 lines.
2. All new knowledge docs and recipes carry correct v2 frontmatter.
3. No #+begin_src blocks remain inside any of the seven skill files.

• Do phases in order: each phase's knowledge doc is a potential cross-link target for later phases.
• The domain-type-creator is a dependency of all other skills; port it first so later skill rewrites can id-link to a v2 doc.
• The entity_lifecycle.org umbrella (Phase 0) intentionally uses forward id-references to the per-layer docs; these resolve once later phases create those files.
• When writing Qt knowledge docs, check whether doc/knowledge/qt/ already contains any relevant material to merge rather than duplicate.