ready is the discipline layer that keeps pace with AI velocity —
review criteria as committed definitions, evaluated on every change,
with drift detected automatically before it becomes an incident.
No infrastructure. No SaaS. No subscription.
JSON definitions + Python scanner + CI template.
Quickstart • Docs • Architecture • Verification Types • CI Integration
AI coding tools removed the friction from writing and shipping code. They did not remove the friction from the discipline work — health checks, secrets hygiene, on-call registration, telemetry coverage, auth on every endpoint. Velocity is now AI-speed. Discipline is still person-speed. The gap between the two is where incidents live.
Production breakdowns keep hitting strong engineering orgs — not because they lack talent, but because velocity outran the scaffolding. Smart teams moved fast, skipped the prep work, and found out later that the checks weren't there. ready is the tool that implements this practice. It replaces prep work, not judgment.
| Before | After |
|---|---|
| AI writes code in seconds; readiness checks take hours | Readiness checks run in the same pipeline, same pace |
| Manual checklists that can't keep up with AI velocity | Automated scan on every PR — no human bottleneck |
| Point-in-time review ceremonies | Continuous compliance, not a quarterly ritual |
| Drift detected by incidents | Drift detected before merge |
| Tribal knowledge of what's missing | Structured gap list with file-path evidence |
| "Are we ready?" is a subjective question | "Are we ready?" has a deterministic answer |
| Accepted risks forgotten over time | Accepted risks expire and re-surface automatically |
pip install readiness-as-code
cd your-repo
ready scanWindows / PATH issues? Use
python -m ready scan— works anywhere Python is installed.
ready? — your-service 80% 1 blocking · 2 warnings
✗ No secrets in code
src/config.py:14
→ Remove hardcoded keys. Use environment variables or a secrets manager.
+ 2 warnings (ready scan --verbose)
No config. No accounts. No init required. ready scan auto-detects your project type and runs immediately. When you're ready to customize, run ready init.
When everything is passing:
ready? — your-service 100% ✓ ▲ +12%
One line. The drift indicator appears automatically whenever a committed baseline exists.
Built from production use managing 86+ readiness checkpoints across enterprise reliability engineering at scale. This is the vendor-neutral, portable version of a system that enforces production readiness across real services handling real incidents — not a weekend experiment.
your-repo/
└── .readiness/
├── checkpoint-definitions.json # What to check
├── exceptions.json # Accepted risks + expiry
├── external-evidence.json # Human attestations for non-code artifacts
└── review-baseline.json # Last scan snapshot (committed = audit trail)
Four JSON files and a scanner. Checkpoints resolve through three verification types: code checks (grep/glob/file_exists against the repo), external checks (human attestations for artifacts outside the repo), and hybrid checks (both must pass). → Architecture details · Verification types
Start with a curated pack, then customize:
ready init # Universal starter (default)
ready init --pack web-api # REST/HTTP API checks
ready init --pack security-baseline # Secrets, dependency hygiene, security policy
ready init --pack telemetry # Logging, tracing, metrics, dashboards
ready init --pack engineering-review # Full engineering review (arch, security, testing, AI/RAI)
ready init --pack operational-review # Operational readiness (SLOs, on-call, data, capacity)
ready init --pack governance # SDLC gates + external review attestations
ready init --pack service-migration # Service identity migration, auth provisioning, cutover
ready init --list-packs # Show all available packs| Pack | Checks | Best for |
|---|---|---|
starter |
11 | Any repo |
web-api |
17 | REST/HTTP services |
security-baseline |
8 | Any repo with sensitive data |
telemetry |
8 | Production services |
engineering-review |
26 | Pre-launch engineering review |
operational-review |
14 | Pre-launch operational review |
governance |
15 | SDLC compliance + sign-off tracking |
service-migration |
9 | Service identity migration + cutover |
ready is based on a system used in enterprise reliability engineering environments, enforcing 80+ readiness checkpoints across real services.
It has been used to:
- continuously evaluate production readiness across services
- detect regression before deployment
- reduce reliance on manual review preparation
This open-source version is the portable, vendor-neutral implementation.
Checkpoint packs are continuously tested against real-world repository structures to eliminate false negatives and false positives. Results from our benchmark suite against a representative cloud service repo:
| Checkpoint | Before | After | Issue Fixed |
|---|---|---|---|
| eng-sec-03 Input validation | fail | pass | Nested dirs (src/app/validators/) now detected |
| eng-sec-06 SDL gates in CI | fail | pass | Microsoft tooling (PoliCheck, BinSkim, Roslyn) recognized |
| eng-sec-08 Hardcoded secrets | fail | pass | Test fixtures excluded via exclude_paths |
| eng-doc-04 OpenAPI spec | fail | pass | docs/openapi.yaml pattern added |
Readiness score: 20% → 36% (+16%) on the same repo, same code.
| Checkpoint | Before | After | Issue Fixed |
|---|---|---|---|
| ops-oncall-02 Post-mortem template | fail | pass | POST_MORTEM_TEMPLATE.md case variant detected |
| ops-data-02 Failure modes | fail | pass | failure_modes.md underscore variant detected |
Readiness score: 64% → 79% (+14%) on the same repo, same code.
Secrets detection (eng-sec-08) previously flagged test fixtures as real secrets:
BEFORE: fail — 2 false positives
tests/test_auth.py:2 mock_token = "fake-token-1234567890"
tests/test_auth.py:3 api_key = "test-api-key-for-unit-tests"
AFTER: pass — 0 false positives
Test directories excluded. Production code still scanned.
- Auto-drift detection. If a committed baseline exists, every scan shows a delta:
▲ +12%or▼ -5%. No flags, no extra commands. - Closed-loop work item tracking. Gaps become tracked work items (GitHub, Azure DevOps, Jira); ticket-closed-but-code-failing flags as regression, code-fixed-but-ticket-open as stale.
- Executive scorecard.
ready scorecardgenerates a one-page HTML summary — score ring, forecast, blocking gaps, regression risk, chronic blockers, MTTR. The artifact you forward to leadership or project into a review. - Cross-repo leaderboard.
ready leaderboardranks services by readiness score with medals, bar charts, and ready/not-ready status. Gamification drives adoption without mandates. - Cross-repo aggregation.
ready aggregateturns multiple baselines into an HTML heatmap — "telemetry gaps in 4 of 5 services" is a platform problem, not a team problem. - Expiring accepted risks. Acknowledge a gap with a justification and expiry date; the scanner re-flags it when the expiry passes.
- Predictive readiness.
ready predictforecasts your score trajectory, flags regression-risk checkpoints (currently passing but historically flapping), identifies chronic blockers, and spots stale-green checks that may need tightening. Pure math on scan history — no AI API needed. - HTML dashboard.
ready dashboardgenerates a self-contained HTML dashboard — score ring, sparkline trajectory, blocking gaps, flapping checks, MTTR leaderboard. One file, no dependencies, dark theme. - Readiness audit.
ready auditreports the health of the readiness system itself — exception age, definition staleness, review_by coverage, score trend. - AI-tool remediation context.
ready scan --fix-contextoutputs structured remediation prompts for every failing check — pipe directly toclaude,gh copilot suggest, or any LLM. The scanner provides the context, your AI tool writes the fix. - Codebase-aware inference.
ready inferanalyzes stack, frameworks, dependencies, ADRs, and auth patterns to propose tailored checkpoints you approve one at a time. - AI-assisted authoring.
ready author --from guidelines.mdgenerates a paste-ready prompt for any model (Claude, ChatGPT, Copilot, Cursor, Gemini). - README badge.
ready badgegenerates a shields.io badge from the committed score. - CI gating. Non-zero exit on red failures; templates for GitHub Actions, Azure Pipelines, GitLab CI. → Details
- Azure DevOps extension. Pipeline task publishes each checkpoint as a test case, plus a dashboard widget for score, trend, and blocking count. → Details
- Not a static analysis tool. SonarQube checks code quality. This checks whether your service meets its review requirements.
- Not a policy engine. OPA/Sentinel enforce infra policies at deploy time. This tracks operational and engineering readiness across code and non-code artifacts.
- Not a compliance SaaS. Drata/RegScale automate regulatory frameworks. This enforces your team's own internal review standards.
- Not a replacement for AI coding tools. It's the complement to them — the discipline layer that keeps pace with the velocity they enable.
- Not a replacement for review meetings. This replaces the prep work so the meeting can focus on judgment calls the scanner can't make.
# Scanning
ready scan # Score + blocking items
ready scan --verbose # Full detail — all checks, evidence, fix hints
ready scan --calibrate # Report-only (no exit code failure)
ready scan --json # Machine-readable output
ready scan --baseline FILE # Write baseline snapshot (enables drift tracking)
ready scan --suggest-tuning # Show pattern tuning suggestions after scan
ready scan --fix-context # Output remediation context for AI tools
ready scan --fix-context | claude # Pipe to Claude CLI for auto-fix
ready scan --fix-context --checkpoint ID # Fix context for one checkpoint
# Setup
ready init # Scaffold .readiness/ with starter pack
ready init --pack web-api # Scaffold with a specific pack
ready init --list-packs # List available packs
# Authoring & inference
ready infer # Analyze codebase → propose tailored checkpoints (human approves each)
ready author --from FILE # Generate AI prompt from a guideline document
# Audit trail
ready badge # Generate README badge from current score
ready decisions # Show all active, expiring, and expired exceptions
ready history [BASELINES...] # Show readiness trend from baseline snapshots
ready audit # Audit exception health, definition staleness, and score health
# Work items
ready items --create # Propose + create work items (human approves each)
ready items --verify # Cross-check work items vs code
ready items --verify --auto-reopen # Reopen closed items for regressions
ready items --verify --dry-run # Preview without API calls
# Analytics & observability
ready trends # Score timeline from scan history
ready trends --last 50 # Show last 50 scans
ready health # Chronic failures, flapping, MTTR analysis
ready predict # Forecast trajectory, flag at-risk checks
ready predict --days 14 # Custom forecast horizon
ready scorecard # Executive scorecard (predict + trends + gaps)
ready scorecard --open # Generate and open in browser
ready dashboard # Self-contained HTML readiness dashboard
ready dashboard --open # Generate and open in browser
ready watch # Watch for changes and re-scan continuously
ready watch --interval 5 # Custom poll interval (seconds)
# Cross-repo
ready leaderboard PATHS... # Cross-repo ranked leaderboard
ready leaderboard PATHS... --html # HTML leaderboard with medals
ready aggregate PATHS... # Cross-repo heatmap from multiple baselines
ready aggregate PATHS... --html # Generate self-contained HTML heatmap reportAdd readiness gating to any repo with one step:
# .github/workflows/readiness.yml
name: Readiness Check
on: [pull_request]
jobs:
readiness:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: jtwalters25/readiness-as-code@v0.7.1On pull requests, the action automatically posts a PR comment with the readiness score, blocking count, and pass/fail status — updated on each push.
With options:
- uses: jtwalters25/readiness-as-code@v0.7.1
with:
pack: web-api # auto-init with a checkpoint pack
fail-on-red: "true" # fail the build on blocking gaps
baseline: .readiness/baseline.json
markdown: .readiness/gaps.md
fix-context: .readiness/fix-context.md # AI remediation context artifact
dashboard: .readiness/dashboard.html # HTML dashboard artifactOutputs are available for downstream steps:
- uses: jtwalters25/readiness-as-code@v0.7.1
id: ready
- run: echo "Readiness: ${{ steps.ready.outputs.readiness-pct }}%"| Input | Description | Default |
|---|---|---|
pack |
Checkpoint pack to auto-init with | |
fail-on-red |
Fail the build on blocking gaps | "true" |
baseline |
Write baseline snapshot for drift tracking | |
markdown |
Write markdown gaps checklist | |
fix-context |
Generate AI remediation context (pipe to Claude/Copilot) | |
dashboard |
Generate self-contained HTML dashboard | |
args |
Additional ready scan arguments |
| Output | Description |
|---|---|
readiness-pct |
Readiness percentage (0-100) |
failing-red |
Number of blocking failures |
failing-yellow |
Number of warnings |
passing |
Number of passing checks |
is-ready |
true if no blocking failures |
ready ships a Model Context Protocol server (ready-mcp) so any MCP client — Claude, Cursor, Copilot — can run scans and inspect checkpoints directly.
pip install "readiness-as-code[mcp]"
ready-mcp| Tool | Description |
|---|---|
scan_repo |
Full readiness scan with results |
list_checkpoints |
View all checkpoint definitions |
explain_checkpoint |
Deep-dive on a specific check |
aggregate_baselines |
Cross-repo heatmap for systemic gap detection |
For prompt-based authoring with any model:
ready author --from docs/ops-review.md # generates author-prompt.md, paste into any AI→ MCP setup for Claude Desktop, Cursor, VS Code
These principles define what readiness as code means in practice. They are not implementation choices — they are the practice itself.
- Detection, not decisions. The scanner finds gaps. Humans decide what to do.
- Continuous, not ceremonial. Checked on every PR, not once a quarter.
- Velocity-aware, not velocity-hostile. Designed to run at the speed of AI-assisted development — no human bottleneck in the loop.
- Portable, not hosted. Files in your repo. No infrastructure.
- Evidence-backed, not trust-based. Every assertion has a file path, attestation, or work item.
- Expiring, not permanent. Accepted risks have expiry dates. Nothing is forever.
- Score-first, not report-first. The answer to "are we ready?" is one line. Detail is on demand.
See CONTRIBUTING.md.