AI Agent Readiness Checklist — 84 Repository Checks

Larridin product documentation · Updated September 7, 2026

Agent Readiness grades how ready a repository is for AI coding agents. Every repository is scored against 84 binary checks across nine categories, and the results roll up into five readiness levels. This page documents each level, how scoring works, and every check we assess: what we look for, why it matters for agents, and how to satisfy it.

The five readiness levels

Repositories progress through five levels, each a qualitative shift in how autonomously agents can work in the codebase.

Level	Name	What it means	Example checks
1	Baseline	The starting tier. Repos climb from here as the basic checks (formatter, linter, types, unit tests) come online and run locally, so agents can change code and know it compiles.	Formatter, Unit Tests Exist, Dependencies Pinned
2	Documented	The workflows are written down: agent guides, environment templates, schema, ownership. Agents stop guessing at tribal knowledge.	AGENTS.md, .env Example, Structured Logging
3	Agent-ready	Standards are enforced through automation: CI, hooks, tracing, release workflows. Agents get automated feedback before a change is reviewed and merged.	Pre-commit Hooks, Integration Tests Exist, API Schema Docs
4	Optimized	Feedback loops are fast and measured: coverage gates, flaky-test tracking, build timing. Agents iterate at machine speed instead of CI speed.	Test Coverage Thresholds, Flaky Test Detection, Secret Scanning
5	Autonomous	Production signal feeds work back into the loop: canary rollouts, auto-rollback, error-to-issue pipelines. The system improves itself with agents in it.	Progressive Rollout, Rollback Automation, Error-to-Insight Pipeline

How scoring works

Every check is binary: it passes or it fails. Checks that can't be assessed for a repository are skipped and excluded from scoring, so they never count against you.

A level clears when both of these hold:

At least half of the level's evaluated checks pass.
At least half of the level's checks were actually evaluated, so a level can't clear on a sparse sample.

A repository's readiness level is the highest level where that level and every level below it clear. Levels are contiguous: a repository can't reach Level 4 over an uncleared Level 3, no matter how many higher-level checks pass. Every repository starts at Level 1.

Worked example. A repository passes 7 of 8 evaluated Level 1 checks (88%), 9 of 12 at Level 2 (75%), and 5 of 12 at Level 3 (42%). Enough checks were evaluated at each level to meet the coverage bar, so Levels 1 and 2 clear; Level 3 falls short of the 50% pass bar. The repository is Level 2.

Alongside the level, each report includes an overall pass rate (passed / evaluated, across all checks), per-level and per-category scores, the repository's top strengths, priority fixes, and the specific failing checks that block the next level.

Checks by category

Each check lists its stable key in code font. Keys never change and match the key field on check results in the readiness API, so the tables below double as an API reference. "What we look for" states exactly what the scan measures; "How to satisfy" is the shortest path to passing.

Style & Validation

Formatters, linters, and type checkers catch mistakes in seconds, locally. Agents self-correct before a human ever sees the diff.

