Project
agent-readiness-kit
Open source
A readiness audit for repos that want coding agents to work from explicit instructions, repeatable checks, and reviewable boundaries.
- TypeScript
- CLI
- Agent Workflows
- CI
- GitHub Actions
Problem
Coding agents work best when the repository tells them what matters and gives them one deterministic way to prove the work is finished. Many repos rely on tribal knowledge instead: the test command is implied, credentials are required for local flows, review boundaries live in a human's head, and agent instructions either do not exist or grow into context bloat. A codebase can be healthy for humans and still hard for an agent to operate in safely.
Approach
agent-readiness-kit turns that operational contract into a score. The generic preset checks for root agent instructions, focused skill files, a single quality gate, secret scanning, mock/offline paths, AI review boundaries, CI coverage, package metadata, and copy-paste runnable docs. The design-system preset adds checks for token sources of truth, component contracts, accessibility signals, visual verification, human review workflows, and isolated external design input.
Implementation
The package exposes both a CLI and a library API. It reads a project snapshot, runs weighted rules, and returns pass, warn, fail, or skip findings with evidence and recommendations. Output formats cover human text, stable JSON, GitHub Actions annotations, and shields.io badge payloads. CI can enforce a minimum score with --fail-under, while the init command scaffolds an AGENTS.md template and composes a check script from existing package scripts without overwriting existing files.
Quality Bar
The repo dogfoods its own rubric and publishes a calibration table against real repositories, including its own 100/100 generic score and a design-system score for DesignRail. The local CI mirror runs secret checks, lint, typecheck, format checks, tests, coverage, build, and a dry-run package publish. Releases use semantic-release and npm provenance, keeping the tool's package contract as explicit as the project contracts it audits.
First Field Test: 48 to 100
The rubric got its first field test on zod-ai-tool, my own published npm package. It scored 48/100. The repo had a twelve-leg CI matrix, enforced coverage thresholds, and a thorough CONTRIBUTING guide, and the gaps were still real: no agent entry point, no single check command, no secret scanning, and a semantic-release setup where a mislabeled fix: commit publishes an npm version. The knowledge existed for human contributors; nothing placed it where an agent starts. The init command scaffolded AGENTS.md and a check script and moved the score to 82. The remaining 18 points were the actual engineering: filling the instructions with the repo's real rules, writing two skill files for the workflows that repeat, and wiring in a secrets scan. The new gate failed its first run by flagging the scanner I had just added, which is the job description. An A/B test with fresh agents against both states measured the difference: nine files of archaeology to reconstruct the finishing workflow before, one entry-point file and one gate command after.
Stack
TypeScript · Node.js CLI · Vitest · tsup · semantic-release · GitHub Actions · npm provenance