Web steward
Upgrades break pages in two quiet ways: a peer dependency that no longer
matches (the build passes, the component fails at runtime), and a minor bump
that changes how something looks or moves. This skill catches the first
mechanically and the second with screenshots, and it stops at a draft PR.
1. Inventory — measure before touching anything
node .claude/skills/web-steward/peer-check.mjs --root . # watch list
node .claude/skills/web-steward/peer-check.mjs --root apps/web # a monorepo app
node .claude/skills/web-steward/peer-check.mjs --root . --all # every direct dependency
It reads package.json plus pnpm-lock.yaml, package-lock.json, or
node_modules, and asks the npm registry for each package's peers at the
resolved version. No install is needed. Exit 1 means an unmet peer, and exit
3 means the registry was unreachable, so nothing was checked. Report a 3 as
"not checked", never as clean.
Then check the pack itself:
- in a site repo, against a
claude-skills-library clone:
diff -rq <clone>/packs/web-excellence/skills .claude/skills | grep -v "Only in .claude/skills"
lists every installed pack skill that differs from the pack, and every pack
skill that is missing. (install.sh --dry-run prints "update" for every
installed skill whether or not it changed, so it cannot answer this.) The fix
is install.sh <repo>, and its diff is reviewed like any other change;
- in
claude-skills-library: packs/web-excellence/sync-upstream.sh --check
lists vendored skills that drifted from their upstream pins.
2. Triage — in this order
- Unmet peers. These are broken now. Fix them by moving versions so the
ranges hold, either by upgrading the host (React 18 → 19 for R3F 9) or by
moving the dependent to the line that matches the host (R3F 8 for React 18).
Pick the option that changes fewer surfaces and say why.
- Advisories. Run
pnpm audit --prod or npm audit --omit=dev if
available, and record the result as it printed.
- Breaking drift. A major bump, and in
0.x any minor bump: 0.185 → 0.186
is a breaking change by semver. Read the release notes or changelog for every
version crossed before editing, and list the breaking items you found.
- Minor and patch drift. Batch it, one family per commit.
Leave a bump for later when its notes describe a change you cannot verify here.
Say which one and what would verify it.
3. Branch and change
- One branch per repo:
agent/<harness>/web-steward-<yyyy-mm-dd>, cut from the
default branch.
- One commit per package family (
react + react-dom + @types/react;
three + @react-three/* + @types/three; gsap + @gsap/react; and so on),
so a revert removes one family and nothing else.
- Use the repo's package manager to change versions. Regenerate the lockfile
with it and never edit a lockfile by hand. Pin
0.x packages exactly (-E).
- Re-run
peer-check.mjs after each family. Unmet peers must reach zero
before the next family.
4. Gates and proof
- Run the repo's own gates, read from its
CLAUDE.md/AGENTS.md: type-check,
lint, build at minimum. Paste the result lines.
- Take the route's first-load JS from the build output before and after. A
dependency upgrade that adds weight is a finding.
- Find the routes that import a changed package (
grep -rl "<package>" app components).
Run visual-proof on those routes before (default branch) and after
(upgrade branch), at 375 / 768 / 1440 in light and dark, plus a
--reduced-motion run where they animate. Open the shots and compare them.
- Animation libraries (GSAP, Lenis, Framer Motion) change timing without
changing pixels. For those routes, also run
review-animations on any code
the upgrade forced you to edit.
5. Hand off — draft PR, never merge
Open a draft PR with this body, and keep the same block as the reply:
Repo: <name> @ <base sha>
Peers: before <N unmet> → after <N unmet> (peer-check output attached)
Bumps: <pkg> <from> → <to> (<drift class>) — breaking notes: <list or "none in notes">
Deferred: <pkg> — <why, and what would verify it>
Pack: <skills that differ from the pack, or "in sync">
Gates: <command → result>, one per line
Weight: <route> first-load JS <before> → <after>
Visual: <routes> before/after, 375 / 768 / 1440, light + dark (+ reduced motion)
Open: <anything not verified>
On an unattended run with nothing to upgrade, still leave a durable record:
commit the report or comment on the standing upkeep issue. A run that leaves
nothing behind is indistinguishable from a run that never happened.
Refusals
- No
--force, --legacy-peer-deps, or overrides/resolutions entries to
silence a peer error. They hide the mismatch and leave the runtime failure in place.
- No React or Next.js major mixed into the same commit as other bumps.
- No hand edits to vendored skills. Re-run
install.sh from the pack.
- No upgrade on a protected surface, such as a homepage under a
preservation contract, without that repo's own preservation steps.
- Never merge, mark ready, or deploy. The PR is the deliverable.
1---2name: web-steward3description: Keep a website's front-end dependencies and installed design skills current without breaking the page. Covers React, Next.js, three.js, React Three Fiber, drei, Paper Shaders, GSAP, Lenis, Framer Motion, Tailwind, and this pack's own skills. Use when asked to upgrade, update, or audit dependencies on a web repo; when a build or install warns about unmet peer dependencies; before adding any dependency that declares peers; or on a scheduled upkeep run. Produces a peer and drift report from the lockfile and the npm registry, then one upgrade branch per repo with gates and before/after proof. Never merges.4metadata:5 source: https://skillmd.com/skills/frankxai/web-steward6---78# Web steward910Upgrades break pages in two quiet ways: a peer dependency that no longer11matches (the build passes, the component fails at runtime), and a minor bump12that changes how something looks or moves. This skill catches the first13mechanically and the second with screenshots, and it stops at a draft PR.1415## 1. Inventory — measure before touching anything1617```bash18node .claude/skills/web-steward/peer-check.mjs --root . # watch list19node .claude/skills/web-steward/peer-check.mjs --root apps/web # a monorepo app20node .claude/skills/web-steward/peer-check.mjs --root . --all # every direct dependency21```2223It reads `package.json` plus `pnpm-lock.yaml`, `package-lock.json`, or24`node_modules`, and asks the npm registry for each package's peers at the25resolved version. No install is needed. Exit `1` means an unmet peer, and exit26`3` means the registry was unreachable, so nothing was checked. Report a `3` as27"not checked", never as clean.2829Then check the pack itself:3031- in a site repo, against a `claude-skills-library` clone:32 `diff -rq <clone>/packs/web-excellence/skills .claude/skills | grep -v "Only in .claude/skills"`33 lists every installed pack skill that differs from the pack, and every pack34 skill that is missing. (`install.sh --dry-run` prints "update" for every35 installed skill whether or not it changed, so it cannot answer this.) The fix36 is `install.sh <repo>`, and its diff is reviewed like any other change;37- in `claude-skills-library`: `packs/web-excellence/sync-upstream.sh --check`38 lists vendored skills that drifted from their upstream pins.3940## 2. Triage — in this order41421. **Unmet peers.** These are broken now. Fix them by moving versions so the43 ranges hold, either by upgrading the host (React 18 → 19 for R3F 9) or by44 moving the dependent to the line that matches the host (R3F 8 for React 18).45 Pick the option that changes fewer surfaces and say why.462. **Advisories.** Run `pnpm audit --prod` or `npm audit --omit=dev` if47 available, and record the result as it printed.483. **Breaking drift.** A major bump, and in `0.x` any minor bump: `0.185 → 0.186`49 is a breaking change by semver. Read the release notes or changelog for every50 version crossed before editing, and list the breaking items you found.514. **Minor and patch drift.** Batch it, one family per commit.5253Leave a bump for later when its notes describe a change you cannot verify here.54Say which one and what would verify it.5556## 3. Branch and change5758- One branch per repo: `agent/<harness>/web-steward-<yyyy-mm-dd>`, cut from the59 default branch.60- One commit per package family (`react` + `react-dom` + `@types/react`;61 `three` + `@react-three/*` + `@types/three`; `gsap` + `@gsap/react`; and so on),62 so a revert removes one family and nothing else.63- Use the repo's package manager to change versions. Regenerate the lockfile64 with it and never edit a lockfile by hand. Pin `0.x` packages exactly (`-E`).65- Re-run `peer-check.mjs` after each family. Unmet peers must reach zero66 before the next family.6768## 4. Gates and proof6970- Run the repo's own gates, read from its `CLAUDE.md`/`AGENTS.md`: type-check,71 lint, build at minimum. Paste the result lines.72- Take the route's first-load JS from the build output before and after. A73 dependency upgrade that adds weight is a finding.74- Find the routes that import a changed package (`grep -rl "<package>" app components`).75 Run `visual-proof` on those routes before (default branch) and after76 (upgrade branch), at 375 / 768 / 1440 in light and dark, plus a77 `--reduced-motion` run where they animate. Open the shots and compare them.78- Animation libraries (GSAP, Lenis, Framer Motion) change timing without79 changing pixels. For those routes, also run `review-animations` on any code80 the upgrade forced you to edit.8182## 5. Hand off — draft PR, never merge8384Open a draft PR with this body, and keep the same block as the reply:8586```87Repo: <name> @ <base sha>88Peers: before <N unmet> → after <N unmet> (peer-check output attached)89Bumps: <pkg> <from> → <to> (<drift class>) — breaking notes: <list or "none in notes">90Deferred: <pkg> — <why, and what would verify it>91Pack: <skills that differ from the pack, or "in sync">92Gates: <command → result>, one per line93Weight: <route> first-load JS <before> → <after>94Visual: <routes> before/after, 375 / 768 / 1440, light + dark (+ reduced motion)95Open: <anything not verified>96```9798On an unattended run with nothing to upgrade, still leave a durable record:99commit the report or comment on the standing upkeep issue. A run that leaves100nothing behind is indistinguishable from a run that never happened.101102## Refusals103104- **No `--force`, `--legacy-peer-deps`, or `overrides`/`resolutions` entries to105 silence a peer error.** They hide the mismatch and leave the runtime failure in place.106- **No React or Next.js major mixed into the same commit as other bumps.**107- **No hand edits to vendored skills.** Re-run `install.sh` from the pack.108- **No upgrade on a protected surface**, such as a homepage under a109 preservation contract, without that repo's own preservation steps.110- **Never merge, mark ready, or deploy.** The PR is the deliverable.