Agent-Ready Repositories

“Agent-ready” is an overloaded phrase already. Sometimes it means a repository has a CLAUDE.md, AGENTS.md, or similar instruction file. Sometimes it means the tests pass. Sometimes it means a developer had one successful session with a coding agent and declared victory.

That is too weak.

A repository is agent-ready when a human-supervised agent can safely understand, modify, verify, and explain a bounded change without relying on hidden human context.

The instruction file matters, but it is only one artifact. The deeper question is whether the repository is agent-operable.

Context Is Not a Prompt

A prompt says what the user wants now. Repository context says what must remain true.

Useful context includes:

• the purpose of the repository;
• owned and non-owned boundaries;
• build, test, lint, and typecheck commands;
• architecture notes;
• important invariants;
• forbidden paths or change classes;
• deployment and rollback notes;
• known flaky tests or environmental prerequisites;
• review expectations.

This context should be explicit because agents are good at local plausibility. They can infer a style from nearby files, but inference is not governance. If a repository has an invariant, write it down. If a command must be run before committing, write it down. If a directory is generated, write it down.

The Minimum Artifact Set

For Level 2 maturity, I would expect at least:

• AGENTS.md or CLAUDE.md;
• documented build and test commands;
• issue template with intent, non-goals, risk, and testing expectations;
• PR template with validation, risk, rollback, and issue linkage;
• CODEOWNERS or equivalent review ownership;
• working CI;
• repo-local architecture notes;
• repo-local invariants;
• deployment and rollback notes when the repo deploys anything.

The exact filenames matter less than the discoverability and consistency. The agent must be able to find the information without guessing. The human reviewer must be able to verify that the agent used it.

Verification Is Part of Readiness

An untestable repository is not agent-ready. It may still be useful for exploration, documentation, or local assistance, but delegation should stay narrow.

Verification strength is not binary. A repository can have unit tests but no integration tests. It can have typechecks but no contract tests. It can have static analysis but no realistic local environment. The maturity question is: what kind of changes can be trusted under the available verification?

For example:

• documentation edits may need link checks and build validation;
• test-only changes may need deterministic test execution;
• service changes may need unit, integration, and contract coverage;
• infrastructure changes need formatting, validation, plan review, and policy checks;
• IAM changes need stricter human review and explicit security gates.

The repository should encode this difference instead of pretending every pull request has the same risk.

Boundaries Prevent Local Optimization

Agents optimize locally unless the environment tells them otherwise. That is normal. Humans do it too, only slower.

Repository instructions should define boundaries:

• Do not change generated files manually.
• Do not refactor unrelated modules.
• Do not modify CI without explicit approval.
• Do not alter public APIs without compatibility notes.
• Do not touch Terraform or IAM in a low-risk service issue.
• Do not introduce new dependencies without rationale.

These rules are not meant to make the agent timid. They make the review surface legible.

Readiness Can Be Scored

Eventually, repo readiness should become a scorecard. OpenSSF Scorecard and SLSA are useful analogies: they do not make a project safe by themselves, but they turn hidden supply-chain assumptions into visible checks.

An agent readiness scorecard could evaluate:

• context completeness;
• spec quality;
• verification commands;
• CI reliability;
• ownership metadata;
• security boundaries;
• deployment and rollback documentation;
• autonomy eligibility.

The score should not be vanity. It should answer a practical question: which change classes can this repository safely accept from a supervised agent?

Readiness Is Not Autonomy

A Level 2 repository supports human-supervised agent work. It does not imply auto-merge. It does not imply autonomous deployment. It does not imply that the agent may modify infrastructure or security controls.

That distinction is important. Repo readiness gives the team a reliable local loop. Autonomy requires stronger evidence, broader context, policy enforcement, and operational reversibility.

The fastest way to damage trust is to label a repository agent-ready and then let agents perform actions the repository was never prepared to verify.