Assess Codebase Readiness

Assess codebase readiness

You are assessing the current working directory's codebase against the Readiness Grid — a nine-dimension diagnostic defined at https://framework.ai-native-transformation.com/codebase-readiness.

Produce a structured report: the codebase's state (greenfield / brownfield / hybrid), a score 1-5 per dimension with evidence, an overall readiness level (set by the lowest score, not the average), and a prioritized remediation plan.

Operating rules

1. Actually run commands. Use Bash to collect evidence. Don't guess at coverage or CI times — measure them.
2. Cite evidence. For every score, reference file paths, line numbers, or command output.
3. Score conservatively. If the signal is ambiguous, round down.
4. The ceiling is the lowest score. A codebase with eight 5s and one 1 is at the level of that 1. Agents fail at the weakest link.
5. Apply deferral credit. An intentional, documented deferral (in a spec, ADR, roadmap, or README) scores one level higher than the same gap undocumented. Never apply deferral credit based on a verbal claim — only on something in the repo.
6. Every score below 4 must map to a concrete remediation item. "Add tests" is not concrete. "Add test coverage for src/billing/invoice.ts (currently 0%)" is.
7. Keep the output navigable. Follow the output template exactly. No creative reformatting.

Process

Step 1 — Detect the codebase shape

Before scoring, establish:

• Primary language(s) and framework(s). Read package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.
• Repo size: find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" -o -name "*.php" \) -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" | wc -l
• Test infrastructure: presence of tests/, __tests__/, spec/, *_test.go, etc.
• CI config: check .github/workflows/, .circleci/config.yml, .gitlab-ci.yml, azure-pipelines.yml.

Report what you found in the opening section of the scorecard.

Step 2 — Determine the codebase state

