Agent Readiness Pillars
Eight pillars for comprehensive codebase assessment. Pillars 1-5 measure agent readiness (fixes offered). Pillars 6-8 measure production readiness (reported only).
Pillar 1: Style & Validation
Automated tools that catch bugs instantly. Without them, agents waste cycles on syntax errors and style drift.
Criteria
| ID |
Criterion |
Pass Condition |
| SV1 |
Linter configured |
ESLint, Biome, oxlint, Flake8, Ruff, golangci-lint, or Clippy config exists |
| SV2 |
Formatter configured |
Prettier, Biome, Black, gofmt, or rustfmt config/usage detected |
| SV3 |
Type checking |
TypeScript strict, mypy, pyright, or language with static types |
| SV4 |
Pre-commit hooks |
Husky, pre-commit, lefthook, or similar configured |
| SV5 |
Lint script exists |
lint command in package.json, Makefile, or equivalent |
| SV6 |
Format script exists |
format command available |
Scoring
- ✅ 80%+: All core tools configured
- ⚠️ 40-79%: Partial setup
- ❌ <40%: Missing fundamentals
Pillar 2: Build System
Clear build process that agents can execute reliably.
Criteria
| ID |
Criterion |
Pass Condition |
| BS1 |
Build tool detected |
Vite, webpack, tsc, cargo, go build, Turbo, etc. |
| BS2 |
Build command exists |
build script in package.json/Makefile |
| BS3 |
Dev command exists |
dev or start script available |
| BS4 |
Build output gitignored |
dist/, build/, .next/, target/ in .gitignore |
| BS5 |
Lock file committed |
package-lock.json, pnpm-lock.yaml, Cargo.lock, uv.lock, etc. |
| BS6 |
Monorepo tooling |
Turborepo, Nx, Lerna, or pnpm workspaces (if applicable) |
Scoring
- ✅ 80%+: Reproducible builds
- ⚠️ 40-79%: Builds work but fragile
- ❌ <40%: Build process unclear
Pillar 3: Testing
Test infrastructure that lets agents verify their work.
Criteria
| ID |
Criterion |
Pass Condition |
| TS1 |
Test framework configured |
Jest, Vitest, pytest, go test, etc. |
| TS2 |
Test command exists |
test script available |
| TS3 |
Tests exist |
>0 test files in repo |
| TS4 |
Tests runnable |
pytest --collect-only or equivalent succeeds |
| TS5 |
Coverage configured |
nyc, c8, coverage.py, etc. |
| TS6 |
E2E tests exist |
Playwright, Cypress, or integration tests |
Scoring
- ✅ 80%+: Comprehensive test setup
- ⚠️ 40-79%: Basic testing in place
- ❌ <40%: Testing gaps
Pillar 4: Documentation
Clear docs that tell agents how the project works.
Criteria
| ID |
Criterion |
Pass Condition |
| DC1 |
README exists |
README.md with meaningful content (not just template) |
| DC2 |
CLAUDE.md/AGENTS.md exists |
Agent instruction file present |
| DC3 |
Setup documented |
Installation/setup instructions in README or docs |
| DC4 |
Build commands documented |
How to build/run in README or CLAUDE.md |
| DC5 |
Test commands documented |
How to run tests documented |
| DC6 |
Architecture documented |
ARCHITECTURE.md, ADRs, or docs/ with structure |
Scoring
- ✅ 80%+: Agents can self-serve
- ⚠️ 40-79%: Basic docs present
- ❌ <40%: Agents must guess
Pillar 5: Dev Environment
Reproducible environment setup.
Criteria
| ID |
Criterion |
Pass Condition |
| DE1 |
.env.example exists |
Template for required env vars |
| DE2 |
.env gitignored |
.env in .gitignore |
| DE3 |
Runtime version pinned |
.nvmrc, .python-version, .tool-versions, etc. |
| DE4 |
Setup script or docs |
setup.sh or clear setup instructions |
| DE5 |
Devcontainer available |
.devcontainer/ config present |
| DE6 |
Docker available |
Dockerfile or docker-compose.yml |
Scoring
- ✅ 80%+: One-command setup possible
- ⚠️ 40-79%: Setup mostly documented
- ❌ <40%: Setup requires tribal knowledge
Pillar 6: Observability (Production Readiness)
Informational only — reported but not scored for agent readiness. No fixes offered.
Runtime visibility that helps debug issues.
Criteria
| ID |
Criterion |
Pass Condition |
| OB1 |
Structured logging |
winston, pino, bunyan, structlog, or similar |
| OB2 |
Distributed tracing |
OpenTelemetry, X-Request-ID propagation |
| OB3 |
Metrics collection |
Prometheus, Datadog, NewRelic instrumentation |
| OB4 |
Error tracking |
Sentry, Bugsnag, Rollbar configured |
| OB5 |
Health endpoints |
/health, /healthz, /ready endpoints |
| OB6 |
Alerting configured |
PagerDuty, OpsGenie, or alert rules |
Status Indicators
- ✅ Configured
- ❌ Not detected
Pillar 7: Security (Production Readiness)
Informational only — reported but not scored for agent readiness. No fixes offered.
Security posture and access controls.
Criteria
| ID |
Criterion |
Pass Condition |
| SE1 |
Branch protection |
Main/master branch protected (via gh api) |
| SE2 |
Secret scanning |
GitHub secret scanning enabled |
| SE3 |
CODEOWNERS |
.github/CODEOWNERS file exists |
| SE4 |
Dependency updates |
Dependabot or Renovate configured |
| SE5 |
Secrets management |
.env gitignored, no secrets in code |
| SE6 |
Security scanning |
CodeQL, Snyk, or similar configured |
Status Indicators
- ✅ Configured
- ❌ Not detected
Pillar 8: Workflow & Process (Production Readiness)
Informational only — reported but not scored for agent readiness. No fixes offered.
Team processes and automation.
Criteria
| ID |
Criterion |
Pass Condition |
| WP1 |
CI/CD pipeline |
GitHub Actions, GitLab CI, or similar |
| WP2 |
PR template |
.github/PULL_REQUEST_TEMPLATE.md exists |
| WP3 |
Issue templates |
.github/ISSUE_TEMPLATE/ exists |
| WP4 |
Automated PR review |
CodeRabbit, Greptile, or similar configured |
| WP5 |
Release automation |
Semantic-release, changesets, or similar |
| WP6 |
CONTRIBUTING.md |
Contribution guidelines present |
Status Indicators
- ✅ Configured
- ❌ Not detected
Scoring Summary
Agent Readiness Score (Pillars 1-5)
Used for maturity level calculation and remediation decisions.
| Level |
Name |
Requirements |
| 1 |
Minimal |
<30% overall |
| 2 |
Functional |
30-49% overall |
| 3 |
Standardized |
50-69% overall, all pillars ≥40% |
| 4 |
Optimized |
70-84% overall, all pillars ≥60% |
| 5 |
Autonomous |
85%+ overall, all pillars ≥80% |
Agent Readiness Score = average of Pillars 1-5 scores
Production Readiness Score (Pillars 6-8)
Informational only. Reported for awareness.
Production Readiness Score = average of Pillars 6-8 scores
Overall Score
Overall Score = average of all 8 pillars
What Gets Fixed vs Reported
| Pillars |
Category |
Remediation |
| 1-5 |
Agent Readiness |
✅ Fixes offered via AskUserQuestion |
| 6-8 |
Production Readiness |
❌ Reported only, address independently |
Level 3 (Standardized) is the target for agent readiness. It means agents can handle routine work: bug fixes, tests, docs, dependency updates.
1---2name: agent-readiness-pillars3description: Eight pillars for comprehensive codebase assessment. Pillars 1-5 measure agent readiness (fixes offered). Pillars 6-8 measure production readiness (reported only).4---5# Agent Readiness Pillars67Eight pillars for comprehensive codebase assessment. Pillars 1-5 measure **agent readiness** (fixes offered). Pillars 6-8 measure **production readiness** (reported only).89---1011## Pillar 1: Style & Validation1213Automated tools that catch bugs instantly. Without them, agents waste cycles on syntax errors and style drift.1415### Criteria1617| ID | Criterion | Pass Condition |18|----|-----------|----------------|19| SV1 | Linter configured | ESLint, Biome, oxlint, Flake8, Ruff, golangci-lint, or Clippy config exists |20| SV2 | Formatter configured | Prettier, Biome, Black, gofmt, or rustfmt config/usage detected |21| SV3 | Type checking | TypeScript strict, mypy, pyright, or language with static types |22| SV4 | Pre-commit hooks | Husky, pre-commit, lefthook, or similar configured |23| SV5 | Lint script exists | `lint` command in package.json, Makefile, or equivalent |24| SV6 | Format script exists | `format` command available |2526### Scoring27- ✅ 80%+: All core tools configured28- ⚠️ 40-79%: Partial setup29- ❌ <40%: Missing fundamentals3031---3233## Pillar 2: Build System3435Clear build process that agents can execute reliably.3637### Criteria3839| ID | Criterion | Pass Condition |40|----|-----------|----------------|41| BS1 | Build tool detected | Vite, webpack, tsc, cargo, go build, Turbo, etc. |42| BS2 | Build command exists | `build` script in package.json/Makefile |43| BS3 | Dev command exists | `dev` or `start` script available |44| BS4 | Build output gitignored | dist/, build/, .next/, target/ in .gitignore |45| BS5 | Lock file committed | package-lock.json, pnpm-lock.yaml, Cargo.lock, uv.lock, etc. |46| BS6 | Monorepo tooling | Turborepo, Nx, Lerna, or pnpm workspaces (if applicable) |4748### Scoring49- ✅ 80%+: Reproducible builds50- ⚠️ 40-79%: Builds work but fragile51- ❌ <40%: Build process unclear5253---5455## Pillar 3: Testing5657Test infrastructure that lets agents verify their work.5859### Criteria6061| ID | Criterion | Pass Condition |62|----|-----------|----------------|63| TS1 | Test framework configured | Jest, Vitest, pytest, go test, etc. |64| TS2 | Test command exists | `test` script available |65| TS3 | Tests exist | >0 test files in repo |66| TS4 | Tests runnable | `pytest --collect-only` or equivalent succeeds |67| TS5 | Coverage configured | nyc, c8, coverage.py, etc. |68| TS6 | E2E tests exist | Playwright, Cypress, or integration tests |6970### Scoring71- ✅ 80%+: Comprehensive test setup72- ⚠️ 40-79%: Basic testing in place73- ❌ <40%: Testing gaps7475---7677## Pillar 4: Documentation7879Clear docs that tell agents how the project works.8081### Criteria8283| ID | Criterion | Pass Condition |84|----|-----------|----------------|85| DC1 | README exists | README.md with meaningful content (not just template) |86| DC2 | CLAUDE.md/AGENTS.md exists | Agent instruction file present |87| DC3 | Setup documented | Installation/setup instructions in README or docs |88| DC4 | Build commands documented | How to build/run in README or CLAUDE.md |89| DC5 | Test commands documented | How to run tests documented |90| DC6 | Architecture documented | ARCHITECTURE.md, ADRs, or docs/ with structure |9192### Scoring93- ✅ 80%+: Agents can self-serve94- ⚠️ 40-79%: Basic docs present95- ❌ <40%: Agents must guess9697---9899## Pillar 5: Dev Environment100101Reproducible environment setup.102103### Criteria104105| ID | Criterion | Pass Condition |106|----|-----------|----------------|107| DE1 | .env.example exists | Template for required env vars |108| DE2 | .env gitignored | .env in .gitignore |109| DE3 | Runtime version pinned | .nvmrc, .python-version, .tool-versions, etc. |110| DE4 | Setup script or docs | setup.sh or clear setup instructions |111| DE5 | Devcontainer available | .devcontainer/ config present |112| DE6 | Docker available | Dockerfile or docker-compose.yml |113114### Scoring115- ✅ 80%+: One-command setup possible116- ⚠️ 40-79%: Setup mostly documented117- ❌ <40%: Setup requires tribal knowledge118119---120121## Pillar 6: Observability (Production Readiness)122123**Informational only** — reported but not scored for agent readiness. No fixes offered.124125Runtime visibility that helps debug issues.126127### Criteria128129| ID | Criterion | Pass Condition |130|----|-----------|----------------|131| OB1 | Structured logging | winston, pino, bunyan, structlog, or similar |132| OB2 | Distributed tracing | OpenTelemetry, X-Request-ID propagation |133| OB3 | Metrics collection | Prometheus, Datadog, NewRelic instrumentation |134| OB4 | Error tracking | Sentry, Bugsnag, Rollbar configured |135| OB5 | Health endpoints | /health, /healthz, /ready endpoints |136| OB6 | Alerting configured | PagerDuty, OpsGenie, or alert rules |137138### Status Indicators139- ✅ Configured140- ❌ Not detected141142---143144## Pillar 7: Security (Production Readiness)145146**Informational only** — reported but not scored for agent readiness. No fixes offered.147148Security posture and access controls.149150### Criteria151152| ID | Criterion | Pass Condition |153|----|-----------|----------------|154| SE1 | Branch protection | Main/master branch protected (via `gh api`) |155| SE2 | Secret scanning | GitHub secret scanning enabled |156| SE3 | CODEOWNERS | .github/CODEOWNERS file exists |157| SE4 | Dependency updates | Dependabot or Renovate configured |158| SE5 | Secrets management | .env gitignored, no secrets in code |159| SE6 | Security scanning | CodeQL, Snyk, or similar configured |160161### Status Indicators162- ✅ Configured163- ❌ Not detected164165---166167## Pillar 8: Workflow & Process (Production Readiness)168169**Informational only** — reported but not scored for agent readiness. No fixes offered.170171Team processes and automation.172173### Criteria174175| ID | Criterion | Pass Condition |176|----|-----------|----------------|177| WP1 | CI/CD pipeline | GitHub Actions, GitLab CI, or similar |178| WP2 | PR template | .github/PULL_REQUEST_TEMPLATE.md exists |179| WP3 | Issue templates | .github/ISSUE_TEMPLATE/ exists |180| WP4 | Automated PR review | CodeRabbit, Greptile, or similar configured |181| WP5 | Release automation | Semantic-release, changesets, or similar |182| WP6 | CONTRIBUTING.md | Contribution guidelines present |183184### Status Indicators185- ✅ Configured186- ❌ Not detected187188---189190## Scoring Summary191192### Agent Readiness Score (Pillars 1-5)193194Used for maturity level calculation and remediation decisions.195196| Level | Name | Requirements |197|-------|------|--------------|198| 1 | Minimal | <30% overall |199| 2 | Functional | 30-49% overall |200| 3 | Standardized | 50-69% overall, all pillars ≥40% |201| 4 | Optimized | 70-84% overall, all pillars ≥60% |202| 5 | Autonomous | 85%+ overall, all pillars ≥80% |203204**Agent Readiness Score** = average of Pillars 1-5 scores205206### Production Readiness Score (Pillars 6-8)207208Informational only. Reported for awareness.209210**Production Readiness Score** = average of Pillars 6-8 scores211212### Overall Score213214**Overall Score** = average of all 8 pillars215216---217218## What Gets Fixed vs Reported219220| Pillars | Category | Remediation |221|---------|----------|-------------|222| 1-5 | Agent Readiness | ✅ Fixes offered via AskUserQuestion |223| 6-8 | Production Readiness | ❌ Reported only, address independently |224225**Level 3 (Standardized)** is the target for agent readiness. It means agents can handle routine work: bug fixes, tests, docs, dependency updates.
tools-only