agent-readiness-kit

Score whether a repo is ready for coding agents to work in it.

The check is deliberately practical. It looks for project-specific instructions, focused skills, deterministic quality gates, mock/offline defaults, secret scanning, human review boundaries, CI coverage, and npm release hygiene. For design-system repos, it adds token, component-contract, accessibility, visual verification, and external design-input checks.

The rubric rewards the patterns that make agents effective in practice: layered instructions, focused skills, hook-based gates, mock-first workflows, and human-in-the-loop review. For a living example, see DesignRail, a design-system repo that runs this audit in CI with the design-system preset. The audit itself is fully standalone: your repo needs nothing but the CLI.

Install

Run it once from npm:

npx agent-readiness-kit audit .

Or run it once with pnpm:

pnpm dlx agent-readiness-kit audit .

Install it locally:

npm install --save-dev agent-readiness-kit
# or
pnpm add -D agent-readiness-kit

Start A Repo On The Right Path

init scaffolds the two highest-weight pieces and never overwrites anything that exists:

agent-readiness init .

It creates an AGENTS.md template (with clearly marked sections to fill in), composes a check script in package.json from your existing lint/typecheck/format/test scripts when one is missing, then runs the audit and prints your score with next steps.

Run An Audit

agent-readiness audit .

Run the design-system preset:

agent-readiness audit . --preset design-system

Use JSON for custom dashboards:

agent-readiness audit . --format json

Emit GitHub Actions annotations (warnings and errors show up inline on the workflow run):

agent-readiness audit . --format github

Fail CI below a threshold:

agent-readiness audit . --preset design-system --fail-under 85

What It Checks

The generic preset scores 100 points across:

