Agent readiness

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.

What this skill is - and isn't

Skill	Question it answers	Output
vd:agent-readiness (this)	"How well can an AI agent work in this repo, and what is missing?"	A scored report; optionally safe additive fixes plus a proposal list
vd:docs	"Are the shared ./docs/ files true and current?" (site subcommand: "How do we publish a public docs site?")	Written docs content / a Starlight site
vd:scout	"Where does X live in this repo?"	A file map, no writes
vd:simplify --aggressive	"What would this change look like if the architecture existed from day one?"	A refactored diff
vd:skill-creator	"How do I author a skill an agent reliably loads?"	A SKILL.md

This skill measures and remediates affordances. It may create a scaffold (an AGENTS.md, an ARCHITECTURE.md) only when the repo's own evidence fills it enough to pass the signal, then hands the prose to the owning skill. It never writes the architecture narrative, and never refactors code to raise a score.

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.

Read-only-document carve-out. A file that only a human or an agent reads passes condition 4 even though it is auto-discovered: instruction files (AGENTS.md, CLAUDE.md), PR and issue templates, docs stubs. Nothing executes them, nothing gates on them, no build changes. An instruction file does change future agent behaviour - that is the fix's entire intent, not a side effect to guard against - and the stub rule below keeps it honest: evidence-filled, never hollow.

Qualifying categories, all four checked: a dead-code or duplicate-code tool config plus a standalone runner script nothing yet calls, a marker scanner script, and the read-only documents above. Categories failing condition 4: CI workflow files, review and dependency automation config, runtime-version selectors. Every per-signal classification lives on the Fix: line in references/signals.md (rule 7), never a list here.

Stub rule. A generated stub may be auto-applied only when it already satisfies the signal it targets - real resolved commands, real top-level directory names, over the 100-character floor. A hollow skeleton (# Architecture + TODO) fails its own signal's content clause and violates rule 5, so it is propose-only; hand the writing to vd:docs or vd:skill-creator.

Propose only (never auto-apply). Any one of these disqualifies a fix:

Category	Why it is not safe
Editing or reformatting an existing file	Overwrites a maintainer decision; a tree-wide reformat buries the next diff
Changing runtime behaviour	A readiness score is not worth a production incident
Gating CI or blocking merges	Turns a pre-existing gap into a broken build for everyone
Adding a dependency	Supply-chain and maintenance cost the user must weigh
Lowering or disabling an existing check	Reduces real safety to raise a number
A new file a build, CI, dependency, or runtime tool acts on	Takes effect on creation - condition 4. A file only a human or agent reads is carved out
A warn-severity rule in a repo that treats warnings as errors	The advisory rule is a build failure there
A stub the repo cannot fill from real evidence	Fails the signal it targets and games it - rule 5
Repo metadata or remote changes (branch protection, labels, enabling scanning)	Outside the working tree; often irreversible without admin

Present proposals as a concrete diff or a checklist the user approves item by item.

After fixing: run the repo's own commands (test, lint, build) in its declared environment, report exactly what was run and the result, then re-score that branch per rule 6. When the commands cannot be run (tooling absent or execution not permitted), say so and report which fixes are therefore unverified; never claim a green run you did not observe.

Anti-patterns

• Running the full test suite to score test_command_runnable. Slow, can mutate state, and conflates "the command works" with "the tests pass". Use a collection-only or dry-run flag.
• Hardcoding one stack's evidence. The original rubric checked tsconfig.json strict and [tool.black] with no fallback, so Go, Rust, and PHP repos matched no rule and the scoring improvised. Every criterion needs its per-language clauses (references/stacks/) plus a catch-all.
• Auto-applying a formatter. Passes format_check_available and rewrites blame for the whole tree.
• Creating an AGENTS.md with a heading and a TODO. Fails its own 100-character floor and teaches an agent nothing. A stub earns auto-apply only when generated content already passes the signal.
• Treating "it is a new file" as "nothing acts on it". CODEOWNERS, dependabot.yml, a workflow file, and .nvmrc all act the moment they land. Condition 4 exists because of this - and it is about tools acting, not about a document being read.
• Scoring a signal on a live API result. The same commit must score the same with a token and without one. CI durations and status checks are observations in the rationale, never score inputs.
• Scoring against the host. A missing binary is not a repo gap, and a token without API access is not a skippable signal.
• Scoring app-scope signals against the root only. Root-only instructions in a 6-app monorepo are 1/6, not 1/1. Collapsing that hides exactly the gap the user is asking about.
• Reporting a projected score. Only a re-run counts.
• Rewriting the rubric mid-run. Adjusting a criterion because the repo fails it turns the score into an opinion.

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.

Workflow position

"is this repo agent-ready?"
        ↓
vd:agent-readiness --report  →  scored report + ranked gaps
        ↓ (--fix)
branch per group → safe fixes applied → proposals for approval
        ↓
re-score per branch (real, not projected)  →  vd:code-review  →  vd:ship
        ↓
hand off writing: vd:docs (architecture, guidelines) · vd:skill-creator (skills/)