feat(agents): move ground rules into a shared AGENTS.md

FAQ.md

@@ -105,6 +105,18 @@ Load:
 nvim -i custom.shada
 ```
 
+## Agents
+
+### Why keep the ground rules in `AGENTS.md`?
+
+[AGENTS.md](https://agents.md) is the file most coding agents already look for, so a
+single copy in `misc-configs/agents/AGENTS.md` covers all of them. A per-vendor copy of
+the same rules would drift the moment one of them is edited and the other isn't.
+
+Claude Code is the exception: it reads `CLAUDE.md`, not `AGENTS.md`. `bootstrap` handles
+that by symlinking `~/.claude/CLAUDE.md` to the shared file. Projects do the same with an
+`@AGENTS.md` import, see `example-configs/CLAUDE.md`.
+
 ## Claude
 
 ### Why disable `autoMemoryEnabled`?

bootstrap

@@ -46,9 +46,14 @@ ln -sf ~/dotfiles/misc-configs/lazygit/config.yml .config/lazygit/config.yml
 # -- Git --
 ln -sf ~/dotfiles/gitignore_global .gitignore_global
 
-# -- Claude Code --
+# -- Agent instructions --
+# Ground rules live in an agent-neutral AGENTS.md (https://agents.md) so any
+# coding agent can read the same file. Claude Code reads CLAUDE.md and not
+# AGENTS.md, so it gets a symlink named after what it looks for.
 mkdir -p .claude
-ln -sf ~/dotfiles/misc-configs/claude/CLAUDE.md .claude/CLAUDE.md
+ln -sf ~/dotfiles/misc-configs/agents/AGENTS.md .claude/CLAUDE.md
+
+# -- Claude Code --
 # Linked individually (not the whole dir) to allow third-party skills alongside ours.
 mkdir -p .claude/skills
 for skill in ~/dotfiles/misc-configs/claude/skills/*/; do

example-configs/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## CRITICAL REMINDERS
+
+- **ALWAYS** use the task runner (Taskfile) to execute any commands related to this project.
+
+## Key Technologies
+
+- **Task Runner**: Taskfile (Taskfile.yaml)
+
+## Environment Variables
+
+- When adding environment variables, prefix them with `MY_APP_` to avoid collisions with system and third-party variables.
+  - `MY_APP_` will be replaced with this project's actual prefix.
+  - Use `SCREAMING_SNAKE_CASE`: `MY_APP_DATABASE_URL`, not `my_app-databaseUrl`.

example-configs/CLAUDE.md

@@ -1,15 +1,13 @@
 # CLAUDE.md
 
-## CRITICAL REMINDERS
+<!--
+Claude Code reads CLAUDE.md and not AGENTS.md, so the shared instructions are
+pulled in with an import. Keep this file thin: everything that applies to every
+agent belongs in `AGENTS.md`, and only Claude-specific instructions go below.
+-->
 
-- **ALWAYS** use the task runner (Taskfile) to execute any commands related to this project.
+@AGENTS.md
 
-## Key Technologies
+## Claude Code
 
-- **Task Runner**: Taskfile (Taskfile.yaml)
-
-## Environment Variables
-
-- When adding environment variables, prefix them with `MY_APP_` to avoid collisions with system and third-party variables.
-  - `MY_APP_` will be replaced with this project's actual prefix.
-  - Use `SCREAMING_SNAKE_CASE`: `MY_APP_DATABASE_URL`, not `my_app-databaseUrl`.
+- Use plan mode for changes that span more than one package.

example-configs/README.md

@@ -8,3 +8,9 @@ Skills installed with the [`skills`](https://skills.sh) CLI are pinned in `skill
 npx skills update          # update all
 npx skills update <name>   # update one
 ```
+
+## Agent instructions
+
+Instructions shared by every agent go in `AGENTS.md`. `CLAUDE.md` pulls them in with an
+`@AGENTS.md` import and adds only the Claude-specific rules below it, so there's one copy
+of the shared rules instead of one per agent.

misc-configs/claude/CLAUDE.md → misc-configs/agents/AGENTS.md

@@ -1,5 +1,11 @@
 # Ground Rules
 
+<!--
+Agent-neutral ground rules (https://agents.md), shared by every coding agent.
+The bootstrap script symlinks this file to ~/.claude/CLAUDE.md, since Claude Code
+reads CLAUDE.md and not AGENTS.md.
+-->
+
 ## Attribution
 
 <!--
@@ -8,9 +14,9 @@
 > — IBM Training Manual, 1979
 -->
 
-- If a human committed it, it's their responsibility, not Claude's.
-- Claude is a collaborative partner tool, similar to a rubber duck that can code.
-- Never add Claude/Anthropic attribution (e.g. "Generated with Claude Code", "🤖", "Co-Authored-By") to any output: commits, PRs, issues, comments, or any other content.
+- If a human committed it, it's their responsibility, not the agent's.
+- An agent is a collaborative partner tool, similar to a rubber duck that can code.
+- Never add agent attribution (e.g. "Generated with Claude Code", "🤖", "Co-Authored-By") to any output: commits, PRs, issues, comments, or any other content.
 
 ## Tooling