Production readiness

Production Readiness Skill

Overview

Orchestrate deterministic OSS scanners across a multi-language repo (TypeScript/React, Python, containers, Helm/K8s manifests, IaC) and synthesize results into a single audit report. The skill installs missing tools on demand, runs the scanners in parallel where possible, parses their JSON/SARIF output, and writes a human-readable Markdown report plus machine-readable artifacts to .production-readiness/.

This skill differs from LLM-only readiness reviewers by relying on real CVE/secret/IaC databases (OSV, Trivy DBs, TruffleHog verifiers, Checkov policies). The LLM's role is triage and synthesis, not pattern detection.

Tools used (all OSS): Trivy, Semgrep CE, TruffleHog, Gitleaks, detect-secrets, OSV-Scanner, pip-audit, Bandit, Ruff, Hadolint, Dockle, Checkov, kube-score, Polaris, kubescape, OpenSSF Scorecard, Lighthouse CI, axe-core, OWASP ZAP (opt-in), k6 (opt-in), Playwright (opt-in).

When to invoke

Invoke on the signals in the Workflow Router table below (prod-ready check, PRR, pre-release audit, Go/No-Go, ship-readiness scan). Do NOT invoke for narrow questions ("is this one function safe?") — use security-review instead.

Workflow Router

Determine the audit scope before running. This skill has one workflow shape — audit — but the scope varies. The router picks which phases run; every scope converges on the same synthesize-and-verdict phase.

Is the user re-reading a prior audit, or running a new one?
  |
  RE-READ (--cached) --> CACHED REVIEW
  |                       Phases: (verify HEAD unchanged) -> Present cached report
  |                       Refuses if HEAD moved; tells the user to drop --cached.
  |
  NEW AUDIT --> What scope?
           |
           +-> Whole repo, default coverage (no scope flags)
           |     --> FULL AUDIT
           |     Phases: Detect -> Bootstrap -> [default parallel phases] -> Synthesize -> Present
           |
           +-> A named subset of phases (--only / --skip)
           |     --> SCOPED AUDIT
           |     Phases: Detect -> Bootstrap -> [selected phases] -> Synthesize -> Present
           |
           +-> Add runtime/expensive checks (--include=dast,load,visual)
                 --> DEEP AUDIT
                 Phases: Detect -> Bootstrap -> [default + opt-in phases] -> Synthesize -> Present

Signal detection:

Signal in request	Scope
"Is this prod-ready?", "run a PRR", "pre-release audit", "Go/No-Go"	Full Audit
"Just check secrets and deps", "only scan K8s", "skip the frontend checks"	Scoped Audit
"Include a DAST scan", "run load tests too", "capture visual screenshots"	Deep Audit
"Show me the last report", "what did the audit say" (unchanged HEAD)	Cached Review

Stack detection (detect_stack.sh) further prunes phases automatically: a backend-only repo skips frontend, a repo with no K8s manifests skips k8s_iac, regardless of scope. The phase pipeline for each scope is detailed in the sections below.

Phases

The skill runs default phases plus opt-in phases. Phases marked [parallel] run concurrently after detect/bootstrap.