| Area | What the audit looks for | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Instructions | Root agent instructions (AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules, copilot-instructions), specificity, and size | | Skills | Dedicated skill files (.claude/skills, agents/*.SKILL.md, .cursor/rules) for repeated or high-risk workflows | | Deterministic gates | A single quality gate (package scripts, Makefile, justfile, tox, pre-commit) plus secret scanning | | Safety | Mock, offline, or fixture paths that do not require private credentials | | AI boundaries | Human review, confidence, rationale, uncertainty, and schema validation | | CI | Install (npm, pip, cargo, poetry, bundler, ...), lint, typecheck, test, and build coverage | | Release | npm-facing package metadata; marked N/A and excluded from the score when the repo has no package.json | | Docs | Copy-paste runnable commands |

The design-system preset adds:

| Area | What the audit looks for | | -------------- | ----------------------------------------------------------------------------------- | | Tokens | A design-token source of truth and guidance | | Components | Component registry, schema, Storybook, or mapping contracts | | Accessibility | A11y rules and check signals | | Visual gates | Visual regression, screenshot, Playwright, Chromatic, or design verification | | Human review | Accept, reject, edit, compare, and compliance review language | | External input | Figma or design-file input isolated behind public fixtures and optional credentials |

Output

Text output is meant for humans:

Agent readiness: 91/100 (excellent)
Preset: design-system
Root: /repo

Category scores:
- Instructions: 100/100 (28/28)
- Deterministic Gates: 100/100 (20/20)

Findings:
- [PASS] agent.instructions.present (12/12): Found AGENTS.md.
- [WARN] docs.commands (3/6): README has limited runnable command coverage.

JSON output is a stable object with the same score, category scores, findings, evidence, and recommendations.

Real-World Scores

Scores from running the audit against a small set of real repositories. The spread is intentional: the tool rewards explicit agent scaffolding rather than general project quality:

| Repository | Preset | Score | Verdict | | --------------------------------------------------------------------------------------- | ------------- | ------- | --------------- | | connordibble/agent-readiness-kit | generic | 100/100 | excellent | | connordibble/DesignRail | design-system | 92/100 | excellent | | colinhacks/zod | generic | 57/100 | partially ready | | connordibble/zod-ai-tool | generic | 48/100 | not ready yet | | expressjs/express | generic | 16/100 | not ready yet | | pallets/flask | generic | 18/100 | not ready yet | | BurntSushi/ripgrep | generic | 15/100 | not ready yet |

Generated with node scripts/calibrate.mjs --update-readme.

Scores are snapshots from the current rubric rather than endorsements or permanent grades. A low score usually points to missing agent workflow docs rather than overall project quality.

Regenerate this table after pnpm build with:

node scripts/calibrate.mjs --update-readme

The repo list lives at the top of scripts/calibrate.mjs; remote entries are shallow-cloned, audited locally, and deleted.

The Path To 90

Every rule maps to a concrete fix. Worked top-down by weight, most repos can reach 90 in an afternoon:

| Rule | Weight | Fastest fix | | -------------------------------- | ------ | -------------------------------------------------------------------------------- | | agent.instructions.present | 12 | Run agent-readiness init to scaffold AGENTS.md | | deterministic.quality-gate | 12 | Add one check command (script or Makefile) that runs lint, typecheck, and test | | agent.instructions.specificity | 10 | Fill the template with this repo's mission, safety rules, and exact commands | | skills.structure | 10 | Split repeated or high-risk workflows into .claude/skills/<name>/SKILL.md | | mock.offline-default | 10 | Document the fixture/mock path; make real credentials optional | | ai.boundary.human-loop | 10 | State who reviews AI output, and require rationale and schema validation | | deterministic.secret-scan | 8 | Wire gitleaks, secretlint, or a secrets:check script into the gate | | ci.readiness | 8 | Run install, lint, typecheck, and test in CI, or delegate to the gate | | release.package-metadata | 8 | Fill npm publish metadata (skipped automatically when not an npm package) | | agent.instructions.bloat-control | 6 | Keep instructions between 10 and 260 lines; link deeper docs instead of inlining | | docs.commands | 6 | Make README install, usage, and test commands copy-paste runnable |

Library API

import { auditProject, initProject } from "agent-readiness-kit";

const result = await auditProject({
  root: process.cwd(),
  preset: "design-system",
});

console.log(result.score);

// Scaffold AGENTS.md and a check script without overwriting anything:
const scaffolded = await initProject({ root: process.cwd() });
console.log(scaffolded.created);

Score Interpretation

| Score | Meaning | | ------ | --------------------------------------------------------------------- | | 90-100 | Excellent. The repo has strong agent guidance and gates. | | 75-89 | Ready with minor gaps. Good enough for CI with known cleanup. | | 55-74 | Partially ready. Agents can work, but reviewers will carry more risk. | | 0-54 | Not ready yet. Add instructions and deterministic checks first. |

Warnings earn half credit. Failing rules earn no credit. Rules that do not apply to a repo (for example npm publish metadata in a repo without package.json) are marked SKIP and excluded from the denominator, so non-npm repos are not penalized for not being npm packages. The default command never fails your process on score alone. Use --fail-under when you want CI enforcement.

The score measures how legible a repo is to coding agents, not whether agent output will be correct. The checks are deterministic text and file heuristics: they can be satisfied by writing the right words in the right files. Treat the score as a checklist you can enforce, not a certification.

CI

- name: Audit agent readiness
  run: pnpm dlx agent-readiness-kit audit . --preset design-system --fail-under 85

Add --format github to surface each warning and failure as an inline annotation on the workflow run:

- name: Audit agent readiness
  run: pnpm dlx agent-readiness-kit audit . --format github --fail-under 85

Or use the bundled composite action:

- uses: connordibble/agent-readiness-kit/action@v1
  with:
    preset: generic
    fail-under: "85"

Score Badge

--format badge emits a shields.io endpoint payload. Publish it anywhere CI can write (a gist, GitHub Pages, an artifact host) and reference it:

agent-readiness audit . --format badge > agent-readiness.json

![agent readiness](https://img.shields.io/endpoint?url=https://<your-host>/agent-readiness.json)

This repo also exposes a local CI mirror:

pnpm ci:check

Scope

audit never edits files. init writes exactly two things — an AGENTS.md template and a check script — and refuses to overwrite anything that already exists. Nothing here calls model providers, and a high score does not make agent output correct. The score says the repo gives agents a clearer contract and gives humans better checks.

Releases

Releases use semantic-release and npm provenance. The GitHub workflow expects a protected environment named release with NPM_TOKEN configured as an environment secret. Follow Conventional Commits:

| Commit type | Release | | ------------------------------ | ------- | | fix: | patch | | feat: | minor | | feat!: or BREAKING CHANGE: | major |

Other commit types do not publish a new version.