Readiness Scores
How to read and interpret the readiness score for each of your repositories.
Where scores appear
Open Agentic Foundation in the sidebar to see every connected repo in a list. Each row shows the overall score (0–100) and a color band. Click a repo name to open its detail view, where the same number sits at the top with a per-dimension breakdown underneath.
The 9 dimensions
What each pillar measures before you drill into criteria.
AI Resolution Hub
Turn gaps from the detail view into a prioritized fix queue.
The overall score
Each repository has one overall readiness score from 0 to 100. It rolls up the nine dimension scores with extra weight on pillars that matter most for day-to-day agent work (especially Agentic Readiness and Test Coverage). It is not a simple average of the nine percentages.
| Band | Range | What it usually means |
|---|---|---|
| Excellent | 85–100 | Strong docs, automation, and agent context. |
| Good | 65–84 | Solid base; a handful of targeted fixes left. |
| Fair | 40–64 | Meaningful gaps; check the Resolution Hub. |
| Needs attention | 0–39 | Structural friction; prioritize top items. |
Example: payments-api might show 58 (Fair) while handbook shows 82 (Excellent). The API repo has fixable gaps; the docs repo simply has a different shape of criteria (many delivery rows are N/A).
Dimension scores
Below the overall score in the detail view, you see all nine dimensions. Each row includes:
| Field | What it tells you |
|---|---|
| Score % | How well this repo meets that pillar’s criteria. |
| Confidence | How much evidence the scan found. Low confidence means thin or missing signals, not necessarily a bad codebase. |
| Status badge | Same band colors as the overall score (Excellent / Good / Fair / Needs attention). |
Example: On web-checkout, Agentic Readiness might be 45% with low confidence because there is no .cursorignore and no agent instructions. Test Coverage might be 72% with high confidence because Jest files and a vitest.config.ts are easy to detect.
Low confidence often means we didn’t find much to measure: no test files, no CI config, or an unfamiliar layout. Add the missing artifacts and both confidence and score usually move on the next scan.
Reading the detail view
Click a repository to open three main areas.
Dimension breakdown
Each dimension expands to show individual criteria with a status:
| Status | Meaning | Quick example |
|---|---|---|
| Met | Fully satisfied. | AGENTS.md lists npm test and npm run build. |
| Partial | Present but incomplete. | README says “run tests” without an exact command. |
| Gap | Missing expected signal. | No .github/workflows/ in a service repo. |
| N/A | Doesn’t apply here. Excluded from the dimension score. | No Dockerfile expected in handbook. |
| Blocked | Couldn’t verify at scan time. | K8s manifests live in acme-infra, not this repo. |
Example: In payments-api → Agentic Readiness, you might see Gap on “Agent instructions” and Met on “Scriptable build & test” because the README has commands but there is no AGENTS.md.
Issues list
A flat list of every Gap, Partial, and Blocked item across all dimensions, sorted High → Medium → Low severity. Each line has a short description and a remediation hint. This is the same content the AI Resolution Hub pulls from, scoped to one repo.
Score history
After two or more completed scans, a trend chart shows how the overall score moved over time. Use it to confirm that a merged PR actually improved readiness.
Example: payments-api goes from 54 → 71 after adding AGENTS.md and a CI test job. The chart should show a step up on the scan date following that merge.
Example: reading one repo end to end
Walk through payments-api (Node/TypeScript API) as a new engineering lead would:
-
1List view
Overall 58 (Fair), last scanned yesterday. Agentic Readiness and Governance look like the weak pillars from the mini breakdown on the row.
-
2Detail header
Nine dimension tiles: Agentic Readiness 41% (low confidence), Test Coverage 68%, Delivery Readiness 75%, and so on.
-
3Drill into Agentic Readiness
Gap: no
AGENTS.md. Partial:.cursor/rules/exists but descriptions are empty. Met: README hasnpm testandnpm run build. -
4Issues list
Top item: “Add agent instructions” (High). Second: “CI does not run tests” (High). Jump to AI Resolution Hub to see the same items ranked against other repos.
When scores update
Scores refresh on every completed scan. Pushing a fix to GitHub does not change numbers until the next run finishes.
| Trigger | What happens |
|---|---|
| Initial onboarding | First scan queues automatically for each visible repo. |
| Scheduled scan | About every 24 hours per connected repo. |
| Manual Re-scan | Click Re-scan on the repo row or Analyze from the list. |
| Failed scan | Previous score stays; the row shows failed status until you retry. |
Typical wait: 5–15 minutes after you trigger a scan. Large monorepos can take longer.
Common questions
Why did only one dimension move?
Fixes are pillar-specific. Adding openapi.yaml lifts API & Contract Design; it won’t move Test Coverage unless you also wire tests.
Why did the overall score drop?
New Gap or Blocked rows appeared: a file was removed, GitHub governance checks failed, or the rubric now detects something that was invisible before. Check the issues list for what changed.
Why is overall “Good” but agents still struggle?
A single Gap in Agentic Readiness (no AGENTS.md, no ignore file) can hurt agents more than the headline number suggests. Read dimension scores, not just the total.