AGENTS.md: the file that briefs coding agents

A briefing for agents

Human contributors read a README and learn the rest by asking. An agent cannot ask a colleague, so projects write the missing context down: how to build and test, which conventions to follow, which directories to leave alone. AGENTS.md is the common name for that file.

Why DevFlow requires it

When you start planning, DevFlow creates the task's worktree and then looks for it. A legacy CLAUDE.md also counts.

If neither file exists, the task fails before the planner spends any tokens.

You do not have to write it from scratch. When a repository is onboarded, the repo scanner proposes one, and you can approve it, edit it or skip it.

What belongs in it

Useful entries are the ones an agent cannot infer quickly from the code. Think of the commands that build and test the project, architecture rules, naming habits and things that must never be done. Each rule should be short, specific and easy to check.

The gate commands themselves are configured separately in DevFlow. The briefing can still name them, so every role sees how the project is meant to be checked.

Where it lives

It lives next to the code, so it is versioned and reviewed like code. A change to the rules goes through review like any other change, and the history shows who changed what.

Readiness

The workspace readiness check reports, per repository, whether a briefing is present, at info level. Planning still refuses to start without it.