Skip to content

Commit e57488e

Browse files
alainnclsalainncls
committed
chore: add dependency maintenance skill
1 parent 958483c commit e57488e

7 files changed

Lines changed: 456 additions & 10 deletions

File tree

‎.agents/skills/linea-dependency-maintenance/SKILL.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
name: linea-dependency-maintenance
3+
description: Safely plan and execute JavaScript/TypeScript dependency maintenance across npm and pnpm repositories, including npm lockfiles, pnpm workspaces, catalogs, overrides, release-age policies, audits, CI validation, Dependabot boundaries, PRs, and GitHub tracking issues. Use whenever the user asks to update, bump, refresh, audit, clean, modernize, or review dependencies, reduce vulnerabilities, clean overrides, or prepare dependency PRs/issues.
4+
metadata:
5+
short-description: Safe npm/pnpm dependency maintenance
6+
---
7+
8+
# Dependency Maintenance
9+
10+
Use this workflow to maximize safe dependency progress without changing the repository's package-manager contract or hiding remaining risk.
11+
12+
## Preflight
13+
14+
1. Read repo instructions first: `AGENTS.md`, `CLAUDE.md`, package-specific instructions, and `CONTRIBUTING.md`.
15+
2. Detect the package-manager contract from lockfiles, `packageManager`, CI, deploy config, and package-manager guard scripts:
16+
- npm repo: use npm, preserve `package-lock.json`, and validate with `npm ci`.
17+
- pnpm repo: use pnpm, preserve `pnpm-lock.yaml`, `pnpm-workspace.yaml`, catalogs, and overrides.
18+
- Do not introduce a different lockfile, workspace file, package-manager metadata, or install command.
19+
3. Check branch and worktree state with `git status --short --branch`. If unrelated changes are present, use an isolated worktree or avoid touching those files.
20+
4. Read `.nvmrc`, `.node-version`, `engines`, `.npmrc`, CI workflows, deploy config, and `dependabot.yml`.
21+
5. Capture the baseline: outdated report, audit report, lockfile state, and relevant validation commands.
22+
23+
## Policy
24+
25+
- Treat release-age and cooldown rules as hard gates. Compute exact cutoff timestamps before selecting versions.
26+
- In pnpm repos, `minimumReleaseAge` is a maturity window in minutes; respect `minimumReleaseAgeExclude` exactly.
27+
- Treat npm/pnpm dependency updates as owned by this skill. Do not re-enable Dependabot npm/pnpm package-ecosystem jobs unless the user explicitly asks; GitHub Actions, Docker, and other non-JavaScript ecosystems may remain under Dependabot.
28+
- Preserve version style: exact pins, ranges, `catalog:` references, `workspace:` references, and repo-specific package placement.
29+
- Default PR scope is eligible patch and minor updates. Major upgrades, risky transitive fixes, and broad migrations get tracking issues unless the user explicitly approves doing them now.
30+
- Prefer official migration guides, changelogs, package registry metadata, and advisory pages for decisions that affect risk.
31+
32+
## Inventory
33+
34+
Build an inventory from direct dependencies, dev dependencies, peer dependencies, optional dependencies, catalogs, overrides, lockfiles, and audit output.
35+
36+
Use native commands first:
37+
38+
```bash
39+
npm outdated --json || true
40+
npm audit --json || true
41+
npm explain <package>
42+
npm ls <package>
43+
44+
pnpm outdated -r --format json || true
45+
pnpm audit --json || true
46+
pnpm why <package> -r
47+
```
48+
49+
When registry-age gates matter, use the bundled helper as a reproducible first pass:
50+
51+
```bash
52+
node <skill-dir>/scripts/eligible-updates.mjs --manager auto --days 3
53+
```
54+
55+
Replace `<skill-dir>` with the directory containing this `SKILL.md`. Adjust `--days` or `--minutes` to match the repo policy.
56+
57+
## Triage
58+
59+
Classify every candidate before changing files:
60+
61+
- Safe now: patch/minor, older than cutoff, peer-compatible, and locally validatable.
62+
- Blocked non-major: too fresh, peer-conflicting, runtime-breaking, upstream-pinned, or requiring nontrivial code/config migration.
63+
- Major migration: semver-major or framework/toolchain migration that needs a dedicated issue.
64+
- Audit-only blocked: no patched version, incompatible transitive major, bundled dependency, or upstream package must move first.
65+
- Removable: unused dependency that should be deleted instead of bumped.
66+
67+
Group tightly coupled packages together when separate bumps are likely to create peer, type, or runtime friction.
68+
69+
## Apply
70+
71+
- Update catalogs before workspace manifests when dependencies are shared through `catalog:`.
72+
- In npm repos, update `package.json` and regenerate `package-lock.json` with npm. Prefer lockfile-only install when appropriate, then validate with clean install.
73+
- In pnpm repos, regenerate `pnpm-lock.yaml` with normal pnpm install flow. Do not bypass `minimumReleaseAge`.
74+
- Preserve package-manager script safety settings such as `engine-strict`, `ignore-scripts`, LavaMoat allow-scripts, and `only-allow`.
75+
- Keep code/config changes minimal and only when required by the dependency update.
76+
- If a supposedly safe update breaks validation, revert just that candidate and document why it moved to blocked work.
77+
78+
## Overrides
79+
80+
Treat overrides as temporary exceptions:
81+
82+
- Remove stale overrides after direct bumps when they no longer affect resolution or audit posture.
83+
- Keep or add only targeted overrides that are compatible with the dependent package and materially improve security or toolchain behavior.
84+
- Avoid broad overrides for transitive major jumps unless upstream compatibility is proven.
85+
- Document every kept override with package path, advisory or compatibility reason, current resolution, target resolution, and remaining risk.
86+
87+
## Validation
88+
89+
Run the narrowest meaningful checks first, then broaden by blast radius:
90+
91+
- install or clean install
92+
- audit after changes
93+
- lint, typecheck, build, and tests
94+
- repo-specific checks such as Docusaurus prebuild/build, Turbo filters, Prisma generate, Playwright/Storybook browsers, Docker builds, Foundry/forge, subgraph codegen/tests, or generated-doc checks
95+
96+
If a command cannot run, report why. If CI fails, inspect the actual logs and classify the failure as introduced by the update, exposed baseline debt, or external/non-actionable.
97+
98+
## Tracking
99+
100+
Open one draft PR for safe updates unless the user asks otherwise. Include:
101+
102+
- updated packages and grouped stacks
103+
- release-age cutoff and skipped versions with publish timestamps
104+
- audit before/after summary
105+
- overrides removed, kept, added, or narrowed
106+
- blocked non-major updates and remaining advisories
107+
- major or blocked migration issue links
108+
- validation commands and caveats
109+
110+
Open English `chore(deps): ...` issues for deferred major upgrades or blocked migration streams. Each issue should include official docs, current and target versions, expected code areas, migration plan, validation, rollout risk, and rollback notes.
111+
112+
## Stop And Ask
113+
114+
Pause before contract deployments, public API breakage, package-manager migration, broad refactors, invalid override trees, or CI failures that suggest a cross-cutting regression.
115+
116+
## Additional Resources
117+
118+
- For npm/package-lock repositories, read `references/npm.md`.
119+
- For pnpm workspace/catalog/override repositories, read `references/pnpm.md`.
120+
- For reproducible release-age inventory, run `scripts/eligible-updates.mjs`.

