pnpm-supply-chain
Skill0 starsChanged 50 days agoApache-2.0View on GitHub
Add or update third-party dependencies, keep the lockfile authoritative and keep dependency lifecycle scripts denied by default.
- Installs packages
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- changesets-releaseSkill
- local-ci-paritySkill
- npm-releaseSkill
- package-architectureSkill
- package-artifact-validationSkill
- provider-adapter-developmentSkill
- public-api-evolutionSkill
- runtime-contract-evolutionSkill
- runtime-lifecycle-coordinationSkill
- workspace-lifecycleSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Use this skill when a change touches any of:
- Distinctive: line 25
Do not use this skill when:
- Distinctive: line 73
Never write a literal range in a package.
- Very specific: line 80
Do not widen this exception based only on semver, a typecheck, or a handshake: check queued-interrupt semantics and the packed peer …
- Very specific: line 84
Verify compatibility, do not assume latest works: Check engines and peerDependencies of the candidate against our Node matrix and our …
- Very specific: line 100
When an install fails with ERR_PNPM_NO_MATURE_MATCHING_VERSION, the correct fix is to
- Very specific: line 120
Never run pnpm install --unsafe-perm, never set dangerouslyAllowAllBuilds, and never add a blanket enable-pre-post-scripts=true.
- Distinctive: line 134
Audit at the boundary you actually ship: Run the audit and triage by whether the advisory is reachable from a _runtime_ dependency of a …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
pnpm supply chain
Trigger
Use this skill when a change touches any of:
- a third-party entry in any
dependencies/devDependencies/peerDependencies - the
catalog:block ofpnpm-workspace.yaml pnpm-lock.yamltools/repo/check-supply-chain.tsortools/repo/check-licenses.ts.npmrconlyBuiltDependencies- the
packageManagerpin
Counter-trigger
Do not use this skill when:
- the edge is between two workspace packages — use
package-architecture - you are changing what a package publishes — use
package-artifact-validation - you are only changing a Node version in CI — use
local-ci-parity
Owns
pnpm-lock.yaml— the resolution of record.npmrc— install policypnpm-workspace.yaml#catalog— the single version pin per third-party packagepnpm-workspace.yaml#onlyBuiltDependencies— the install-script allow-listpnpm-workspace.yaml#minimumReleaseAge— the publish-cooldown policypackage.json#packageManager— the exact pnpm pindocs/adr/ADR-0013-supply-chain-policy.md— the policy decision recordtools/repo/check-supply-chain.ts— effective dependency-policy validationtools/repo/check-licenses.ts— production dependency license validation
Does not own
pnpm-workspace.yaml#packages— owned bypackage-architecturepackages/*/package.json#exports— owned bypackage-artifact-validation
Relationships
boundary-with→package-architecture— both write dependency fields; this skill owns third-party edges and versions, that skill owns workspace edges and layering.depends-on→local-ci-parity— the frozen-lockfile install is a CI gate.
Procedure
- Justify the dependency. For a foundation SDK, prefer the platform. Before adding, answer in the PR body: what does it replace, how many transitive packages does it pull, is it ESM-native, is it maintained, and what is the removal cost. A dependency that only saves a few lines of Node built-in usage is rejected.
Pin exactly, in the catalog, once.
# pnpm-workspace.yaml catalog: some-lib: 1.2.3// packages/x/package.json { "dependencies": { "some-lib": "catalog:" } }Never write a literal range in a package. Exact pins plus a committed lockfile give a reproducible tree; ranges give a lockfile that drifts on every unrelated install.
Exception: the proprietary Claude Agent SDK is a host-installed optional peer, not a workspace resolution. Its explicitly checked published range
>=0.3.259 <0.3.261names the releases whose SDK seam/lifecycle were reviewed;catalog:still pins the exact recorded baseline0.3.260. Do not widen this exception based only on semver, a typecheck, or a handshake: check queued-interrupt semantics and the packed peer manifest first. Seedocs/adr/ADR-0013-supply-chain-policy.md.Verify compatibility, do not assume latest works. Check
enginesandpeerDependenciesof the candidate against our Node matrix and our TypeScript line before installing:npm view <pkg> version engines peerDependencies --jsonstrict-peer-dependencies=trueis set deliberately — an unmet peer is a design defect and must be resolved, not silenced.Respect the publish cooldown; do not exclude your way past it. The workspace sets
minimumReleaseAge: 4320(3 days) withminimumReleaseAgeStrict: true. The window immediately after a publish is when a compromised release is most likely to be live and least likely to have been noticed.When an install fails with
ERR_PNPM_NO_MATURE_MATCHING_VERSION, the correct fix is to pin the previous version and wait the window out, not to add an exclusion:npm view <pkg> time --json # find the newest version older than the cutoff # edit the catalog pin, then: pnpm installminimumReleaseAgeExcludemust stay empty. An entry there is a reviewed, documented exception with a stated reason — and it is a liability the next contributor inherits. A transitive range resolves to an older version automatically; only exact catalog pins need manual attention.Install scripts stay denied. pnpm does not run dependency lifecycle scripts unless the package is listed in
onlyBuiltDependencies. Adding an entry requires:- naming the package and why a build step is unavoidable (native addon, etc.)
- confirming there is no prebuilt or pure-JS alternative
- a line in
docs/adr/ADR-0013-supply-chain-policy.md
Never run
pnpm install --unsafe-perm, never setdangerouslyAllowAllBuilds, and never add a blanketenable-pre-post-scripts=true.Keep the lockfile honest.
pnpm install # local: updates the lockfile pnpm install --frozen-lockfile # what CI runs; must be a no-op git diff --stat pnpm-lock.yamlA lockfile diff in a PR that added no dependency means something drifted — investigate before committing it. Never hand-edit
pnpm-lock.yaml.Audit at the boundary you actually ship. Run the audit and triage by whether the advisory is reachable from a runtime dependency of a published package. Dev-only advisories are tracked, not release-blocking:
pnpm audit --prod --audit-level=high pnpm licenses list --prodA published package may only carry runtime dependencies under permissive licences (MIT, ISC, BSD-2/3, Apache-2.0). Copyleft in a runtime dependency is a blocker.
- The
packageManagerpin is exact. Bump it deliberately, with the corresponding lockfile format check, never as a drive-by.
Verification
pnpm install --frozen-lockfile # must not modify pnpm-lock.yaml
pnpm audit --prod --audit-level=high
pnpm licenses list --prod
git diff --exit-code pnpm-lock.yaml
pnpm gateProvenance
- Source: independent — authored for this repository against the pnpm documentation
(
catalogs,onlyBuiltDependencies,--frozen-lockfile, settings reference) and the npm audit documentation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

