agentleFS
relvo-labsrelvo-labs/agent-runtime/.agents/skills/pnpm-supply-chain/SKILL.md

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

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
  1. Distinctive:

    Use this skill when a change touches any of:

    line 13
  2. Distinctive:

    Do not use this skill when:

    line 25
  3. Distinctive:

    Never write a literal range in a package.

    line 73
  4. Very specific:

    Do not widen this exception based only on semver, a typecheck, or a handshake: check queued-interrupt semantics and the packed peer …

    line 80
  5. Very specific:

    Verify compatibility, do not assume latest works: Check engines and peerDependencies of the candidate against our Node matrix and our …

    line 84
  6. Very specific:

    When an install fails with ERR_PNPM_NO_MATURE_MATCHING_VERSION, the correct fix is to

    line 100
  7. Very specific:

    Never run pnpm install --unsafe-perm, never set dangerouslyAllowAllBuilds, and never add a blanket enable-pre-post-scripts=true.

    line 120
  8. Distinctive:

    Audit at the boundary you actually ship: Run the audit and triage by whether the advisory is reachable from a _runtime_ dependency of a …

    line 134

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 of pnpm-workspace.yaml
  • pnpm-lock.yaml
  • tools/repo/check-supply-chain.ts or tools/repo/check-licenses.ts
  • .npmrc
  • onlyBuiltDependencies
  • the packageManager pin

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 policy
  • pnpm-workspace.yaml#catalog — the single version pin per third-party package
  • pnpm-workspace.yaml#onlyBuiltDependencies — the install-script allow-list
  • pnpm-workspace.yaml#minimumReleaseAge — the publish-cooldown policy
  • package.json#packageManager — the exact pnpm pin
  • docs/adr/ADR-0013-supply-chain-policy.md — the policy decision record
  • tools/repo/check-supply-chain.ts — effective dependency-policy validation
  • tools/repo/check-licenses.ts — production dependency license validation

Does not own

  • pnpm-workspace.yaml#packages — owned by package-architecture
  • packages/*/package.json#exports — owned by package-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

  1. 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.
  2. 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.261 names the releases whose SDK seam/lifecycle were reviewed; catalog: still pins the exact recorded baseline 0.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. See docs/adr/ADR-0013-supply-chain-policy.md.

  3. Verify compatibility, do not assume latest works. Check engines and peerDependencies of the candidate against our Node matrix and our TypeScript line before installing:

    npm view <pkg> version engines peerDependencies --json

    strict-peer-dependencies=true is set deliberately — an unmet peer is a design defect and must be resolved, not silenced.

  4. Respect the publish cooldown; do not exclude your way past it. The workspace sets minimumReleaseAge: 4320 (3 days) with minimumReleaseAgeStrict: 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 install

    minimumReleaseAgeExclude must 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.

  5. 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 set dangerouslyAllowAllBuilds, and never add a blanket enable-pre-post-scripts=true.

  6. 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.yaml

    A lockfile diff in a PR that added no dependency means something drifted — investigate before committing it. Never hand-edit pnpm-lock.yaml.

  7. 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 --prod

    A 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.

  8. The packageManager pin 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 gate

Provenance

  • Source: independent — authored for this repository against the pnpm documentation (catalogs, onlyBuiltDependencies, --frozen-lockfile, settings reference) and the npm audit documentation.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.