From 562b40bfe5e83a2b25eaef7ef19eda6bece9dca5 Mon Sep 17 00:00:00 2001
From: clawbot <35+clawbot@noreply.example.org>
Date: Sun, 4 Oct 2026 08:02:24 +0200
Subject: [PATCH] Keep agent guidance in one root AGENTS.md (closes #31)

Writes 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` gains one bullet after the files a new repo must contain: guidance for coding agents lives in one `AGENTS.md` at the repository root, never under a file or directory named after one agent tool, and never split into separate memory files. `AGENTS.md` joins the files allowed in the repo root, which would otherwise forbid it. Both checklists get the matching item; the existing-repo one says to move such a file's content into `AGENTS.md` and delete it.

The Dockerfile finding at the end of the issue is tracked in https://git.eeqj.de/sneak/prompts/issues/90.

Model: opus-5-5
---
 TODO.md                            |  6 ++++++
 prompts/EXISTING_REPO_CHECKLIST.md |  4 ++++
 prompts/NEW_REPO_CHECKLIST.md      |  3 +++
 prompts/REPO_POLICIES.md           | 12 ++++++++----
 4 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/TODO.md b/TODO.md
index 3bc4690..8c21fbd 100644
--- a/TODO.md
+++ b/TODO.md
@@ -21,6 +21,12 @@ fmt-check, and commit.
 
 # Completed Steps
 
+- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents
+  lives in one `AGENTS.md` at the repository root, never under a file or
+  directory named after one agent tool and never in separate memory files (issue
+  31). This retires the rule, still present in older vendored copies, that kept
+  agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the
+  list of files allowed in the root, and both checklists say so.
 - 2026-10-04: Rewrote the note under the canonical Go `make test` example in
   `REPO_POLICIES.md` (issue 77), which still named the cache-busting build
   argument that `--no-cache` replaced. It now says where Go's test result cache
diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md
index 21b00fa..316cc29 100644
--- a/prompts/EXISTING_REPO_CHECKLIST.md
+++ b/prompts/EXISTING_REPO_CHECKLIST.md
@@ -24,6 +24,10 @@ with your task.
 - [ ] `LICENSE` file exists and matches the README
 - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
+- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
+      root — never a file or directory named after one agent tool, such as
+      `CLAUDE.md` or `.claude/`, and never separate memory files. Move what any
+      such committed file says into `AGENTS.md` and delete it.
 - [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language
       artifacts, secrets) — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing.
diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md
index ecdd444..c229df2 100644
--- a/prompts/NEW_REPO_CHECKLIST.md
+++ b/prompts/NEW_REPO_CHECKLIST.md
@@ -54,6 +54,9 @@ Template files can be fetched from:
 - [ ] `LICENSE` file matching the chosen license
 - [ ] `REPO_POLICIES.md` — fetch from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
+- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the
+      root — never a file or directory named after one agent tool, such as
+      `CLAUDE.md` or `.claude/`, and never separate memory files
 - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
     - Extend `.dockerignore` with the repo's own host-built artifacts, giving
diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md
index d424a49..af0ea80 100644
--- a/prompts/REPO_POLICIES.md
+++ b/prompts/REPO_POLICIES.md
@@ -607,10 +607,10 @@ style conventions are in separate documents:
   settings.
 
 - Avoid putting files in the repo root unless necessary. Root should contain
-  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
-  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
-  language-specific config). Everything else goes in a subdirectory. Canonical
-  subdirectory names:
+  only project-level config files (`README.md`, `AGENTS.md`, `Makefile`,
+  `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`,
+  and language-specific config). Everything else goes in a subdirectory.
+  Canonical subdirectory names:
     - `bin/` — executable scripts and tools
     - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
       body is a single call into `internal/` or `pkg/`, no project logic in
@@ -641,3 +641,7 @@ style conventions are in separate documents:
     - Go: `go.mod`, `go.sum`, `.golangci.yml`
     - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
     - Python: `pyproject.toml`
+
+- 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, such
+  as `CLAUDE.md` or `.claude/`, and never split into separate memory files.