codebase-ai-readiness

Cairn is an open-source toolkit of AI agent plugins that measure and improve how ready your codebase is for autonomous AI coding agents — charting a path from AI-assisted coding to verified, end-to-end autonomy.

A cairn is a stack of stones that marks the trail on a climb — each one confirming how far you've come and pointing the way to the next. This project does the same for your codebase's journey to autonomy: marking where you stand today and the path to the next level.

Why

AI coding agents can now generate code faster than humans can review it. The bottleneck has shifted from writing code to trusting it: can an agent change this codebase safely, without a human reading every line? Most codebases were built for human workflows (implicit knowledge, inconsistent tests, fragile CI, unclear ownership, and little machine-readable intent) and agents amplify those weaknesses at machine speed.

Cairn treats autonomy as something you measure and earn, not switch on. Install the plugins in any AI assistant that supports the plugin standard (Claude Code, Cursor, Codex), run a skill, and get back concrete, committable reports.

What you get

• 📊 AI readiness score & autonomy maturity map — where your codebase sits on a 0–5 autonomy scale, a category breakdown, and the blockers holding you at your current level.
• 🗺️ Prioritized improvement roadmap — specific, effort-ranked actions to reach the next level.
• 🔬 Verification strategy — per-component oracles, missing tests, and what to verify to unlock safe autonomous iteration.
• 🚦 AI-smell detection gates — whether your CI catches the failure patterns AI-generated code tends to introduce.
• 🔗 Requirement traceability — proof that every change traces back to an intent, so agents don't silently drift from what was asked.

Who it's for: engineering teams adopting AI coding agents who want a measurable, incremental path to autonomy — not a leap of faith.

Getting started

Installation

Install the plugins in your AI agent:

Claude Code:

Add the marketplace

/plugin marketplace add krokoko/cairn

Add the plugins

/plugin install codebase-ai-readiness@cairn
/plugin install software-verification@cairn

Codex:

1. Clone this repository locally.
2. Open the repo in Codex so it discovers .agents/plugins/marketplace.json.
3. Restart Codex, open the plugin directory, choose the Cairn marketplace, and install a plugin.

Claude-specific PostToolUse hooks are not wired into Codex manifests; skills and references work the same.

Cursor:

Install plugins from a marketplace that indexes this repo, or copy skills into your project's agent configuration per Cursor's plugin documentation.

Usage

Once installed, use the skills via slash commands in your AI agent:

/assess-readiness              # Assess codebase AI readiness
/generate-roadmap              # Generate improvement roadmap
/assess-verification           # Assess verification maturity
/design-strategy               # Design verification strategy
/detect-ai-smells              # Assess AI smell detection gates

Recommended workflow

For a full autonomy readiness pass on a codebase:

1. /assess-readiness → readiness-report.md
2. /generate-roadmap → readiness-roadmap.md
3. /assess-verification → verification-report.md
4. /design-strategy → verification-strategy.md
5. /detect-ai-smells → ai-smells-gates-report.md

Or use natural language triggers:

• "How AI-friendly is this codebase?"
• "What should I improve for AI readiness?"
• "What verification do I need?"
• "Design a verification strategy for this module"

Levels of autonomy

We consider the following levels of autonomy: