Motivation
CLAUDE.md content is currently Claude Code-only. Other AI coding tools (Codex, Cursor, OpenCode, etc.) follow the emerging AGENTS.md convention and won't pick up any of these instructions.
Prior art: pingdotgg/t3code makes AGENTS.md the canonical instructions file and turns CLAUDE.md into a plain filesystem symlink to it (ln -s AGENTS.md CLAUDE.md) — confirmed via the GitHub API (CLAUDE.md blob type symlink, target AGENTS.md). They apply the same trick to skill directories (.claude/skills → symlink → ../.agents/skills), but this ticket is scoped to the instructions files only.
Proposed approach
Apply the same pattern to every CLAUDE.md in this repo (currently two: root and frontend/), so Claude ends up referencing only AGENTS.md files:
git mv CLAUDE.md AGENTS.md (root) — content unchanged.
- Create
CLAUDE.md as a symlink to AGENTS.md in the same directory.
- Repeat for
frontend/CLAUDE.md → frontend/AGENTS.md + symlink.
- Update the root
AGENTS.md's cross-reference to the frontend file (currently frontend/CLAUDE.md) to point at frontend/AGENTS.md, since that's now the canonical file.
CLAUDE.md becomes a pure compatibility shim from here on — edit AGENTS.md, never the symlink.
Flagged before writing this ticket
frontend/CLAUDE.md currently pulls in PHILOSOPHY.md via @PHILOSOPHY.md, which is Claude Code's native @file import syntax. Other AGENTS.md-reading tools aren't guaranteed to support that syntax — it may render as inert text for them. Needs a decision during implementation: inline PHILOSOPHY.md's content directly into frontend/AGENTS.md, or accept that line stays Claude-only for now and note it as a known gap.
- Checked: no Dockerfile or CI workflow reads
CLAUDE.md directly, and all workflows run on ubuntu-latest (symlink-safe), so the rename doesn't touch build/deploy.
- Git needs
core.symlinks=true to commit an actual symlink rather than a text file containing the path — default on macOS/Linux (this repo's dev environment); flag if a contributor is on Windows.
- The
ready-for-human / ready-for-agent triage labels referenced in docs/agents/triage-labels.md don't exist as real GitHub labels in this repo yet — filed with documentation instead.
Scope
Root and frontend/ only — the two CLAUDE.md files that currently exist. Not extending to per-tool skill-directory symlinks (.claude/skills etc.) — separate concern if wanted later.
Motivation
CLAUDE.md content is currently Claude Code-only. Other AI coding tools (Codex, Cursor, OpenCode, etc.) follow the emerging
AGENTS.mdconvention and won't pick up any of these instructions.Prior art:
pingdotgg/t3codemakesAGENTS.mdthe canonical instructions file and turnsCLAUDE.mdinto a plain filesystem symlink to it (ln -s AGENTS.md CLAUDE.md) — confirmed via the GitHub API (CLAUDE.mdblob typesymlink, targetAGENTS.md). They apply the same trick to skill directories (.claude/skills→ symlink →../.agents/skills), but this ticket is scoped to the instructions files only.Proposed approach
Apply the same pattern to every
CLAUDE.mdin this repo (currently two: root andfrontend/), so Claude ends up referencing onlyAGENTS.mdfiles:git mv CLAUDE.md AGENTS.md(root) — content unchanged.CLAUDE.mdas a symlink toAGENTS.mdin the same directory.frontend/CLAUDE.md→frontend/AGENTS.md+ symlink.AGENTS.md's cross-reference to the frontend file (currentlyfrontend/CLAUDE.md) to point atfrontend/AGENTS.md, since that's now the canonical file.CLAUDE.mdbecomes a pure compatibility shim from here on — editAGENTS.md, never the symlink.Flagged before writing this ticket
frontend/CLAUDE.mdcurrently pulls inPHILOSOPHY.mdvia@PHILOSOPHY.md, which is Claude Code's native@fileimport syntax. OtherAGENTS.md-reading tools aren't guaranteed to support that syntax — it may render as inert text for them. Needs a decision during implementation: inlinePHILOSOPHY.md's content directly intofrontend/AGENTS.md, or accept that line stays Claude-only for now and note it as a known gap.CLAUDE.mddirectly, and all workflows run onubuntu-latest(symlink-safe), so the rename doesn't touch build/deploy.core.symlinks=trueto commit an actual symlink rather than a text file containing the path — default on macOS/Linux (this repo's dev environment); flag if a contributor is on Windows.ready-for-human/ready-for-agenttriage labels referenced indocs/agents/triage-labels.mddon't exist as real GitHub labels in this repo yet — filed withdocumentationinstead.Scope
Root and
frontend/only — the twoCLAUDE.mdfiles that currently exist. Not extending to per-tool skill-directory symlinks (.claude/skillsetc.) — separate concern if wanted later.