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, in-repo secret scanning, local git hooks |
| 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 | Is CI set up, and are merges reviewed and gated? | CI workflows or linked templates, branch protection, required checks |
| 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 |
Four CI questions
CI setup and merge governance share Continuous Integration. The ship path stays on Continuous Delivery. Live pass/fail health stays on SDLC Insights.
| What you are looking at | What it answers |
|---|---|
| Continuous Integration rows: CI on change, CI runs build, CI runs tests, CI static analysis | Is CI configured for this repo? Config can live in the repo, in a linked CI templates repo, or both. Evidence used chips show the source. |
| Continuous Integration (same pillar) | Merge governance: branch protection, required checks, and reviews. |
| Continuous Delivery | Ship path: artifact, deploy, GitOps, and Terraform signals. |
| SDLC Insights → CI Pipeline Insights | Is CI healthy lately (pass/fail, flake, duration)? Live run charts need GitHub Actions. |
A week of red or green Actions runs does not rewrite the Continuous Integration setup rows. A solid workflow with failing runs stays a setup Met or Partial. Health shows on Insights.
CI ships artifact sits on the ship path (Continuous Delivery). Linked CI templates can credit the four setup rows. They do not credit CI ships artifact.
A workflow file with no real on: trigger and jobs: is a stub. CI on change is then Partial, not Met. Build, test, and static analysis rows are graded on their own evidence. The stub does not force them to Gap.
On a Met or Partial setup row, Evidence used names the source: this repository, a linked platform repository (owner/name), or both. A service with no CI config of its own uses the shared workflow catalog from the CI templates selection. See Linked platform repositories.
A: Agentic Readiness Highest weight
Question: If an AI agent lands in this repo today, does it know what to do?
This pillar covers the agent hub (AGENTS.md or CLAUDE.md for your tooling), Cursor or Claude project configuration, skills, ignore files, and commands agents can run without guessing. README setup and run instructions count toward Codebase Hygiene and scriptable build/test rows—not as a substitute for a missing hub.
What we look for: A hub that orients the agent (purpose, boundaries, verified commands, or clear links to README/docs/), plus .cursor/rules/, skills, ignore files, and non-interactive commands. When the repo has a runtime config surface, an env template (.env.example, .env.template, .env.sample, or .env.dist) is part of that convention bar. If config is present and the template is missing, that convention row stays at most Partial (unless the repo has no runtime env to document).
Example (payments-api): Gap without an agent hub; Met when AGENTS.md lists verified npm test / npm run build or points to README sections that do; Partial when the hub file exists but is a placeholder while README is strong.
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 local safety nets reduce onboarding friction.
What we look for: README.md with setup steps, CODEOWNERS, lockfiles (package-lock.json, Gemfile.lock), .editorconfig, in-repo secret scanning, and runnable local git hooks.
In-repo secret scanning: Met when the tree shows a scanner such as gitleaks, detect-secrets, trufflehog, or equivalent in .pre-commit-config.yaml, a CI job that runs that scanner, or husky/lefthook invoking the same. Partial when scanner config is present but unused (empty hooks, commented-out CI step). Gap when a normal commit/CI repo has none of that. GitHub organization or advanced secret scanning alone does not count as Met here; the scan needs evidence in the repo.
Local git hooks: Met when .pre-commit-config.yaml has at least one hook, or husky (with .husky/), or lefthook.yml / .lefthook.yml, or lint-staged wired through husky/lefthook. Partial when those tools are declared but have no runnable hook body. Gap when none of the above exist. CI lint alone does not satisfy this row, and a solid CI lint setup does not force a Gap here either.
Env templates such as .env.example still help people onboard. The scored env-template check lives under Agentic Readiness when the repo has a config surface. Missing an env template does not create a separate hygiene criterion.
Example (web-checkout): Partial when README covers install but omits how to run Storybook; Met when CODEOWNERS routes src/payments/ to the right team.
Example (secrets and hooks): Met on both when .pre-commit-config.yaml runs gitleaks. Gap on local hooks (and usually secrets) when only ESLint runs in CI and there is no husky, lefthook, or pre-commit setup.
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?
On the dashboard this dimension is Continuous Integration: CI setup (on change, build, tests, static analysis, with Evidence used chips) plus merge governance (branch protection, required checks, reviews). Live run health is not scored here. See Four CI questions.
Especially important when agents open PRs: branch protection keeps automation inside guardrails.
What we look for: CI workflows or linked CI templates, branch protection (via GitHub signals), required checks, quality-gate evidence.
How branch protection is read: the platform reads the rules active on your default branch — including rules inherited from organization rulesets — using the read-only access you granted when connecting GitHub. Required pull requests, required status checks, and force-push restrictions defined in rulesets are all visible. GitHub’s older classic branch protection settings require repository admin access that the platform does not request, so a repo protected only by classic rules is reported as a limit on the evidence rather than as a missing control.
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?
On the dashboard this dimension is Continuous Delivery: the ship path (artifact, deploy, GitOps, Terraform). CI ships artifact is part of that path. A linked CI templates repo does not satisfy it. Live run health is not scored here. See Four CI questions.
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 a GitHub API call failed and the deploy workflow could not be verified. That usually counts as not met.
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.