tony Update one package
Move one named package to a target version wherever it is pinned, with a body that says what the release means for each repository it lands in.
Use ../updating-packages/SKILL.md for the
phase structure, and its references:
../../references/repo-scope.md,
../../references/ecosystems.md,
../../references/commit-conventions.md,
../../references/upstream-links.md, and
../../references/follow-ups.md.
For a full sweep, use /package-updater:update. For a runtime or
toolchain pin, use /package-updater:update-toolchain.
User arguments: $ARGUMENTS
Context
Repository:
!git remote get-url origin 2>/dev/null || echo "(not a git repository)"
Default branch:
!git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo "(unknown)"
Manifests that could pin it:
!out=$(git ls-files -- 'pyproject.toml' '**/pyproject.toml' 'requirements*.txt' 'package.json' '**/package.json' 'Cargo.toml' 'go.mod' 2>/dev/null | grep -v node_modules | head -30); if [ -n "$out" ]; then echo "$out"; else echo "(none found)"; fi
Cooldown configuration:
!out=$({ grep -hi 'minimumReleaseAge\|min-release-age' pnpm-workspace.yaml .npmrc; grep -hi 'exclude-newer' uv.toml pyproject.toml "${UV_CONFIG_FILE:-$HOME/.config/uv/uv.toml}"; } 2>/dev/null); if [ -n "$out" ]; then echo "$out"; else echo "(no cooldown configured)"; fi
Procedure
1. Resolve the target and confirm it exists
If the user named a version, use it. Otherwise take the latest stable release. Either way confirm it is published and record its publication timestamp — you need it to reason about the cooldown, and a version written before it is confirmed to exist is the expensive failure this ordering prevents.
If the cooldown currently hides it, say when it becomes visible and stop rather than exempting it. Exempt only when the release is needed now, and then per the exemption protocol in the ecosystems reference: narrow, annotated, its own commit, reverted when the block lapses.
2. Find every pin site
The package can be pinned in more than one place in one repository — several workspace members, a dependency group, a lockfile, a pre-commit configuration, a CI workflow. Enumerate them all. Every pin site in a repository moves in the same commit, or none does.
Note where the pin shapes disagree — an exact pin in one package and a caret range in another is drift worth reporting even when both resolve to the same version.
3. Establish scope
Default scope is the current repository. --root, --repo and
--owner widen it as in /package-updater:update. Drop repositories
that do not pin the package and those already at the target.
A widened scope goes through
../../references/repo-scope.md first: worktrees and
forks are out, and a repository whose ownership is unclear is a question
for the user, not a guess.
4. Research the span once
Read the release notes for every version between the current pin and the target, not just the endpoint. Collect links per the upstream-links reference and verify each resolves.
Then, separately per repository, work out what the release actually reaches. A release note describes the package; only the repository can say whether the change applies. Where the general claim does not hold, the body says something different in that repository.
Predict the follow-up now — a formatter, compiler or framework bump usually needs one, per the follow-ups reference.
5. Present the plan and wait
Show the pin sites per repository, the target, the verified links, the
follow-up expected, and whether any repository will be red between the
bump and its follow-up. With --audit-only, stop here.
6. Land
One commit per repository, subject and body per the commit-conventions
reference — why: then what:, written through a heredoc or a file.
The follow-up lands immediately after as its own commit.
Commits land on the default branch by default. --branch works on a
branch; --pr opens a pull request; --no-push stops after committing.
7. Verify
Run the project's own quality checks. Attribute failures against the default branch before blaming the bump. A knowingly-red bump is only acceptable when its body said so and its follow-up lands in the same run.
Rules
- No version is written before it is confirmed published; no URL before it is confirmed to resolve.
- Every pin site in a repository moves in one commit, or none does.
- The body says what the release means for this repository, never a generalization that does not hold here.
- A follow-up is its own commit, never folded into the bump.
- Waiting out a cooldown is the default; an exemption is narrow, annotated, separately committed and reverted.
- Report unrelated breakage; fix it only when the bump caused it.
- ruff belongs to
/ruff:bump; action pins to/github-actions:update-action; Terraform providers to/terraform:bump-provider.
Output
Open with a one-line hero (✓ <package> <old> -> <new> across N repos
or ⚠ Gated: <package> <version> visible <date>), then exactly these
sections:
## Release— what the span changes, with verified links to every version in it.## Pin sites— per repository, every place the package is pinned and its current shape, plus what was excluded as not pinning it or already current.## Impact— per repository, what the release actually reaches there, and where the general claim does not apply.## Commits— the commits made, their follow-ups, and whether they were pushed.## Verification— the quality checks run and their real results, with any pre-existing failure named as pre-existing.## Drift— pin shapes disagreeing across a workspace or a fleet.
End with an AskUserQuestion panel offering next steps — for example:
run the sweep for the rest of the tree, take a gated release once it
ages out, land the follow-up separately, or stop here. Skip the panel
only in plan mode.