Score a codebase's readiness for autonomous AI agent work across 8 dimensions and produce an improvement roadmap.

version
2026.10.1
GitHub stars
72

Install

/plugin install codebase-readiness@dgalarza-agent-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dgalarza/claude-code-workflows.

Contents

Discovered from source

Agents 1

Agent-Ready Codebase Assessment

Does the codebase support AI agent work, or fight it?

This plugin scores a repository across 8 dimensions and reports where it stands, framed against teams shipping 1,000+ AI-generated pull requests per week.

The result is a score (0-100), a band rating, and a concrete improvement roadmap. Evidence comes from the repository, not from opinions.

Start at the landing page: codebase readiness.

Install

From this repository, after the marketplace is added:

/plugin marketplace add dgalarza/agent-skills
/plugin install codebase-readiness@dgalarza-agent-skills
npx skills add dgalarza/agent-skills --skill codebase-readiness

These commands are the GitHub install path. The landing page is the supported way to get the assessment.

Usage

From a project directory, ask the agent to run the codebase-readiness assessment.

The skill runs four assessment passes. It launches them together when the runtime can run subagents, and runs them one after another in the current agent when it cannot. It scores all 8 dimensions with language-specific rubrics and produces a report. Optionally save the report as AGENT_READY_ASSESSMENT.md.

Score Bands

ScoreBandWhat it means
85–100Agent-ReadySupports autonomous agent work
70–84Agent-AssistedAgents work well with human oversight
50–69Agent-SupervisedAgents need heavy review before merging
30–49Agent-CautionFoundational improvements needed first
0–29Not Agent-ReadySignificant investment required

What Gets Scored

Weights depend on language. Dynamic languages such as Ruby and Python weight tests higher. Static languages such as TypeScript, Go, and Rust weight type safety higher.

DimensionWhat it measures
Test FoundationCoverage, quality, test-to-code ratio, mutation testing
Documentation & ContextCanonical agent instructions, ARCHITECTURE.md, domain context, ADRs, topic docs
Code ClarityFile size, naming, catch-all directories, complexity/duplication/dead-code gate coverage
Architecture ClarityDomain boundary visibility in the file tree, not just conceptual DDD
Type SafetyStrict types, semantic type names, database-level invariants
Consistency & ConventionsLinting, formatting, custom architectural linters, lint-debt baseline treatment
Feedback LoopsCI speed, ephemeral environments, actionable and reproducible quality-gate feedback
Change SafetyCoupling, migrations, feature flags, CI blocking new/worsened debt vs a governed baseline

Layout

The skill lives at skills/codebase-readiness/. This plugin directory is a thin manifest. skills/codebase-readiness here is a symlink to that canonical skill, which Claude Code copies into the plugin cache.

  • Dimension files (references/dimensions/) define what to assess and how to score.
  • Language files (references/languages/) carry language-specific tooling and criteria.
  • Shared references (references/quality-gates.md) cover regression-aware quality gates. Reconnaissance assigns one Gate Maturity Level (L0-L4). Four dimensions each score a distinct slice so nothing is double-counted. Top-band credit requires CI that blocks new or worsened debt.

Next step

If Documentation & Context is a weak dimension, agent-ready scaffolds AGENTS.md, ARCHITECTURE.md, domain-aware docs, and documentation checks. Claude Code 2.1.277+ reads AGENTS.md directly. Existing CLAUDE.md files stay in place.

Want help improving the score?

Built by Damian Galarza.

What each dimension means

If the assessment surfaces gaps to fix with a team, a Foundation Sprint ships one foundation piece in two weeks, with the option to continue on a Production AI retainer.

Sponsors

Details

Marketplace
dgalarza/claude-code-workflows
Source
plugins/codebase-readiness
Category
Community

More from dgalarza/claude-code-workflows

All 11