Overview
Aggregator and router for release readiness: detect what the repo actually ships, dispatch only the matching focused audit skills, and synthesize one scorecard with an ordered ship-blocker list. This is a readiness GATE, not a remediation plan — if the human wants the full audit-to-fix-spec pipeline afterward, route them to nuke-audit.
When to use / when NOT
Use when:
- A human asks whether a project is ready to ship/release/publish/deploy and wants one answer.
- Before a version tag, first npm/PyPI publish, docs launch, or making a repo public.
- The human cannot or does not want to enumerate the individual audit dimensions.
Do NOT use when:
- The question is single-dimension ("is the docs site deployable?") — invoke that focused skill directly (e.g. docs-deploy-readiness).
- The human wants the fixes planned and executed — that is nuke-audit.
- Mid-feature code review — use code-audit or a normal review flow.
How it works
Step 1 — Detect the project's shape (never skip)
Enumerate what the repo contains and ships. Read, do not assume:
- Root + workspace manifests:
package.json(look forworkspaces,bin,exports,files,publishConfig,private),pyproject.toml,Cargo.toml,go.mod, etc. - CI/deploy config:
.github/workflows/,Dockerfile,vercel.json/netlify.toml/fly.toml, release scripts. - Docs/content: docs app dirs,
*.mdx/markdown content trees, static-site config. - Network surfaces: servers, listened ports, auth tokens, webhooks, anything reachable at runtime.
- UI surfaces: web apps, TUIs, component libraries.
Output a shape table: each shipped surface, its distribution channel (npm package / copy-paste registry / deployed site / installed binary / hosted service), and its audience (end users, developers, internal). Illustrative example only: a monorepo might ship a shadcn-style component registry, an installer CLI, a localhost Hono server, and a docs site — four surfaces, four different bars. Your repo will differ; detect, don't transplant.
Step 2 — Route to dimension skills
Run ONLY the dimensions the shape justifies. Dispatch by name; never re-implement their checklists inline.
| Surface detected | Dimension skills to run |
|---|---|
| Publishable library / package / copy-distributed source | handoff-readiness (per artifact), jargon-leak |
| Docs or content site | docs-deploy-readiness, humanizer (or humanize-readme for READMEs), jargon-leak |
| Deployable app / hosted service | security-surface-audit, accessibility-compliance (if UI) |
| CLI binary | handoff-readiness, jargon-leak, security-surface-audit (if it opens ports or handles secrets) |
| Local/embedded server, webhook, any network listener | security-surface-audit, security-review |
| React code anywhere | react-senior-guide (+ its relevant subskills) |
| Multi-package repo / monorepo | reusability-audit |
| Any codebase (always on) | code-audit (DRY/SRP/naming/dead code/types/errors), anti-slop |
| Any user-facing prose: README, CLI help, error messages | humanizer |
Step 3 — Scale the run
Heuristic:
- Single-pass (run each dimension once, directly): ≤2 shipped surfaces, single package, roughly ≤20k LOC.
- Convergence loop (REQUIRED reference: convergence-loop): anything larger — multi-surface monorepos, 3+ dimensions in play, or any repo where one pass cannot hold the whole surface in context. Run the dimensions as parallel agents inside the loop until findings converge.
Step 4 — Synthesize one scorecard
Merge all dimension reports into the Output format below. Ordering rule for blockers: deploy/release-pipeline blockers FIRST (red CI, failing build, broken publish/install) — a red pipeline gates validating everything else — then security/correctness, then public-contract/docs gaps, then polish.
Quality bar
Score each routed dimension 1–5:
| Score | Meaning |
|---|---|
| 5 | No findings at medium+ severity; ship as-is |
| 4 | Minor findings only, none user-visible |
| 3 | At least one significant finding; shippable with known caveats |
| 2 | Contains a ship-blocker in this dimension |
| 1 | Dimension fundamentally broken (build fails, publish broken, site 404s) |
Gate rule: overall verdict is NOT READY if any dimension scores ≤2, or if any pipeline blocker exists, regardless of the average.
Output
# Release Audit — <repo>
## Shape detected
| Surface | Channel | Audience |
| ...rows from Step 1... |
Dimensions skipped and why: <e.g. "no docs site → docs-deploy-readiness skipped">
## Scorecard
| Dimension (skill) | Score | Worst findings (file:line) |
| ...one row per routed dimension... |
## Top blockers to ship (ordered)
1. <pipeline/release blocker> — <evidence>
2. ...
## What static analysis could NOT verify — human/runtime must
- Clean-environment build (fresh clone, no caches, pinned toolchain)
- Publish smoke (pack → install in temp dir → import/run)
- Deploy dry-run on the real target
- Live performance under realistic data/load
- Real screen-reader pass (automated a11y checks are not this)
- <anything dimension skills flagged as runtime-only>
## Verdict: READY / NOT READY (+ why)
Next step if NOT READY: run nuke-audit for the full remediation plan.
Common mistakes
- Running every dimension on every repo. A private internal tool needs no handoff-readiness pass; a docs-less library needs no docs-deploy-readiness. Route from the detected shape.
- Hardcoding one project's specifics. Checks like "verify the registry JSON" or "test the
--tokenflag" apply only if Step 1 found that surface. - Re-implementing focused skills inline. Dispatch handoff-readiness etc. by name; this skill owns routing and synthesis only.
- Burying the red pipeline. A failing build outranks every style finding; order blockers accordingly.
- Declaring READY without the runtime caveats section. Static analysis cannot prove a clean-env install or a screen-reader pass; say so explicitly.
- Drifting into remediation. Findings + verdict only; full fix planning belongs to nuke-audit.
- Referencing sibling skills via @-paths. Name them; @-paths force-load and burn context.