AGENTS.md cross-tool agent instructions
Header
Use the pencil to edit title, status, priority, and owner. Changing status auto-prepends a changelog entry.
Why
Outside contributors using non-Claude AI tools (Cursor, Codex CLI, Aider,
Continue) won't auto-load Josh's project guidance — those tools look forAGENTS.md, the cross-tool convention. Today everything lives inCLAUDE.md, which only Claude Code reads. To keep contribution quality
high regardless of which agent a contributor uses, both filenames must
resolve to the same content. Low priority — only matters once the repo
is public and outside contributions land.
User stories
As an outside contributor using Cursor, I want my agent to auto-load Josh's working rules and critical rules so that my PRs follow the same standards as Claude Code contributions.
As a maintainer, I want one canonical source of agent guidance so that rules don't drift between two files.
Acceptance criteria (EARS)
- When the repo is cloned, both `AGENTS.md` and `CLAUDE.md` shall exist at the project root.
- When either file is read, it shall resolve to identical content (one is the canonical regular file; the other is a symlink to it).
- When the canonical file is edited, both filenames shall reflect the change without a second edit.
- When `CONTRIBUTING.md` exists (separate spec), it shall direct contributors to point their AI tool at AGENTS.md.
Success determiner
Command
test -e AGENTS.md && test -e CLAUDE.md && diff -q AGENTS.md CLAUDE.md > /dev/null
Expect
Direction (which file is canonical, which is the symlink) is an implementation choice — see `plan`. The determiner is direction-agnostic.
Clarifications needed
None.
Out of scope
- Writing distinct AGENTS.md content separate from CLAUDE.md — they must be one file via symlink.
- CONTRIBUTING.md itself (tracked in a separate launch-readiness spec when written).
- Per-tool config files (`.cursorrules`, `.aider.conf.yml`, etc.) — AGENTS.md is the convergence point all modern tools support.
Dependencies
None.
Plan
Direction. Make AGENTS.md the canonical regular file and CLAUDE.md
the symlink (ln -s AGENTS.md CLAUDE.md). Reasoning: AGENTS.md is the
vendor-neutral convergence point (Cursor, Codex, Aider, Continue all read
it as of 2025); CLAUDE.md is Claude Code's tool-specific path. The
vendor-neutral name should be the durable one.
Git handling. Git tracks symlinks natively as long as core.symlinks=true
(default on macOS/Linux; Windows users with WSL or modern Git for Windows are
fine). No .gitattributes change required.
Tooling check. Verify Claude Code resolves CLAUDE.md symlinks to read
the target — should "just work" since the OS resolves the symlink before the
reader sees it, but worth a smoke test before flipping status to verified.
Order of operations at flip time:
1. git mv CLAUDE.md AGENTS.md
2. ln -s AGENTS.md CLAUDE.md
3. git add CLAUDE.md (git stores it as a symlink blob)
4. Smoke test: cat CLAUDE.md should print AGENTS.md contents.
Tasks
0 of 4 done.
- t1 Decide canonical direction (recommendation in plan — AGENTS.md as the regular file).
- t2 Rename CLAUDE.md → AGENTS.md and create CLAUDE.md as a symlink.
- t3 Smoke test that Claude Code, Cursor, and at least one other AGENTS.md-aware tool read the file correctly.
- t4 Reference AGENTS.md (not CLAUDE.md) in CONTRIBUTING.md when that doc is written.
Changelog
No history yet.