Add a root AGENTS.md, so the rules survive the session that learned them

[Peeja]

You asked what would make sure the wiki gets updated as things happen rather than when someone remembers. This is the answer. Two files, based on main, stacked on nothing.

It says up front that it is scaffolding

Added at your prompt, and it changes how the whole file reads, so it is the first section rather than a footnote:

Most of what follows exists because this repository is being assembled, not because it is how Forge is worked on. Rules 7 and 8 are entirely about git subtree; rule 1 is about what is still being moved in; the wiki and the four-document split exist to carry decisions across a construction that spans many sessions and one person's attention. None of that is a durable guide to a finished monorepo, and left in place it will read as though it were.

The replacement trigger is a checkable set of conditions, not a feeling — nothing left to import, no subtree pulls pending, the forge-2 → forge rename done, Phase 1's release machinery real. Same reason the wiki trigger is an event.

It also guesses at the split — rules 2–5 and the conventions probably survive; rules 1 and 6–9, the wiki and most of the document table probably don't — and says explicitly not to treat that guess as settled.

The honest diagnosis it came from

Nothing would have, because every rule this repository runs on has been living in one session's scheduled check-in prompts — session-local, timer-driven, gone when the session ends. That is also why the wiki updates were lumpy: they happened when a check-in fired, not when the thing they describe changed.

All ten services carry an AGENTS.md. The monorepo root carried none. So nothing told a new session — or a person — that a wiki exists, what belongs in it versus MAJOR_DECISIONS.md versus MONOREPO_TODO.md, or what the nine rules are.

The wiki instruction is an event, not a standing wish

"Keep it current" is the exact phrasing that failed twice in one hour, so the file does not use it:

Opened, pushed to, rebased, merged or closed a PR? Made a decision, or took one on someone's behalf? Found something you are deliberately not fixing?
→ update the wiki before you report what you did, not after.

A main sha or a PR list that is one merge stale is worse than no snapshot, because it is believed.

What else is in it

Short on purpose, pointing at the wiki for reasoning rather than duplicating it — duplicated prose is the thing that goes stale. Only what is already decided and observable: where the four documents differ; the nine rules in one-line form; the four workflows, and that nothing is path-filtered on purpose; and two conventions that have caught real mistakes here — never hand-transcribe a digest or a sha, and verify a guard in both directions.

CLAUDE.md is @AGENTS.md, matching every service in the tree.

The draft was wrong, and checking it is what found that

The first version enumerated three guard scripts. main has two — check-stack-images.sh arrives with #17. So the guards section now names the directory and lets it be the list, which is what rule 3 says to do anyway. A document that opened by breaking its own rule 3 would not have been worth much.

Worth your eye

This is a proposal about how this repository is worked on, not a record of something already agreed. In particular: the nine rules are compressed from the wiki and may have flattened a nuance; the wiki trigger is the one line that actually has to work; and the scaffolding section's guess at what survives the rewrite is a guess.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CGAGAib517Ae1kg8SCdcEt