AI readiness audit

What this audit answers

The AI readiness audit asks how ready a repository is for low-friction agent-led engineering. It evaluates whether a coding agent can find a task, understand product and technical intent, make a safe change, verify it, and leave durable context for another agent or human. It measures repository support for that workflow—not which model or vendor a team uses.

A named methodology or an AGENTS.md file is evidence, not the goal. A current custom workflow can score better than a stale framework scaffold, and a repository is not penalized merely because a particular agent file is absent when equivalent context exists elsewhere.

What Guard inspects

Guard reads agent instructions, product and architecture docs, task and planning artifacts, repository scripts, development setup, tests, quality commands, CI evidence, skills and playbooks, issue and pull-request conventions, decision records, and handoff or work-memory artifacts. It checks whether those sources are discoverable, current, internally consistent, and usable without private chat history.

Context depth is reviewed across technical context, product context, and working-process context. The combined context score weights them 40%, 30%, and 30%, then applies a bounded penalty for material contradictions or desynchronization. An instruction conflict matters only when it can mislead real work; intentionally different modes with clear scopes are not contradictions.

The nine readiness categories

Each category is scored from 0 to 10: agent delivery path, context depth, planning system, machine verification, cross-agent portability, skills quality, work memory and handoff, quality gates, and environment safety. The audit asks practical questions: can an agent identify scope and acceptance criteria, find safe extension points, run verification, complete non-interactive setup, and hand the work to a different agent type?

The result distinguishes durable repository evidence from tool-specific memory. Files that merely name a framework without current plans, acceptance criteria, or verification do not earn the same credit as a working system.

How the score works

The weighted total uses these category weights: 15%, 20%, 14%, 14%, 10%, 9%, 7%, 6%, and 5%, in the category order above. The 0–10 result is multiplied by ten and rounded to produce the final 0–100 score.

Quality gates may be left unscored when the only visible gap is absent or decorative CI/CD pipeline evidence. In that case its weight is excluded and the remaining weights are renormalized; an unknown is not silently treated as zero. Context depth cannot reach 8 or higher unless technical, product, and process context are each at least 7 and no major contradiction remains unresolved.

Guard labels 90–100 Agent-ready, 70–89 Mostly ready, 40–69 Needs context, and 0–39 Needs groundwork. These labels summarize friction; they do not promise that every task is safe to delegate without review.

Limitations and boundaries

The audit is read-only and repository-centered. It can recognize links to external product or planning systems, but inaccessible content reduces coverage rather than becoming invented negative evidence. It does not score general code quality, security, test coverage, or pipeline maturity again; it uses those surfaces only to judge whether an agent has an understandable verification and delivery path.

Improvements and reruns

Useful improvements make context or workflow more durable: clarify the product boundary, connect tasks to acceptance criteria, document runnable verification, repair contradictory instructions, provide safe environment setup, or establish a portable handoff. The smallest valuable artifact is preferred over adopting a methodology for its name.

Rerun after the new artifact or workflow is merged and used by the repository. A higher score should be supported by an easier task-to-verification path, not merely by adding more prose.