Story: Document MASD and code generation principles
Table of Contents
This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Produce a permanent technical knowledge document that establishes code
generation as a first-class engineering principle of ORE Studio. The
document weaves the theoretical foundations of Model-Driven Engineering
(MDE) and the MASD method with the concrete choices made in ORE Studio's
ores.codegen implementation, so that both new contributors and LLM
agents understand not just what the generator does but why it exists
and what it is working towards.
The document also articulates the long-term objective: backing out code generation from a reference implementation. Rather than designing abstract models first, ORE Studio commissions entities by hand, extracts the recurring pattern into a generator, and then uses that generator to produce all subsequent entities. The currency entity is the current reference implementation; it is the yardstick against which codegen coverage is measured.
Once written, the document is linked from ores.compass (the site entry point) so that it is reachable from the top of the documentation tree.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 19 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-01 |
Acceptance
- A knowledge document exists in
doc/knowledge/titled "MASD and code generation principles" covering:- The theoretical underpinnings of MDE and MASD as they apply to ORE Studio.
- How
ores.codegenrealises these principles in practice (inputs, templates, outputs, profiles). - The reference-implementation backout strategy: hand-write one entity
fully (
currency), extract the pattern, generate all others. - A clear statement of what code generation covers today vs. what remains manual, keyed to the entity evaluation checklist.
- The document is linked from ores.codegen (component overview) and from
compass.org(the top-level site entry point). - The document links back to ores.codegen, ores.codegen architecture, and the entity evaluation checklist.
- The document passes
validate_docs.shand the site builds cleanly.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| T1: Write the MASD and code generation principles doc | DONE | 2026-06-01 | 2026-06-01 | Author the knowledge document; wire into site nav |
Decisions
- Document type:
knowledge(cross-cutting reference, not a recipe or task). Lives indoc/knowledge/with a#+level: crosstag so it appears in the knowledge index. - Entry point linkage: add a bullet in
compass.orgunder a new** Engineering principlessubsection rather than burying it inside a component page; this makes it discoverable from the top of the tree. - MASD scope: focus on ORE Studio's own usage of MASD concepts (meta-models, templates, profiles, the backout strategy). Do not attempt a comprehensive survey of the academic literature — one citation to the foundational Brambilla et al. or Selic work is sufficient.
Out of scope
- Changes to
ores.codegenitself (new templates, new outputs). - Generation of new entity artefacts from the expanded generator.
- Documentation of non-codegen architectural decisions.