agentleFS
rjdelleceserjdellecese/confect/.agents/skills/upgrade-published-deps/SKILL.md

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

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

    When bumping an in-scope dependency, update its development pins, dependency ranges, and overrides across the workspace together.

    line 25
  2. Very specific:

    Do not create routine upgrades of effect or its in-scope runtime companions, refresh their development pins or overrides, or raise their …

    line 38
  3. Distinctive:

    When no fix is needed, report that no upgrade is needed rather than listing routine patches as migrations awaiting verification.

    line 48
  4. Very specific:

    Read the release notes/changelogs for each pending update before applying it.

    line 50
  5. Distinctive:

    Instead, summarize what's available, what it breaks, and a rough migration scope—in the PR description if this run opens one, otherwise in …

    line 53
  6. Distinctive:

    If a non-major upgrade snowballs into a real migration (API rewrites, behavioral changes beyond mechanical fixes), drop it from the batch …

    line 56
  7. Very specific:

    If the behavior of Convex or the Confect CLI changed, regenerate the server's mock-backend fixtures and the shared local-backend fixtures …

    line 59
  8. Distinctive:

    Commit the complete output, including newly generated files: CI checks both tracked changes and untracked output in each fixture directory.

    line 62
  9. Very specific:

    Keep existing exact runtime pins, such as the server's AI dependencies, and keep devDependencies exactly pinned.

    line 73
  10. Very specific:

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

    line 76
  11. Very specific:

    Read the published metadata for each selected dependency version, including its peerDependencies (for example, pnpm view …

    line 82
  12. Very specific:

    Leave a published peer range alone unless Confect's code or required dependencies demand a higher minimum.

    line 87
  13. Distinctive:

    Check peer compatibility without treating workspace overrides as evidence: our lockfile and overrides do not constrain consumers' …

    line 98
  14. Distinctive:

    When changing a peer range, inspect the packed package manifests to confirm the published requirement, and call out the change in the PR …

    line 102
  15. Distinctive:

    If nothing gets applied, say so and stop—no branch, no PR, even if deferred upgrades (e.g.

    line 107
  16. Very specific:

    Verify with the full repo checks (pnpm check, pnpm test, pnpm build) plus pnpm test:server:mock-backend, pnpm test:server:local-backend, …

    line 110
  17. Very specific:

    Add a changeset iff the applied upgrade changes something consumers can observe: a published package's dependencies or peerDependencies, a …

    line 116

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

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 effect or 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.x packages 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-backend and pnpm 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 effect peers and @effect/platform-node requirements 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 keep devDependencies exactly 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.0 admits 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.3 peer, raise the CLI's Effect floor to ~4.1.3 and 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

  1. 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.
  2. Verify with the full repo checks (pnpm check, pnpm test, pnpm build) plus pnpm test:server:mock-backend, pnpm test:server:local-backend, and pnpm 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.
  3. Add a changeset iff the applied upgrade changes something consumers can observe: a published package's dependencies or peerDependencies, a consumer-facing range or override, shipped code, or runtime behavior. A devDependencies-only edit does not become user-facing merely because its package.json belongs to a published package; do not add a changeset for that alone. Follow the create-changeset skill when a changeset is required.
  4. Push a branch (deps/<short-description>, unless this session was assigned a branch) and open a PR against main. In the body, list what was bumped with links to release notes, and note anything deliberately skipped and why.

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.