Check	Level	What we look for	Why it helps agents	How to satisfy
Formatter `formatter`	1	A committed formatter config file: a Prettier config (.prettierrc, prettier.config.js) or rustfmt.toml. A bare .editorconfig also passes today.	A formatter removes whole classes of review churn and lets agents match house style automatically.	Adopt an auto-formatter and commit its config (prettier.config.js, rustfmt.toml).
Lint Config `lint_config`	1	A committed linter configuration (ESLint, golangci-lint, ruff, rubocop).	Linters give agents fast, local feedback on mistakes before review.	Configure a linter and commit its config next to the code it governs.
Strict Typing `strict_typing`	1	Strict type settings enabled (tsconfig "strict": true, mypy --strict; Go is strict by default).	Strict typing narrows the space of plausible-but-wrong edits an agent can make.	Turn on strict mode and burn down the resulting errors module by module.
Type Check `type_check`	1	A statically typed language or a configured type checker (tsconfig.json, mypy, pyright).	Types are the cheapest correctness signal an agent can self-verify against.	Add a type checker and wire it into the standard check command (tsc --noEmit, mypy).
Large File Detection `large_file_detection`	2	A guard against oversized files (git LFS, check-added-large-files, eslint max-lines).	Huge files blow agent context windows and slow every read.	Add a pre-commit size check (check-added-large-files) or an eslint max-lines rule.
Naming Consistency `naming_consistency`	2	Documented naming conventions that the code actually follows.	Consistent naming lets agents infer intent and locate code by convention.	Write the naming rules into CONTRIBUTING.md or AGENTS.md and enforce the mechanical ones with lint rules.
Pre-commit Hooks `pre_commit_hooks`	3	A commit-time hook framework configured (Husky, pre-commit, lefthook).	Hooks catch agent mistakes at commit time instead of in CI minutes later.	Install Husky or pre-commit and run the formatter, linter, and type check on staged files.
Code Modularization `code_modularization`	4	Enforced module boundaries (dependency-cruiser, eslint import rules, Go internal packages).	Clear boundaries bound the blast radius of an agent edit.	Add dependency-cruiser or import-boundary lint rules that encode the intended layering.
Cyclomatic Complexity `cyclomatic_complexity`	4	A committed complexity limit (eslint complexity, gocyclo, radon).	Bounded complexity keeps functions small enough for an agent to reason about safely.	Add a complexity rule to your linter and ratchet the threshold down in CI.
Dead Code Detection `dead_code_detection`	4	Dead-code detection wired into CI (knip, ts-prune, vulture, deadcode).	Dead code misleads agents into maintaining paths that no longer matter.	Run knip (JS/TS) or vulture (Python) in CI and delete what it finds.
Duplicate Code Detection `duplicate_code_detection`	4	Duplicate-code detection in CI (jscpd, PMD CPD, SonarQube).	Duplication multiplies the edits an agent must keep in sync.	Add jscpd or PMD CPD to CI with a sensible threshold.
Tech Debt Tracking `tech_debt_tracking`	4	A machine-readable debt convention (TODO(TICKET-123) lint rule or a TODO scanner).	Linked debt markers give agents a machine-readable backlog of known gaps.	Enforce TODO(TICKET-123) format with a lint rule, or run a TODO-to-issue scanner.
N+1 Detection `n_plus_one_detection`	5	Automated N+1 query detection for ORM code (query analyzers, ORM lint plugins).	Agents readily introduce N+1s; automated detection catches them before prod.	Enable your ORM's query analyzer or an N+1 lint plugin and fail CI on regressions.

Build System

Deterministic builds and documented commands let agents verify their own work. Fast, automated pipelines turn every change into a tight edit-verify loop.

