Agent-Ready Repository Checklist

A checklist can make an ill-defined practice look settled very quickly, especially once every repository has acquired the same files and every pull request has acquired the same boxes. This is useful right up to the point where the boxes start standing in for the engineering judgment they were meant to support.

So I would not use this checklist to certify a repository as agent-ready, and I would certainly not run it once and attach a badge. I would use it to decide whether a repository can admit one stated change class, within one authority boundary and for a stated assessment window. The same repository may pass for a documentation correction and fail for a schema migration, which is not an inconsistency but the expected result of asking a more precise question.

The working definition and the reasoning behind that scope live in Agent-Ready Repositories. This companion is the operational part: it asks what evidence must exist, who owns the decision, and which missing or failed condition stops the work.

Before using the checklist

Start by writing a small admission record. It does not need its own platform or an elaborate template, but it does need to survive the agent run and the pull request so that a reviewer is judging the same claim the agent was asked to make.

Then apply the checks below to that record. An answer such as “documented in AGENTS.md” may be perfectly good evidence, but the filename is not the control; the current, reachable and reviewable content is.

1. Intent and scope

• The change class is named narrowly enough to assess.
  Evidence: the task distinguishes, for example, a prose correction from a dependency update, an API change or a data migration.
  Owner: the person accepting the task into the engineering workflow.
  Stop when: the proposed change crosses into another class whose risks and evidence have not been assessed.

• Acceptance conditions and non-goals are explicit.
  Evidence: the task says what must become true, what must remain unchanged, and what would count as an unacceptable side effect.
  Owner: the product or engineering owner of the intended outcome.
  Stop when: the agent has to invent the product decision or infer a consequential non-goal from silence.

• Affected components and external dependencies are identified.
  Evidence: the task or repository references the interfaces, consumers, data contracts, services or operational processes which may be affected.
  Owner: the system owner, with owners of affected external systems involved where necessary.
  Stop when: the repository view is known to be incomplete and no authoritative system context is available.

2. Local operating surface

• Authoritative sources and generated artifacts are distinguishable.
  Evidence: repository guidance identifies what may be edited, what is generated, how generation is reproduced, and which external source wins when copies disagree.
  Owner: the maintainer of the build or generation path.
  Stop when: the agent would edit a derived artifact without its source, or regenerate files through an unknown toolchain.

• The supported build and verification entry points work from the assessed state.
  Evidence: commands are executable from a clean checkout or a documented environment, with required versions and inputs available.
  Owner: the repository maintainer or platform team which publishes the supported path.
  Stop when: the only successful path depends on undocumented local state, hidden credentials or a person repairing the environment during the run.

• Local invariants and compatibility obligations are reachable.
  Evidence: tests, schemas, architecture records, interface definitions or concise repository guidance explain the properties the change must preserve.
  Owner: the owner of the affected interface or invariant.
  Stop when: a change can be produced syntactically but its compatibility obligations cannot be established.

• Ownership and escalation routes resolve to current roles.
  Evidence: the affected area maps to a person, team or on-call role which can review it; a CODEOWNERS file is one possible implementation, not the definition of ownership.
  Owner: repository or service governance.
  Stop when: the listed owner is absent, lacks the relevant authority, or cannot identify a substitute.

3. Verification and evidence

• Each required check corresponds to an affected property.
  Evidence: the admission record explains what a unit test, contract test, schema check, security scan, preview or manual review is intended to show.
  Owner: the reviewer accepting that proof obligation.
  Stop when: a green check is being used to support a claim which its predicate does not test.

• Failure, skip and flaky states remain visible.
  Evidence: required commands fail closed, skipped coverage is reported, and known flaky checks have an explicit treatment rather than a retry-until-green convention.
  Owner: the maintainer of the verification surface.
  Stop when: a failed or absent check can be silently converted into a successful run.

