Agent Plans Could Become The Next AGENTS.md
A new study of coding-agent plan files suggests an emerging layer between repository context and execution: explicit implementation plans that tell agents what to change, test, and validate.
Counting reads...
Agent Plans Could Become The Next AGENTS.md
Short Summary
AGENTS.md gave coding agents a place to find repository-specific instructions. A new study points to the next possible layer: persistent plan files that tell agents not only what the project is, but how a specific change should be executed.
The researchers examined 36,710 GitHub repositories and looked specifically for plan artifacts created for coding agents. They found 85 Markdown plan files across 10 repositories. That is a small sample, so this is not yet a standard.
But it is an important signal. Agentic development may be moving from context files toward execution specifications.
The rough progression looks like this:
- README.md -> context for humans
- AGENTS.md -> context for coding agents
- plan files -> task-specific execution instructions
What Happened
The exploratory study looked for persistent plan files used by agentic AI coding tools. The plan files described implementation steps, relevant files, testing requirements, validation instructions, and review context.
The study’s supplementary material reports 36,710 repositories in the search corpus, with 85 plan files identified across 10 repositories. That matters because the practice is visible, but still early.
This is not just academic curiosity. OpenAI’s Codex guidance describes PLANS.md as a way to give an agent a living implementation plan: a self-contained document that records the goal, current status, decisions, and validation criteria as work progresses.
GitHub’s own Copilot guidance also points in the same direction. Its research-plan-iterate workflow asks developers to gather context, ask Copilot for an implementation plan, iterate on the plan, and then move into implementation. GitHub’s implementation-planner custom agent is even more direct: it is designed to turn requirements into a concrete technical plan.
The pattern is becoming familiar: ask the agent to plan before it edits, then keep that plan visible enough for humans and other agents to review.
Why It Matters
AGENTS.md solved one problem: agents need repository context. They need to know commands, conventions, test expectations, coding style, and project-specific rules.
But repository context is not the same as task execution.
A good coding task often needs more specific instructions:
- which files are likely relevant,
- what behavior should change,
- what should not change,
- which edge cases matter,
- which tests must pass,
- what validation proves the change is done,
- what tradeoffs were already considered.
That is exactly the gap plan files can fill.
For humans, the plan becomes a review artifact. For agents, it becomes a working spec. For teams, it becomes a handoff surface when one agent, one developer, or one session cannot finish the whole change at once.
The Useful Version
The useful version is not “let the agent make a giant plan and blindly follow it.”
The useful version is smaller and more practical:
- Ask for a plan before large edits.
- Make the plan name the relevant files and commands.
- Review the plan before implementation.
- Keep it updated when reality changes.
- Treat validation as part of the plan, not an afterthought.
That turns an agent plan into something close to a lightweight technical spec.
It also makes coding-agent work less mysterious. Instead of asking “what did the agent do?”, reviewers can ask “did the agent follow the plan, and was the plan good?”
The Risk
Plans can also create false confidence.
A polished plan can still be wrong. It can miss hidden coupling, misunderstand requirements, skip migration details, or name tests that do not actually cover the risky behavior.
There is also a maintenance problem. If teams start committing plan files, they need a rule for what persists. Some plans are useful only during implementation. Others explain decisions that future maintainers should keep.
If every agent task leaves behind stale plan documents, repositories become noisier, not clearer.
What To Watch
The next question is whether plan files become a convention like AGENTS.md or remain a tool-specific habit.
For that to happen, teams will need answers to practical questions:
- Should plans live in
docs/,.agents/,.codex/, or temporary task folders? - Should plans be committed, attached to pull requests, or discarded after merge?
- What minimum fields should every plan include?
- Who owns plan accuracy: the agent, the developer, or the reviewer?
- Should CI validate plan checklists against real commands?
The study is early, but the direction is worth watching.
Agents are no longer only reading repository instructions. They are starting to work from explicit execution specs. That may become one of the quiet infrastructure layers behind reliable AI-assisted software development.