Skip to content

docs(agent-context): clarify refresh/overwrite behavior in the generated always-on doc #184

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dmealing merged 1 commit into from
Jul 7, 2026
Merged

docs(agent-context): clarify refresh/overwrite behavior in the generated always-on doc #184

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions agent-context/templates/always-on.md.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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}}`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions ...-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions ...-context-conformance/java-kotlin-react-tanstack/expected/.metaobjects/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions fixtures/agent-context-conformance/java-react/expected/.metaobjects/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions fixtures/agent-context-conformance/java-react/expected/.metaobjects/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions fixtures/agent-context-conformance/python/expected/.metaobjects/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions fixtures/agent-context-conformance/python/expected/.metaobjects/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions ...res/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
16 changes: 13 additions & 3 deletions ...res/agent-context-conformance/ts-react-tanstack/expected/.metaobjects/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Expand All @@ -27,6 +30,13 @@ For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use
matching `metaobjects-*` skill — its body links the `references/<lang>.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 `<path>.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 `<path>.new`: diff it against `<path>`, **keep the hand-edits and take
the upstream changes**, write the merged result back to `<path>`, then delete `<path>.new`.
Loading