The 9 Dimensions
Nine rubric areas that roll up into each repo’s readiness score.
Overview
Repository readiness is not one number in isolation. Nine dimensions each capture a different angle of how well a repo supports humans and AI agents. Together they answer: can someone open this repo cold and be productive?
Higher-impact pillars (especially Agentic Readiness and Test Coverage) pull the overall score more than lighter-touch areas like minor formatting conventions.
Readiness scores
How overall and per-dimension percentages appear in the app.
AI Resolution Hub
Where high-severity gaps from these dimensions become fix tasks.
At a glance
| Dimension | Focus | Example signal we look for |
|---|---|---|
| A · Agentic Readiness | Can agents work here without guessing? | AGENTS.md, .cursor/rules/, scriptable commands |
| B · Codebase Hygiene | Can a new contributor find basics? | README, CODEOWNERS, lockfiles, .env.example |
| C · Code Quality | Are quality gates wired in? | ESLint/Ruff config, static analysis in CI |
| D · Test Coverage | Can changes get fast feedback? | Unit/integration tests, CI test job |
| E · Observability | Can runtime behavior be understood? | Structured logging, metrics, health endpoints |
| F · API & Contract Design | Are boundaries machine-readable? | openapi.yaml, GraphQL schemas, protobuf |
| G · Governance & Compliance | Are changes reviewable and safe? | Branch protection, SECURITY.md, CODEOWNERS |
| H · Delivery Readiness | Can this repo ship repeatably? | Dockerfile, Helm/K8s, IaC, CI/CD pipelines |
| I · Token Efficiency | Does context stay bounded? | .cursorignore, doc layering, no huge always-on files |
A: Agentic Readiness Highest weight
Question: If an AI agent lands in this repo today, does it know what to do?
This pillar covers agent instruction files, Cursor or Claude project configuration, skills, ignore files, and copy-pasteable build/test commands. It is the strongest predictor of “can an agent start working here?”
What we look for: AGENTS.md or CLAUDE.md, .cursor/rules/ and .cursor/skills/, .cursorignore or Claude deny rules, documented hooks, and non-interactive commands in docs.
Example (payments-api): Gap without AGENTS.md; Met when README lists npm test and npm run build; Partial when .cursor/rules/ exists but rule descriptions are empty.
Example (handbook): May still need a short AGENTS.md for doc-editing conventions even though it is not application code.
B: Codebase Hygiene
Question: Can a new hire (human or agent) orient without a tour?
README quality, ownership routing, reproducible dependencies, and configuration templates reduce onboarding friction.
What we look for: README.md with setup steps, CODEOWNERS, lockfiles (package-lock.json, Gemfile.lock), .editorconfig, .env.example.
Example (web-checkout): Partial when README covers install but omits how to run Storybook; Met when CODEOWNERS routes src/payments/ to the right team.
C: Code Quality
Question: Are there automated guardrails before merge?
Static analysis, lint rules, and CI quality gates catch issues agents might introduce.
What we look for: eslint.config.js, ruff.toml, sonar-project.properties, lint/typecheck steps in .github/workflows/.
Example: Met when CI runs npm run lint and fails on errors; Gap when lint config exists locally but CI only runs build.
D: Test Coverage High weight
Question: Can the agent verify its own changes?
Automated tests give fast feedback. Agents are far more reliable when a test command is one copy-paste away.
What we look for: Test frameworks (jest, vitest, pytest, JUnit), test directories, CI jobs that run tests, and (for backend repos) integration or load-test hints where appropriate.
Example (payments-api): Met with src/**/*.test.ts and CI running npm test; Gap when tests exist but CI never executes them.
Example (acme-ios): XCTest or Fastlane test lanes instead of Jest; k6/Gatling are N/A for a store-only app.
E: Observability
Question: If something breaks in production, are there signals to debug?
Instrumentation helps agents reason about runtime behavior when fixing incidents or adding features.
What we look for: Structured logging patterns, metrics exporters, tracing hooks, /health or readiness endpoints.
Example: Partial when logs are plain console.log without structure; Met when OpenTelemetry or a structured logger is configured and documented.
F: API & Contract Design
Question: Are service boundaries written down in a machine-readable form?
Contracts let agents generate compatible clients and servers without inventing field names.
What we look for: openapi.yaml, .graphql / .graphqls files, asyncapi.yaml, .proto files, Flyway/Liquibase migrations for schema evolution.
Example (payments-api): Gap without OpenAPI for the public REST surface; Met with a versioned spec checked into docs/api/.
G: Governance & Compliance
Question: Are changes reviewed, owned, and auditable?
Especially important when agents open PRs: branch protection and ownership files keep automation inside guardrails.
What we look for: CODEOWNERS, branch protection (via GitHub signals), SECURITY.md, pull request templates.
Example: Blocked when the repo is on GitLab but governance rows expect gh evidence; Met on GitHub with protection on main and a CODEOWNERS file.
H: Delivery Readiness
Question: Can this artifact ship through a repeatable pipeline?
Containers, orchestration config, and IaC show the path from commit to deploy.
What we look for: Dockerfile, Helm charts, Kubernetes manifests, Terraform (in-repo or linked), CI deploy stages.
Example (payments-api): Met with Dockerfile + GitHub Actions deploy workflow.
Example (acme-ios): N/A for Dockerfile when the app ships to the App Store; Fastlane + Xcode Cloud documented instead.
Example: Blocked when Terraform lives only in acme-infra and the scan could not reach it.
I: Token Efficiency
Question: Will an agent waste context on noise?
Large unscoped trees, missing ignore files, and one giant doc file burn context window budget.
What we look for: .cursorignore / .claudeignore, sensible exclusions (node_modules/, build/), layered docs instead of one megabyte README, bounded “always on” rule scope.
Example (web-checkout): Gap without .cursorignore (build output indexed); Met after excluding dist/, .next/, and coverage reports.
Severity inside each dimension
Every criterion is tagged High, Medium, or Low severity. High-severity gaps hurt the score most and bubble to the top of the AI Resolution Hub.
| Severity | Typical examples |
|---|---|
| High | Missing AGENTS.md, no branch protection, tests not runnable in CI |
| Medium | Thin README, missing contract file, no .editorconfig |
| Low | Optional conventions, minor structural niceties |
Example: Two repos each have one gap. payments-api missing agent instructions (High) ranks above handbook missing a low-severity formatting hint (Low) in the Resolution Hub.
A docs repo legitimately scores N/A on Docker and k6 rows. A backend API does not. The rubric adapts to archetype; you are not compared to a one-size-fits-all checklist.