Skip to content

Commit f50258f

Browse files
committed
Merge origin/main into fm/mo-verify-fk (CHANGELOG: keep both; language-differences rows for verify.handEdits and foreignKeyIndexes)
2 parents 3f4d75c + b0987a5 commit f50258f

58 files changed

Lines changed: 722 additions & 819 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,41 @@ loaded before stops loading. This vocabulary ships in 1.3.0 with `metamodelVersi
5656
converged no-op). Java's config reader now carries the `migrate` block's
5757
`foreignKeyIndexes`, `conventions` and `dialect` on the loaded root (`MigrateSettings`).
5858

59+
- **`meta init --skills-dir <dir>` and `meta agent-docs --skills-dir <dir>`: install the skills
60+
for any coding assistant.** The `metaobjects-*` skills went only to `.claude/skills/`, which
61+
Claude Code reads. `--skills-dir .agents/skills` (or any project-relative directory) puts them
62+
where another assistant looks; the choice is recorded in `.metaobjects/.agent-context.json`,
63+
so a later `--refresh-docs` keeps it, and moving the directory prunes the untouched copies at
64+
the old one. The always-on file names the directory, so an assistant that does not load
65+
skills opens `<dir>/<skill>/SKILL.md` by path. A directory outside the project is refused.
66+
- **[What differs by language](docs/features/language-differences.md).** One page lists what
67+
the same model does differently per port: that schema migrations and database checks need
68+
the Node `meta` tool in every language, the list default and cap, the validation error body,
69+
filter extras, field names in code, generated data access and hand-edit handling. Every port
70+
page now says up front that migrations and `verify --db` run in Node, and the README's
71+
getting-started path says it for Java, Kotlin, C# and Python teams.
72+
5973
### Changed
6074

75+
- **The always-on agent file works with any coding assistant, carries the REST conventions,
76+
and is written once.** `.metaobjects/CLAUDE.md`, an identical copy of `.metaobjects/AGENTS.md`
77+
that nothing imported, is no longer written; a refresh removes an untouched one and names a
78+
hand-edited one. The text no longer tells the reader to use a root `CLAUDE.md` only, and
79+
`--wire-root` on a project with neither root file now creates `AGENTS.md` as well as
80+
`CLAUDE.md`, each with a plain pointer line beside the `@` import. A first init on a project
81+
that has only a root `CLAUDE.md` creates `AGENTS.md` too (assistants other than Claude Code
82+
read no `@` import out of `CLAUDE.md`); a refresh creates no root file and instead prints one
83+
advisory line naming the missing `AGENTS.md`. A new "Calling the
84+
generated REST API" block gives the filter form (`?filter[status][eq]=active`, never
85+
`?status=active`) with its nine operators, sorting and paging (including each port's default
86+
when `limit` is omitted), and the error bodies. To offset it, the Java and Kotlin generator
87+
class lists, the TypeScript catalog pipeline and the prompt and report rules moved behind the
88+
skills they already pointed to. Measured on the agent-context conformance stacks (C#,
89+
Java + React, Java + Kotlin + React + TanStack, Python, TypeScript + React + TanStack), the
90+
file an assistant loads each session is 5,580 / 6,045 / 6,705 / 5,585 / 6,572 bytes, from
91+
4,978 / 5,767 / 6,731 / 4,983 / 6,207: the REST block adds more than the moved detail takes
92+
out. The always-on bytes written to disk fall by 44 to 50% because the copy is gone. The C#,
93+
Java and Python staleness notices no longer name `.claude/skills`.
6194
- **Breaking, TypeScript: a value object is never renamed; one claim registry refuses real
6295
collisions** (amending ADR-0044 and ADR-0056). `acme::alpha::Note` is declared as `Note` in its
6396
own module; the `AcmeAlphaNote` derived name, `assignEmittedNames` and its

‎README.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,11 @@ gated by `meta verify --codegen`, which is what keeps output from drifting. See
5555
[write your own generator](docs/recipes/write-your-own-generator.md).
5656

5757
Java, Kotlin, C# and Python start the same way from their own package: see
58-
[`docs/ports/`](docs/ports/).
58+
[`docs/ports/`](docs/ports/). **Their schema migrations and database checks still run in the
59+
Node `meta` tool** (`npx meta migrate`, `npx meta verify --db`), so those teams need Node where
60+
migrations are written or applied. Where the ports behave differently (list defaults, error
61+
bodies, field names, data access) is listed in
62+
[What differs by language](docs/features/language-differences.md).
5963

6064
The metamodel is the **durable spine**; generated code is the **disposable
6165
artifact**. Substrate is local-first: typed metadata lives in your repo as YAML or
@@ -341,6 +345,11 @@ metaobjects/
341345
| C# | `dotnet tool install --global MetaObjects.Cli` → [`docs/ports/csharp.md`](docs/ports/csharp.md) |
342346
| Python | `pip install metaobjects` → [`docs/ports/python.md`](docs/ports/python.md) |
343347

348+
Every language also needs the Node `meta` CLI for the schema: `npm i -D @metaobjectsdev/cli`,
349+
then `npx meta init --config-only` in a Maven-, .NET- or pip-rooted project, and
350+
`npx meta migrate` / `npx meta verify --db` from there. The per-language differences are in
351+
[What differs by language](docs/features/language-differences.md).
352+
344353
## Cross-language conformance
345354

346355
Every port runs against the same fixture corpora at [`fixtures/`](fixtures/).

‎agent-context/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,14 @@
22

33
This tree is the single source the assembler (`@metaobjectsdev/sdk`,
44
`src/agent-context/`) turns into the files scaffolded into a consumer project:
5-
the slim always-on Markdown (`.metaobjects/AGENTS.md` + `CLAUDE.md`) and the six
6-
`metaobjects-*` Claude skills (each a universal `SKILL.md` plus the
7-
`references/<token>.md` fragments matching the project's resolved stack).
5+
the slim always-on Markdown (`.metaobjects/AGENTS.md`, imported by the project's root
6+
`AGENTS.md` / `CLAUDE.md`) and the six `metaobjects-*` skills (each a universal `SKILL.md` plus
7+
the `references/<token>.md` fragments matching the project's resolved stack). The skills
8+
install under `.claude/skills/` unless `--skills-dir` names another directory (such as
9+
`.agents/skills/`); the always-on text names the directory through `{{skillsDir}}`.
810

911
- `servers/<lang>.meta.json` — per-server install, codegen command and the always-on's verify step (`verifyStep`).
10-
- `templates/always-on.md.mustache` — the slim always-on body: a working loop first (`{{stackLine}}`, `{{stackLoops}}`, `{{verifySteps}}`), then the rules. The full principles it shortens live in `metaobjects-codegen/references/principles.md`.
12+
- `templates/always-on.md.mustache` — the slim always-on body: a working loop first (`{{stackLine}}`, `{{stackLoops}}`, `{{verifySteps}}`), the REST conventions agents trip on, then the rules and the skill pointers (`{{skillsDir}}`). The full principles it shortens live in `metaobjects-codegen/references/principles.md`.
1113
- `templates/loops/<server>.md`, `templates/loops/client.md` — the generate steps of that loop, one per declared server (and one for a web client), concatenated by the assembler.
1214
- `skills/<skill>/SKILL.md` — universal skill body.
1315
- `skills/<skill>/references/<token>.md` — language/framework fragment; installed iff `<token>` is in the stack (`Stack.tokens`). The requirements pages are universal topic files: they install in every stack, because whether a project declares `requirement.*` nodes changes after `meta init` runs.
@@ -18,7 +20,7 @@ The **scaffolded** set is exactly the six skills in the SDK's `SKILL_NAMES`
1820
(`src/agent-context/types.ts`) — the assembler emits only those. `skills/`
1921
additionally holds **`metaobjects-fit-assessment`**, a *pre-adoption* tool that is
2022
deliberately **not** in `SKILL_NAMES` and so is never scaffolded (a not-yet-adopted
21-
target has no `.claude/skills/metaobjects-*` to receive it); it carries
23+
target has no installed `metaobjects-*` skills to receive it); it carries
2224
`scaffold: false` under `metadata:` in its front-matter as the human marker (no code reads it). Its design + retro-test
2325
validation live in `docs/superpowers/specs/2026-07-12-metaobjects-fit-assessment-design.md`.
2426

‎agent-context/skills/metaobjects-codegen/references/principles.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ reasons. Read it when a rule there does not settle the case in front of you.
1212
## Principles
1313

1414
- **Adopting onto existing code? Metadata FOLLOWS the code.** On a migration (existing working code / live DB), author metadata + tune codegen to *reproduce* what the code already is — native types (`field.uuid` when the code uses `UUID`, not `field.string`; and the type a JSON column's WRITER declares — `list[str]`, a dataclass, `dict[str, X]` — not an open jsonb bag), names, nullability — so regen changes as little existing code as possible. The only existing code that should change is the hand-written layer codegen replaces; ask when a modeling choice is ambiguous. (Greenfield: model-first, below.)
15-
- Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate. Don't hand-write divergent SQL; where a stack owns its own migration files, GENERATE them — `meta migrate --migration-format flyway` emits the paired `V<n>__`/`U<n>__` files a Flyway runner expects, and leaves applying them to Flyway. The one exception is a schema this project deliberately owns outside MetaObjects (hand-written migrations by rule, or another team's database): when the root `CLAUDE.md` says so, follow it, and keep `meta verify --db` catching drift.
15+
- Pattern-derivable from metadata = codegen, never hand-write — FKs, CRUD, validators, finders, and the database schema and migrations. The schema is a disposable, generated artifact: change the metadata and regenerate. Don't hand-write divergent SQL; where a stack owns its own migration files, GENERATE them — `meta migrate --migration-format flyway` emits the paired `V<n>__`/`U<n>__` files a Flyway runner expects, and leaves applying them to Flyway. The one exception is a schema this project deliberately owns outside MetaObjects (hand-written migrations by rule, or another team's database): when the root `AGENTS.md` or `CLAUDE.md` says so, follow it, and keep `meta verify --db` catching drift.
1616
- **Once this project declares any `template.prompt`, every LLM prompt is one** — the text in the template, the data in a payload value object, rendered by the render engine. A structured reply is read through a response model (`@responseRef` and its generated extractor), never a regex or string search. This covers code that does not look like MetaObjects: a format string, text block, template literal or string builder sent to an LLM, and it covers every module, including test harnesses and scripts. Changing a prompt that is still hand-built means migrating it first (snapshot its current output and keep the rendered text byte-identical), not adding a line to it; the `metaobjects-prompts` skill has the steps.
1717
- The **live database** is a derived artifact too — never hand-apply a schema change to a running DB (ad-hoc `psql`/console `ALTER`/`CREATE`/`DROP`), not even to preview a column or unblock a boot. Drive every schema change from the metadata, never ad-hoc: on the Node/TS-owned migrate stack that is `meta migrate` (metadata → DDL, ADR-0015); on a **Flyway**-owned JVM stack that is `meta migrate --migration-format flyway`, which emits the migration and deliberately refuses `--apply` because Flyway owns applying it. Hand-authoring a migration to match the generated schema is the LAST resort — for a runner MetaObjects has no writer for — never the default for Flyway. A hand-applied ad-hoc change drifts the live DB from the metadata + migration history and collides at the next migrate/boot ("column already exists") — a state no migration can reproduce. Run `meta verify --db <url>` after any DB-touching work to catch that drift early — the URL is required, and the bare form exits 2.
1818
- **If this project declares `requirement.*` nodes, a commit that adds, changes or removes behaviour updates them in the same commit** (the claim, its `@status` and `@implementedBy`), or says in the commit message why not. `meta verify` checks that the links resolve, not that the ledger is current.

‎agent-context/templates/always-on.md.mustache‎

Lines changed: 37 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33
> {{stackLine}}
44
>
55
> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your
6-
> **root `CLAUDE.md`**, not here — this file is regenerated.
6+
> root `AGENTS.md` or `CLAUDE.md`, not here: this file is regenerated.
77

88
The metadata (`metaobjects/` unless `.metaobjects/config.json` says otherwise) is the source of
99
truth. Code, schema and migrations are generated from it and are disposable.
1010

1111
## Start here: the whole loop, in order
1212

1313
{{stackLoops}}
14-
### Schema (every stack: the Node `meta` CLI owns it)
14+
### Schema (every stack: the Node `meta` CLI owns it, so Java, Kotlin, C# and Python projects need Node too)
1515

1616
Never hand-write DDL, and never `ALTER` a live database by hand.
1717

@@ -21,16 +21,15 @@ Never hand-write DDL, and never `ALTER` a live database by hand.
2121
- At boot or deploy: `npx meta migrate apply-pending --db <url>`.
2222
- A later change: edit the metadata, regenerate, then
2323
`npx meta migrate --dialect <dialect> --slug <name>` (offline, from the committed snapshot).
24-
For a renamed field add `--rename-column <table>.<old_column>=<new_column>` (a renamed object:
25-
`--rename-table <old>=<new>`), which keeps the data. A destructive change is refused until you
26-
allow its kind by name, and the refusal names it: `--allow drop-check` for a changed enum,
27-
`--allow drop-column` only when the data should go.
24+
A renamed field needs `--rename-column <table>.<old_column>=<new_column>` (an object:
25+
`--rename-table <old>=<new>`) to keep its data. A destructive change is refused until you
26+
allow its kind by name: `--allow drop-check` for a changed enum, `--allow drop-column` only
27+
when the data should go.
2828

2929
### Requirements, when the metadata declares `requirement.*` nodes
3030

31-
They list what the software must do. A commit that changes behaviour updates them in the same
32-
commit: `@status: live` once a claim is built (never before), a new node for new behaviour.
33-
`meta verify` checks that links resolve, not that a status is true.
31+
A commit that changes behaviour updates them in the same commit: `@status: live` once a claim
32+
is built (never before), a new node for new behaviour.
3433

3534
### Before you call it done
3635

@@ -39,6 +38,21 @@ commit: `@status: live` once a claim is built (never before), a new node for new
3938
Commit the metadata, the generated code, `.metaobjects/migrations/` and
4039
`.metaobjects/.gen-state/.hashes.json`.
4140

41+
## Calling the generated REST API
42+
43+
When the project serves the generated routes (any port):
44+
45+
- Filter as `?filter[<field>][<op>]=<value>`: `?filter[status][eq]=active`, never
46+
`?status=active` (TypeScript refuses that with 400; the other ports ignore it). Operators: `eq`, `ne`, `isNull` (`true`/`false`), `in` (comma list, at most 100), `like`
47+
(case-sensitive, `%` and `_`), `gt`, `gte`, `lt`, `lte`. Filters AND; only `@filterable`
48+
fields filter.
49+
- `?sort=<field>:asc|desc`, `?limit=N&offset=N`; `withCount=1` returns `{"rows", "total"}`.
50+
Always send `limit`: without it TypeScript and C# return every row, the other ports 50.
51+
- `PUT` is the same partial update as `PATCH`.
52+
- Errors are `{"error": "<code>"}`: 400 for validation (only TypeScript adds `issues`) and for
53+
a bad filter or sort (`invalid_filter_field`, `_op`, `_value`, `invalid_sort`, each naming
54+
`field`), 404 `not_found`, 409 for a unique or foreign-key conflict.
55+
4256
## Rules
4357

4458
- What the metadata describes is generated, never hand-written (tables, types, validators,
@@ -47,27 +61,24 @@ Commit the metadata, the generated code, `.metaobjects/migrations/` and
4761
broken? Fix the generator: eject it and it is yours, no permission needed, nothing to wait on.
4862
- Never spell a table or column name as a string; use the generated table or names constants.
4963
- Wire a generator only for output you will import.
50-
- Once the project declares a `template.prompt`, every LLM prompt is one: the text in a
51-
template, the data in a payload, a structured reply read through its generated extractor
52-
(`metaobjects-prompts`).
53-
- A grouped total, dashboard number or read-only report view (per client, per month) is an
54-
`object.report` over `dimension.*` / `measure.*` (`metaobjects-authoring`,
55-
`references/declaring-reports.md`). A hand-written `@sql` view body is the last resort.
64+
- An LLM prompt in a project that declares `template.prompt` is a declared template
65+
(`metaobjects-prompts`); a grouped total or report view is an `object.report`
66+
(`metaobjects-authoring`). Open the skill before writing either by hand.
5667
- Never invent metadata vocabulary. Search it: `npx meta types <term>`, and
5768
`npx meta types <type>.<subType> --detail` for one construct's valid attributes.
5869
- Metadata nodes are fused-key maps, `{"field.string": {"name": "email"}}`. Attribute names are
5970
unique within a node, and package paths use `::`.
6071

6172
## Going deeper
6273

63-
The loop above needs no skill. The `metaobjects-*` skills hold the detail for less common work:
64-
unusual shapes or adopting existing code (`metaobjects-authoring`), owning or writing a
65-
generator and the full principles (`metaobjects-codegen`), REST routes and the web client
66-
(`metaobjects-runtime-ui`), LLM prompts (`metaobjects-prompts`), migration edge cases, drift and
67-
upgrades (`metaobjects-verify`), an adoption review (`metaobjects-audit`). Load one by name when
68-
its task comes up; it names the one reference page to open.
69-
70-
This file and the skills are regenerated by `meta init --refresh-docs`; put project guidance in
71-
the root `CLAUDE.md`, or copy a skill to a new name to override it. A refresh never overwrites a
72-
file you edited (only `--force` does, so never `--force` one with local edits): it writes
73-
`<path>.new` beside it. Merge that into `<path>`, keeping your edits, and delete the `.new`.
74+
The loop above needs no skill. For less common work load a `metaobjects-*` skill by name, or open
75+
`{{skillsDir}}/<skill>/SKILL.md` if your assistant does not load skills: `metaobjects-authoring`
76+
(unusual shapes, reports, adopting existing code), `metaobjects-codegen` (owning or writing a
77+
generator), `metaobjects-runtime-ui` (REST routes, the web client), `metaobjects-prompts` (LLM
78+
prompts), `metaobjects-verify` (migration edge cases, drift, upgrades), `metaobjects-audit` (an
79+
adoption review). Each names the one reference page to open.
80+
81+
`meta init --refresh-docs` regenerates this file and the skills, so keep project guidance in
82+
the root `AGENTS.md` or `CLAUDE.md` (or copy a skill to a new name). A refresh never overwrites a
83+
file you edited; it writes `<path>.new` beside it, which you merge into `<path>` and delete.
84+
Never `--force` a refresh over local edits.

‎agent-context/templates/loops/java.md‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,8 @@
22

33
1. **Config.** The `metaobjects-maven-plugin`'s `<generators>` in `pom.xml` is the generator
44
list, one `<generator><classname>` each, under `<loader><sourceDir>` pointing at the metadata.
5-
Nothing is generated until it is listed. The Spring REST tier is `SpringDtoGenerator`,
6-
`SpringValueObjectGenerator`, `SpringRepositoryGenerator`, `SpringFilterAllowlistGenerator` and
7-
`SpringControllerGenerator` (package `com.metaobjects.generator.spring`); the build refuses a
8-
list missing a generator another one's output needs, and names it. `JUnitRequirementTestsGenerator`
9-
writes one test per requirement; `JavaApiDocsGenerator` writes `api/java/AGENT-API.md`. The
10-
full table is in the `metaobjects-codegen` skill's `references/java.md`.
5+
Nothing is generated until it is listed; the build names any generator a listed one needs.
6+
Which classes to list (the Spring REST tier, requirement tests, API docs) is in the
7+
`metaobjects-codegen` skill's `references/java.md`.
118
2. **Generate.** `mvn metaobjects:generate`. `mvn metaobjects:eject -Dnames=<name> -Dport=java`
129
copies a generator to change what it emits.

0 commit comments

Comments
 (0)