Agent Readiness Criteria
Complete reference of all 81 criteria evaluated across nine technical pillars.
Criteria Format
Each criterion is binary (pass/fail) and includes:
- ID: Unique identifier (snake_case)
- Level: Maturity level (1-5) where criterion is evaluated
- Detection: How to check if the criterion is met
- Impact: What happens when this criterion fails
1. Style & Validation
Automated tools that catch bugs instantly. Without them, agents waste cycles on syntax errors and style drift.
| Criterion |
Level |
Detection |
Impact |
formatter |
1 |
Prettier, Black, Ruff format, gofmt config exists |
Agent submits code with formatting issues, waits for CI, fixes blindly |
lint_config |
1 |
ESLint, Ruff, golangci-lint, or language-specific linter configured |
Style inconsistencies accumulate, harder to review |
type_check |
1 |
TypeScript strict, mypy, Go (static by default) |
Type errors caught late in CI instead of immediately |
strict_typing |
2 |
TypeScript strict:true, mypy strict=true |
Partial typing allows bugs to slip through |
pre_commit_hooks |
2 |
.pre-commit-config.yaml or Husky config |
Checks run in CI instead of locally, slower feedback |
naming_consistency |
2 |
Linter rules or documented conventions |
Inconsistent names make codebase harder to navigate |
large_file_detection |
2 |
Git LFS, pre-commit check-added-large-files |
Large files bloat repository, slow clones |
code_modularization |
3 |
import-linter, Nx boundaries, Bazel modules |
Architecture degrades over time |
cyclomatic_complexity |
3 |
gocyclo, lizard, radon, SonarQube |
Complex functions harder to understand and modify |
dead_code_detection |
3 |
vulture, knip, deadcode in CI |
Unused code clutters codebase |
duplicate_code_detection |
3 |
jscpd, PMD CPD, SonarQube |
Duplicated code increases maintenance burden |
tech_debt_tracking |
4 |
TODO scanner, SonarQube, linter TODO rules |
Tech debt accumulates without visibility |
n_plus_one_detection |
4 |
nplusone, bullet gem, query analyzer |
Performance issues in database queries |
2. Build System
Fast, reliable builds enable rapid iteration. Slow CI kills agent productivity.
| Criterion |
Level |
Detection |
Impact |
build_cmd_doc |
1 |
Build commands documented in README/AGENTS.md |
Agent doesn't know how to build |
deps_pinned |
1 |
Lockfile exists (package-lock.json, uv.lock, go.sum) |
Non-reproducible builds |
vcs_cli_tools |
1 |
gh/glab CLI authenticated |
Can't interact with PRs/issues |
fast_ci_feedback |
2 |
CI completes in <10 minutes |
Agent waits too long for feedback |
single_command_setup |
2 |
One command to set up dev environment |
Agent can't bootstrap quickly |
release_automation |
2 |
Automated release workflow exists |
Manual releases slow deployment |
deployment_frequency |
2 |
Regular releases (weekly+) |
Infrequent deploys signal process issues |
release_notes_automation |
3 |
Auto-generated changelogs/release notes |
Manual release notes are error-prone |
agentic_development |
3 |
AI agent commits visible in history |
No prior agent integration |
automated_pr_review |
3 |
Danger.js, automated review bots |
Reviews require human intervention |
feature_flag_infrastructure |
3 |
LaunchDarkly, Statsig, Unleash, custom system |
Hard to ship incrementally |
build_performance_tracking |
4 |
Build caching, timing metrics |
Build times creep up unnoticed |
heavy_dependency_detection |
4 |
Bundle size analysis (webpack-bundle-analyzer) |
Bundle bloat goes unnoticed |
unused_dependencies_detection |
4 |
depcheck, deptry in CI |
Bloated dependency tree |
dead_feature_flag_detection |
4 |
Stale flag detection tooling |
Abandoned flags clutter code |
monorepo_tooling |
4 |
Nx, Turborepo, Bazel for monorepos |
Cross-package changes are error-prone |
version_drift_detection |
4 |
Version consistency checks |
Packages diverge silently |
progressive_rollout |
5 |
Canary deploys, gradual rollouts |
All-or-nothing deployments are risky |
rollback_automation |
5 |
One-click rollback capability |
Slow recovery from bad deploys |
3. Testing
Tests verify that changes work. Without them, agents can't validate their own work.
| Criterion |
Level |
Detection |
Impact |
unit_tests_exist |
1 |
Test files present (_test., .spec.) |
No way to verify basic correctness |
unit_tests_runnable |
1 |
Test command documented and works |
Agent can't run tests |
test_naming_conventions |
2 |
Consistent test file naming |
Tests hard to find |
test_isolation |
2 |
Tests can run in parallel |
Slow test runs |
integration_tests_exist |
3 |
E2E/integration test directory |
Only unit-level coverage |
test_coverage_thresholds |
3 |
Coverage enforcement in CI |
Coverage drifts down |
flaky_test_detection |
4 |
Test retry, quarantine, or tracking |
Flaky tests erode trust |
test_performance_tracking |
4 |
Test timing metrics |
Slow tests accumulate |
4. Documentation
Documentation tells the agent what it needs to know. Missing docs mean wasted exploration.
| Criterion |
Level |
Detection |
Impact |
readme |
1 |
README.md exists with setup instructions |
Agent doesn't know project basics |
agents_md |
2 |
AGENTS.md or CLAUDE.md exists |
Agent lacks operational guidance |
documentation_freshness |
2 |
Key docs updated in last 180 days |
Stale docs mislead agent |
api_schema_docs |
3 |
OpenAPI spec, GraphQL schema, or API docs |
Agent must reverse-engineer APIs |
automated_doc_generation |
3 |
Doc generation in CI |
Docs drift from code |
service_flow_documented |
3 |
Architecture diagrams (mermaid, PlantUML) |
Agent lacks system context |
skills |
3 |
Skills directory (.claude/skills/, .factory/skills/) |
No specialized agent instructions |
agents_md_validation |
4 |
CI validates AGENTS.md commands work |
AGENTS.md becomes stale |
5. Dev Environment
Reproducible environments prevent "works on my machine" issues.
| Criterion |
Level |
Detection |
Impact |
env_template |
2 |
.env.example or documented env vars |
Agent guesses at configuration |
devcontainer |
3 |
.devcontainer/devcontainer.json exists |
Environment setup is manual |
devcontainer_runnable |
3 |
Devcontainer builds and works |
Devcontainer is broken |
database_schema |
3 |
Schema files or migration directory |
Database structure undocumented |
local_services_setup |
3 |
docker-compose.yml for dependencies |
External services need manual setup |
6. Debugging & Observability
When things go wrong, observability helps diagnose issues quickly.
| Criterion |
Level |
Detection |
Impact |
structured_logging |
2 |
Logging library with structured output |
Logs hard to parse |
code_quality_metrics |
2 |
Coverage reporting in CI |
No visibility into code quality |
error_tracking_contextualized |
3 |
Sentry, Bugsnag with context |
Errors lack context for debugging |
distributed_tracing |
3 |
OpenTelemetry, trace IDs |
Can't trace requests across services |
metrics_collection |
3 |
Prometheus, Datadog, or custom metrics |
No runtime visibility |
health_checks |
3 |
Health/readiness endpoints |
Can't verify service status |
profiling_instrumentation |
4 |
CPU/memory profiling tools |
Performance issues hard to diagnose |
alerting_configured |
4 |
PagerDuty, OpsGenie, alert rules |
Issues discovered late |
deployment_observability |
4 |
Deploy tracking, dashboards |
Can't correlate issues to deploys |
runbooks_documented |
4 |
Runbooks directory or linked docs |
No guidance for incident response |
circuit_breakers |
5 |
Resilience patterns implemented |
Cascading failures |
7. Security
Security criteria protect the codebase and data.
| Criterion |
Level |
Detection |
Impact |
gitignore_comprehensive |
1 |
.gitignore excludes secrets, build artifacts |
Sensitive files committed |
secrets_management |
2 |
GitHub secrets, vault, cloud secrets |
Hardcoded secrets |
codeowners |
2 |
CODEOWNERS file exists |
No clear ownership |
branch_protection |
2 |
Protected main branch |
Unreviewed changes to main |
dependency_update_automation |
3 |
Dependabot, Renovate configured |
Dependencies go stale |
log_scrubbing |
3 |
Log sanitization for PII |
Sensitive data in logs |
pii_handling |
3 |
PII redaction mechanisms |
PII exposure risk |
automated_security_review |
4 |
CodeQL, Snyk, SonarQube in CI |
Security issues caught late |
secret_scanning |
4 |
GitHub secret scanning enabled |
Leaked credentials |
dast_scanning |
5 |
Dynamic security testing |
Runtime vulnerabilities missed |
privacy_compliance |
5 |
GDPR/privacy tooling |
Compliance gaps |
8. Task Discovery
Structured task management helps agents find and understand work.
| Criterion |
Level |
Detection |
Impact |
issue_templates |
2 |
.github/ISSUE_TEMPLATE/ exists |
Inconsistent issue quality |
issue_labeling_system |
2 |
Consistent labels on issues |
Issues hard to categorize |
pr_templates |
2 |
pull_request_template.md exists |
PRs lack context |
backlog_health |
3 |
Issues have descriptive titles, labels |
Unclear what to work on |
9. Product & Analytics
Connect errors to insights and understand user behavior.
| Criterion |
Level |
Detection |
Impact |
error_to_insight_pipeline |
5 |
Sentry-GitHub issue creation automation |
Errors don't become actionable issues |
product_analytics_instrumentation |
5 |
Mixpanel, Amplitude, PostHog, Heap |
No user behavior data to inform decisions |
Skipped Criteria
Some criteria are skipped based on repository type:
- Libraries: Skip deployment-related criteria (progressive_rollout, health_checks)
- CLI tools: Skip web-specific criteria (dast_scanning)
- Database projects: Skip N+1 detection (they ARE the database)
- Single apps: Skip monorepo tooling criteria
The analysis script automatically determines which criteria to skip based on detected repository characteristics.
1---2name: agent-readiness-criteria3description: Complete reference of all 81 criteria evaluated across nine technical pillars.4---5# Agent Readiness Criteria67Complete reference of all 81 criteria evaluated across nine technical pillars.89## Criteria Format1011Each criterion is binary (pass/fail) and includes:12- **ID**: Unique identifier (snake_case)13- **Level**: Maturity level (1-5) where criterion is evaluated14- **Detection**: How to check if the criterion is met15- **Impact**: What happens when this criterion fails1617---1819## 1. Style & Validation2021Automated tools that catch bugs instantly. Without them, agents waste cycles on syntax errors and style drift.2223| Criterion | Level | Detection | Impact |24|-----------|-------|-----------|--------|25| `formatter` | 1 | Prettier, Black, Ruff format, gofmt config exists | Agent submits code with formatting issues, waits for CI, fixes blindly |26| `lint_config` | 1 | ESLint, Ruff, golangci-lint, or language-specific linter configured | Style inconsistencies accumulate, harder to review |27| `type_check` | 1 | TypeScript strict, mypy, Go (static by default) | Type errors caught late in CI instead of immediately |28| `strict_typing` | 2 | TypeScript strict:true, mypy strict=true | Partial typing allows bugs to slip through |29| `pre_commit_hooks` | 2 | .pre-commit-config.yaml or Husky config | Checks run in CI instead of locally, slower feedback |30| `naming_consistency` | 2 | Linter rules or documented conventions | Inconsistent names make codebase harder to navigate |31| `large_file_detection` | 2 | Git LFS, pre-commit check-added-large-files | Large files bloat repository, slow clones |32| `code_modularization` | 3 | import-linter, Nx boundaries, Bazel modules | Architecture degrades over time |33| `cyclomatic_complexity` | 3 | gocyclo, lizard, radon, SonarQube | Complex functions harder to understand and modify |34| `dead_code_detection` | 3 | vulture, knip, deadcode in CI | Unused code clutters codebase |35| `duplicate_code_detection` | 3 | jscpd, PMD CPD, SonarQube | Duplicated code increases maintenance burden |36| `tech_debt_tracking` | 4 | TODO scanner, SonarQube, linter TODO rules | Tech debt accumulates without visibility |37| `n_plus_one_detection` | 4 | nplusone, bullet gem, query analyzer | Performance issues in database queries |3839---4041## 2. Build System4243Fast, reliable builds enable rapid iteration. Slow CI kills agent productivity.4445| Criterion | Level | Detection | Impact |46|-----------|-------|-----------|--------|47| `build_cmd_doc` | 1 | Build commands documented in README/AGENTS.md | Agent doesn't know how to build |48| `deps_pinned` | 1 | Lockfile exists (package-lock.json, uv.lock, go.sum) | Non-reproducible builds |49| `vcs_cli_tools` | 1 | gh/glab CLI authenticated | Can't interact with PRs/issues |50| `fast_ci_feedback` | 2 | CI completes in <10 minutes | Agent waits too long for feedback |51| `single_command_setup` | 2 | One command to set up dev environment | Agent can't bootstrap quickly |52| `release_automation` | 2 | Automated release workflow exists | Manual releases slow deployment |53| `deployment_frequency` | 2 | Regular releases (weekly+) | Infrequent deploys signal process issues |54| `release_notes_automation` | 3 | Auto-generated changelogs/release notes | Manual release notes are error-prone |55| `agentic_development` | 3 | AI agent commits visible in history | No prior agent integration |56| `automated_pr_review` | 3 | Danger.js, automated review bots | Reviews require human intervention |57| `feature_flag_infrastructure` | 3 | LaunchDarkly, Statsig, Unleash, custom system | Hard to ship incrementally |58| `build_performance_tracking` | 4 | Build caching, timing metrics | Build times creep up unnoticed |59| `heavy_dependency_detection` | 4 | Bundle size analysis (webpack-bundle-analyzer) | Bundle bloat goes unnoticed |60| `unused_dependencies_detection` | 4 | depcheck, deptry in CI | Bloated dependency tree |61| `dead_feature_flag_detection` | 4 | Stale flag detection tooling | Abandoned flags clutter code |62| `monorepo_tooling` | 4 | Nx, Turborepo, Bazel for monorepos | Cross-package changes are error-prone |63| `version_drift_detection` | 4 | Version consistency checks | Packages diverge silently |64| `progressive_rollout` | 5 | Canary deploys, gradual rollouts | All-or-nothing deployments are risky |65| `rollback_automation` | 5 | One-click rollback capability | Slow recovery from bad deploys |6667---6869## 3. Testing7071Tests verify that changes work. Without them, agents can't validate their own work.7273| Criterion | Level | Detection | Impact |74|-----------|-------|-----------|--------|75| `unit_tests_exist` | 1 | Test files present (*_test.*, *.spec.*) | No way to verify basic correctness |76| `unit_tests_runnable` | 1 | Test command documented and works | Agent can't run tests |77| `test_naming_conventions` | 2 | Consistent test file naming | Tests hard to find |78| `test_isolation` | 2 | Tests can run in parallel | Slow test runs |79| `integration_tests_exist` | 3 | E2E/integration test directory | Only unit-level coverage |80| `test_coverage_thresholds` | 3 | Coverage enforcement in CI | Coverage drifts down |81| `flaky_test_detection` | 4 | Test retry, quarantine, or tracking | Flaky tests erode trust |82| `test_performance_tracking` | 4 | Test timing metrics | Slow tests accumulate |8384---8586## 4. Documentation8788Documentation tells the agent what it needs to know. Missing docs mean wasted exploration.8990| Criterion | Level | Detection | Impact |91|-----------|-------|-----------|--------|92| `readme` | 1 | README.md exists with setup instructions | Agent doesn't know project basics |93| `agents_md` | 2 | AGENTS.md or CLAUDE.md exists | Agent lacks operational guidance |94| `documentation_freshness` | 2 | Key docs updated in last 180 days | Stale docs mislead agent |95| `api_schema_docs` | 3 | OpenAPI spec, GraphQL schema, or API docs | Agent must reverse-engineer APIs |96| `automated_doc_generation` | 3 | Doc generation in CI | Docs drift from code |97| `service_flow_documented` | 3 | Architecture diagrams (mermaid, PlantUML) | Agent lacks system context |98| `skills` | 3 | Skills directory (.claude/skills/, .factory/skills/) | No specialized agent instructions |99| `agents_md_validation` | 4 | CI validates AGENTS.md commands work | AGENTS.md becomes stale |100101---102103## 5. Dev Environment104105Reproducible environments prevent "works on my machine" issues.106107| Criterion | Level | Detection | Impact |108|-----------|-------|-----------|--------|109| `env_template` | 2 | .env.example or documented env vars | Agent guesses at configuration |110| `devcontainer` | 3 | .devcontainer/devcontainer.json exists | Environment setup is manual |111| `devcontainer_runnable` | 3 | Devcontainer builds and works | Devcontainer is broken |112| `database_schema` | 3 | Schema files or migration directory | Database structure undocumented |113| `local_services_setup` | 3 | docker-compose.yml for dependencies | External services need manual setup |114115---116117## 6. Debugging & Observability118119When things go wrong, observability helps diagnose issues quickly.120121| Criterion | Level | Detection | Impact |122|-----------|-------|-----------|--------|123| `structured_logging` | 2 | Logging library with structured output | Logs hard to parse |124| `code_quality_metrics` | 2 | Coverage reporting in CI | No visibility into code quality |125| `error_tracking_contextualized` | 3 | Sentry, Bugsnag with context | Errors lack context for debugging |126| `distributed_tracing` | 3 | OpenTelemetry, trace IDs | Can't trace requests across services |127| `metrics_collection` | 3 | Prometheus, Datadog, or custom metrics | No runtime visibility |128| `health_checks` | 3 | Health/readiness endpoints | Can't verify service status |129| `profiling_instrumentation` | 4 | CPU/memory profiling tools | Performance issues hard to diagnose |130| `alerting_configured` | 4 | PagerDuty, OpsGenie, alert rules | Issues discovered late |131| `deployment_observability` | 4 | Deploy tracking, dashboards | Can't correlate issues to deploys |132| `runbooks_documented` | 4 | Runbooks directory or linked docs | No guidance for incident response |133| `circuit_breakers` | 5 | Resilience patterns implemented | Cascading failures |134135---136137## 7. Security138139Security criteria protect the codebase and data.140141| Criterion | Level | Detection | Impact |142|-----------|-------|-----------|--------|143| `gitignore_comprehensive` | 1 | .gitignore excludes secrets, build artifacts | Sensitive files committed |144| `secrets_management` | 2 | GitHub secrets, vault, cloud secrets | Hardcoded secrets |145| `codeowners` | 2 | CODEOWNERS file exists | No clear ownership |146| `branch_protection` | 2 | Protected main branch | Unreviewed changes to main |147| `dependency_update_automation` | 3 | Dependabot, Renovate configured | Dependencies go stale |148| `log_scrubbing` | 3 | Log sanitization for PII | Sensitive data in logs |149| `pii_handling` | 3 | PII redaction mechanisms | PII exposure risk |150| `automated_security_review` | 4 | CodeQL, Snyk, SonarQube in CI | Security issues caught late |151| `secret_scanning` | 4 | GitHub secret scanning enabled | Leaked credentials |152| `dast_scanning` | 5 | Dynamic security testing | Runtime vulnerabilities missed |153| `privacy_compliance` | 5 | GDPR/privacy tooling | Compliance gaps |154155---156157## 8. Task Discovery158159Structured task management helps agents find and understand work.160161| Criterion | Level | Detection | Impact |162|-----------|-------|-----------|--------|163| `issue_templates` | 2 | .github/ISSUE_TEMPLATE/ exists | Inconsistent issue quality |164| `issue_labeling_system` | 2 | Consistent labels on issues | Issues hard to categorize |165| `pr_templates` | 2 | pull_request_template.md exists | PRs lack context |166| `backlog_health` | 3 | Issues have descriptive titles, labels | Unclear what to work on |167168---169170## 9. Product & Analytics171172Connect errors to insights and understand user behavior.173174| Criterion | Level | Detection | Impact |175|-----------|-------|-----------|--------|176| `error_to_insight_pipeline` | 5 | Sentry-GitHub issue creation automation | Errors don't become actionable issues |177| `product_analytics_instrumentation` | 5 | Mixpanel, Amplitude, PostHog, Heap | No user behavior data to inform decisions |178179---180181## Skipped Criteria182183Some criteria are skipped based on repository type:184- **Libraries**: Skip deployment-related criteria (progressive_rollout, health_checks)185- **CLI tools**: Skip web-specific criteria (dast_scanning)186- **Database projects**: Skip N+1 detection (they ARE the database)187- **Single apps**: Skip monorepo tooling criteria188189The analysis script automatically determines which criteria to skip based on detected repository characteristics.
tools-only