AGENTS.md vs ota.yaml: Instructions vs Readiness Contracts for AI Agents

AGENTS.md is a useful idea. It gives AI agents a place to look for repo-specific instructions: how the project is organized, what conventions to follow, what files to avoid, and what commands may be useful.

That is valuable. The problem starts when teams expect AGENTS.md to carry the full weight of repo readiness.

An instruction file can guide an agent. It can explain intent. It can warn against risky changes. But it is still prose.

It cannot prove the repo is ready. It cannot validate that setup still works. It cannot guarantee that a command exists. It cannot make CI, humans, and agents share the same execution path.

That is the difference between instructions and readiness contracts.

An AGENTS.md file is best at giving agents human-written context. For example, it can explain:

• how the repo is structured
• which coding conventions to follow
• what areas need extra caution
• how to write tests
• what files are generated
• what commands are usually useful
• how to summarize changes

This kind of guidance helps agents behave less like generic code generators and more like collaborators inside a specific repo.

A good AGENTS.md can reduce noise. It can tell an agent not to edit generated files, not to touch production config, or not to run destructive database commands. That matters.

But AGENTS.md works best as an instruction layer, not as the repo's execution authority.

The limitation is simple: prose can drift. An AGENTS.md file may say:

Run the tests before finishing.

But which tests?

Unit tests? Integration tests? Type checks? Lint? Build? The same command used locally, or the stricter command used in CI?

It may say:

Do not edit generated files.

But which paths are generated? Are they listed explicitly? Are they enforced anywhere?

It may say:

Start the database before running integration tests.

But how should the database be started? Which version? Which port? How does the agent know it is ready?

These instructions are useful, but they are not executable by themselves.

They depend on the agent interpreting prose correctly and on the prose staying current as the repo changes.

That is risky when the agent is expected to run commands, edit files, and verify work.

A readiness contract turns repo expectations into structured, reviewable rules. Instead of only saying what an agent should generally do, the repo declares what it needs and how work should run.

A contract can describe:

• required runtimes and tools
• setup tasks
• declared commands
• task dependencies
• safe tasks for agents
• protected paths
• verification steps after changes
• expected execution mode

That changes the operating model. The agent no longer has to infer the repo's setup path from scattered prose, package scripts, CI files, and README notes. The repo has a declared source for readiness and execution.

This is why Ota uses ota.yaml.

Ota's docs describe a starter ota.yaml as a contract that names the repo, declares core runtime and tools, defines safe tasks and verification tasks, and gives agents a deterministic entrypoint.

That is a different category from instruction prose.

Imagine a repo with all three of these surfaces:

• AGENTS.md says: "Run the tests before handoff."
• the README says: "Use make check."
• CI runs pnpm lint && pnpm test:ci.

An agent now has three overlapping signals and no clear authority.

It can read the repo. It can inspect scripts. It can guess that make check wraps the right commands. But it still has to infer:

• whether make check is current
• whether CI is the stricter path
• whether setup must run first
• whether lint is part of the verification contract
• whether the repo expects pnpm, npm, or something else entirely

That is where instruction files stop helping on their own.

AGENTS.md can still say:

• Prefer small diffs.
• Do not touch generated files.
• Explain your changes clearly.

But the repo still needs an execution authority that can say:

• setup is required before test
• build must run before test
• safe tasks are setup, build, test
• verify_after_changes is build and test
• these paths are protected

That is the boundary Ota is trying to make explicit.

This is the simplest way to understand the difference:

• AGENTS.md tells the agent how to behave.
• ota.yaml tells the repo how execution is governed.

Those two things can work together.

AGENTS.md can say:

• Prefer small changes.
• Explain what you changed.
• Do not edit generated files manually.
• Run the appropriate verification task before handoff.

An Ota contract can define:

• The setup task is safe.
• The test task depends on setup.
• The build task must run before test.
• The agent may run setup, build, and test.
• The agent should verify changes with build and test.
• These paths are protected.

The instruction file provides context. The readiness contract provides structure. One is guidance. The other is an operating boundary.

AI agents are increasingly expected to do more than suggest edits. They inspect a repo, choose commands, change files, run tests, interpret failures, and report whether work is complete.

That means they need more than "please be careful." They need the repo to expose safe, finite, verifiable paths.

Without that, an agent may run a helpful-looking command that is not the real verification path. It may skip setup. It may edit a protected file. It may treat a missing tool as a code failure. It may report success after passing a small local check while CI would still fail.

These are not always model failures. They are governance failures. The repo did not make the safe path explicit enough.

Ota is software execution governance for humans and AI agents. It helps a repo declare what it needs, how it should be prepared, what can be safely executed, and how work should be verified.

With Ota, humans, CI, automation, and AI agents can work from the same repo-level contract instead of guessing from READMEs, scripts, CI files, and scattered configuration.

A typical Ota loop looks like this:

• ota doctor checks whether the repo is ready and points to the blocker.
• ota validate checks whether the contract itself is valid.
• ota up prepares the repo from the contract.
• ota run <task> runs declared work through the contract.

The value is not just command execution. The value is that execution becomes explicit, bounded, and reviewable.

This should not be framed as AGENTS.md versus Ota in a winner-takes-all sense. The better model is both.

Use AGENTS.md for repo-specific guidance, collaboration style, coding conventions, and human-readable cautions.

Use Ota for readiness, setup, execution, verification, task boundaries, and agent-safe operations.

That gives you a cleaner split:

• AGENTS.md: human-readable instructions for how an agent should behave.
• Ota: machine-readable execution governance for what the repo allows, requires, and verifies.

When those two layers agree, agents get both context and structure. They know how to behave, and they know what the repo is prepared to run.

Use AGENTS.md by itself when the repo mainly needs behavioral guidance:

• coding style
• review expectations
• generated-file warnings
• collaboration conventions

Use Ota when the repo needs execution truth:

• setup must be reproducible
• safe tasks must be explicit
• verification must be deterministic
• CI and local execution should share one path
• AI agents should not guess which command counts as done

That is the real decision boundary.

AGENTS.md is useful, but it should not be asked to do everything.

It can explain how an agent should work inside a repo. It can capture conventions, preferences, and warnings.

But repo execution needs more than instructions.

It needs a readiness contract that can declare setup, safe tasks, protected paths, verification steps, and execution rules in a form humans, CI, and agents can share.

That is where Ota fits.

Instructions help agents understand the repo.

Readiness contracts help the repo govern execution.