v1.0.0 to v1.1.0

---

name: agent-readiness

description: "Scores how ready a repository is for AI coding agents to work in it effectively, then remediates the gaps - grades agent instruction files, verifiable feedback loops, onboarding reproducibility, and codebase navigability against a fixed 30-signal rubric, stack-agnostic across TypeScript, Python, Go, Rust, Ruby, Java, C#, and PHP/Laravel. Activates when the user says 'is this repo agent-ready', 'readiness report', 'readiness score', 'agent readiness', 'audit this repo for AI agents', 'why do agents struggle in this codebase', 'make this repo agent-friendly', 'audit our agent instruction files', or 'score our agent readiness'. Owns the scoring and the remediation plan; defers the writing of ./docs content to vd:docs, locating code to vd:scout, public documentation sites to vd:docs site, refactoring a change toward its intended architecture to vd:simplify --aggressive, and authoring instruction files and skills to vd:skill-creator."

license: MIT

argument-hint: "[path] [--report | --fix] [--group <1-4|name>]"

metadata:

author: vanducng

---

# Agent Readiness

> An agent's effectiveness in a repo is capped by what the repo lets it verify. Score the affordances, not the code quality.

## Hard rules

1. **Identical repo, identical output.** Score on committed evidence. Prefer existence checks over deep semantic analysis, order signals by id, and cap each rationale at ~500 characters. Record an `as_of` date and score every date-relative clause against it, run runnable checks in the repo's declared environment rather than against whatever the host happens to have installed, and treat missing API access as a fallback to static config evidence - never as non-applicability. Live measurements (CI durations, status APIs) are reported as observations and never change a score. A score that drifts with the host, the clock, or a token's permissions is not a property of the repo. **One signal is explicitly weaker:** `service_dependencies_documented` matches config keys to services by name, so `references/signals.md` marks it `determinism: narrowed` and requires the collected list verbatim in the rationale. That caveat is named rather than hidden; no other signal may claim it.

2. **If evidence is ambiguous, fail the item.** A plausible filename is not a passing check. Optimistic scoring produces a number the user cannot act on.

3. **Every signal is evaluated on every repo.** Stack detection selects which evidence to look for; it never changes which signals are scored. Only signals explicitly marked skippable in the `references/signals.md` registry may score `null`. **A missing or unreadable `references/stacks/<name>.md` is never a skip:** score that stack's signals on each signal's language-agnostic catch-all clause and record the gap in the report. Dropping them shrinks `n` and inflates the pass rate, hiding the finding instead of reporting it.

4. **A fix that breaks existing tests is evidence the fix is wrong, not that the tests are wrong.** Proven the hard way: a readiness pass added a hard-throwing N+1 query guard, 21 tests broke, and the correct resolution was switching the guard to detect-and-log. Never adjust, skip, or delete a test to make a readiness fix pass.

5. **Never game a signal.** No empty placeholder files, no config that technically satisfies a check while providing no value, no disabling a check so it stops failing. A signal exists to make the repo better for an agent, not to raise a number.

6. **Re-score after fixing, never project.** Re-run the full scan **per branch** and report that branch's real before and after. There is no combined after-score across group branches, and an unapplied proposal moves no score - it is reported as pending and unverified. An arithmetic projection ("53.9% should reach ~66%") is unverified and has been wrong.

7. **Auto-apply only what passes the four-part safe test** in `## --fix mode`. Everything else is a proposal the user approves. The per-signal `Fix:` line in `references/signals.md` is the only classification list; there is no second summary to consult.

8. **Isolate the change, one signal group at a time.** Never commit readiness fixes to the mainline. The default is one group per branch and per PR, so a rejected fix cannot block the accepted ones; `references/signals.md` § Branching and re-scoring defines the dirty-tree, existing-branch, no-remote, and trunk-based fallbacks.

## Workflow

### 1. Scope the repository

Resolve the target path (default: the current repo root) and run `references/signals.md` § Preflight, which

gives a defined score-or-skip outcome for a non-git target, no CI config, unrunnable tooling, and a read-only

sandbox. Record `as_of` (the UTC scan date) in the report header.

Discover apps per `references/signals.md` § App discovery: collect candidates from concrete markers

(workspace members, `go.mod`, Cargo members, `pom.xml` modules, `composer.json`, `pyproject.toml`, a

`Dockerfile`, a deployment marker **carrying an explicit source mapping**), subtract the named exclusion paths,

and dedupe to the outermost manifest. An image-only deployment manifest maps to no source directory, so it is

context and not an app. "Could it move to its own repo?" is a tiebreaker only. If 0 candidates survive, count

the repo root as 1. Detect the stack per app per § Stack detection, which is also the index naming each stack's

`references/stacks/<name>.md`; an app may match several, and a signal then passes for that app only when **every

code-bearing stack** in it passes. Record the per-stack verdict so a partial pass stays visible.

**Verify:** print `as_of`, the app list, and the detected stacks before scoring. A wrong N distorts every

app-scope signal, and the user is the cheapest place to catch it.

### 2. Score the signals

Load the signal registry in `references/signals.md` - all 30 ids (7 / 9 / 7 / 7) with scope, skippability, fix

class, and where the evidence lives - then load `references/stacks/<name>.md` for every stack detected in step 1.

The registry defines the denominator; the stack files supply per-language evidence for the 13 stack-heavy signals.

