SOTA Watch #1 — AGENTS.md and the Rise of the Agent-Readable Repo

Each week we take one move in the AI ecosystem and analyze it on its merits: what it is, what it actually changes, and what we'd do about it. No hype, no doom — just the state of the art, watched closely.

What happened. A convention has been spreading quietly through the software ecosystem: a file named AGENTS.md at the root of a repository, written not for human newcomers but for coding agents. It emerged from the agent-tooling world as an open, vendor-neutral answer to a very practical problem — every agent vendor was inventing its own configuration file, and every repo that used two tools had to say everything twice. The pattern has since been adopted well beyond its origin. The standard's own site lists more than twenty tools that read the file natively — OpenAI's Codex, Google's Jules and Gemini CLI, Cursor, Cognition's Devin and Windsurf, GitHub Copilot's coding agent, VS Code, Zed, Warp, JetBrains' Junie, Aider, Amp, and Factory among them. Even tools that keep a richer native file — Claude Code's CLAUDE.md, Gemini's GEMINI.md — bridge to it with a one-line import. And its website-side sibling — llms.txt, a manifest telling AI crawlers what a site is — follows the same logic for the open web.

What's actually in the file. Nothing exotic — and that's the point. A typical AGENTS.md tells an agent the four things it cannot safely guess: how to build and test the project (the exact commands), what the code conventions are, where the boundaries sit (what it may touch and what it must never), and where truth lives when documents disagree. The README answers what is this project? — AGENTS.md answers how do I work here without breaking things? For the agent, that turns a cold start from an archaeology dig into a briefing. For the person running the CLI, it means the working rules are written once and every tool obeys the same ones — switch from Codex to Cursor mid-project and your discipline travels with you, instead of living in per-vendor copies that drift apart.

What it actually changes. More than it appears. A convention like this is the ecosystem admitting, in file-naming form, that agents are now a first-class audience — for your codebase and for your website. Three consequences follow:

1. The onboarding document is being split. README for humans, AGENTS.md for the workforce that starts cold on every session. Teams that treat the two as the same document will serve both audiences badly: humans need narrative; agents need contracts — what the rules are, where truth lives, what they may touch.
2. Vendor neutrality is becoming the default posture. The whole point of a shared convention is that you write your working rules once and any agent — today's or next year's — reads them. Teams that instead pour their process into one vendor's proprietary config are taking on a quiet dependency they will feel the day they switch tools or add a second one.
3. It rewards teams whose process is actually written down. An agent-readable repo presumes there is something coherent to read: rules, roles, task shapes, definitions of done. The convention exposes — instantly — which teams have an operating discipline and which have tribal knowledge.

The honest caveat. A root file is a doorway, not a method. Nothing about naming a file AGENTS.md makes its contents good, and an empty convention adopted for fashion changes nothing. The signal here is directional: the ecosystem is converging on agent-legibility as a property of serious repositories, the way CI-presence became one a decade ago.

What we'd do with it. Treat agent-legibility as a design requirement, not a bolt-on. We scaffold every project with a vendor-neutral contract at the root and thin per-vendor adapters beside it — one truth, many agents — plus machine-readable governance and a state folder any cold-starting agent can orient on. We published exactly how, this week — Your Repo Is the Prompt Now walks the whole shape — and the scaffold itself is free to clone: github.com/SynaptixLabs/scaffold. The test we hold ourselves to applies to any repo you own: swap the agent, keep the project.

That's the watch. Same time next week.