Phase script	Tools	Scope
scripts/detect_stack.sh	—	Stack detection → .production-readiness/stack.json
scripts/bootstrap_tools.sh	brew/pipx/upstream installers	Installs missing OSS scanners
phases/secrets.sh [parallel]	TruffleHog, Gitleaks, detect-secrets	Git history + working tree
phases/deps.sh [parallel]	OSV-Scanner, pnpm/npm audit, pip-audit	TS/JS + Python dependencies
phases/sast.sh [parallel]	Semgrep CE, Bandit, Ruff	Source code (OWASP/typescript/react/python rule packs)
phases/containers.sh [parallel]	Trivy fs (vuln+secret+misconfig), Hadolint	Dockerfiles + working tree
phases/k8s_iac.sh [parallel]	Checkov, kube-score, Polaris, kubescape	environments/*.yaml, Helm
phases/repo_posture.sh [parallel]	OpenSSF Scorecard	Repo metadata (GitHub remote required)
phases/observability.sh [parallel]	grep heuristics	Logger, OTel, /healthz, structured logs
phases/frontend.sh [parallel]	Lighthouse CI	Built SPA (perf/a11y/SEO/best-practices)
phases/resilience.sh [parallel]	Custom Semgrep rules	Timeouts, retries, graceful shutdown, bare except
phases/docs.sh [parallel]	File presence checks	README, RUNBOOK, ARCHITECTURE, ADRs
phases/dast.sh [opt-in]	OWASP ZAP (Docker)	Requires --include=dast --target-url=URL
phases/load.sh [opt-in]	k6 OSS	Requires --include=load and scripts under tests/load/
phases/visual.sh [opt-in]	Playwright	Requires --include=visual --target-url=URL; captures desktop+mobile screenshots
scripts/render_report.py	—	Aggregates raw output → PRODUCTION_READINESS.md + findings.sarif

Invocation

/production-readiness [--only=phase,phase] [--skip=phase,phase] [--include=dast,load,visual] [--target-url=URL] [--fresh] [--cached] [--no-bootstrap] [--out=PATH]

• --only=secrets,deps,k8s_iac — run a subset (overrides defaults).
• --skip=frontend,docs — skip listed default phases. Note: dast, load, visual are NOT default; --skip does not affect them. Use --include to opt them in.
• --include=dast,visual — opt into expensive/runtime phases.
• --target-url=http://localhost:5173 — base URL for dast and visual phases.
• --fresh — invalidate cache, re-run every scanner.
• --cached — display the previous report unchanged (refuses if HEAD has moved).
• --out=docs/PRODUCTION_READINESS.md — output path (parent dir auto-created).
• --no-bootstrap — skip the install step (assume tools already on $PATH).

Workflow

One command

scripts/scan.sh orchestrates everything. It runs detect → bootstrap → phases → render automatically. Steps below describe what scan.sh does internally; you don't normally invoke them yourself.

Step 1 — Detect stack

Calls scripts/detect_stack.sh. Writes .production-readiness/stack.json describing detected languages, package managers, container files, K8s manifests, frameworks. The orchestrator uses this to skip irrelevant phases automatically (e.g., skip the frontend phase on a backend-only repo).

Step 2 — Bootstrap tools

Calls scripts/bootstrap_tools.sh. It checks each scanner on $PATH and installs only what is missing, preferring brew on macOS, pipx for Python tools, falling back to upstream script: install URLs (printed for the user; never auto-piped). On Linux, apt is attempted only if passwordless sudo is available; otherwise the install is skipped with a warning. Pass --no-bootstrap to scan.sh to skip this step.

If a tool is unavailable, the orchestrator marks that phase as SKIPPED — tool unavailable rather than failing the whole run.

Host prerequisites:

• bash 3.2+ — works in practice on macOS's stock /bin/bash. bash 4+ is recommended (and auto-picked-up via #!/usr/bin/env bash if installed via brew install bash).
• jq — required for JSON post-processing in observability.sh and docs.sh. Auto-installed by bootstrap_tools.sh. If you pass --no-bootstrap, install jq yourself first.
• timeout or gtimeout — recommended. macOS users should brew install coreutils for gtimeout. The orchestrator detects either automatically; if neither is found, phases run without a timeout (and emit a warning).

Step 3 — Run scanners

Run scripts/scan.sh with the user's flags. The orchestrator:

1. Loads .production-readiness/stack.json and the --only/--skip filters.
2. Dispatches phase scripts in scripts/phases/*.sh. Independent phases run in parallel via & + wait.
3. Each phase writes .production-readiness/raw/<phase>.<tool>.json.
4. Per-phase exit codes are non-fatal; failures are recorded in .production-readiness/errors.log.
5. Cache: each scan is keyed by git rev-parse HEAD. --cached short-circuits to the cached report only if HEAD matches .cache-key; otherwise it refuses and tells the user to drop --cached. --fresh deletes .production-readiness/raw/ first.

Step 4 — Synthesize report

Run scripts/render_report.py. It:

1. Reads each .production-readiness/raw/*.json and normalizes to a common finding schema (severity, tool, category, path, line, message, remediation).
2. Deduplicates findings that multiple tools surface (e.g., a CVE in both pnpm audit and OSV-Scanner).
3. Applies the rubric in references/report-format.md to compute the Go/No-Go verdict and per-category scores.
4. Writes the report (default PRODUCTION_READINESS.md) using assets/report-template.md as the skeleton.
5. Also writes .production-readiness/findings.sarif for GitHub code-scanning.

Step 5 — Present results

After the report is written, output to the user:

1. The verdict (GO / NO-GO / GO WITH RISKS) and the top 3 blocking issues.
2. The full report path.
3. Suggested next skills to chain: security-review for the diff, github-actions to wire CI gates, doc-authoring for missing runbooks, kanopy-drone-deployer to fix environments/*.yaml.

Rules

• Cite file:line for every finding that has one. If a tool does not emit a path/line, omit the cite — never print a placeholder.
• Differentiate intent. A console.log inside a logger utility (logger.ts, logging/) is INFO, not WARN. The observability phase already excludes those paths.
• Respect .gitignore. Never scan node_modules, dist, build, .venv, __pycache__, .production-readiness.
• Time-box. Default 600 s per phase, total wall clock left to user. Override via PRR_PHASE_TIMEOUT_SEC.
• Always include "What's Good". The report's first content section lists conformant practices so the user sees signal, not just noise.
• Never run write-scope commands. No kubectl apply, no terraform apply, no docker push. Read-only.
• OSS-only. Do not invoke paid/SaaS scanners (SonarCloud, Snyk Cloud, Datadog, Vanta, JFrog Xray) even if API keys are present.
• Verify before recommend. Before suggesting a tool's finding to the user, sanity-check: does the file/line actually exist in the current tree? If a finding is stale, drop it.

Files in this skill

production-readiness/
├── SKILL.md                              ← this file
├── scripts/
│   ├── bootstrap_tools.sh                ← installs missing OSS scanners
│   ├── detect_stack.sh                   ← writes stack.json
│   ├── scan.sh                           ← phase orchestrator
│   ├── render_report.py                  ← finding aggregator + Markdown writer
│   ├── phases/*.sh                       ← one per phase row in the Phases table above
│   └── semgrep-rules/
│       └── resilience.yml
├── references/
│   ├── checklist.md                      ← full PRR checklist (12-Factor + SRE PRR + Well-Architected)
│   ├── tool-matrix.md                    ← tool ↔ dimension mapping with install commands
│   ├── report-format.md                  ← rubric, severities, verdict logic
│   └── cache-management.md               ← cache key strategy, invalidation rules
└── assets/
    └── report-template.md                ← Markdown skeleton for the final report

When working in this skill, load references/checklist.md to answer "what does prod-ready mean for X?" and references/tool-matrix.md to answer "which tool covers Y?". Load references/report-format.md only when synthesizing or interpreting the report.