Skip to content

Adopt AGENTS.md as canonical instructions file, symlink CLAUDE.md to it #132

Description

@YanivZalach

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:

  1. git mv CLAUDE.md AGENTS.md (root) — content unchanged.
  2. Create CLAUDE.md as a symlink to AGENTS.md in the same directory.
  3. Repeat for frontend/CLAUDE.mdfrontend/AGENTS.md + symlink.
  4. 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.
  5. 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.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationready-for-humanRequires human implementation

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions