paperclip: Skill for Claude Code

Release Changelog Skill

Generate the user-facing changelog for the stable Paperclip release.

Versioning Model

Paperclip uses calendar versioning (calver):

• Stable releases: YYYY.MDD.P (e.g. 2026.318.0)
• Canary releases: YYYY.MDD.P-canary.N (e.g. 2026.318.1-canary.0)
• Git tags: vYYYY.MDD.P for stable, canary/vYYYY.MDD.P-canary.N for canary

There are no major/minor/patch bumps. The stable version is derived from the intended release date (UTC) plus the next same-day stable patch slot.

Output:

• releases/vYYYY.MDD.P.md
• a release Case, upserted by (caseType, key) when Cases are enabled, with a body document revision containing the changelog body

Important rules:

• even if there are canary releases such as 2026.318.1-canary.0, the changelog file stays releases/v2026.318.1.md
• do not derive versions from semver bump types
• do not create canary changelog files

Channel Process — Source Commit and File Location

Stables promote a soaked beta, so the changelog describes the beta's source commit, not the tip of master:

• The release source is the commit the newest beta/v<beta-version> tag points at ({beta-src} below). Resolve it with:

  git fetch origin --tags
  npm view paperclipai dist-tags   # the beta dist-tag names the version
  git rev-parse 'beta/v{beta-version}^{commit}'
  

• Commits on master after {beta-src} ship in the next release. Never include them; they are input for a "what's next" section, not the changelog.

• During the soak, the file lives at releases/beta/v{beta-version}.md on the branch release-notes/v{beta-version} (PR to master). The release workflow pushes that branch with a generated skeleton when the beta publishes; work on it and rewrite the skeleton in place. If the branch does not exist (a beta cut before the automation), create it from origin/master and seed the skeleton:

  ./scripts/draft-stable-notes.sh {beta-version}