codebase_readiness_audit v1.0.0

name: "codebase_readiness_audit" description: "Score how ready a codebase is for agent work: can a fresh agent session, with no tribal knowledge, find the instructions, set up reproducibly from locked dependencies, run test and lint commands that pass on a clean tree, work inside safe defaults, and know what done means. Ships a runnable auditor that scores 17 file checks across 7 dimensions for 100 points, plus caps for failures files cannot show, a ranked fix list, and a worked before and after audit (13 to 97). Use when a repo is about to be handed to coding agents, agent output from a repo is hard to verify, onboarding an agent takes repeated human help, or a team wants a readiness score with fixes ordered by what blocks agents most. Harness neutral: any agent tool, any language, any repo host."

Codebase Readiness Audit

Purpose

Answer one question with evidence: could a fresh agent session, dropped into this repo with no chat history and no team member to ask, set up, do a small task, and prove the work is good, without guessing or doing anything unsafe on the way. The audit produces a score out of 100, a grade, a blocker list, and a ranked fix list. It is not a project maturity audit. Governance, community health and release polish do not help an agent run a test command, so they are out of scope here. A repo can be mature and still score low, and a small repo can score high.

Workflow

1. Set the mode and the scope. Say at the start whether this run is report only or fixes applied, and which repo or folder is in scope. Monorepos get one score per package plus one for the root, because an agent works in a package, not in an average.

1. Run the auditor. Run bin/audit_readiness.py <repo-path> --out-dir <audit-folder>. It writes scorecard.csv with the evidence for every point and readiness.md with the score, grade and blockers. Exit code 0 means 70 or more, exit code 1 means below 70, exit code 2 is a usage error. Read the evidence lines before repeating any of them. A flag in the CSV is a lead until you open the file it names.

1. Do the clean-tree run. Copy the repo to a fresh folder, or use a clean checkout, and follow the repo's own written setup exactly as a new session would. Record each command, its exit code and roughly how long it took. Then run the documented test command, the focused test form if one is named, and the lint or typecheck command. Anything the run needed that the docs never mention, a local path, a team member's file, a secret with no documented source, is a finding with the step where it bit. Never run a documented command that deploys, migrates a real database, deletes data or pushes anywhere during an audit. Note it as a dangerous default instead.

1. Apply the caps. Follow references/rubric.md. The script scores what files claim. The caps score what the clean-tree run proved: a test command that fails on an untouched tree caps verification at half, a setup that fails as written caps reproducible setup at half, and instructions that name commands which do not exist cap the instruction score at half. A real secret in a tracked file sets the grade to Not ready until it is rotated, whatever the points say. Write every cap in the report with the points removed.

1. Read the instructions like a stranger. Presence is 8 points. Content is the real check. Using references/rubric.md, read the instruction file and the README and mark whether each names the stack and versions, exact setup and test commands, where source and generated files live, what not to touch, and what done means. Check that the README, the instruction file, the task runner and CI all name the same commands. Drift between them is a finding even when each file reads fine alone.

1. Check safe defaults by hand. Run git ls-files on the repo and look at the tracked names for env files, keys and credentials. Read any script or doc section that runs migrations, deploys, data fixes or deletions and check for a dry run mode, an environment name, or a confirmation step. Look at how generated files and vendored code are marked. An agent follows defaults at machine speed, so a default that is merely risky for a careful person can be a blocker here.

1. Rank the fix list by what blocks agents most. Fixed order: safety blockers first, then a missing or failing test command, then unlocked or machine-bound setup, then missing or wrong instructions, then structure and recovery gaps. Each fix gets the file to change, the exact change, a rough effort of small, medium or large, and the points it recovers from scorecard.csv. Use references/fix-recipes.md for the standard fixes, including the instruction file template in assets/agents-md-template.md.

1. If the mode is fixes applied, apply and re-score. Work the list top down, keeping each fix a small reviewable change. Fill any instruction file from the manifest and CI config in front of you, never from memory of similar projects. After the fixes, rerun the auditor and the clean-tree commands and report before and after scores side by side. A fix that does not move the score or the clean-tree result is not done.

1. Check the worked example when unsure. examples/worked-audit.md audits two small trees that ship with this skill. The before tree scores 13 of 100 with five blockers. The after tree, with an instruction file, a lockfile, safe defaults and real commands added, scores 97 of 100, and its own test run passes. Rerun those commands before trusting the numbers in your own report format.

Output Contract

An audit folder containing: readiness.md and scorecard.csv from the auditor, adjusted for any caps with the caps listed and the points removed, a clean-tree run log naming each command with its exit code and what the docs failed to mention, a ranked fix list in the order from step 7 with files, exact changes, effort and points recovered, and a finished report built from assets/readiness-report-template.md. When fixes were applied, the folder also holds the after versions of readiness.md and scorecard.csv and the before and after scores side by side. Anything not checked, such as services that need a paid account or a platform no auditor could reach, is named in the report under what was not checked. No score is reported without the evidence file behind it.

Operating Rules

1. Evidence or zero. Every point in the report traces to a file in the tree or a command in the clean-tree log. Knowledge a team member states in conversation explains a gap, it does not close one.
2. Files claim, runs prove. Never report a test or setup command as working because it is written down. It works when the clean-tree run in this audit passed, with the exit code recorded.
3. Wrong instructions are worse than none. A missing instruction file makes an agent explore. A wrong one makes it run the wrong commands with confidence. Score the content, not just the presence, and use the cap.
4. Never print a secret. If the audit finds a real secret value in any file, report the file path and the variable name only, stop, and hand the rotation to the owner. Do not copy the value into the report, a fix, or an example file.
5. No destructive commands during an audit. Deploys, migrations against real data, deletions and pushes are read about, never run. The audit's own writes stay inside the audit folder and, in fixes mode, inside the agreed fix list.
6. Harness neutral, always. Accept any instruction file, task runner, CI system or package manager the repo actually uses. Score whether a fresh session can find and follow it, not whether it matches one vendor's layout. Recommend a shared instruction file only when copies have already drifted.
7. Do not pad the score. Adding files just to collect points, like a docs folder a tiny repo does not need, is called out in the report as padding when it happens. The worked example keeps a 3 point gap for exactly this reason.
8. Small repo, fair reading. A single file tool with a clear README, a lockfile and one test command can be agent-ready. Do not demand enterprise machinery. The rubric scales by what a fresh session needs, not by repo size or age.
9. Separate readiness from quality. This audit never grades whether the code is good, the product is sound, or the project is well run. It grades whether an agent can work in the repo safely and verifiably. Say so when a report is shared, so a low score is not read as a verdict on the team.
10. Report counts and commands, not adjectives. Scores before and after, blockers with their evidence, commands with exit codes, fixes with files named. A reader should be able to rerun the auditor and the clean-tree commands and land on the same numbers.