‎.agents/skills/linea-dependency-maintenance/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Dependency Maintenance"
3+
short_description: "Safe npm/pnpm upgrades, audits, PRs"
4+
default_prompt: "Use this skill to refresh eligible dependencies safely, respect repo package-manager policy, document blocked work, and prepare a validated dependency PR."

‎.agents/skills/linea-dependency-maintenance/evals/evals.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"skill_name": "linea-dependency-maintenance",
3+
"evals": [
4+
{
5+
"id": 1,
6+
"prompt": "In an npm Docusaurus/Vercel repo with package-lock.json, refresh eligible non-major dependencies, keep npm as the package manager, avoid pnpm files, document skipped majors, and prepare a PR summary with validation.",
7+
"expected_output": "Uses npm only, preserves package-lock.json, checks registry publish dates, avoids npm audit fix --force, validates lint/typecheck/build/audit, and documents blocked updates.",
8+
"files": []
9+
},
10+
{
11+
"id": 2,
12+
"prompt": "In a pnpm monorepo with pnpm-workspace catalogs, minimumReleaseAge: 4320, and many pnpm overrides, bump safe patch/minor dependencies, clean stale overrides, and create issues for majors.",
13+
"expected_output": "Updates catalog entries where appropriate, respects the 3-day maturity window and exclusions, regenerates pnpm-lock.yaml, minimizes overrides, validates affected workspaces, and tracks majors separately.",
14+
"files": []
15+
},
16+
{
17+
"id": 3,
18+
"prompt": "An audit report shows vulnerable transitive packages where the only patched version is a major that upstream tools may not support. Decide what to update now and what to track.",
19+
"expected_output": "Avoids forcing incompatible major overrides, records dependency paths and advisories, applies only compatible direct or targeted transitive fixes, and opens follow-up issues for blocked items.",
20+
"files": []
21+
},
22+
{
23+
"id": 4,
24+
"prompt": "A dependency PR fails CI after a safe update. Inspect logs, identify whether it is introduced or baseline debt, apply the smallest safe fix, and update the PR summary.",
25+
"expected_output": "Uses CI logs rather than guessing, reproduces narrowly when possible, classifies the failure, narrows or reverts the problematic update if needed, and keeps the PR description aligned with the actual update set.",
26+
"files": []
27+
}
28+
]
29+
}

