This repository is the Codebase Agentic Readiness Framework. It says what makes a codebase safe for AI coding agents,
and it holds tools that check a codebase. This page is the one router for the documentation. Each page under docs/
is linked below, once. The engine keeps its own docs tree beside its code; its router is under
Components.
To audit a repository, open Claude Code at the root of this repository and say "Audit <repo-path> and write the
output to <output-path>". To fix the findings, say "Start implementing the fixes on <repo-path> based on
<audit-json-path>".
| Page | What it teaches |
|---|---|
| First audit on a fixture | One guided audit on a small sample repository |
| Page | What it does |
|---|---|
| Contribute a change | Move one change from a work branch into dev through a pull request |
| Set up the agent tools | Give your coding agent the code index, or skip it; the one-time offer agents make |
| Install the skills | Put both skills from a release into a project, with no clone |
| Run an audit | Produce a confirmed report through the agent and the audit recipe |
| Implement an audit report | Apply the confirmed findings, one theme per branch |
| Resume an interrupted run | Continue an audit or an implementation after a stop |
| Add a stack profile | Add support for a new toolchain |
| Run the evals | Evaluate the recipes headlessly |
| Page | What it lists |
|---|---|
| Audit master list | Every audit check by area: what passes, why it matters, which playbook fixes it |
| Implement master list | Every playbook by theme: its goal, what it changes per check, what it never does |
| Tools CLI | Each tool's synopsis, inputs, outputs and exit codes |
| Versions | What each version number means, where it is written, and which reports and states the tools read |
| Harness notes | What differs between Claude Code, opencode, Codex and Cursor |
| Checks to framework map | Each check, its requirement and its framework section |
| Evaluation results | Fixture-sweep and real-repository results |
| Self-audit | This repository's own Phase 1 score and the CI ratchet |
| Development tooling | Each tool that checks this repository, its command, its CI job and its pin |
| Branch protection | The branch model, and the rulesets on dev and main |
| Licensing | Which licence covers which files |
| Glossary | The terms of the recipes and tools |
| Page | What it explains |
|---|---|
| Explanation index | The two tracks below, in reading order |
| Purpose and non-goals | What the recipes are, and what they refuse to be |
| How the recipes work | The stages and decisions, for evaluators |
| Trust and safety | What the recipes may do to a repository and a machine |
| Tool contract | The contract that each tool follows |
| Report schema | The schema, its versions and the engine mapping |
| Check catalogue and rubrics | The catalogue, the methods and the rubric anatomy |
| Stack profiles | How profiles adapt checks and playbooks |
| Evaluation | The corpus, the metrics and the models |
| Architecture | A map of the repository's parts and what each reads and writes |
The framework is normative. If a tool disagrees with it, the tool is wrong.
| Page | What it holds |
|---|---|
| Overview | What an agentic-ready codebase is |
| Phased approach | The four phases; the recipes implement Phase 1 |
| Brownfield track | How to make a legacy codebase agentic-ready |
| Tool ecosystem | Index tools and other tools the framework uses |
| Risks and mitigations | The risk register |
| References | Sources |
| Framework glossary | The framework's own terms |
spec/ |
The numbered requirements (REQ-...) for a repository |
greenfield/ |
The recipe and templates for a new project |
The ADR index lists every decision of record, in all five groups. ADRs live beside the component they govern (ADR 0001). The ADR policy says how to add, change and delete one.
| Component | Entry point |
|---|---|
| The audit recipe, its checks, schemas and tools | audit/README.md |
| The implement recipe, its playbooks and tools | implement/README.md |
| The deterministic audit engine (own docs tree) | audit/engine/docs/architecture/README.md |
The worked example shows a real run: two audits of one repository, before and after the implement recipe.
| Page | Use |
|---|---|
| Communication rules | Plain-language rules, diagrams, and how to report and ask for decisions |
| Style guide | The authoring rules for every page |
| Tutorial template | Start a tutorial |
| How-to template | Start a how-to guide |
| Explanation template | Start an explanation page |
| Reference template | Start a reference page |
| Architecture doc template | Start an architecture page |
| ADR policy | How to add, change and delete a decision record |
| ADR template | Start a decision record |
Gates and commit rules: AGENTS.md. Setup and contributing: CONTRIBUTING.md.
Changes: CHANGELOG.md. Releases: RELEASE_PROCESS.md.