Classify the codebase as one of three states (see https://framework.ai-native-transformation.com/brownfield-strategy#first-is-your-codebase-actually-brownfield):

• Greenfield — new codebase, not yet in production or young enough that the architecture is still being actively designed. Low scores are usually scheduling decisions, not debt. Signal: short git history (5% of type annotations).
• 3: Types enforced; some escape hatches.
• 4: Strict mode on; any rare and justified ( 600.
• 2: Many 1000+ line files, responsibilities tangled.
• 3: p50 under 500 lines, some outliers over 1000.
• 4: p50 under 300 lines, outliers rare and justified.
• 5: Files sized to one responsibility each; largest files are intentional.

4. Module boundary clarity

Signals to collect:

• Directory structure: find . -maxdepth 3 -type d -not -path "*/node_modules*" -not -path "*/.git*" -not -path "*/dist*" -not -path "*/build*" -not -path "*/.next*" | head -50
• Dependency graph (if available): npx madge --json src/ for JS/TS, pydeps for Python, or the language equivalent.
• Boundary violations: check for lint rules like @typescript-eslint/no-restricted-imports, Nx boundary rules, import-linter for Python.
• Sample cross-cutting concerns (auth, logging, data access): grep -rn "import.*auth\|import.*logger\|import.*db" src/ | head -20.

Scoring rubric:

• 1: No visible modular structure; everything reaches everything.
• 2: Structure on paper, violated in practice.
• 3: Clear high-level modules, occasional leaks.
• 4: Enforced boundaries (lint/check rules), stable contracts.
• 5: Module graph is a navigable map; architecture documented and current.

5. API directness

Signals to collect:

• Find data/API access patterns: grep -rn "fetch\|axios\|\.request\|\.query\|\.exec\|HttpClient" src/ | head -30.
• Detect Factory/Registry patterns: grep -rn "Factory\|\.resolve\b\|\.dispatch\b\|\.invoke\b" src/ | head -20.
• Sample 3 representative API-calling files and read them. Is the HTTP/SQL call visible at the call site, or hidden?

Scoring rubric:

• 1: All API access via opaque abstractions (Factory, dynamic dispatchers, ORM magic with invisible queries).
• 2: Significant abstraction; traceable with effort.
• 3: Mix of direct and abstracted; common patterns clear.
• 4: Mostly direct calls with typed responses; abstraction limited to cross-cutting concerns.
• 5: Call sites show what's happening; no hidden network or database operations.

6. Documented intent

Signals to collect:

• ADR/decision-log presence: find . -type d -iname "adr*" -o -iname "decisions*" -o -iname "rfc*".
• Module-level docs: find . -name "README.md" -not -path "*/node_modules/*".
• CLAUDE.md or AGENTS.md: ls CLAUDE.md AGENTS.md 2>/dev/null.
• Sample 5 non-trivial modules. Read the main file. Can you explain why it exists from what's documented, or only what it does from the code?

Scoring rubric:

• 1: No intent documentation. Code is the only truth.
• 2: Scattered docs, often stale. No ADR process.
• 3: Module-level READMEs, some ADRs.
• 4: Current ADR log, intent documented for critical modules, CLAUDE.md / AGENTS.md in place.
• 5: Every non-trivial decision has a spec or ADR; historical context preserved; documentation current enough to trust.

Note: this dimension is LLM-assisted by necessity. Static signals are weak. Read modules and judge.

7. Observability

Signals to collect:

• Telemetry libraries: grep -r "opentelemetry\|datadog\|sentry\|newrelic\|honeycomb" package.json requirements.txt go.mod Gemfile composer.json 2>/dev/null.
• Structured logging: grep -r "winston\|pino\|structlog\|zap\|slog\|logrus\|log/slog" package.json requirements.txt go.mod 2>/dev/null; sample a representative file and check for structured log output vs. console.log / print.
• Error tracking: Sentry, Bugsnag, Rollbar etc. presence.
• Metrics: Prometheus, StatsD, Datadog APM, OpenTelemetry instrumentation.

Scoring rubric:

• 1: No structured logs, no traces, no metrics, no error tracking.
• 2: Some logs, no tracing.
• 3: Structured logs and basic metrics; error tracking in place.
• 4: Full telemetry (logs + traces + metrics) with query access.
• 5: Production behavior fully observable; errors produce reproducible test cases; observability itself is part of the dev workflow.

8. Dev and deploy simplicity

Signals to collect:

• Dev setup: read README.md setup section or Makefile; count the commands required to go from fresh clone to running locally.
• Dev environment: check for docker-compose.yml, devcontainer.json, Nix config, or a setup script — anything that makes dev reproducible.
• Deploy: check CI for auto-deploy config; count steps in deploy config.
• Dev/prod parity: look for differences between dev and prod (different databases, different auth, mocked services).

Scoring rubric:

• 1: Dev setup takes days or requires tribal knowledge; deploys manual and fragile.
• 2: Setup scripted but fragile; deploys require runbook steps.
• 3: Setup works with documented commands; deploy reliable.
• 4: One-command setup; one-command (or auto-) deploy.
• 5: Dev, CI, and prod are architecturally identical; anyone can set up and deploy on day one.

9. Dependency and runtime currency

Signals to collect:

• Runtime version: check engines in package.json, python_requires / .python-version, go directive in go.mod, rust-version in Cargo.toml. Compare against current supported versions (e.g., Node 14 is EOL since 2023-04; Python 3.8 is EOL since 2024-10; Go is well-supported; Rust is always current).
• Core framework version: compare against latest stable. For JS/TS: React, Vue, Angular, Next.js, Nuxt, Svelte, Ember. For Python: Django, Flask, FastAPI. For Java: Spring, etc. Count how many major versions behind.
• Abandoned libraries: known abandonware includes Enzyme (React testing, last release 2022, React 16 adapter is highest official), Moment.js (maintenance mode, replaced by Temporal/date-fns/Luxon), jQuery in a React app, AngularJS (v1, not Angular 2+), request/request-promise, Bower. grep for these in package.json / requirements.txt / go.mod.
• Paradigm mix: look for class components + hooks mixed in the same codebase, callbacks + promises, multiple i18n systems, CommonJS + ESM, Python 2/3 code, untyped JS + TypeScript migration in progress.
• Dependency freshness: npm outdated --long | head -50 or pip list --outdated | head -50 for a sample of what's behind.

Scoring rubric:

• 1: Runtime EOL (e.g., Node 14, Python 3.8). Core framework 2+ major versions behind. Abandoned libraries in use (Enzyme, jQuery-in-React, AngularJS 1.x, etc.). Legacy paradigms mixed with modern ones that contradict each other.
• 2: Runtime current but many major deps 1+ versions behind. Some abandoned libraries. Paradigm mix.
• 3: Runtime current. Most deps within 1 major version of current. Occasional legacy pattern with documented reason.
• 4: Runtime current. Deps within current major versions. Consistent modern paradigms.
• 5: Aggressive dependency hygiene. No EOL runtimes, no abandoned libraries. Conventions match current community standards (e.g., hooks-only React, async/await-only JS, Redux Toolkit not raw Redux).

Why this matters: agents are trained on current library versions and idioms. Patterns 2–3 years behind current will cause the agent to produce code that contradicts the existing codebase (hallucinating modern patterns) or to fail at recognizing legacy idioms (producing code that doesn't fit). This is a distinct AI-readiness concern from the other dimensions.

Output template

Produce the report in this exact format.

# Codebase readiness assessment

**Repo:** {repo-name-or-path}
**Primary language:** {language}
**Framework(s):** {frameworks}
**Source files (approx):** {count}
**Date:** {YYYY-MM-DD}

## Codebase state: {Greenfield | Brownfield | Hybrid}

{1-2 sentences on why — git history, production status, architectural maturity.}

## Readiness level: {Level X — {name}}

Ceiling set by dimension {N} ({name}), scoring {X}.

{If any of D1, D2, D5 score 1–2, add a "Blocking dimensions" callout here:}

### Blocking dimensions at 1–2

{List each blocking dimension (D1, D2, D5) that scores 1 or 2. These compromise agent work fundamentally and cannot be compensated by high scores elsewhere. Raise them first.}

## Scorecard

| # | Dimension | Score | Evidence |
|:-:|---|:-:|---|
| 1 | Test coverage and feedback latency | {X} | {one-line summary with numbers} |
| 2 | Type strictness | {X} | {one-line summary} |
| 3 | File size and context legibility | {X} | {one-line summary} |
| 4 | Module boundary clarity | {X} | {one-line summary} |
| 5 | API directness | {X} | {one-line summary} |
| 6 | Documented intent | {X} | {one-line summary} |
| 7 | Observability | {X} | {one-line summary} |
| 8 | Dev and deploy simplicity | {X} | {one-line summary} |
| 9 | Dependency and runtime currency | {X} | {one-line summary: runtime version, framework version lag, any abandoned libs} |

{If any scores include deferral credit, note which dimensions and what document the deferral is based on.}

## Evidence

### 1. Test coverage and feedback latency — {X}/5
{2-4 sentences with specific numbers: coverage %, CI duration, test file count. Paths cited.}

### 2. Type strictness — {X}/5
{Evidence: strict mode on/off, `any` count, escape hatch count, citations}

### 3. File size and context legibility — {X}/5
{p50, p95, largest file with path, notable outliers}

### 4. Module boundary clarity — {X}/5
{Module structure summary, enforcement mechanism (if any), violations observed}

### 5. API directness — {X}/5
{Call-site patterns observed, abstractions detected, specific file:line examples}

### 6. Documented intent — {X}/5
{ADR count/status, README count, CLAUDE.md present?, intent-documentation assessment}

### 7. Observability — {X}/5
{Telemetry SDKs detected, structured logging presence, error tracking, metrics}

### 8. Dev and deploy simplicity — {X}/5
{Dev setup command count, deploy process, dev/prod parity}

### 9. Dependency and runtime currency — {X}/5
{Runtime version and EOL status, framework major version lag, any abandoned libraries detected, paradigm mix}

## Prioritized remediation

Sequenced by ceiling-raising potential. Start with the lowest scores.

1. **{Dimension, action}** — {why this first; concrete first step; expected score lift}
2. **{Dimension, action}** — {...}
3. **{Dimension, action}** — {...}

## Reference

- Framework: https://framework.ai-native-transformation.com/codebase-readiness
- Brownfield strategy: https://framework.ai-native-transformation.com/brownfield-strategy

## Path to Level 5

{Pick ONE of the three templates below based on the codebase state classified above.}

### If Greenfield:
**Path: continue development, close deferred gaps on project milestone timing.**

Items that should close before GA: {list items below 4 that are tied to a production-readiness concern}.
Items that can wait until post-GA if already deferred in the roadmap: {list deferred items}.

No brownfield mode applies — this codebase is not in that situation yet. Re-run the assessment at GA and treat unclosed gaps as brownfield.

### If Brownfield:
**Path: {Remediate in place | Strangler-fig | Rebuild | Isolate and bypass}.**

{One paragraph explaining why this mode is the shortest path to Level 5 for this codebase, based on the evidence: architectural soundness, seam availability, remaining value, structural fixability. Do not consider team size, strategic priorities, or resource allocation — those are human decisions that sit outside this assessment. Reference the decision criteria at https://framework.ai-native-transformation.com/brownfield-strategy#decision-criteria.}

{If the path is Isolate and bypass, state plainly: "Level 5 does not happen in this codebase. The path is through new Level 5-ready codebases alongside it."}

### If Hybrid:
**Path for the greenfield service: continue development.** {Remediation items for the new service.}
**Path for each legacy integration layer:** {For each legacy boundary, recommend a mode: Remediate / Strangler-fig / Rebuild / Isolate.}

Constraints on the output

• Do not invent scores. If a signal is missing (no coverage report, no CI), say so in the evidence section and score conservatively.
• Do not propose remediations that skip the framework's harness-building order. Fast sensors (dimension 1) before legibility (3, 4, 5) before intent (6) before scenarios — this is the sequencing from the framework page. Your remediation plan must respect it.
• Do not recommend a brownfield mode without referencing the decision criteria table at https://framework.ai-native-transformation.com/brownfield-strategy#decision-criteria.
• Keep evidence paragraphs to 2-4 sentences. Link evidence, don't narrate it.
• Never pad. If a dimension scored 5/5 and the evidence is two sentences, that's the right length.

When to invoke

This skill runs in the current working directory. Before starting, confirm with the user that the CWD is the codebase to assess. If the user meant a different path, switch to it first.

If the repo requires commands that depend on installed toolchains not present locally (e.g., running go test but Go isn't installed), note the missing toolchain in the evidence section and score based on static inspection only. Don't stall the assessment over one missing signal.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Kenogami-AI
• Source: Kenogami-AI/codebase-readiness
• License: MIT

Install and usage instructions live in the source repository linked above.