‎.agents/skills/linea-dependency-maintenance/references/npm.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# npm Dependency Maintenance
2+
3+
Use these notes only for npm repositories with `package-lock.json`, npm CI, or npm-based hosting/deploy detection.
4+
5+
## Rules
6+
7+
- Keep npm as the only package manager unless the user explicitly asks for a migration.
8+
- Do not commit `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `yarn.lock`, or `packageManager` changes to an npm repo just to inspect dependencies.
9+
- Preserve existing version specifier style. Exact pins stay exact; intentional ranges stay ranges.
10+
- Do not rely on `npm audit fix --force` for dependency-refresh PRs because it can apply semver-major changes or obscure why the tree changed.
11+
12+
## Baseline
13+
14+
```bash
15+
node --version
16+
npm --version
17+
npm outdated --json || true
18+
npm audit --json > /tmp/npm-audit-before.json || true
19+
```
20+
21+
Inspect `engines.node`, `.nvmrc`, Vercel/Docusaurus config, GitHub Actions, and existing `overrides`.
22+
23+
## Update Flow
24+
25+
1. Select eligible patch/minor direct dependencies using registry publish times.
26+
2. Inspect peer-sensitive updates before editing:
27+
```bash
28+
npm view <package>@<target> peerDependencies --json
29+
npm view <package>@<target> peerDependenciesMeta --json
30+
```
31+
3. Update `package.json` and regenerate the lockfile:
32+
```bash
33+
npm install --package-lock-only
34+
```
35+
4. Validate the resulting tree:
36+
```bash
37+
npm ls --all --depth=0
38+
npm ci
39+
```
40+
41+
## Overrides
42+
43+
- Use package-manager-native `overrides` in `package.json`.
44+
- Confirm paths with `npm explain <package>` or `npm ls <package>`.
45+
- Prefer parent-scoped overrides when a broad override creates invalid peer/range errors.
46+
- If the tree becomes invalid, remove the override and document the advisory as blocked.
47+
48+
## Common Validation
49+
50+
Documentation and Docusaurus repos usually need:
51+
52+
```bash
53+
npm run lint
54+
npm run typecheck
55+
npm run build
56+
npm audit --json > /tmp/npm-audit-after.json || true
57+
```
58+
59+
If build/prebuild scripts mutate generated docs, images, or metadata unrelated to dependency maintenance, restore those unrelated files before staging.

‎.agents/skills/linea-dependency-maintenance/references/pnpm.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# pnpm Dependency Maintenance
2+
3+
Use these notes for pnpm repositories with `pnpm-lock.yaml`, `pnpm-workspace.yaml`, catalogs, overrides, or pnpm-specific CI.
4+
5+
## Rules
6+
7+
- Keep pnpm as the only package manager. Respect `packageManager`, `.npmrc`, `engines`, `engine-strict`, and `only-allow` guards.
8+
- `minimumReleaseAge` is a maturity window in minutes. For example, `4320` means 3 days.
9+
- Respect `minimumReleaseAgeExclude`; do not manually block an excluded package solely because it is inside the maturity window.
10+
- Preserve `catalog:` and `workspace:` dependency references. Update the catalog entry rather than each manifest when a catalog owns the version.
11+
12+
## Baseline
13+
14+
```bash
15+
node --version
16+
pnpm --version
17+
pnpm install --frozen-lockfile
18+
pnpm outdated -r --format json || true
19+
pnpm audit --json || true
20+
```
21+
22+
Inspect `pnpm-workspace.yaml`, package manifests, `pnpm.overrides`, `minimumReleaseAge`, `minimumReleaseAgeExclude`, `onlyBuiltDependencies`, `patchedDependencies`, LavaMoat/allow-scripts settings, and workspace-specific CI.
23+
24+
## Update Flow
25+
26+
1. Build a workspace-wide inventory of direct dependencies, catalog entries, and overrides.
27+
2. Select the highest eligible same-major version older than the maturity cutoff, unless the package is explicitly excluded.
28+
3. Update shared catalog entries first.
29+
4. Run normal pnpm install to regenerate the lockfile:
30+
```bash
31+
pnpm install
32+
```
33+
5. Re-run outdated and audit reports.
34+
35+
## Overrides
36+
37+
- Test whether an override is stale by checking whether removing it changes resolution or audit output in a temporary copy/worktree.
38+
- Prefer targeted selectors such as `parent>child` when a global override changes unrelated tooling.
39+
- Do not force transitive major versions through overrides for Hardhat, Jest/Istanbul, Graph/Matchstick, Playwright, or framework stacks unless compatibility is proven.
40+
- Confirm override effects:
41+
```bash
42+
pnpm why <package> -r
43+
pnpm audit --json || true
44+
```
45+
46+
## Common Validation
47+
48+
Choose checks by affected workspace:
49+
50+
```bash
51+
pnpm run lint
52+
pnpm run prettier
53+
pnpm run build
54+
pnpm run test
55+
```
56+
57+
For monorepos, prefer filtered checks where they match CI:
58+
59+
```bash
60+
pnpm run --filter=<workspace> lint
61+
pnpm run --filter=<workspace> build
62+
pnpm run --filter=<workspace> test
63+
```
64+
65+
Also check domain-specific tasks when touched: Turbo pipelines, Prisma generate, Playwright browser installs, Storybook visual tests, Foundry/forge, subgraph codegen/tests, Docker builds, and generated artifacts.

0 commit comments

Comments
 (0)