Coordinate a full Paperclip release across engineering verification, npm, GitHub, smoke testing, and announcement follow-up. Use when leadership asks to ship a release, not merely to discuss versioning.
Run the full Paperclip maintainer release workflow, not just an npm publish.
This skill coordinates:
stable changelog drafting via release-changelog
canary verification and publish status from master
Docker smoke testing via scripts/docker-onboard-smoke.sh
manual stable promotion from a chosen source ref
GitHub Release creation
website / announcement follow-up tasks
Trigger
Use this skill when leadership asks for:
"do a release"
"ship the release"
"promote this canary to stable"
"cut the stable release"
Preconditions
Before proceeding, verify all of the following:
.agents/skills/release-changelog/SKILL.md exists and is usable.
The repo working tree is clean, including untracked files.
Verwandte Skills
There is at least one canary or candidate commit since the last stable tag.
The candidate SHA has passed the verification gate or is about to.
If manifests changed, the CI-owned pnpm-lock.yaml refresh is already merged on master.
npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
If running through Paperclip, you have issue context for status updates and follow-up task creation.
If any precondition fails, stop and report the blocker.
Inputs
Collect these inputs up front:
whether the target is a canary check or a stable promotion
the candidate source_ref for stable
whether the stable run is dry-run or live
release issue / company context for website and announcement follow-up
Step 0 — Release Model
Paperclip now uses a commit-driven release model:
every push to master publishes a canary automatically
canaries use YYYY.MDD.P-canary.N
stable releases use YYYY.MDD.P
the middle slot is MDD, where M is the UTC month and DD is the zero-padded UTC day
the stable patch slot increments when more than one stable ships on the same UTC date
stable releases are manually promoted from a chosen tested commit or canary source commit
only stable releases get releases/vYYYY.MDD.P.md, git tag vYYYY.MDD.P, and a GitHub Release
Critical consequences:
do not use release branches as the default path
do not derive major/minor/patch bumps
do not create canary changelog files
do not create canary GitHub Releases
Step 1 — Choose the Candidate
For canary validation:
inspect the latest successful canary run on master
record the canary version and source SHA
For stable promotion:
choose the tested source ref
confirm it is the exact SHA you want to promote
resolve the target stable version with ./scripts/release.sh stable --date YYYY-MM-DD --print-version
Useful commands:
git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version
Step 2 — Draft the Stable Changelog
Stable changelog files live at:
releases/vYYYY.MDD.P.md
Invoke release-changelog and generate or update the stable notes only.
Rules:
review the draft with a human before publish
preserve manual edits if the file already exists
keep the filename stable-only
do not create a canary changelog file
Step 3 — Verify the Candidate SHA
Run the standard gate:
pnpm -r typecheck
pnpm test:run
pnpm build
If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.
For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.
Step 4 — Validate the Canary
The normal canary path is automatic from master via:
.github/workflows/release.yml
Confirm:
verification passed
npm canary publish succeeded
git tag canary/vYYYY.MDD.P-canary.N exists
Useful checks:
npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5