Check	Level	What we look for	Why it helps agents	How to satisfy
Dependencies Pinned `deps_pinned`	1	A committed lockfile pinning exact dependency versions (pnpm-lock.yaml, go.sum, uv.lock).	Pinned deps make agent runs reproducible across machines and CI.	Commit the lockfile and make CI install from it.
Documented Build Commands `build_cmd_doc`	1	Build and run commands documented where agents look first (README, AGENTS.md).	Agents need the canonical build command to verify their own work.	Write the canonical build, run, and check commands into AGENTS.md.
Git Hosting CLI `vcs_cli_tools`	1	Scriptable git-hosting CLI usage (gh, glab) in scripts or docs.	A scriptable hosting CLI lets agents open PRs and inspect CI without a browser.	Standardize on gh or glab and document the common operations in AGENTS.md.
Single Command Setup `single_command_setup`	1	One documented command that produces a working dev environment (make setup, ./script/bootstrap).	A single setup command removes the biggest source of agent onboarding failure.	Ship a setup or doctor script and document it as the only setup step.
Agentic Development `agentic_development`	3	Artifacts of agent-assisted development (Co-authored-by agent commits, .claude/ config, agent skills).	Repos that already work with agents leave artifacts agents can build on.	Adopt an agent guide and skills, and let agent co-authorship land in the git history.
Automated PR Review `automated_pr_review`	3	An automated first-pass reviewer on pull requests (review bots, policy checks).	Automated review gives agent-authored PRs a consistent first pass.	Wire a PR review bot or policy checks that run on every pull request.
Fast CI Feedback `fast_ci_feedback`	3	A CI workflow configured to run on pull requests.	Fast CI tightens the agent edit-verify loop.	Split slow suites, cache dependencies, and keep the merge-blocking path under ten minutes.
Feature Flag Infrastructure `feature_flag_infrastructure`	3	Feature-flag infrastructure (LaunchDarkly, Unleash, Statsig, or a homegrown system).	Flags let agents ship behind a switch instead of all-or-nothing.	Adopt a flag SDK and gate new behavior behind flags by default.
Release Automation `release_automation`	3	Releases published by CI (release workflows, semantic-release, GoReleaser).	Automated releases remove a manual step agents otherwise can't complete.	Automate tagging and publishing with semantic-release, GoReleaser, or release-please.
Build Performance Tracking `build_performance_tracking`	4	Build caching or timing visibility (Turborepo/Nx cache, Bazel, CI timing dashboards).	Build-time visibility keeps the agent loop from silently regressing.	Enable remote build caching and track build times in CI.
Deployment Frequency `deployment_frequency`	4	Regular, automated deployments (deploy workflows, platform configs).	Frequent small deploys are the natural cadence for agent-sized changes.	Automate deploys from main and ship on every merge or on a fixed cadence.
Release Notes Automation `release_notes_automation`	4	Generated release notes (changesets, release-please, CHANGELOG automation).	Structured release notes give agents a contract for commit formatting.	Adopt changesets or release-please so notes are generated from commits.
Unused Dependencies Detection `unused_dependencies_detection`	4	Unused-dependency detection in CI (depcheck, knip, deptry, go mod tidy).	Lean dependency graphs reduce the surface an agent must understand.	Run depcheck or deptry (or go mod tidy) in CI and prune what it flags.
Dead Feature Flag Detection `dead_feature_flag_detection`	5	Automated detection of stale feature flags (flag-lifecycle tooling, cleanup jobs).	Stale flags accumulate dead branches that confuse agents.	Track flag age in your flag system and open cleanup tasks when a flag fully rolls out.
Heavy Dependency Detection `heavy_dependency_detection`	5	Bundle-size budgets for shipped bundles (size-limit, bundlesize, bundlewatch).	Bundle budgets keep agents from importing the world for a one-liner.	Add size-limit with a budget per entry point and fail CI on regressions.
Monorepo Tooling `monorepo_tooling`	5	Workspace-aware build tooling in monorepos (Turborepo, Nx, Bazel, pnpm workspaces).	Monorepo tooling lets agents reason about cross-package impact.	Adopt Turborepo or Nx so task graphs and caching span packages.
Progressive Rollout `progressive_rollout`	5	Progressive delivery for deployed services (canary or percentage rollouts via Argo Rollouts, Flagger).	Progressive rollout limits the impact of an agent-introduced regression.	Adopt canary or percentage rollouts via Argo Rollouts, Flagger, or your platform's traffic splitting.
Rollback Automation `rollback_automation`	5	One-command or automated rollback for deployed services.	One-command rollback makes shipping agent changes low-risk.	Add a rollback workflow, or automated health-gated rollback, and document the trigger.
Version Drift Detection `version_drift_detection`	5	Cross-package version-drift detection (syncpack, manypkg).	Drift detection stops agents from pinning incompatible versions across packages.	Run syncpack or manypkg in CI to keep shared dependency versions aligned.

Testing

Tests are the strongest signal an agent can check its work against. Runnable, isolated, trustworthy suites make agent changes safe to merge.

Check	Level	What we look for	Why it helps agents	How to satisfy
Unit Tests Exist `unit_tests_exist`	1	Unit tests present, following the language's standard layout (test.go, tests/, test.py).	Tests are the single strongest signal an agent can verify a change against.	Start a unit suite in the standard location and grow it with every change.
Test Naming Conventions `test_naming_conventions`	2	Consistent test naming and placement across the suite.	Conventional test layout lets agents find and extend the right tests.	Write the test layout rules into AGENTS.md and align the stragglers.
Unit Tests Runnable `unit_tests_runnable`	2	A single documented, reliable command that runs the unit tests.	If an agent can't run the tests, it can't self-verify.	Document one test command in AGENTS.md and make it pass from a fresh clone.
Integration Tests Exist `integration_tests_exist`	3	Integration or end-to-end tests covering real flows (e2e/, Playwright, Cypress).	Integration tests catch the cross-module breakage unit tests miss.	Stand up an integration suite covering the top user flows.
Test Isolation `test_isolation`	3	Tests that run isolated and in parallel (no shared state, race detection on).	Isolated tests give agents trustworthy, order-independent results.	Remove shared fixtures and state, then enable parallel execution (and -race for Go).
Flaky Test Detection `flaky_test_detection`	4	Flaky-test detection or tracking (retry telemetry, stress runs, quarantine lists).	Flaky tests poison the agent's pass/fail signal.	Track retried failures in CI and quarantine flaky tests behind a burn-down list.
Test Coverage Thresholds `test_coverage_thresholds`	4	Coverage reporting or a threshold config present (coverageThreshold, fail-under, Codecov).	Coverage gates push agents to test what they change.	Publish coverage and enforce a ratcheting threshold in CI.
Test Performance Tracking `test_performance_tracking`	4	Test-suite timing tracked over time (--durations, benchmark CI).	Perf tracking catches agent changes that quietly slow the suite.	Record the slowest tests per run and alert on suite-time regressions.