• Agent-produced evidence is reviewed for dependence and blind spots.
  Evidence: generated tests, explanations and evaluations are labelled as candidate evidence, with independent or differently sourced evidence added where the risk requires it.
  Owner: the accountable technical reviewer.
  Stop when: the same agent defines the requirement, writes the implementation and supplies the only test of its own interpretation.

• The evidence can be retained and attributed.
  Evidence: the pull request or attached artifact records the relevant commands, results, environment, commit and material limitations.
  Owner: the delivery workflow and its reviewer.
  Stop when: the result cannot be connected to the candidate change which produced it.

4. Authority and escalation

• The execution identity and tool boundary are explicit.
  Evidence: the run identifies the actor, available tools, reachable repositories and services, and the credentials or delegated roles it may use.
  Owner: the identity or platform owner granting access.
  Stop when: the actor, credential source or reachable system cannot be established.

• Granted permissions are no wider than the admitted change requires.
  Evidence: repository, CI, cloud and data access are constrained to the operations and duration needed for the change class.
  Owner: the IAM or platform control owner, not the instruction file.
  Stop when: least privilege cannot be applied, or a broad standing credential is the only available path.

• Sensitive and irreversible operations have enforced boundaries.
  Evidence: secrets, IAM, production data, destructive migrations, deployment and policy changes require the appropriate approval or are technically unavailable to the run.
  Owner: the authority which owns the affected production or security boundary.
  Stop when: the restriction exists only as prose while the agent can still perform the operation.

The repository can describe or reference these boundaries, but it cannot issue enterprise credentials, grant production authority or enforce every external policy. That hand-off belongs to the SDLC platform described in An AI Platform Needs an SDLC Platform First.

5. Delivery, review and recovery

• The proposed change remains reviewable at the declared scope.
  Evidence: unrelated edits are absent, generated changes are separable, and the diff can be mapped back to the acceptance conditions.
  Owner: the pull-request author and accountable reviewer.
  Stop when: the review would require accepting a large unexplained change merely to preserve the intended one.

• Merge and promotion gates are enforced by the delivery system.
  Evidence: required review, status checks, environment promotion or other policy is configured and observable for the target branch and environment.
  Owner: repository and release governance.
  Stop when: the proposed path depends on bypassing a required gate or on an unenforced convention for a consequential change.

• Rollback or recovery is credible for the change class.
  Evidence: the pull request names how to revert, disable, restore, roll forward or otherwise recover, including data and compatibility consequences.
  Owner: the operator who would execute recovery and the owner accepting its limitations.
  Stop when: recovery depends on unavailable state, an untested assumption or an authority not involved in the review.

• Post-change observation and accountability are assigned.
  Evidence: relevant logs, metrics, user outcomes, data-quality checks or other observations have an owner, a review period and an escalation route.
  Owner: the service, product or operational owner affected by the result.
  Stop when: nobody is accountable for deciding whether the technically accepted change produced the intended system or product behaviour.

A note on repository controls

Repository-host controls are useful enforcement examples, not universal requirements. GitHub rulesets can control interactions with branches and tags, while GitHub CODEOWNERS can request owners for changed paths and, when combined with the relevant repository protection, participate in required review. Another host or an enterprise control plane may implement the same decision differently.

The NIST Secure Software Development Framework (SSDF) is also relevant but narrower: it supplies high-level secure-development practices intended for integration into an SDLC, and it does not define agent readiness. These are examples, not universal requirements for every check in this article.

Record the admission decision

The useful output is not a row of ticks but a decision tied to its scope:

This repository may admit this change class, using this identity and tool boundary, provided this evidence is produced; these conditions stop the run, and this owner accepts the result until the assessment expires.

If that statement cannot be completed without hand-waving, the repository is not ready for the proposed work yet. The missing item may be local documentation, but it may just as easily be system context, a verification surface, an IAM control, production recovery or a product decision, and putting another instruction file in the repository will not repair the wrong layer.