upgrade-published-deps
Skill382 starsChanged 5 days agoISCView on GitHub
Upgrade dependencies on the published surface of the @confect/* packages (their dependencies/peerDependencies), adding a changeset only when consumers are affected
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- audit-convexSkill
- create-changesetSkill
- effectSkill
- managing-prereleasesSkill
- release-docsSkill
- upgrade-internal-depsSkill
- upgrade-runtime-pinsSkill
- writing-commit-messagesSkill
- writing-technical-documentationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 8 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
When bumping an in-scope dependency, update its development pins, dependency ranges, and overrides across the workspace together.
- Very specific: line 38
Do not create routine upgrades of effect or its in-scope runtime companions, refresh their development pins or overrides, or raise their …
- Distinctive: line 48
When no fix is needed, report that no upgrade is needed rather than listing routine patches as migrations awaiting verification.
- Very specific: line 50
Read the release notes/changelogs for each pending update before applying it.
- Distinctive: line 53
Instead, summarize what's available, what it breaks, and a rough migration scope—in the PR description if this run opens one, otherwise in …
- Distinctive: line 56
If a non-major upgrade snowballs into a real migration (API rewrites, behavioral changes beyond mechanical fixes), drop it from the batch …
- Very specific: line 59
If the behavior of Convex or the Confect CLI changed, regenerate the server's mock-backend fixtures and the shared local-backend fixtures …
- Distinctive: line 62
Commit the complete output, including newly generated files: CI checks both tracked changes and untracked output in each fixture directory.
- Very specific: line 73
Keep existing exact runtime pins, such as the server's AI dependencies, and keep devDependencies exactly pinned.
- Very specific: line 76
Keep the Foldkit adapter's peers on a verified pair: a pre-1.0 Foldkit minor (^0.170.0 admits only 0.170.x) and an Effect minor (~4.1.0).
- Very specific: line 82
Read the published metadata for each selected dependency version, including its peerDependencies (for example, pnpm view …
- Very specific: line 87
Leave a published peer range alone unless Confect's code or required dependencies demand a higher minimum.
- Distinctive: line 98
Check peer compatibility without treating workspace overrides as evidence: our lockfile and overrides do not constrain consumers' …
- Distinctive: line 102
When changing a peer range, inspect the packed package manifests to confirm the published requirement, and call out the change in the PR …
- Distinctive: line 107
If nothing gets applied, say so and stop—no branch, no PR, even if deferred upgrades (e.g.
- Very specific: line 110
Verify with the full repo checks (pnpm check, pnpm test, pnpm build) plus pnpm test:server:mock-backend, pnpm test:server:local-backend, …
- Very specific: line 116
Add a changeset iff the applied upgrade changes something consumers can observe: a published package's dependencies or peerDependencies, 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
Upgrade the dependencies that consumers of the @confect/* packages can see,
and open a PR for review. Never merge it yourself.
Scope
Exclude convex, convex-test, convex-helpers, and @convex-dev/* packages,
including their workspace pins and overrides. The audit-convex skill owns
their upgrades and feature assessments. When that skill references the shared
policies below, apply them to its Convex scope rather than running this entire
upgrade workflow.
A package is published iff its package.json does not say "private": true—note that some private fixture workspaces also carry @confect/* names, so go
by the field, not the name. A dependency is in scope iff it appears in the
dependencies or peerDependencies of any published package, together with
its lockstep companions: packages that must match its version (e.g.
react-dom with react) and any overrides entry in pnpm-workspace.yaml
that pins one of its transitive dependencies (e.g. @effect/typeclass with
effect). Everything else is handled by the upgrade-internal-deps skill.
When bumping an in-scope dependency, update its development pins, dependency
ranges, and overrides across the workspace together; handle published peer
ranges under the policy below. Search the repo for the dependency's name
rather than enumerating locations from memory. Syncpack (pnpm lint) polices consistency
between package.json files, but nothing lints the overrides block, and
a stale override silently forces the old version at install time. After
bumping, confirm the new versions actually resolved (e.g. pnpm why <dep>).
Rules
- Trust Effect's patch-version compatibility within the supported minor.
Existing compatible ranges already admit newer patches; supporting them
does not require a Confect release or manual certification of each patch.
Do not create routine upgrades of
effector its in-scope runtime companions, refresh their development pins or overrides, or raise their minimums solely because a newer patch exists. Existing regression and consumer checks may continue; they are not a per-patch support gate. - Apply an Effect patch upgrade only for a concrete correctness or security fix Confect needs. Cite the upstream fix and explain the affected Confect behavior before selecting versions. A newly selected companion's higher Effect peer floor is not itself a reason to upgrade: retain the existing compatible dependency requirements when no such fix is needed. Do not override or ignore upstream peers to force an incompatible combination. When no fix is needed, report that no upgrade is needed rather than listing routine patches as migrations awaiting verification.
- Read the release notes/changelogs for each pending update before applying
it. Treat minor bumps of
0.xpackages as potentially breaking, not routine. - Never attempt a major of a peer ecosystem (effect, convex, react). Instead, summarize what's available, what it breaks, and a rough migration scope—in the PR description if this run opens one, otherwise in your final report (the no-PR rule below still applies).
- If a non-major upgrade snowballs into a real migration (API rewrites, behavioral changes beyond mechanical fixes), drop it from the batch and document it the same way.
- If the behavior of Convex or the Confect CLI changed, regenerate the server's
mock-backend fixtures and the shared local-backend fixtures with
pnpm codegen:server:mock-backendandpnpm codegen:local-backend. Commit the complete output, including newly generated files: CI checks both tracked changes and untracked output in each fixture directory.
Dependency ranges and peer compatibility
- Preserve existing dependency range styles. Keep caret ranges for stable
APIs; do not replace them with exact pins merely because they belong to
the Effect ecosystem. Effect APIs marked unstable may break in minor
releases. The CLI and server use these APIs, so keep their
effectpeers and@effect/platform-noderequirements within the verified minor using tilde ranges. Update their Syncpack rule when migrating to a new minor. Keep existing exact runtime pins, such as the server's AI dependencies, and keepdevDependenciesexactly pinned. Do not normalize these different roles into one version policy during a routine upgrade. - Keep the Foldkit adapter's peers on a verified pair: a pre-1.0 Foldkit minor
(
^0.170.0admits only 0.170.x) and an Effect minor (~4.1.0). Align the browser platform with Foldkit's published peer requirement. Update the adapter's Syncpack rules, exact development pins, documentation, and both packed-consumer lanes together; do not use workspace overrides to claim compatibility with a new Foldkit or Effect minor. - Read the published metadata for each selected dependency version,
including its
peerDependencies(for example,pnpm view @effect/platform-node@4.0.1 peerDependencies --json). Account for relevant transitive peer requirements too. A dependency upgrade can raise the effective minimum Effect version even when Confect needs no code edits. - Leave a published peer range alone unless Confect's code or required
dependencies demand a higher minimum. When they do, make that minimum
explicit in the affected package's peer range. For Effect patches, first
establish the correctness or security need under the rules above; choosing
an optional upgrade must not manufacture that need. For example, if a fix
Confect needs requires a CLI dependency with an
effect: ^4.1.3peer, raise the CLI's Effect floor to~4.1.3and explain why older patches cannot meet that requirement. Do not raise unrelated packages' floors just to match development pins, and do not require every Effect package to have the same version number. Document a raised peer floor in a minor changeset, per the create-changeset skill, with the version consumers must install. - Check peer compatibility without treating workspace overrides as evidence: our lockfile and overrides do not constrain consumers' installations. Consumers must satisfy the intersection of all applicable peer ranges; caret dependencies can resolve to later releases with higher peer floors. When changing a peer range, inspect the packed package manifests to confirm the published requirement, and call out the change in the PR description.
Delivering
- If nothing gets applied, say so and stop—no branch, no PR, even if deferred upgrades (e.g. a peer-ecosystem major) were spotted; the next scheduled run will surface them again.
- Verify with the full repo checks (
pnpm check,pnpm test,pnpm build) pluspnpm test:server:mock-backend,pnpm test:server:local-backend, andpnpm test:js:local-backend. Run the two local-backend suites sequentially because they share ports. Anything the local environment genuinely can't run, leave to the PR's CI—and get it green. Drop upgrades that fail here before moving on. - Add a changeset iff the applied upgrade changes something consumers can
observe: a published package's
dependenciesorpeerDependencies, a consumer-facing range or override, shipped code, or runtime behavior. AdevDependencies-only edit does not become user-facing merely because itspackage.jsonbelongs to a published package; do not add a changeset for that alone. Follow the create-changeset skill when a changeset is required. - Push a branch (
deps/<short-description>, unless this session was assigned a branch) and open a PR againstmain. In the body, list what was bumped with links to release notes, and note anything deliberately skipped and why.
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.