Documentation

Written instructions capture what "everyone just knows." Agents can't absorb tribal knowledge, so the docs are their onboarding.

Check	Level	What we look for	Why it helps agents	How to satisfy
README `readme`	1	A README covering setup, architecture, and how to run the project.	The README is an agent's first orientation to the repo.	Write the README an agent needs on its first read: setup, run, test, layout.
AGENTS.md `agents_md`	2	An agent guide file present: AGENTS.md, CLAUDE.md, .github/AGENTS.md, or .cursorrules. Presence only; the Substance, Completeness, and Structure checks grade the content.	A dedicated agent guide is the highest-leverage readiness artifact there is.	Add AGENTS.md with the commands, architecture map, and conventions agents must follow.
AGENTS.md Substance `agents_md_size`	2	The agent guide has real substance: more than a stub, without ballooning past what fits in context.	A stub guide teaches an agent nothing; a bloated one crowds out the code it came to read.	Grow the guide past a skeleton (commands, layout, conventions) and split anything encyclopedic into linked docs.
Documentation Freshness `documentation_freshness`	2	The newest commit touching any core doc (README, CONTRIBUTING, agent guides, docs/) falls within 180 days of the repository's latest commit. Measured against repo HEAD, not scan date, and the most recently touched doc sets the result.	Stale docs send agents down paths that no longer exist.	Review core docs on a schedule and delete or update anything stale.
AGENTS.md Completeness `agents_md_content`	3	The guide covers what an agent actually needs: how to run the tests, build/run commands, repo layout, and conventions.	An agent guide that omits the test command leaves agents unable to verify their own work, however long the guide is.	Add the missing sections: test command first, then build/run, layout, and conventions.
AGENTS.md Freshness `agents_md_freshness`	3	The agent guide has been updated recently (last commit touching it within ~6 months).	A stale guide sends agents down paths that no longer exist, worse than no guide because they trust it.	Update the agent guide in the same PR as any change to commands, layout, or conventions.
API Schema Docs `api_schema_docs`	3	Machine-readable API schemas (OpenAPI, GraphQL SDL) committed or generated.	Machine-readable schemas let agents call APIs correctly.	Publish an OpenAPI spec or GraphQL SDL and keep it generated from source.
Automated Doc Generation `automated_doc_generation`	3	Docs generated from source (TypeDoc, Sphinx, MkDocs, Docusaurus pipelines).	Generated docs stay in sync, so agents trust them.	Generate reference docs in CI so they can't drift from the code.
Service Flow Documented `service_flow_documented`	3	Architecture or service-flow documentation (Mermaid or PlantUML diagrams, flow notes).	Flow docs give agents the cross-service mental model code alone can't.	Add a Mermaid diagram of the main request and data flows to the docs.
Skills `skills`	3	Reusable agent skills or commands (.claude/skills, .claude/commands) with frontmatter.	Skills encode repeatable repo workflows an agent can invoke.	Extract repeated agent workflows into .claude/skills with YAML frontmatter.
AGENTS.md Structure `agents_md_validation`	4	A structured agent guide with clearly delineated sections (multiple headings).	A sectioned guide lets agents jump straight to the part they need instead of re-reading one wall of text.	Break the agent guide into clearly headed sections (Commands, Architecture, Conventions).

Dev Environment

Reproducible environments boot with one command. When agents and developers work in identical environments, setup failures disappear.

