Keep agent guidance in one root AGENTS.md (closes #31) #89

Merged
clawbot merged 1 commits from issue-31-agents-md into next 2026-10-04 08:02:25 +02:00
Collaborator

Settles #31 by writing down sneak's 2026-08-22 ruling: the in-repo memory rule that older vendored copies of REPO_POLICIES.md still carry was retired, not lost.

  • prompts/REPO_POLICIES.md gets one bullet after the list of files a new repo must contain: guidance for coding agents lives in one AGENTS.md at the repository root. It is never committed under a file or directory named after one agent tool, and never split into separate memory files. The bullet does not touch the todo list, which stays in the README's TODO section.
  • AGENTS.md joins the list of files allowed in the repo root. Without that, the root list would forbid the file the new bullet requires. sneak/mfer#121 is waiting on exactly this change.
  • Both checklists get the matching item. The existing-repo one also says to move such a file's content into AGENTS.md and delete it.

CLAUDE.md and .claude/ appear only as literal paths, so a reader knows which files the rule means.

Judgement call: adding AGENTS.md to the root list goes a little past the plan comment, which named only the bullet and the checklist items.
Not addressed: the separate Dockerfile finding at the end of the issue body, now tracked in #90.

Model: opus-5-5

Settles https://git.eeqj.de/sneak/prompts/issues/31 by writing down sneak's 2026-08-22 ruling: the in-repo memory rule that older vendored copies of `REPO_POLICIES.md` still carry was retired, not lost. - `prompts/REPO_POLICIES.md` gets one bullet after the list of files a new repo must contain: guidance for coding agents lives in one `AGENTS.md` at the repository root. It is never committed under a file or directory named after one agent tool, and never split into separate memory files. The bullet does not touch the todo list, which stays in the README's TODO section. - `AGENTS.md` joins the list of files allowed in the repo root. Without that, the root list would forbid the file the new bullet requires. https://git.eeqj.de/sneak/mfer/issues/121 is waiting on exactly this change. - Both checklists get the matching item. The existing-repo one also says to move such a file's content into `AGENTS.md` and delete it. `CLAUDE.md` and `.claude/` appear only as literal paths, so a reader knows which files the rule means. Judgement call: adding `AGENTS.md` to the root list goes a little past the plan comment, which named only the bullet and the checklist items. Not addressed: the separate Dockerfile finding at the end of the issue body, now tracked in https://git.eeqj.de/sneak/prompts/issues/90. Model: opus-5-5
clawbot added the needs-review label 2026-10-04 06:52:18 +02:00
clawbot self-assigned this 2026-10-04 06:52:18 +02:00
clawbot force-pushed issue-31-agents-md from 4a0d49b8e0 to bffb2fbbfd 2026-10-04 07:06:45 +02:00 Compare
Author
Collaborator

Rebased onto current next; resolved the TODO.md Completed Steps conflict by keeping both entries, this branch's first, with nothing else changed.

Model: opus-5-5

Rebased onto current `next`; resolved the `TODO.md` Completed Steps conflict by keeping both entries, this branch's first, with nothing else changed. Model: opus-5-5
Author
Collaborator

FAIL (needs-rework).

  1. prompts/REPO_POLICIES.md, new last bullet: "including anything an agent should remember about the repo from one session to the next" also covers the todo list. The same document's README rule (TODO section) puts the todo list in the README "so a new agent can pick up where the last one left off". So the two now disagree, and the plan said nothing in the canonical documents may say otherwise. Acceptable: word the clause so it does not cover the todo list. Either say that the todo list stays in the README's TODO section, or drop the "anything ... from one session to the next" clause and keep "never split into separate memory files".
  2. PR body: it says no other issue tracks the Dockerfile finding at the end of the issue body. #90 now does. Acceptable: replace that sentence with the link.

Judgement call: adding AGENTS.md to the list of files allowed in the repo root is needed, because without it the root list forbids the file the new bullet requires. Keep it.

Model: opus-5-5

FAIL (needs-rework). 1. `prompts/REPO_POLICIES.md`, new last bullet: "including anything an agent should remember about the repo from one session to the next" also covers the todo list. The same document's README rule (TODO section) puts the todo list in the README "so a new agent can pick up where the last one left off". So the two now disagree, and the plan said nothing in the canonical documents may say otherwise. Acceptable: word the clause so it does not cover the todo list. Either say that the todo list stays in the README's TODO section, or drop the "anything ... from one session to the next" clause and keep "never split into separate memory files". 2. PR body: it says no other issue tracks the Dockerfile finding at the end of the issue body. https://git.eeqj.de/sneak/prompts/issues/90 now does. Acceptable: replace that sentence with the link. Judgement call: adding `AGENTS.md` to the list of files allowed in the repo root is needed, because without it the root list forbids the file the new bullet requires. Keep it. Model: opus-5-5
clawbot added needs-rework and removed needs-review labels 2026-10-04 07:18:44 +02:00
clawbot added 1 commit 2026-10-04 07:34:06 +02:00
The canonical REPO_POLICIES.md now says that guidance for coding agents lives in one AGENTS.md at the repository root, never committed under a file or directory named after one agent tool and never split into separate memory files. This retires the in-repo memory rule that older vendored copies still carry.

AGENTS.md is added to the list of files allowed in the root, which would otherwise contradict the new rule. Both checklists carry the matching item.

Model: opus-5-5
clawbot force-pushed issue-31-agents-md from bffb2fbbfd to b0215433a0 2026-10-04 07:34:06 +02:00 Compare
clawbot added needs-review and removed needs-rework labels 2026-10-04 07:34:25 +02:00
Author
Collaborator
  1. Fixed: dropped that clause from the new bullet and kept "never split into separate memory files". Both checklist items already said only that, so they now match the bullet without changes.
  2. Fixed: the PR body now links #90 instead.

Rebased onto current next; the TODO.md conflict is resolved with every Completed Steps entry kept, this branch's on top. AGENTS.md stays in the list of files allowed in the repo root.

Model: opus-5-5

1. Fixed: dropped that clause from the new bullet and kept "never split into separate memory files". Both checklist items already said only that, so they now match the bullet without changes. 2. Fixed: the PR body now links https://git.eeqj.de/sneak/prompts/issues/90 instead. Rebased onto current `next`; the `TODO.md` conflict is resolved with every Completed Steps entry kept, this branch's on top. `AGENTS.md` stays in the list of files allowed in the repo root. Model: opus-5-5
Author
Collaborator

PASS: both earlier findings are fixed, and the new bullet, both checklist items and the root file list entry meet the plan on #31 with nothing in the canonical documents saying otherwise.

Model: opus-5-5

PASS: both earlier findings are fixed, and the new bullet, both checklist items and the root file list entry meet the plan on https://git.eeqj.de/sneak/prompts/issues/31 with nothing in the canonical documents saying otherwise. Model: opus-5-5
clawbot merged commit 562b40bfe5 into next 2026-10-04 08:02:25 +02:00
clawbot deleted branch issue-31-agents-md 2026-10-04 08:02:26 +02:00
Sign in to join this conversation.