Walk all 30 in id order, recording `id`, group, scope, `numerator/denominator`, the deciding evidence, and a

rationale under ~500 characters. A skipped signal records `null` plus its reason - only its own stated skip

condition qualifies, never an unreachable API, an uninstalled tool, or a missing stack file.

**Verify:** every signal has a score and a named piece of evidence. A verdict with no evidence is a guess -

re-inspect or fail it.

### 3. Report

Follow the canonical template in `references/signals.md` § Report contract: the filename fallback when no Reports

path is injected, one-decimal percentages, the table columns, the sort keys (signals in id order; gaps by group

then id), and any stack that had no file (rule 3). Ranking is **remediation priority, not scoring weight** - all

signals score equally, but fix Group 2 gaps first: they remove the agent's ability to self-check.

**Verify:** recompute the pass rate from the signal table and confirm it matches the headline number.

### 4. Fix (only with `--fix`)

See `## --fix mode`, then return to step 2 and re-score that branch.

## Scoring

Each signal scores a ratio `numerator/denominator`:

| Scope | Denominator | Numerator |

|---|---|---|

| repo | 1 | 1 if it passes, 0 if not |

| app | N = apps discovered | how many apps pass |

| skipped (skippable only) | excluded | `null` |

```

pass_rate_pct = 100 * sum(numerator_i / denominator_i) / n where n = count of non-skipped signals

```

The result is a **percentage in [0, 100]**, rounded half up to **one decimal place** (`53.85` renders

`53.9`) before comparison to a band, so two agents computing the same ratio report the same number and land

in the same band at a boundary. A repo passing every signal scores `100 * n/n = 100.0%` (Level 5); one

passing none scores `0.0%` (Level 1). **All signals are weighted equally**, and skipped signals leave the

denominator entirely, so a repo is never penalised for a signal that does not apply to it.

Bands are half-open, so every pass rate lands in exactly one: `[a, b)` includes `a` and excludes `b`. There

is no Level 6. Report the raw percentage alongside the level so progress within a band stays visible.

| Pass rate (%) | Level | Reading |

|---|---|---|

| `[0, 20)` | Level 1 | An agent works blind; every task needs a human in the loop |

| `[20, 40)` | Level 2 | Basic affordances exist but are unreliable or undocumented |

| `[40, 60)` | Level 3 | An agent can build and test, but cannot navigate or self-verify fully |

| `[60, 80)` | Level 4 | An agent works productively; gaps are specific and known |

| `[80, 100]` | Level 5 | An agent can pick up a task, verify it, and ship it unaided |

## `--fix` mode

**Auto-applyable (safe).** All four must hold:

1. It creates a **new** file rather than editing an existing one.

2. Any check it introduces is **advisory** - lint rules at `warn` severity, CI steps with `continue-on-error: true` - so it cannot fail a build on pre-existing code. Before applying, grep the repo for warning-to-error policies (`--max-warnings=0`, `-Werror`, `-D warnings`, `TreatWarningsAsErrors`, `failOnWarning`, `strict = true` on the linter). Under any of them a `warn` rule is a build failure and the fix is not advisory.

3. It changes **no runtime behaviour**.

4. **No build, CI, dependency, or runtime tool acts on the new file.** It fails this condition when an existing local or remote **tool** discovers it by path and then *does something*: executes code, gates a merge, requests reviewers, opens PRs, switches an interpreter, or joins a run. `CODEOWNERS` requests reviewers, a `dependabot.yml` opens scheduled PRs, a `.github/workflows/*.yml` runs on the next push, a `.nvmrc`/`.python-version`/`.tool-versions` switches the interpreter for everyone, and a linter config at a discovered path joins the next lint run.

## Rationalizations to catch

| Thought | Reality |

|---|---|

| "This config is obviously safe to add" | It is safe only if it is new, advisory, non-runtime, and acted on by no tool. Check all four. |

| "It's a new file, so it can't break anything" | A path a build, CI, or runtime tool acts on takes effect on creation. Condition 4. |

| "An `AGENTS.md` is auto-discovered, so condition 4 blocks it" | Read-only-document carve-out. Nothing executes or gates on it; the stub rule is the guard. |

| "The suite is red but the commands all work" | `verification_baseline_green`. An agent there cannot tell its regression from the baseline. |

| "`warn` severity can't fail CI" | It does under `--max-warnings=0`, `-Werror`, or `TreatWarningsAsErrors`. Grep first. |

| "The API is unreachable, so this signal is null" | Only a signal's own skip condition nulls it. Fall back to static CI config. |

| "The tests were already fragile" | Rule 4. A fix that breaks tests is the wrong fix. |

| "An empty `.env.example` still passes the check" | Gaming the signal. It has to list the variables the code actually reads. |

| "This repo has no CI, so most signals should be skipped" | Only signals marked skippable may be null. Missing CI is a 0, and that is the finding. |

| "I can compute the new score from the fixes I made" | Rule 6. Projections have been wrong; re-run the scan. |

| "PHP/Go isn't in the rubric, so I'll approximate" | `references/stacks/` holds a file per stack, eight of them, plus a catch-all clause per criterion. Use it. |

| "There's no stack file for this language, so skip its signals" | Rule 3. Score them on the catch-all and report the gap; skipping inflates the rate. |

| "Branch protection would fix three signals at once" | A remote change. Propose it; never apply it. |