Check	Level	What we look for	Why it helps agents	How to satisfy
.env Example `env_template`	2	A committed .env.example documenting every required variable.	An env template removes a silent source of agent setup failure.	Add .env.example and update it in the same PR as any new variable.
Database Schema `database_schema`	2	Schema managed by migrations or a schema tool (Prisma, Alembic, migrations/).	A declared schema lets agents reason about data shapes and migrations.	Adopt a migration tool and make every schema change land as a migration.
Local Services Setup `local_services_setup`	2	One-command local dependencies (docker-compose.yml, dev scripts).	One-command local services let agents run the app end to end.	Add a docker-compose file that boots every local dependency.
Devcontainer `devcontainer`	3	A .devcontainer configuration for a reproducible workspace.	A devcontainer gives agents a known-good, pre-provisioned workspace.	Add .devcontainer/devcontainer.json describing the full toolchain.
Devcontainer Runnable `devcontainer_runnable`	4	The devcontainer.json declares a runnable source: an image, build, dockerFile, or dockerComposeFile key. We check the declaration, not an actual build or boot.	A devcontainer only helps agents if it actually boots.	Point the devcontainer at a real image or Dockerfile and verify it boots in CI or Codespaces.

Debugging & Observability

Structured logs, traces, and metrics show what the code actually does at runtime. Agents debug from evidence instead of guesswork.

Check	Level	What we look for	Why it helps agents	How to satisfy
Health Checks `health_checks`	2	Health and readiness endpoints on services.	Health checks give agents a definitive "is it up" signal.	Add a lightweight /healthz for process liveness, and a /readyz that runs bounded checks of the dependencies required to serve traffic.
Metrics Collection `metrics_collection`	2	Runtime metrics collected (prom-client, Datadog, CloudWatch).	Metrics let agents confirm a change's runtime impact.	Instrument the key paths with a metrics client and ship them to your monitoring stack.
Structured Logging `structured_logging`	2	A structured logging library in use (pino, zap, structlog, winston).	Structured logs are parseable evidence an agent can debug from.	Adopt a structured logger and emit JSON with stable field names.
Alerting Configured `alerting_configured`	3	Alerting rules under version control (Alertmanager, Datadog monitors, PagerDuty).	Alerts catch regressions agents introduce after merge.	Define alert rules as code for the golden signals and route them to an on-call target.
Deployment Observability `deployment_observability`	3	Deployments visible in dashboards or deploy-tracking metrics.	Deployment visibility ties an agent change to its rollout outcome.	Emit deploy markers to your dashboards so every change is correlated with its rollout.
Distributed Tracing `distributed_tracing`	3	Distributed tracing instrumentation (OpenTelemetry, request-ID propagation).	Traces let agents follow a request across services.	Add OpenTelemetry auto-instrumentation and propagate request IDs across calls.
Error Tracking `error_tracking_contextualized`	3	Contextual error tracking wired in (Sentry, Bugsnag, Rollbar).	Contextual errors point agents straight at the failing path.	Install Sentry (or an equivalent) with release and user context attached.
Profiling Instrumentation `profiling_instrumentation`	3	Profiling hooks available (pprof, Pyroscope, Datadog profiler).	Profiling lets agents diagnose performance, not just correctness.	Expose pprof (Go) or attach a continuous profiler in production.
Circuit Breakers `circuit_breakers`	4	Resilience patterns on external calls (circuit breakers, retries with backoff, bulkheads).	Resilience patterns contain failures agents might otherwise cascade.	Wrap external calls in a resilience library (opossum, resilience4j) with sane defaults.
Code Quality Metrics `code_quality_metrics`	4	Code-quality trends tracked (coverage upload, SonarQube, CodeClimate).	Quality trends keep agents from eroding the codebase over time.	Upload coverage and quality metrics per PR so trends stay visible.
Runbooks Documented `runbooks_documented`	4	Operational runbooks committed or linked (runbooks/, RUNBOOK.md, on-call docs).	Runbooks give agents the human playbook for incidents.	Write runbooks for the top operational scenarios and link them from alerts.

Security

Guardrails like branch protection, secret scanning, and ownership keep agent mistakes from becoming incidents. Agents move fast inside hard limits.

