From 93f81573f2c371b8ceb7636d4a4393e17bbb8857 Mon Sep 17 00:00:00 2001 From: Doug Mealing Date: Tue, 7 Jul 2026 09:13:05 -0400 Subject: [PATCH] docs(agent-context): tell adopters how refresh/customization works in the always-on doc The generated always-on doc (`.metaobjects/CLAUDE.md`/`AGENTS.md`) said the skills were "safe to read and edit" while also telling adopters to "re-run the agent-context scaffold to refresh them" -- a contradiction: an edit followed by a refresh parks the fresh copy at `.new` (or clobbers it with `--force`), which adopting apps trip over with no clear home for project-specific notes. Fix by telling, in the doc itself (no code merge): mark the file as generated, direct project notes to the root `CLAUDE.md`, explain that a refresh never silently destroys edits (it parks `.new`; only `--force` overwrites in place), and give the reconcile procedure for `.new`. Regen the 8 conformance goldens (AGENTS.md + CLAUDE.md across the 4 stacks). Docs-only; no runtime/codegen change. Co-Authored-By: Claude --- agent-context/templates/always-on.md.mustache | 16 +++++++++++++--- .../expected/.metaobjects/AGENTS.md | 16 +++++++++++++--- .../expected/.metaobjects/CLAUDE.md | 16 +++++++++++++--- .../java-react/expected/.metaobjects/AGENTS.md | 16 +++++++++++++--- .../java-react/expected/.metaobjects/CLAUDE.md | 16 +++++++++++++--- .../python/expected/.metaobjects/AGENTS.md | 16 +++++++++++++--- .../python/expected/.metaobjects/CLAUDE.md | 16 +++++++++++++--- .../expected/.metaobjects/AGENTS.md | 16 +++++++++++++--- .../expected/.metaobjects/CLAUDE.md | 16 +++++++++++++--- 9 files changed, 117 insertions(+), 27 deletions(-) diff --git a/agent-context/templates/always-on.md.mustache b/agent-context/templates/always-on.md.mustache index 8f3500724..4ff2fac19 100644 --- a/agent-context/templates/always-on.md.mustache +++ b/agent-context/templates/always-on.md.mustache @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > {{stackLine}} +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `{{codegenCommand}}`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/AGENTS.md b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/AGENTS.md index 97d416ccc..61d03613d 100644 --- a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/AGENTS.md +++ b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/AGENTS.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: java, kotlin server, react, tanstack client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `mvn metaobjects:generate`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/CLAUDE.md b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/CLAUDE.md index 97d416ccc..61d03613d 100644 --- a/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/CLAUDE.md +++ b/fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/CLAUDE.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: java, kotlin server, react, tanstack client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `mvn metaobjects:generate`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md b/fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md index 513d86af6..8cd4497e8 100644 --- a/fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md +++ b/fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: java server, react client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `mvn metaobjects:generate`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/java-react/expected/.metaobjects/CLAUDE.md b/fixtures/agent-context-conformance/java-react/expected/.metaobjects/CLAUDE.md index 513d86af6..8cd4497e8 100644 --- a/fixtures/agent-context-conformance/java-react/expected/.metaobjects/CLAUDE.md +++ b/fixtures/agent-context-conformance/java-react/expected/.metaobjects/CLAUDE.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: java server, react client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `mvn metaobjects:generate`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/python/expected/.metaobjects/AGENTS.md b/fixtures/agent-context-conformance/python/expected/.metaobjects/AGENTS.md index 97f4b380f..badf4b87d 100644 --- a/fixtures/agent-context-conformance/python/expected/.metaobjects/AGENTS.md +++ b/fixtures/agent-context-conformance/python/expected/.metaobjects/AGENTS.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: python server, no client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `metaobjects gen`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/python/expected/.metaobjects/CLAUDE.md b/fixtures/agent-context-conformance/python/expected/.metaobjects/CLAUDE.md index 97f4b380f..badf4b87d 100644 --- a/fixtures/agent-context-conformance/python/expected/.metaobjects/CLAUDE.md +++ b/fixtures/agent-context-conformance/python/expected/.metaobjects/CLAUDE.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: python server, no client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `metaobjects gen`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/AGENTS.md b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/AGENTS.md index 0428279cc..41da9172f 100644 --- a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/AGENTS.md +++ b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/AGENTS.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: typescript server, react, tanstack client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `npx meta gen`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`. diff --git a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/CLAUDE.md b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/CLAUDE.md index 0428279cc..41da9172f 100644 --- a/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/CLAUDE.md +++ b/fixtures/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/CLAUDE.md @@ -1,6 +1,9 @@ # Working with MetaObjects in this project > Stack: typescript server, react, tanstack client. +> +> Generated by MetaObjects (refresh: `meta init --refresh-docs`). Put project notes in your +> **root `CLAUDE.md`**, not here — this file is regenerated; see the note at the end before editing it. MetaObjects is a metadata standard: typed metadata in `metaobjects/` is the durable spine; generated code is the disposable artifact. Regenerate with `npx meta gen`. @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use matching `metaobjects-*` skill — its body links the `references/.md` fragment installed for this project's stack. -These `metaobjects-*` skills are plain, inspectable Markdown reference docs (no tools -or hooks) generated by MetaObjects for this project's stack — safe to read and edit; -re-run the agent-context scaffold to refresh them. +## Refreshing / customizing this generated context +This file and the `metaobjects-*` skills are **generated** by MetaObjects for this project's +stack (plain Markdown, no tools/hooks) — refresh with `meta init --refresh-docs`. Don't hand-edit +them expecting the edit to survive: a refresh leaves a file you've edited intact and writes the +new copy to `.new` (only `--force` overwrites in place — never `--force` a file with local +edits). For project-specific guidance, put it in your **root `CLAUDE.md`** (always-on concerns) or +copy a skill to a new name (skill-level overrides) — don't edit the generated originals in place. + +After a refresh, for each `.new`: diff it against ``, **keep the hand-edits and take +the upstream changes**, write the merged result back to ``, then delete `.new`.