readiness-as-code 0.7.1

Know before you ship — continuous readiness as a folder in your repo.

AI tools made your team faster. They didn't make your team safer.

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

---

Connect with Jeremiah Walters

The Problem: Velocity Outran Discipline

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

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

Quickstart

pip install readiness-as-code

cd your-repo
ready scan

Windows / 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.

Origin

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.

How It Works

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

Checkpoint Packs

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

Proven in Production

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.

Key Capabilities

• 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.
• Cross-repo aggregation. ready aggregate turns 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.
• Readiness audit. ready audit reports the health of the readiness system itself — exception age, definition staleness, review_by coverage, score trend.
• Codebase-aware inference. ready infer analyzes stack, frameworks, dependencies, ADRs, and auth patterns to propose tailored checkpoints you approve one at a time.
• AI-assisted authoring. ready author --from guidelines.md generates a paste-ready prompt for any model (Claude, ChatGPT, Copilot, Cursor, Gemini).
• README badge. ready badge generates 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

What This Is Not

• 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.

Commands

# 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

# 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

# Cross-repo
ready aggregate PATHS...               # Cross-repo heatmap from multiple baselines
ready aggregate PATHS... --html        # Generate self-contained HTML heatmap report

GitHub Action

Add 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.1

With options:

      - uses: jtwalters25/readiness-as-code@v0.7.1
        with:
          pack: web-service           # auto-init with a checkpoint pack
          fail-on-red: "true"         # fail the build on blocking gaps
          baseline: .readiness/baseline.json
          markdown: .readiness/gaps.md

Outputs are available for downstream steps:

      - uses: jtwalters25/readiness-as-code@v0.7.1
        id: ready
      - run: echo "Readiness: ${{ steps.ready.outputs.readiness-pct }}%"

AI Integration

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

Design Principles

These principles define what readiness as code means in practice. They are not implementation choices — they are the practice itself.

1. Detection, not decisions. The scanner finds gaps. Humans decide what to do.
2. Continuous, not ceremonial. Checked on every PR, not once a quarter.
3. Velocity-aware, not velocity-hostile. Designed to run at the speed of AI-assisted development — no human bottleneck in the loop.
4. Portable, not hosted. Files in your repo. No infrastructure.
5. Evidence-backed, not trust-based. Every assertion has a file path, attestation, or work item.
6. Expiring, not permanent. Accepted risks have expiry dates. Nothing is forever.
7. Score-first, not report-first. The answer to "are we ready?" is one line. Detail is on demand.

Contributing

See CONTRIBUTING.md.

License

MIT