AGENTS.md tells AI how to work. AGENTOWNERS tells it where to stop.

The pull request looks harmless until you read the file list.

A coding agent opened it overnight. Two files changed. The first is a typo fix in docs/getting-started.md, the kind of edit you'd merge without thinking. The second is src/auth/session.ts, the file that decides when a user is still logged in.

Same branch. Same author. One commit message that reads like a human wrote it, because the agent was told to write commit messages like a human.

Your AGENTS.md did its job. The agent was polite. It used the right test command, kept its diff small, wrote a clear summary, and tagged the PR the way the instructions asked. Nothing in that file was violated.

And none of it answers the only question that matters at 9am: should this repository have let an AI agent walk into the auth code at all?

That gap is the whole story. A handbook is not a door.

A handbook is not a door

AGENTS.md earns its keep, and the reason is simple. It gives an agent the context a new contributor would otherwise have to ask for: how to build, how to test, what conventions to follow, what to avoid. GitHub now documents repository custom instructions and notes that the nearest AGENTS.md in the directory tree takes precedence. It's a behavior file. It shapes how the work gets done once the contributor is already inside.

What it does not do is decide who gets inside, or which rooms stay locked once they are.

That distinction is easy to miss because both things feel like "the rules." But they answer different questions. The handbook tells a contributor how the place runs. The door decides whether they're allowed past the lobby, and which rooms need a key. A perfectly well-mannered agent can still walk straight into money, auth, secrets, or your deploy pipeline, and "it read the handbook" is not a reason to hand it the keys.

Put it on a sticky note: the instruction file is the handbook. The ownership file is the door.

This is the line a new open-source project, AGENTOWNERS, draws in one sentence: "AGENTS.md tells agents how to work. AGENTOWNERS defines what agents are allowed to do."

Why CODEOWNERS is the right metaphor

We already built a version of this for humans, and we built it into the repo.

CODEOWNERS is a plain file that names the individuals or teams responsible for parts of a codebase. Touch payments/, the payments team gets pulled in. The ownership lives next to the code, it's versioned with the code, and it survives whoever happened to be in the room when the convention was set. Nobody has to remember a Slack norm. The repo remembers who holds which key.

AI changes two things about that picture.

The contributor at the door isn't a person you onboarded. It's github-copilot[bot], or a cloud coding agent you kicked off from an issue, or a fleet of bots, and GitHub's own docs now describe starting Copilot coding-agent sessions as a normal part of issue and PR flow. These are first-class participants now. They open PRs, comment on issues, and trigger automation, often while you sleep.

And the traffic is different. Mike McQuaid, who leads Homebrew, put the maintainer's new job bluntly in a New Scientist interview: "The skill right now is being able to skim and spot nonsense while investing as little of your own time as you possibly can." That's not a plea for better agent manners. It's a plea for a door that does some of the screening before you ever look up. CODEOWNERS told you who holds the key. The open question is what checks the badge when the visitor is a bot working through the night.

What AGENTOWNERS is trying to encode

Strip AGENTOWNERS down and it's an attempt to make six questions answerable inside the repo, automatically, the moment an AI-authored PR shows up at the door:

• Who's knocking? It detects AI-agent PRs from actor names, commit signatures, and body patterns, so the repo isn't guessing whether a human or a bot just walked up.
• Where are they trying to go? It checks the changed files against policy.
• Is that room open? It keeps dangerous rooms such as workflows, secrets, and infrastructure locked by default.
• Does someone need to unlock it? Risky moves require a human to turn the key instead of merging quietly.
• Who holds that key? It can route to a named team and label the contribution, so an AI-authored change is visibly an AI-authored change.
• Did anyone sign the guestbook? It posts a verdict as a sticky PR comment and can fail CI on a blocked action, so there's a record instead of a vibe.

The quick start is a single file, .github/AGENTOWNERS.yml, with defaults that read like a posted house rule: known_agent: require_approval, unknown_agent: require_approval, docs_only: allow, workflows: block, secrets: block.

Run that against our overnight PR and the doc typo walks through the open door as docs_only. The src/auth/session.ts edit hits a locked one. In the project's own example, a change to that file by github-copilot[bot] comes back as requires approval, high risk score, required reviewer @maintainers/security, with labels ai-agent, needs-human-review, and risk-high. Same PR, two files, two different doors, decided by the repo instead of by whoever happened to be holding it open.

(The project is young and moving fast. Its README frames it as an early take, and a recent commit switched its own publishing over to GitHub OIDC and provenance. Treat the file format as a starting point, not gospel. The idea underneath it is the durable part.)

The repo door policy

You don't need to adopt any one tool to get the benefit. You need to write the door policy down somewhere the repo can act on it. Here's the shape, in plain language. Copy it, fill in the right side, and you have a door policy for one repo.

Scroll sideways to see all 3 columns.

Field	What it answers	Example for one repo
Who's at the door	Which actors count as agents	github-copilot[bot], *-agent[bot], signed commits matching the agent key
Open rooms	Where an agent may go unescorted	Open PRs, comment, edit docs/**, edit tests under **/__tests__/**
Locked rooms	Doors that never open on agent authority	.github/workflows/**, **/secrets/**, infra/**, src/auth/**, **/billing/**
Key required	What forces a human to unlock	Any change to a locked room, any new dependency, risk score above your line
Keyholder	Who holds the key for each locked room	@maintainers/security for auth, @payments for billing
Guestbook entry	How the visit shows up	ai-agent, needs-human-review, risk-high, plus a sticky verdict comment
Alarm behavior	What happens when a locked door is tried	Fail the check; the PR can't merge until a human turns the key
Logbook location	Where the receipt lives	The verdict comment: what was checked, what was flagged, who unlocked it
Re-key date	When the locks get changed	Re-read on a set date so the policy doesn't quietly rot

Two fields do most of the work, and they're the two people skip. Locked rooms is where you say the quiet part out loud: these directories are not open to autonomous edits, full stop. And the re-key date is what keeps this from becoming the next stale config nobody trusts. A door policy with no re-key date is a guess with good intentions.

Where the door sits relative to everything else

If you've read us before, this sits in front of a few pieces, not on top of them.

A sandbox contract is about runtime: what an agent-written script can call and touch once it actually executes. The dependency exception lane is about what you do when AI drama lands on a package you rely on. And once a change is inside, review staffing sorts out who looks at it.

The door policy is upstream of all three. It governs the act of letting the change in at all, before anyone looks at the diff, before anything runs, before the dependency question even comes up. The sandbox decides what runs. The reviewers decide who reads it. The door decides whether the repo opens for the change in the first place. They stack. None of them replaces the lock on the door.

Bring one repo

Don't write an agent governance framework. Write one door policy for one repo before your next AI-authored PR gets merge rights.

Pick the repo where a bad merge would actually hurt. List its locked rooms first, because that's the part you already know in your gut. Name the keyholder for each one. Decide what forces a human to unlock and what gets to walk straight through. Put a re-key date on it.

Then, the next time a polite agent badges in overnight with a clean diff that quietly reaches for src/auth/session.ts, the door is already locked, and you find out at review time instead of in the incident channel.

If you want a hand turning that into something enforceable, we'll help you draft the door policy for one repo, with the controls in AI workflow controls and the wiring in process automation.