One rules file for every agent on the team

[braianxde]

We drive this repo with several different AI agents and they don't all read the same file, so rules drift and each of us gets a different answer. This makes AGENTS.md the one file anyone edits, and gets it in front of every tool.

What each agent needs to do to pick up the rules

Agent	What it reads	What you have to do
Claude Code	CLAUDE.md → already one line, @AGENTS.md	Nothing. Works on clone.
opencode	AGENTS.md directly, in preference to CLAUDE.md	Nothing. Works on clone.
Codex	AGENTS.md directly	Nothing. Works on clone.
Copilot coding agent / code review	AGENTS.md directly	Nothing. Works on clone.
Copilot in VS Code	.github/copilot-instructions.md, auto-detected	Nothing. Optionally flip the experimental AGENTS.md setting to read the source instead.
Copilot for Xcode	.github/copilot-instructions.md	Nothing. Same generated file.
Cursor, Cline, Gemini CLI, Continue	Their own directory formats	Not generated today — instructions for adding a target are in docs/ai-agents.md.

Most of them read AGENTS.md already. Copilot's editor integrations are the exception — AGENTS.md support in VS Code is experimental and off by default, while .github/copilot-instructions.md is picked up automatically.

So the whole gap is one file, generated verbatim from AGENTS.md with a do-not-edit header.

Changing a rule

# edit AGENTS.md, then:
bash tool/check_agent_rules_sync.sh --fix

Without --fix it verifies and fails on drift, so Copilot users can't quietly end up on different rules. It's the sixth gate in tool/, same shape as check_brace_style.sh.

Shared skills

.claude/skills/ is read natively by both Claude Code and opencode — opencode loads it alongside its own .opencode/skills/. Copilot's agent mode reads SKILL.md too. One directory, no sync, nothing to configure. If your agent supports skills but looks elsewhere, point it at that path rather than copying.

• open-pr — branch off develop, the checks that must pass first, what the description should say, open as draft
• merge-pr — rebase first, --force-with-lease, and when rebase is the wrong tool
• review-pr — what a reviewer checks, ordered by consequence: wallet safety, then correctness the tests miss, then accessibility, then the design system

One thing to agree on

merge-pr writes down rebase-first as the default, and that's a change: #217 through #221 all landed as merge commits, and all three merge methods are still enabled on the repo. The convention is what enforces this, not a setting — so if we'd rather flip the repo settings too, or don't want rebase-first at all, this is the PR to say so on.

Deliberately not here

• No rules-sync package. Ruler, rulesync and AgentSync all solve this properly, and all are the wrong size for generating one file in a repo with no JS toolchain. docs/ai-agents.md records where that tips: if we get past two or three generated targets, switch.
• No symlink. A checkout without core.symlinks turns it into a text file containing a path, which Copilot reads as a literal string and applies no rules at all. A copy plus a failing check is louder.
• GSD skills not vendored. 59 of its 69 skills load workflows from $HOME/.claude/gsd-core/, so copying them here gives everyone else skills that reference files they don't have. Anyone who wants that workflow installs it themselves.
• Nothing for Xcode's built-in Coding Intelligence — it has no repo-level rules convention, so there's no file to generate. Copilot for Xcode is covered by the generated file.

Verification

All six gates pass, flutter analyze clean, 1000 tests passing. The sync gate was confirmed both ways: it fails on drift and --fix repairs it.