You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f50258f
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: agent-context/README.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,14 @@
2
2
3
3
This tree is the single source the assembler (`@metaobjectsdev/sdk`,
4
4
`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}}`.
8
10
9
11
-`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`.
11
13
-`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.
-`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`
18
20
(`src/agent-context/types.ts`) — the assembler emits only those. `skills/`
19
21
additionally holds **`metaobjects-fit-assessment`**, a *pre-adoption* tool that is
20
22
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
22
24
`scaffold: false` under `metadata:` in its front-matter as the human marker (no code reads it). Its design + retro-test
23
25
validation live in `docs/superpowers/specs/2026-07-12-metaobjects-fit-assessment-design.md`.
Copy file name to clipboardExpand all lines: agent-context/skills/metaobjects-codegen/references/principles.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ reasons. Read it when a rule there does not settle the case in front of you.
12
12
## Principles
13
13
14
14
-**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.
16
16
-**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.
17
17
- 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.
18
18
-**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.
Copy file name to clipboardExpand all lines: agent-context/templates/always-on.md.mustache
+37-26Lines changed: 37 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -3,15 +3,15 @@
3
3
> {{stackLine}}
4
4
>
5
5
> 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.
7
7
8
8
The metadata (`metaobjects/` unless `.metaobjects/config.json` says otherwise) is the source of
9
9
truth. Code, schema and migrations are generated from it and are disposable.
10
10
11
11
## Start here: the whole loop, in order
12
12
13
13
{{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)
15
15
16
16
Never hand-write DDL, and never `ALTER` a live database by hand.
17
17
@@ -21,16 +21,15 @@ Never hand-write DDL, and never `ALTER` a live database by hand.
21
21
- At boot or deploy: `npx meta migrate apply-pending --db <url>`.
22
22
- A later change: edit the metadata, regenerate, then
23
23
`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.
28
28
29
29
### Requirements, when the metadata declares `requirement.*` nodes
30
30
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.
34
33
35
34
### Before you call it done
36
35
@@ -39,6 +38,21 @@ commit: `@status: live` once a claim is built (never before), a new node for new
39
38
Commit the metadata, the generated code, `.metaobjects/migrations/` and
40
39
`.metaobjects/.gen-state/.hashes.json`.
41
40
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`
0 commit comments