// Generate the stable Paperclip release changelog at releases/vYYYY.MDD.P.md by reading commits, changesets, and merged PR context since the last stable tag.
| name | release-changelog |
| description | Generate the stable Paperclip release changelog at releases/vYYYY.MDD.P.md by reading commits, changesets, and merged PR context since the last stable tag. |
Generate the user-facing changelog for the stable Paperclip release.
Paperclip uses calendar versioning (calver):
YYYY.MDD.P (e.g. 2026.318.0)YYYY.MDD.P-canary.N (e.g. 2026.318.1-canary.0)vYYYY.MDD.P for stable, canary/vYYYY.MDD.P-canary.N for canaryThere 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.mdImportant rules:
2026.318.1-canary.0, the changelog file stays releases/v2026.318.1.mdBefore generating anything, check whether the file already exists:
ls releases/vYYYY.MDD.P.md 2>/dev/null
If it exists:
Find the last stable tag:
git tag --list 'v*' --sort=-version:refname | head -1
git log v{last}..HEAD --oneline --no-merges
The stable version comes from one of:
./scripts/release.sh stable --date YYYY-MM-DD --print-versiondoc/RELEASING.mdDo not derive the changelog version from a canary tag or prerelease suffix. Do not derive major/minor/patch bumps from API intent — calver uses the date and same-day stable slot.
Collect release data from:
.changeset/*.md filesgh when availableUseful commands:
git log v{last}..HEAD --oneline --no-merges
git log v{last}..HEAD --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels
Look for:
BREAKING: or BREAKING CHANGE: commit signalsKey commands:
git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
git diff v{last}..HEAD -- packages/db/src/schema/
git diff v{last}..HEAD -- server/src/routes/ server/src/api/
git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
If breaking changes are detected, flag them prominently — they must appear in the Breaking Changes section with an upgrade path.
Use these stable changelog sections:
Breaking ChangesHighlightsImprovementsFixesUpgrade Guide when neededExclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.
Guidelines:
When a bullet item clearly maps to a merged pull request, add inline attribution at the end of the entry in this format:
- **Feature name** — Description. ([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)
Rules:
Merge pull request #N from user/branch) to map PRs.([#10](url), [#12](url), @user1, @user2).Template:
# vYYYY.MDD.P
> Released: YYYY-MM-DD
## Breaking Changes
## Highlights
## Improvements
## Fixes
## Upgrade Guide
## Contributors
Thank you to everyone who contributed to this release!
@username1, @username2, @username3
Omit empty sections except Highlights, Improvements, and Fixes, which should usually exist.
The Contributors section should always be included. List every person who authored
commits in the release range, @-mentioning them by their GitHub username (not their
real name or email). To find GitHub usernames:
git log v{last}..HEAD --oneline --merges — the branch prefix (e.g. from username/branch) gives the GitHub username.user@users.noreply.github.com, the username is the part before @.gh api users/{guess} or the PR page.Never expose contributor email addresses. Use @username only.
Exclude bot accounts (e.g. lockfile-bot, dependabot) from the list. List contributors
in alphabetical order by GitHub username (case-insensitive).
Before handing it off:
-canary language in the title or filenameThis skill never publishes anything. It only prepares the stable changelog artifact.
Interact with the Paperclip control plane API to manage tasks, coordinate with other agents, and follow company governance. Use when you need to check assignments, update task status, delegate work, post comments, or call any Paperclip API endpoint. Do NOT use for the actual domain work itself (writing code, research, etc.) — only for Paperclip coordination.
Create new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hire request.
Create agent company packages conforming to the Agent Companies specification (agentcompanies/v1). Use when a user wants to create a new agent company from scratch, build a company around an existing git repo or skills collection, or scaffold a team/department of agents. Triggers on: "create a company", "make me a company", "build a company from this repo", "set up an agent company", "create a team of agents", "hire some agents", or when given a repo URL and asked to turn it into a company. Do NOT use for importing an existing company package (use the CLI import command instead) or for modifying a company that is already running in Paperclip.
Create new Paperclip plugins with the current alpha SDK/runtime. Use when scaffolding a plugin package, adding a new example plugin, or updating plugin authoring docs. Covers the supported worker/UI surface, route conventions, scaffold flow, and verification steps.