Agent-Ready Repositories

Calling a repository agent-ready has become rather easy. Add an AGENTS.md, document a test command, watch a coding agent complete one tidy change, done. The badge is awarded.

I don’t think the term survives contact with a real change unless we make it more precise.

The same repository may be perfectly usable for a documentation correction, awkward for a dependency update, unsafe for a schema migration and entirely outside the permitted boundary for an IAM change. Nothing contradictory is happening there. These are different claims, requiring different evidence and different authority.

Here is the working definition I prefer to use:

An agent-ready repository makes its local operating contract sufficiently legible, verifiable, attributable and stoppable for supervised execution of a stated change class, within a stated authority boundary and assessment window.

Now, that is obviously conditional — repo readiness is the local layer of evidence which allows us to delegate a change to an LLM-powered agent, with well-defined boundaries and with criteria the agent can verify its result against. It says nothing yet about whether this is the right change for the product or the company, whether the agent should be granted wider access to the system, or whether the change belongs in production. Those decisions live outside the repo, and that is precisely why I don’t want “agent-ready” to turn into another badge.

The broader assessment key—scope, change class, authority boundary and time window—is defined in Phases Are a Roadmap; Maturity Levels Are Capability States. Applying it here prevents a successful Markdown edit from becoming evidence that the same repository is ready for an unattended production change.

The repository is a local operating surface

A repository is more than a container for source code. In an agentic workflow it is also the durable surface on which a proposed change meets the local rules of the system.

That surface should make several things discoverable:

• what the repository owns, and what it merely consumes;
• which sources are authoritative and which artifacts are generated;
• the local invariants, interfaces and compatibility obligations;
• supported ways to build and verify a change;
• the evidence a reviewer expects;
• who owns the affected area; and
• when execution must stop or escalate.

The filenames are secondary. One repository may use an instruction file, architecture decision records and executable policies. Another may generate part of its guidance from a service catalogue. What matters is that the contract is durable, current and reachable from the work—not that every repository has accumulated the same ceremonial set of Markdown files.

There is a subtle review consequence here, because I cannot prove that a model “understood” an instruction in any useful internal sense, but I can inspect whether the proposed change conforms to the declared boundary, whether the required checks ran, and whether the retained evidence supports the claim being made. That gives us a much better control surface, since observable conformance can be reviewed while imagined comprehension cannot.

The distinctions between prompts, instructions, context, specifications, policy and evidence matter here, but they don’t need another local redefinition. I use them as set out in Spec-Driven Development: Old Disciplines, New Readers. An instruction can explain how work is performed; it does not replace the requirement, the acceptance conditions or the evidence.

A local contract has an edge

Repository guidance can expose a boundary, but it cannot manufacture the authority on the other side of it.

This edge is routinely blurred. A CODEOWNERS file can name responsible people or teams. On GitHub it can also participate in a rule requiring code-owner review. It still doesn’t decide whether the residual operational risk is acceptable, and the file by itself doesn’t enforce every production boundary. That distinction is visible in GitHub’s CODEOWNERS documentation.

The same applies to deployment notes, which are useful and often necessary, but a sentence saying “deploy to production” is not production authority.

The enterprise agentic-engineering taxonomy places this local surface at the repository-harness layer. Identity, policy enforcement, audit and environment promotion belong to the wider platform. An AI Platform Needs an SDLC Platform First follows that hand-off through the delivery path.

Verification is relative to the claim

The old version excluded any repository without a general test surface, which was too broad: a repository is not ready for a change class when it cannot produce credible evidence for the properties that change may affect. A prose correction, an API compatibility change, an infrastructure plan and a security-policy change do not make the same claim about the system, and their evidence should not be interchangeable.

A documentation change may be well covered by a site build, link validation and a visual inspection. A dependency update may require unit and integration tests, a vulnerability review and inspection of the resolved dependency graph. A schema migration may need forward and backward compatibility evidence, production-data assumptions, failure-path tests and a rehearsed recovery plan. Those are examples, not universal gate lists.

More importantly, a green check proves only its predicate. “Unit tests passed” does not prove compatibility with a consumer absent from the test environment. A generated test is still candidate evidence; it is not independent merely because the same model wrote it in a different file. An eloquent explanation may help a reviewer understand a patch, but eloquence is not verification.

The NIST Secure Software Development Framework (SSDF) provides a useful, narrower precedent: high-level secure software development practices are intended to be integrated into an organization’s SDLC. The SSDF is security guidance. It does not define agent readiness, nor does citing it transfer a security claim to a repository that has not produced the relevant evidence.

This is why the exact operational checks belong in the agent-ready repository checklist. The conceptual rule is simpler: name the affected properties, then demand evidence suitable for those properties and for the proposed authority.

Use an evidence profile, not a readiness score

I previously suggested that repository readiness should eventually become a scorecard. I would no longer turn it into one aggregate number.

An 82-point repository tells me very little if I don’t know which missing eighteen points matter to the proposed change. The weighting changes with the work. Weak rollback evidence may be irrelevant to a spelling correction and decisive for a data migration. Averaging the two cases does not create a useful engineering fact.

The useful artifact is an evidence profile, or an evidence envelope:

This profile may be automated, and many of its entries should be, but the automation should preserve the predicates it evaluated and the conditions which failed, rather than collapsing the result into a badge which survives after its assumptions have expired.

Repository readiness therefore contributes to safe delegation capacity, but it is not the complete capacity, because a capable model does not repair repository ambiguity, a legible repository does not grant enterprise IAM or production authority, and strong platform controls do not make the intended product change correct; each layer removes a different class of uncertainty.

The assessment I want at the end is not “Is this repository agent-ready?” but rather:

Which proposed change may this repository admit, what must the resulting evidence prove, and which failed condition stops the run?

If those questions have concrete answers, supervised execution has a defensible local contract. If they don’t, another instruction file will not rescue it.