Prepare and execute a Plannotator release — draft release notes with full contributor credit, bump versions across all package files, build in dependency order, and kick off the tag-driven release pipeline. Use this skill whenever the user mentions preparing a release, bumping versions, writing release notes, tagging a release, or publishing. Also trigger when the user says things like "let's ship", "prep a release", "what's changed since last release", or "time to cut a new version".
The process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.
This is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.
git tag --sort=-v:refname | head -1git log --oneline <last-tag>..HEAD for commit historygit log --merges --oneline <last-tag>..HEAD for merged PRsgh pr view <number> --json title,author,body,closedIssues,labels to get details.This is critical. Every person who participated in the release gets credit — not just PR authors.
For each PR and linked issue, collect:
Use the GitHub API via gh:
# Get issue details including author
gh issue view <number> --json author,title,body
# Get issue comments to find participants
gh api repos/backnotprop/plannotator/issues/<number>/comments --jq '.[].user.login'
# Get PR review comments
gh api repos/backnotprop/plannotator/pulls/<number>/comments --jq '.[].user.login'
Read the reference release notes in references/ for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.
release-notes-v0.13.0.md — large release, 14 PRs, 3 first-time contributors, "New Contributors" + narrative "Contributors" sectionrelease-notes-v0.12.0.md — large community release, 14 PRs, 10 external, detailed narrative "Contributors" sectionrelease-notes-v0.13.1.md — small patch release, 2 PRs, no external authors, "Community" section focused on issue reportersPay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative "Contributors" section; a patch driven by issue reports uses a lighter "Community" section.
Write the file to the repo root as RELEASE_NOTES_v<VERSION>.md.
X/Twitter follow link — first line, always the same:
Follow [@plannotator](https://x.com/plannotator) on X for updates
"Missed recent releases?" collapsible table — copy from the previous release's notes, then:
"What's New in vX.Y.Z" — the heart of the notes
### subsection with:
closing [#N], and contributor attribution### Additional Changes as bold-titled bulletsInstall / Update — standard block, read from the previous release notes and reuse verbatim
"What's Changed" — bullet list of every PR in the release:
- feat: descriptive PR title by @author in [#N](url)
"New Contributors" — if any first-time contributors:
- @username made their first contribution in [#N](url)
"Contributors" or "Community" — narrative section recognizing everyone who participated:
Full Changelog link:
**Full Changelog**: https://github.com/backnotprop/plannotator/compare/<prev-tag>...<new-tag>
@username — bare at-mentions, not markdown links like [@user](url). GitHub renders bare @mentions with avatar icons in release notes. This is important for community recognition.Write the draft to RELEASE_NOTES_v<VERSION>.md in the repo root and tell the user it's ready for review. Do not git add or commit this file — release notes are kept untracked by design. Wait for their feedback before proceeding to Phase 2.
Bump the version string in these 7 files (and only these — other package.json files use stub versions):
| File | Field |
|---|---|
package.json (root) | "version" |
apps/opencode-plugin/package.json | "version" |
apps/pi-extension/package.json | "version" |
apps/hook/.claude-plugin/plugin.json | "version" |
apps/copilot/plugin.json | "version" |
openpackage.yml (root) | version: |
packages/server/package.json | "version" |
Read each file, confirm the current version matches expectations, then update all 7 atomically.
Do not bump the VS Code extension (apps/vscode-extension/package.json) — it has independent versioning.
Run builds in dependency order:
bun run build:review # 1. Code review editor (standalone Vite build)
bun run build:hook # 2. Plan review + hook server (copies review's built HTML into hook dist)
bun run build:opencode # 3. OpenCode plugin (copies built HTML from hook + review)
bun run build:pi # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)
build:pi chains review and hook internally, so after steps 1-2 it only runs the pi-specific build.
Verify all builds succeed before proceeding.
After builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.
Check imports vs files array. Trace all local imports (starting with ./ or ../) from index.ts, server.ts, tool-scope.ts, and every file in server/. Verify each target is covered by a pattern in the files array of apps/pi-extension/package.json.
Check vendor.sh covers all shared/ai imports. Every ../generated/*.js import in the server files must have a corresponding entry in vendor.sh's copy loops. If a new shared module or AI module was added to packages/shared/ or packages/ai/ and is imported by Pi's server code, it must be added to vendor.sh.
Dry-run the pack. Run cd apps/pi-extension && bun pm pack --dry-run and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.
Quick smoke test. Confirm generated/ contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).
If anything is missing, fix it before proceeding to Phase 4. Common fixes:
vendor.sh's copy loopfiles array in package.json../generated/ not @plannotator/shared or @plannotator/ai)Commit the version bump:
chore: bump version to X.Y.Z
Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).
Create and push the tag:
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z
The v* tag push triggers the release pipeline (.github/workflows/release.yml).
The pipeline handles everything else:
actions/attest-build-provenance (signed through Sigstore, recorded in Rekor)@plannotator/opencode and @plannotator/pi-extension to npm with provenanceNote on immutable releases: The repo has GitHub Immutable Releases enabled, so once the v* tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to "fix" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.
Monitor the pipeline: Watch the release workflow run until it completes:
gh run list --workflow=release.yml --limit=1
gh run view <run-id> --log
Verify:
npm view @plannotator/opencode version and npm view @plannotator/pi-extension version)If anything fails, investigate the logs and report to the user before retrying.
Replace the release notes: Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:
gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v<VERSION>.md
Before tagging, verify:
bun run build:review succeededbun run build:hook succeededbun run build:opencode succeededbun run build:pi succeeded (or pi-specific build step)bun install first if dependencies changed)After tagging, verify:
gh release edit