| name | audit-crates |
| description | Audit and fix crate/package consistency in the amigo-native monorepo. Use whenever new crates are added, branches are merged that introduced new crates, or you need to verify every crate follows the reference conventions established by argon2/csv/sanitize-html/slugify/xxhash. Checks __conformance__ test infrastructure (parity.spec.ts/upstream.spec.ts + fuzz.spec.ts), package.json scripts (test:conformance, test:all) and dev-deps (fast-check), README presence, npm/ platform-stub directories (6 NAPI targets), docs/packages.json registration with all metadata fields, and marquee PACKAGES count. Flags the legacy __parity__/test:parity convention as outdated. After reporting gaps, this skill offers to apply the fix plan interactively — mechanical fixes (renames, script patches, npm stubs) get applied automatically, content fixes (README, docs entries, fuzz tests) get generated as templates the user reviews. Run this before publishing, before opening PRs that add crates, after merging feature branches, or when CI fails on test:conformance or missing platform binaries. |
audit-crates
Verify every crates/* entry in the amigo-native monorepo conforms to the reference conventions established by argon2, csv, sanitize-html, slugify, and xxhash — then offer to fix the gaps.
When to use
- After adding a new crate under
crates/
- After merging a branch that introduced new crates (conventions diverge easily in parallel work)
- Before publishing or opening a PR that touches package layout
- When CI complains about
test:conformance or missing platform stubs
- When the GitHub Pages dashboard shows wrong package count or missing entries
Workflow — how Claude should run this skill
The skill is interactive. Don't just dump the report and stop — offer to apply the fix plan at the end. The concrete loop:
Step 1 — Run the audit
node .claude/skills/audit-crates/scripts/audit.mjs
The script exits non-zero if gaps exist. Read the output — you'll need it for step 3.
Step 2 — If clean, you're done
If the audit reports "All crates conform", confirm briefly to the user and stop.
Step 3 — If gaps exist, fetch the fix plan
node .claude/skills/audit-crates/scripts/audit.mjs --plan
The plan is grouped into sections:
- Automatable — bash commands that run unattended (renames, script rewrites,
napi create-npm-dirs, pnpm add -D fast-check, marquee updates)
- README templates — per-crate markdown skeletons
docs/packages.json entries — JSON skeletons with TODO placeholders for description and speedupfuzz.spec.ts skeleton — a fast-check property-test starting point
Step 4 — Ask the user, tersely
One line summary (e.g. "10 gaps: 10 READMEs, 10 docs entries, 10 fuzz skeletons"), then three options, nothing more:
A mechanical only · B full pass · C report only
Wait for the answer. Honour custom splits ("just READMEs"). No preamble, no recap.
Step 5 — Execute according to the answer
- A: Run section 1 commands. Verify with
node .claude/skills/audit-crates/scripts/audit.mjs after. Report what's left.
- B: A, then for each content section walk crate-by-crate. For speedups, check
docs/data.json — if unmeasured, write "TBD" rather than inventing numbers. For fuzz tests, read the crate's src/lib.rs and __test__/ to understand the API before writing properties.
- C: Stop. Leave the plan output visible so the user can work from it.
After any fix pass, commit using conventional commits (refactor:, feat:, docs:) — one commit per logical group (mechanical fixes, READMEs, docs entries) so the history stays reviewable.
What it checks
For each crate (excluding _template):
| Check | Why it matters |
|---|
__conformance__/ with parity.spec.ts or upstream.spec.ts | Drop-in parity coverage vs. the npm original (either pattern counts) |
__conformance__/fuzz.spec.ts | Property-based tests that catch semantic drift |
package.json scripts: test, test:conformance, test:all, bench | Reference-convention test entrypoints |
fast-check in devDependencies | Only needed when fuzz.spec.ts exists |
README.md | Every published package needs one |
npm/ with 6 platform subdirs (darwin-arm64, darwin-x64, linux-arm64-gnu, linux-x64-gnu, linux-x64-musl, win32-x64-msvc) | NAPI-RS platform-stub packages — without them, npm install fails on that platform |
__bench__/index.bench.ts | Vitest benchmark suite consumed by bench:report |
Registered in docs/packages.json with all metadata fields | Appears on the GitHub Pages dashboard |
WASM dual-target scaffolding (wasm/Cargo.toml, wasm/src/lib.rs, wasm/tests/web.rs, build:wasm script, browser export, the five underscored wasm/pkg/* entries in files, an "Install for the browser" README section, a declared amigo.targets) | Browser bundlers (Vite, webpack, Angular CLI) resolve the browser conditional export; the files entries make sure the tarball actually ships the WASM artifact. Required for every crate not in NODE_ONLY_CRATES. |
Node.js server-only group
A small, explicit allow-list of crates intentionally stays Node-only and
must NOT have a wasm/ directory:
| Crate | Reason |
|---|
argon2 | Performance — ~2× slower in WASM than native (memory-hard hash); browser password hashing is an anti-pattern |
jose | Server-only crypto — private signing keys must not ship to the browser |
jwt | Server-only crypto — same as jose |
The list is the single source of truth — duplicated as a constant in
audit.mjs (NODE_ONLY_CRATES), scripts/sync-registry.mjs,
scripts/build-all-wasm.mjs, scripts/scaffold-wasm-bench.mjs,
.github/workflows/ci.yml, and .github/workflows/release.yml. To add
or remove a crate from the group, edit all six spots together. See
docs/specs/expansion-2026.md § Node.js server-only tier for the policy.
Globally:
docs/packages.json marquee PACKAGES value equals the crate count (docs/data.json is auto-generated benchmark output; packages.json holds the hand-edited brand/marquee/registry)docs/packages.json marquee TARGETS reflects the dual-target / Node-only split- Every crate is registered in
release-please-config.json and .release-please-manifest.json (both hand-maintained; a missing entry means no release PRs / npm publishes)
- Legacy
__parity__/ dirs or test:parity scripts are flagged as must modernize
Invocation flags
| Flag | Purpose |
|---|
| (none) | Markdown report (default — what you show the user first) |
--plan | Executable fix plan — bash commands + templates |
--json | Machine-readable output for scripting or CI gates |
All modes exit non-zero on gaps.
Why the conventions matter
The reference crates were set up so parity with the npm original can be verified independently per-crate (pnpm --filter <crate> run test:conformance) instead of only via a central script. Each crate owns its own conformance suite, and CI can gate on it selectively. fast-check enables property-based fuzz testing — that's how semantic drift gets caught automatically when upstream changes.
The npm/ platform stubs are what @napi-rs/cli publishes as optionalDependencies. Tiny metadata packages, but without them npm install fails on platforms with no matching binary — the publish is effectively broken.
And docs/packages.json is the single source of truth for the GitHub Pages dashboard. A package not listed there is invisible to users even if it's on npm.
A crate that drifts from the conventions will eventually cause a CI failure, a broken install on some platform, or an embarrassing gap on the landing page. This skill catches — and offers to fix — all three before they ship.
Extending the audit
If you add a new convention (e.g. a required CHANGELOG.md, a new lint step), add the check to scripts/audit.mjs in the auditCrate function, then extend the --plan output with the corresponding fix template. Keep checks cheap (no network, no subprocess) so the audit stays fast and CI-friendly.
