What Belongs in AGENTS.md vs ota.yaml

AGENTS.md and ota.yaml are not interchangeable.

They are both useful, but they should not carry the same kind of truth.

When teams blur the boundary, one of two things usually happens:

• AGENTS.md turns into drifting operational prose that agents still have to interpret
• ota.yaml gets treated like a human instructions document instead of an execution contract

The stronger model is simpler:

• AGENTS.md should explain how an agent is expected to behave in the repo
• ota.yaml should declare how the repo is meant to be prepared, verified, and run

That separation makes both layers more useful.

AGENTS.md is an instruction surface.

It is the right place for guidance like:

• coding conventions
• review posture
• change hygiene
• sensitive directories
• generated files
• expectations for summaries and handoff
• when to escalate instead of guessing

This is repo-specific behavior guidance.

For example, AGENTS.md can say things like:

• prefer small diffs
• do not edit generated files manually
• treat deployment config as protected
• explain why a migration was needed
• stop and ask before touching billing logic

That kind of guidance matters, but it is not the same thing as execution truth.

It tells the agent how to behave, not what the repo operationally requires.

ota.yaml is an execution contract.

It should hold the parts of repo truth that need to be explicit, repeatable, and machine-readable.

That includes:

• setup and dependency hydration paths
• required tools and runtimes
• environment requirements
• services and readiness
• executable tasks
• verification workflows
• safe task boundaries
• protected paths
• runtime proof and receipts

This is where a repo declares:

• what needs to happen before work starts
• what task is canonical
• what workflow proves the repo is ready
• what an agent may safely run
• what evidence should exist when the run completes

That is not just useful for agents. It is useful for humans and CI too.

The easiest way to think about it is this:

AGENTS.md says how to work in the repo.

ota.yaml says how the repo works.

That sounds small, but it is a strong boundary.

It prevents guidance from turning into stale operational prose, and it prevents execution contracts from filling up with subjective contributor advice.

Here is the kind of thing that belongs in AGENTS.md:

# AGENTS.md

- Prefer small diffs.
- Do not edit generated OpenAPI clients manually.
- Treat `infra/` and `.github/workflows/` as protected unless the task explicitly requires it.
- Run the declared verification path before handoff.
- Escalate before changing payment or auth flows.

Here is the kind of thing that belongs in ota.yaml:

version: 1project:  name: billing-api tasks:  setup:    prepare:      kind: dependency_hydration      medium: package_dependencies      source:        kind: node_package_manager        manager: pnpm        mode: install   test:    command:      exe: pnpm      args: [test]    depends_on:      - setup workflows:  verify:    setup:      task: setup    run:      task: test agent:  safe_tasks:    - setup    - test  protected_paths:    - infra    - .github/workflows  verify_after_changes:    - test

The difference is clear:

• AGENTS.md gives guidance the agent should understand
• ota.yaml gives execution truth the repo can enforce and verify

The most common mistake is putting operational instructions into prose and assuming that is enough.

For example, an AGENTS.md file might say:

Run the tests before finishing.

That sounds reasonable, but it leaves a lot unresolved:

• which tests
• in which mode
• after which setup
• with which services running
• whether CI uses a stricter path
• what counts as successful verification

Likewise, a repo may say:

Start Postgres before running integration tests.

That still leaves the agent to infer:

• how Postgres should start
• which version or image is expected
• which port or service name matters
• how readiness is determined

Those are contract questions, not guidance questions.

Coding agents are increasingly expected to do more than edit files.

They inspect repos, choose commands, prepare environments, run tasks, interpret failures, and report whether work is complete.

That means they need two different kinds of help:

1. Guidance about how to behave responsibly in the repo.
2. Contract truth about what the repo needs and how execution should work.

AGENTS.md helps with the first.

Ota helps with the second.

When both are present and each does its own job, the agent has a much stronger operating environment:

• it knows what is sensitive
• it knows what is safe
• it knows how to prepare the repo
• it knows how to verify completion
• it has a clearer boundary between code failure, setup failure, and contract drift

This should not be framed as a winner-takes-all choice.

The strongest repos use both:

• AGENTS.md for human-written guidance and caution
• ota.yaml for machine-readable readiness and execution governance

That combination gives agents both context and structure.

They know how they are expected to behave, and they know what the repo is actually prepared to run.

If you put everything in AGENTS.md, agents still have to interpret operational prose.

If you try to use ota.yaml as a contributor style guide, you weaken the contract.

The stronger split is simple:

• put guidance in AGENTS.md
• put execution truth in ota.yaml

That is how the two become complementary instead of competing.