Check	Level	What we look for	Why it helps agents	How to satisfy
Comprehensive .gitignore `gitignore_comprehensive`	1	A .gitignore excluding secrets, build artifacts, and IDE files.	A good .gitignore stops agents from committing secrets or noise.	Extend .gitignore to cover .env files, build output, and editor directories.
Branch Protection `branch_protection`	2	Branch protection or rulesets on the default branch.	Protected branches keep agent mistakes from reaching main unreviewed.	Protect main: require PRs, passing checks, and at least one review.
CODEOWNERS `codeowners`	2	A CODEOWNERS file mapping paths to owning teams.	Ownership routing tells agents who must review which change.	Add CODEOWNERS and require owner review on protected paths.
Secrets Management `secrets_management`	2	Secrets kept out of the repo (gitignored locally, secret-manager SDKs in code).	Managed secrets keep agents from hard-coding credentials.	Move credentials into a secrets manager and reference them by name in code.
Dependency Update Automation `dependency_update_automation`	3	Automated dependency updates (dependabot.yml, renovate.json).	Automated updates keep the dependency graph agents reason over current.	Enable Renovate or Dependabot to open update PRs, auto-merging only allowlisted low-risk updates after required CI and security checks pass under branch protection.
Automated Security Review `automated_security_review`	4	A security scanner workflow or config committed (CodeQL, Semgrep, Snyk).	Security scanning is a backstop for agent-introduced vulnerabilities.	Enable CodeQL or Semgrep on every pull request.
Log Scrubbing `log_scrubbing`	4	Sensitive data redacted in logs (pino redact, scrubbing middleware).	Redaction stops agents from logging secrets or PII.	Configure your logger's redaction list for tokens, credentials, and PII fields.
PII Handling `pii_handling`	4	PII explicitly marked and protected (data classes, redactability systems).	Explicit PII handling tells agents what data is sensitive.	Tag PII fields at the type or schema level and enforce handling rules around them.
Secret Scanning `secret_scanning`	4	Secret scanning or push protection (gitleaks, trufflehog, GitHub secret scanning).	Secret scanning catches credentials before an agent leaks them.	Enable push protection and run gitleaks in CI.
DAST Scanning `dast_scanning`	5	Dynamic security testing against running endpoints (OWASP ZAP, Nuclei, StackHawk).	DAST catches runtime vulns static checks and agents miss.	Run ZAP or StackHawk against a staging deploy on a schedule.
Privacy Compliance `privacy_compliance`	5	Documented privacy and compliance controls (retention, consent, GDPR posture).	Compliance constraints are rules agents must not violate.	Document what user data is collected, why, and how long it is retained.

Task Discovery

Well-structured issues and templates make the backlog machine-readable. Agents can find, scope, and pick up work on their own.

Check	Level	What we look for	Why it helps agents	How to satisfy
Backlog Health `backlog_health`	2	Issues that are descriptive, labeled, and actionable.	A healthy backlog is a queue of agent-actionable work.	Triage the backlog: title, label, and acceptance criteria on every open issue.
Issue Labeling System `issue_labeling_system`	2	A consistent label taxonomy, ideally automated (labeler.yml, labels.yml).	Labels let agents filter and prioritize the backlog.	Define the label taxonomy as code and auto-apply labels with labeler.yml.
Issue Templates `issue_templates`	2	Issue templates for the common request types (.github/ISSUE_TEMPLATE/).	Structured issues give agents well-formed tasks to pick up.	Add bug and feature templates that ask for repro steps and acceptance criteria.
PR Templates `pr_templates`	2	A pull-request template (.github/pull_request_template.md).	A PR template gives agent-authored PRs a consistent shape.	Add a PR template asking for summary, testing evidence, and rollout notes.

Product & Analytics

Usage analytics and error pipelines turn production signal into prioritized work. Agents see impact, not just code.

Check	Level	What we look for	Why it helps agents	How to satisfy
Error-to-Insight Pipeline `error_to_insight_pipeline`	5	Production errors automatically become tracked work (Sentry-to-GitHub, alert-to-ticket automation).	An error-to-issue pipeline turns production signal into agent tasks.	Wire Sentry (or your alerting) to open issues with context attached.
Product Analytics Instrumentation `product_analytics_instrumentation`	5	Product analytics instrumented (PostHog, Mixpanel, Amplitude, GA4).	Usage analytics let agents prioritize changes by real impact.	Instrument the key user actions with an analytics SDK and name events consistently.

Explore Agent Readiness · Measurement methodology