app-production-readiness
Build portable apps (any stack - TypeScript, Python, Go, Rust) for localhost, Docker, Vercel, Netlify, Railway, Render, Fly.io, Cloudflare Free plan, then run an adaptive 21-gate production-readiness
SKILL.mdskills/app-production-readiness/SKILL.md
GitHubPortable Deploy + QA (Production Readiness)
Build once, run anywhere free. Then prove it: looks right everywhere, loads fast, feels polished, audits green — and every claimed PASS is re-derived from evidence.
0. Quick Start & Bootstrap
Verify environment tooling before running audits:
python scripts/bootstrap_env.py # Health-check Node, Python, Playwright, Lighthouse
python scripts/bootstrap_env.py --install # Auto-install missing browsers / dependencies
Run one-command review (starts app, auto-fixes mechanical issues, evaluates scoped gates, writes qa/report.md):
python scripts/review.py --root <app_root> --serve --fix
1. App Inputs & Agnostic Guarantees
Resolve dynamic inputs from arguments, environment, or codebase (never assume port 3000):
| Input | How to detect | Default |
|---|---|---|
APP_URL |
$ARGUMENTS → APP_URL env → package.json → framework configs → ask user |
http://localhost:3000 |
PORT |
Parse from APP_URL, PORT env, Dockerfile EXPOSE, or fly.toml |
3000 |
PKG |
pnpm-lock.yaml→pnpm, bun.lockb→bun, yarn.lock→yarn, else npm |
npm |
ROUTES |
Crawl / links + framework routes dir (app/, pages/, src/routes/) |
/ + 2 key routes |
HEALTHZ |
src/**/health*, /api/health, else / status 200 |
/healthz or / |
Auto-detect via stdlib script:
python scripts/detect_env.py <root>
App-agnostic rules: Accept any project root (JS/TS, Python, Go, Rust, static), detect without guessing, support CLI overrides, and never alter apps outside declared scope.
2. Portable Build & Deploy Platform Matrix
See deploy-matrix.md and free-tier-limits.md.
- Targets: localhost, Docker, Vercel/Netlify, Railway/Render/Fly, Cloudflare Pages/Workers.
- Rules: Env-driven (
process.env.*,os.environ),.env.exampleverified, Cloudflare behind flags, no paid-only SDKs. - README Standards: See readme-standard.md and template assets/README.template.md. Verify with
python scripts/check_readme.py <root>.
3. The 21 Quality Gates
Not all apps have every surface. Gate scoping classifies gates into applies, conditional, or not_applicable from codebase evidence:
python scripts/gate_scope.py --root <app_root>
See checklists: visual + performance in qa-checklists.md, hardening in hardening-checklists.md, and depth in depth-gates.md.
Gate A — Cross-browser visual QA
Check Chrome, Edge, Firefox, Safari (WebKit) at 1280/1440/1920 + 360/390 across default, hover, active, focus, disabled, loading, empty, and error states.
Proof: python scripts/capture_screenshots.py --root <root> --url <APP_URL> --routes /,/a --out docs/screenshots --browsers chromium,firefox,webkit → PNGs + docs/screenshots/manifest.json.
Gate B — Performance / low resource
Code-split routes, tree-shake, WebP/AVIF, minify, cache headers. JS budget <= 200 kB gzipped per route, dep <= 50 kB. CWV: LCP <= 2.5s, CLS <= 0.1, INP <= 200ms.
Proof: python scripts/bundle_report.py <root> → per-route gzip budgets, asset sizes, source map checks.
Gate C — Design polish (measured rubric + human sign-off)
Consistent hierarchy, spacing rhythm, 44px touch targets, 150-250ms transitions, 45-75 char lines, reduced-motion. Rubric score >= 0.85.
Proof: python scripts/design_polish.py --root <root> and stored sign-off python scripts/design_polish.py --root <root> --record-signoff --reviewer "<name>" --verdict approved → writes qa/signoff/design.json.
Gate D — Desktop Lighthouse audit
Incognito desktop preset on key routes. Targets: Perf >= 90, A11y >= 95, BP >= 95, SEO >= 90. Fallback uses absorbed lighthouse_audit.py. CI config: lighthouse-ci.md.
Proof: python scripts/lighthouse_run.py --url <APP_URL> --routes /,/a --out qa/lighthouse → qa/lighthouse/lighthouse-summary.json.
Gate E — Security
Zero HIGH vulnerabilities. Independent scanners run own rules + absorbed vulnerability_security_scan.py. Dependency audit via dep_audit.py. Deep mode playbooks in security/.
Proof: python scripts/security_scan.py <root> and python scripts/dep_audit.py <root> (deep mode: python scripts/security_audit.py --root <root>).
Gate F — Accessibility (WCAG 2.1 AA)
axe-core zero critical/serious issues + keyboard-only traversal, focus visibility, logical tab order, contrast >= 4.5:1.
Proof: python scripts/a11y_audit.py --url <APP_URL> --routes /,/a --browsers chromium,firefox,webkit → qa/a11y/a11y-report.json.
Gate G — SEO & metadata
Unique title + meta description per page, Open Graph/Twitter tags, canonical URL, robots.txt, sitemap.xml, semantic HTML, lang attribute, 404 handling.
Proof: python scripts/runtime_check.py --url <APP_URL> --routes /,/a --healthz <HEALTHZ> and python scripts/seo_static.py --root <root>.
Gate H — Tests & correctness
Unit tests for business logic, integration for APIs. Project test script passes, no .only or skipped tests.
Proof: python scripts/preflight.py <root> checks for skipped tests, and scripts/absorbed/test_runner.py detects and runs test runner.
Gate I — Reliability & error handling
Route-level error boundaries, try/catch with timeouts, no unhandled rejections, loading/empty/error UI. Deep mode boots app with platform runner.
Proof: python scripts/runtime_check.py validates healthz and 404s; deep mode python scripts/deploy_smoke.py --root <root> confirms platform boot → qa/deploy-smoke.json.
Gate J — Docs & DX
README matches standard (readme-standard.md), .env.example synced, CONTRIBUTING and LICENSE present.
Proof: python scripts/check_readme.py <root> and python scripts/preflight.py <root>.
Gate K — Observability
Structured JSON logging in production, request/correlation IDs, error tracking hook, health check endpoint.
Proof: python scripts/verify_claims.py validates >= 3 independent source signals for observability.
Gate L — Free-tier cost check
Verify every service used has a free plan; document fallback behaviors when limits are reached. Proof: README contains free-tier limits table verified against free-tier-limits.md.
Gate M — README & screenshots (delivery gate)
Production README with >= 3 real screenshots, generated contact sheet, resolved image paths, and manifest.
Proof: python scripts/check_readme.py <root> and docs/screenshots/manifest.json.
Gate N — Business rules (executable contract + domain sign-off)
Execute business rule scenarios (qa/scenarios.json) against live app, paired with fingerprint-bound domain sign-off (qa/signoff/business-rules.json).
Proof: python scripts/business_logic_check.py --root <root> --url <APP_URL> and python scripts/signoff.py.
Gate O — Load & soak
p95 <= 1000ms, error rate <= 1%, soak time-series drift <= 50% between first and last third of run.
Proof: python scripts/load_check.py --url <APP_URL> --routes /,/a --duration 10 --soak 60 --soak-interval 10 → qa/load.json.
Gate P — Migrations & schema
Rollback paths defined, destructive DDL guarded, idempotency verified.
Proof: python scripts/migration_check.py --root <root> (deep mode: python scripts/migration_apply.py --root <root> applies and rolls back chain) → qa/migrations.json.
Gate Q — Privacy & GDPR (policy + legal sign-off)
Privacy policy reachable and linked, consent before tracking, no PII in logs/storage/analytics, fingerprinted legal sign-off.
Proof: python scripts/privacy_check.py --root <root> --url <APP_URL> → qa/signoff/privacy.json.
Gate R — i18n & RTL
Catalogs with matching translation keys, declared doc language, RTL dir switching and logical CSS properties.
Proof: python scripts/i18n_check.py --root <root>.
Gate S — Assistive technology contract
Screen-reader contract: programmatic labels, aria-live regions for async updates, landmark roles, skip links.
Proof: python scripts/at_check.py --root <root>.
Gate T — Payment & email flows
No raw card data in code, webhook signatures verified, integer minor currency units, email providers without header injection.
Proof: python scripts/payment_email_check.py --root <root> (deep mode: python scripts/payment_email_live.py --root <root>).
Gate U — Code quality & AI-risk debt
Complexity thresholds, no duplicate blocks, no dead markers (TODO/FIXME/mock), clean type coverage, React performance patterns.
Proof: python scripts/code_quality.py --root <root>.
Panel review
Run reviewer prompts in panel-review/ across correctness, security, architecture, UX, and reliability.
4. Tooling & Automation
| Script | Purpose | Usage |
|---|---|---|
scripts/review.py |
Complete orchestrator: scope → fix → measure → judge → qa/report.md |
python scripts/review.py --root <root> --serve [--fix] [--json] |
scripts/bootstrap_env.py |
Environment dependency checker and installer (Playwright, browsers, Lighthouse) | python scripts/bootstrap_env.py [--install] [--json] |
scripts/serve.py |
Starts app for review using production or dev runner | python scripts/serve.py --root <root> [--dev] [--wait] |
scripts/fixes.py |
Safe auto-fixes: .env.example, .dockerignore, robots.txt, LICENSE, Next headers |
python scripts/fixes.py --root <root> [--only env-example,dockerignore] |
scripts/framework_profiles.py |
Profile layer preventing framework defaults from being marked as defects | python scripts/framework_profiles.py <root> |
scripts/gate_scope.py |
Scopes the 21 gates to the codebase in front of you | python scripts/gate_scope.py --root <root> |
scripts/detect_env.py |
Detects port, URL, package manager, framework, routes, healthz | python scripts/detect_env.py <root> |
scripts/preflight.py |
Production-readiness checks (30 checks with framework scoping) | python scripts/preflight.py <root> |
scripts/security_scan.py |
Secrets and insecure patterns scanner | python scripts/security_scan.py <root> |
scripts/security_audit.py |
Deep security audit ledger and finding validator | python scripts/security_audit.py --root <root> |
scripts/dep_audit.py |
Dependency vulnerability audit for npm, pip, cargo, go | python scripts/dep_audit.py <root> |
scripts/bundle_report.py |
Bundle budgets, asset sizes, source map checks | python scripts/bundle_report.py <root> |
scripts/deploy_verify.py |
Target verification for Docker, Vercel, Netlify, Fly, Render, Cloudflare | python scripts/deploy_verify.py <root> |
scripts/deploy_smoke.py |
Boots app with platform runner and probes healthz | python scripts/deploy_smoke.py --root <root> |
scripts/runtime_check.py |
Live HTTP probe for headers, health, SEO metadata, 404 behavior | python scripts/runtime_check.py --url <APP_URL> --routes /,/a |
scripts/seo_static.py |
Static SEO checks + Generative Engine Optimization (GEO) scoring | python scripts/seo_static.py --root <root> |
scripts/a11y_audit.py |
Multi-engine axe-core (WCAG 2.1 AA) + keyboard navigation audit | python scripts/a11y_audit.py --url <APP_URL> --routes /,/a |
scripts/lighthouse_run.py |
Desktop Lighthouse runner with threshold enforcement | python scripts/lighthouse_run.py --url <APP_URL> --routes /,/a |
scripts/capture_screenshots.py |
Multi-engine Playwright screenshot capture + contact sheet | python scripts/capture_screenshots.py --root <root> --url <APP_URL> --routes /,/a |
scripts/check_readme.py |
Validates README structure, env table, and screenshot assets | python scripts/check_readme.py <root> |
scripts/design_polish.py |
Rubric evaluation for typography, color, spacing rhythm, layout | python scripts/design_polish.py --root <root> |
scripts/business_logic_check.py |
Executes scenario tests and verifies API contracts | python scripts/business_logic_check.py --root <root> --url <APP_URL> |
scripts/load_check.py |
Concurrency load and soak drift time-series measurement | python scripts/load_check.py --url <APP_URL> --soak 60 |
scripts/migration_check.py |
Rollback, idempotency, and destructive DDL analyzer | python scripts/migration_check.py --root <root> |
scripts/migration_apply.py |
Deep migration tester: applies, rolls back, and reapplies on scratch DB | python scripts/migration_apply.py --root <root> |
scripts/privacy_check.py |
Analyzes privacy policy, consent gates, and PII storage | python scripts/privacy_check.py --root <root> --url <APP_URL> |
scripts/i18n_check.py |
Locale key matching and RTL styling verification | python scripts/i18n_check.py --root <root> |
scripts/at_check.py |
Screen-reader accessible name, live region, and landmark checks | python scripts/at_check.py --root <root> |
scripts/payment_email_check.py |
Card security, webhook validation, and mail safety analyzer | python scripts/payment_email_check.py --root <root> |
scripts/payment_email_live.py |
Test-mode payment intent and transactional email round-trip | python scripts/payment_email_live.py --root <root> |
scripts/code_quality.py |
Code complexity, duplication, and AI debt detector | python scripts/code_quality.py --root <root> |
scripts/mobile_check.py |
Viewport, 44px touch targets, and hover traps audit | python scripts/mobile_check.py --root <root> |
scripts/flow_test.py |
Playwright E2E journey flow runner (qa/flows.json) |
python scripts/flow_test.py --root <root> --url <APP_URL> |
scripts/verify_claims.py |
Adversarially re-derives claimed PASSes from disk evidence | python scripts/verify_claims.py --root <root> --claims qa/claims.json |
scripts/scan_workspace.py |
Workspace discovery scanning for multi-app repositories | python scripts/scan_workspace.py <workspace> |
scripts/qa_common.py |
Core CLI parsing, file scoping, subprocess, and format helpers | imported |
scripts/qa_ext.py |
Extensions for HTTP clients and gate runners | imported |
scripts/schema_validate.py |
Schema validators for findings and coverage ledgers | imported |
scripts/signoff.py |
Fingerprint-bound human sign-off manager (Gates C, N, Q) | imported / CLI |
scripts/skill_check.py |
Health-check for skill packaging, scripts, and links | python scripts/skill_check.py --root . |
scripts/remediate.py |
Autonomous remediation engine: codemods + atomic rollback + recipes | python scripts/remediate.py --root <root> [--dry-run] |
scripts/remediation_handlers.py |
Codemods for XSS innerHTML, CORS, touch targets, focus visible, empty catch | imported by remediate.py |
scripts/web_guidelines.py |
Web Interface Guidelines machine checker | python scripts/web_guidelines.py --root <root> |
scripts/absorbed_rules.py |
Rules from absorbed doc skills | imported |
scripts/fixtures/make_sample_app.py |
Fixture generator for good/broken apps | python scripts/fixtures/make_sample_app.py |
scripts/absorbed/verify_manifest.py |
Hash integrity verifier for absorbed sibling tools | python scripts/absorbed/verify_manifest.py |
Exit-code contract
0: Checked and passed.1: Checked and failed.2: SKIPPED — required tool or evidence was unavailable. A skipped gate is never a pass.
Tool failures (unreachable server, failed test runner) report UNSUPPORTED (Exit 2, SKIPPED), not app defects.
Evidence artifacts must reside in the target project (<app>/qa/...). To point to an external directory, use --artifact-dir <dir>.
Unverified sign-offs are marked UNVERIFIABLE.
Self-Tests
Execute test suites:
python -m pytest scripts/test_advanced.py -q # 76 tests
python -m pytest scripts/test_gates_extended.py -q # 45 tests
python -m pytest scripts/test_qa_scripts.py -q # 49 tests
python -m pytest scripts/test_absorbed.py -q # 23 tests
python -m pytest scripts/test_scope.py -q # 22 tests
python -m pytest scripts/test_phase6.py -q # 35 tests
python -m pytest scripts/test_signoff.py -q # 27 tests
python -m pytest scripts/test_frameworks.py -q # 33 tests
python -m pytest scripts/test_measurement_failures.py -q # 11 tests
python -m pytest scripts/test_absorption.py -q # 16 tests
python -m pytest scripts/test_docs.py -q # doc-consistency
python scripts/test_preflight.py # secret-heuristic self-test
Total: 346 tests.
5. End-to-End Workflow
1. BOOTSTRAP -> scripts/bootstrap_env.py => verify local Playwright/Lighthouse
2. SCOPE -> scripts/gate_scope.py => identify applicable gates
3. AUTO-FIX -> scripts/fixes.py => apply safe mechanical fixes
4. SERVE -> scripts/serve.py => boot app
5. MEASURE -> capture screenshots, bundle budgets, a11y, lighthouse, security
6. SIGN-OFF -> store human sign-offs for visual polish, business rules, privacy
7. JUDGE -> verify_claims.py => re-derive all claims adversarially
8. REPORT -> emit qa/report.md
Details: deep-modes.md and verification.md. For workspace reviews: workspace-review.md.
6. Multi-App / Workspace Mode
Discover apps and review each independently without cross-app assumption leaks:
python scripts/scan_workspace.py <workspace>
7. Final Report Format
APP : <name> @ <APP_URL> (<framework>, <PKG>)
DETECTED : port=<PORT> healthz=<HEALTHZ> routes=<ROUTES>
SCOPE : applies=<list of gates> | conditional=<list> | skipped=<list>
GATES : A visual PASS | B perf PASS | C polish PASS (human) | D lighthouse PASS (Perf 96)
E security PASS | F a11y PASS | G seo PASS | H tests PASS
I reliability PASS | J docs PASS | K observability PASS | L cost PASS
M readme+shots PASS (3 shots, contact sheet)
N logic PASS | O load PASS | P migrations PASS | Q privacy PASS
R i18n PASS | S screen-reader PASS | T payments PASS | U quality PASS
EVIDENCE : qa/lighthouse/lighthouse-summary.json, qa/a11y/a11y-report.json,
docs/screenshots/manifest.json, qa/security/findings.json
SKIPPED : <gate + reason, or none>
BLOCKERS : <list or none>
FIXED : <list>
ARTIFACTS : docs/screenshots/, qa/lighthouse/*.html, qa/a11y/a11y-report.json, qa/report.md
Related Skills & Absorbed Tools
Absorbs tools and playbooks from: frontend-design, mobile-design, i18n-localization, api-patterns, database-design, seo-fundamentals, geo-fundamentals, lint-and-validate, nextjs-react-expert, performance-profiling, testing-patterns, vulnerability-scanner, security-audit (in scripts/security_audit_pack/), review-team, web-design-guidelines (in web-interface-guidelines.md), api-contract-testing, security-hardened-api, observability-and-instrumentation, microservices-resilience, ai-debt-detector, property-based-testing, and mutation-testing (in references/knowledge/).