# Production Readiness

> Run an OSS-only production readiness audit of a codebase and emit a Markdown report with file:line citations, severity-ranked findings, a "What's Good" section, and a Go/No-Go verdict. Use when the user asks to audit production readiness, run a deployment readiness check, perform a pre-release audit, validate ship-readiness, generate a production readiness report (PRR), or scan for security/observability/scalability/reliability gaps before going live. Triggers on phrases like "production readiness", "PRR", "deployment readiness", "pre-release audit", "ship-readiness", "is this prod-ready", "production audit". Supports phase flags (--only, --skip), opt-in DAST/load/visual phases (--include), caching (--cached, --fresh), and parallel execution.

- Skill: `mohammaddaoudfarooqi/production-readiness` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx skillmds@latest add mohammaddaoudfarooqi/production-readiness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mohammaddaoudfarooqi/production-readiness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: mohammaddaoudfarooqi (https://skillmd.com/u/mohammaddaoudfarooqi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mohammaddaoudfarooqi/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.