agent-instructionslisted

# Agent Instructions Most AI coding tools read project guidance from a file in the repo — historically each looked in a *different* place (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, …). Copy the same guidance into each one and the copies **drift**: a command changes in one file and the others keep telling agents the old way. The fix is one **canonical** source plus thin tool-specific **shims** (which include the canonical file). Keep all durable guidance in the canonical file; keep only genuine tool-specific quirks in a tool's own file. The good news: `AGENTS.md` is now read by nearly every major tool — **including GitHub Copilot** — so the "one canonical file" ideal is finally achievable without a per-tool copy. ## The canonical file: `AGENTS.md` `AGENTS.md` is the cross-tool standard — a plain-Markdown file at the repo root, read natively by a growing set of agents and editors (Codex, Cursor, Gemini CLI, and GitHub Copilot). Make it the **single source of truth** for everything durable and tool-neutral: - **What the project is** — one-paragraph purpose, the stack, where the important code lives. - **How to build, test, validate, and run** — the exact commands an agent should use (and which one gates a PR). Be specific; agents run these verbatim. - **Conventions** — code style, naming, commit/PR format, branch model, "definition of done". - **Do / don't** — guardrails (never hand-edit generated files, never push to `main`, secret handling) and the