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".
Resources
1Install
npx skillscat add backnotprop/plannotator/release-plannotator Install via the SkillsCat registry.
Plannotator Release
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.
Phase 1: Draft Release Notes
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.
Step 1: Determine scope
- Find the latest release tag:
git tag --sort=-v:refname | head -1 - Determine the new version number. Ask the user if unclear (patch, minor, or major).
- Gather all changes since the last tag:
git log --oneline <last-tag>..HEADfor commit historygit log --merges --oneline <last-tag>..HEADfor merged PRs
- For each PR, use
gh pr view <number> --json title,author,body,closedIssues,labelsto get details.
Step 2: Research contributors
This is critical. Every person who participated in the release gets credit — not just PR authors.
For each PR and linked issue, collect:
- PR authors — the person who wrote the code
- Issue reporters — who filed the bug or feature request
- Issue commenters — who participated in the discussion with useful context
- Discussion creators — who started relevant GitHub Discussions
- Feature requestors — check the linked "closes #N" issues and their authors
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'Step 3: Write the release notes
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 reporters
Pay 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.
Structure
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:
- Add the previous release (the one you're succeeding) as the newest row
- Keep roughly 10-12 rows; drop the oldest if needed
- Each row: version link + comma-separated feature highlights (short phrases). For the previous release's row, use the words of its TL;DR lines (below), joined by commas, without the labels
"What's New in vX.Y.Z" — the heart of the notes
- TL;DR first. Directly under the
## What's New in vX.Y.Zheading, put a### TL;DRheading and a list of 3 to 5 lines. The Inbox's What's new page reads this block: it shows it at the top of the release and in its list of releases. GitHub shows it too.## What's New in v0.28.53 ### TL;DR - **New:** Start an agent in a new folder, or from a git URL - **New:** "+" on each project row starts a session there - **Changed:** New message offers the open thread's files - **Off by default:** Bro mode: agents write to you in plain words Starting an agent from New message now covers a new folder, …- Write each line as
- **Label:** text. Use only these labels, spelled exactly so: New, Changed, Fixed, Removed, Off by default. - Keep each line extremely terse: 10 words or fewer, no full stop at the end. Say what the user sees, in the user's words, not in code terms.
- Put no links, PR numbers or names in the lines. Use
codeonly for a setting or a variable that the user types. - Put the biggest change first. Use Removed for something that is gone, and Off by default for a feature the user must turn on.
- Put nothing between the
### TL;DRheading and its list. The opening sentences come after the list.
- Write each line as
- Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.
- Each major feature/fix gets its own
###subsection with:- A descriptive heading (not the PR title verbatim — rephrase for clarity)
- 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.
- Credit line at the bottom: PR link, linked issues with
closing [#N], and contributor attribution
- Minor changes go under
### Additional Changesas bold-titled bullets
- TL;DR first. Directly under the
Install / 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:
- PR authors get a sentence about what they built
- Issue reporters and commenters get listed with what they reported/discussed
- Group community issue reporters in a bullet list at the end
Full Changelog link:
**Full Changelog**: https://github.com/backnotprop/plannotator/compare/<prev-tag>...<new-tag>
Writing guidelines
- Narrative over noise. Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.
- Bullets where they help. Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.
- No cliches or buzzwords. Don't say "exciting", "game-changing", "seamless", "powerful". Just describe what happened.
- No punchlines. Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.
- Speak through practical benefit. Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.
- Don't overuse em dashes. One or two per release is fine. If you notice them stacking up, restructure the sentence instead.
- Grammatical structure matters. Vary sentence structure. Active voice. Concrete subjects and verbs.
- Contributor tags. Use
@username— bare at-mentions, not markdown links like[@user](url). GitHub renders bare@mentionswith avatar icons in release notes. This is important for community recognition. - Every contributor counts. Everyone who filed an issue, left a comment that shaped a decision, or participated in a discussion gets mentioned. This project's community is its lifeblood.
Step 4: Present for review
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.
Phase 2: Version Bump
Bump the version string in these 11 files (and only these — other package.json files use stub versions). scripts/check-release-version.mjs (run in CI and on the tag) fails if any of them disagrees:
| File | Field |
|---|---|
package.json (root) |
"version" |
apps/opencode-plugin/package.json |
"version" |
apps/dsh-plugin/package.json |
"version" |
apps/cline-plugin/package.json |
"version" |
apps/openclaw-plugin/package.json |
"version" |
apps/pi-extension/package.json |
"version" |
apps/hook/.claude-plugin/plugin.json |
"version" |
apps/copilot/plugin.json |
"version" |
.github/plugin/marketplace.json |
"version" of the plannotator-copilot entry |
openpackage.yml (root) |
version: |
packages/server/package.json |
"version" |
Read each file, confirm the current version matches expectations, then update all 11 atomically.
node scripts/check-release-version.mjs (also bun run check:release-version) checks exactly these 11 files and fails the release when one differs; apps/dsh-plugin/package.json (@plannotator/dsh), apps/cline-plugin/package.json (@plannotator/cline) and apps/openclaw-plugin/package.json (@plannotator/openclaw) are among them.
@plannotator/openclaw (apps/openclaw-plugin) goes to npm like @plannotator/cline, in a publish step allowed to fail until its first version is on npm and its trusted publisher is set up. Its ClawHub release is not automated yet: see "OpenClaw on npm and ClawHub" in docs/agent-guides/project-and-development.md.
The DeepSeek Harness plugin is checked like the other packages: the release workflow's test job runs bun run typecheck (which includes apps/dsh-plugin/tsconfig.json) and bun test (which includes apps/dsh-plugin and apps/hook/server/dsh-*.test.ts).
Do not bump the VS Code extension (apps/vscode-extension/package.json) — it has independent versioning. The Droid manifest (apps/droid-plugin/.factory-plugin/plugin.json) is exempt too: Droid tracks the plugin by the marketplace's git commit and treats version as metadata.
Refresh the Feedback form's "These might help" list
After the bump, and with RELEASE_NOTES_v<VERSION>.md in the repo root, run:
bun scripts/feedback-search-index.tsIt reads public release notes, open issue titles, fixed closed issue titles (with the release whose notes link their fix) and open and merged PR titles with gh, and rewrites packages/inbox/feedbackSearch.data.json. If gh fails or nothing comes back, the file stays as it is.
Phase 3: Build
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:dsh # 4. DeepSeek Harness plugin (Node bundle; no HTML)
bun run build:cline # 5. Cline plugin (Node bundle; no HTML)
bun run build:openclaw # 6. OpenClaw plugin (Node bundle; no HTML)
bun run build:pi # 7. 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.
Pi Parity Gate
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
filesarray. Trace all local imports (starting with./or../) fromindex.ts,server.ts,tool-scope.ts, and every file inserver/. Verify each target is covered by a pattern in thefilesarray ofapps/pi-extension/package.json.Check
vendor.shcovers all shared/ai imports. Every../generated/*.jsimport in the server files must have a corresponding entry invendor.sh's copy loops. If a new shared module or AI module was added topackages/shared/orpackages/ai/and is imported by Pi's server code, it must be added tovendor.sh.Dry-run the pack. Run
cd apps/pi-extension && bun pm pack --dry-runand 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:
- Add the file to
vendor.sh's copy loop - Add the file or directory to the
filesarray inpackage.json - Add an import path fix (Pi uses
../generated/not@plannotator/sharedor@plannotator/ai)
Phase 4: Commit, Tag, and Release
Commit the version bump:
chore: bump version to X.Y.ZStage only the 11 version-bumped files and
packages/inbox/feedbackSearch.data.json. Do not stage the release notes file (it's untracked by design).Push the bump, then run the heavy suites on main and wait for them. A push to main runs only the fast tier (Test, Security). The full browser tests (Inbox window e2e) run on main only every two hours, and the Windows, Inbox Pi, Inbox Claude Code and relay suites only nightly, so start them on the bump commit by hand:
git push origin main for wf in inbox-e2e.yml windows.yml inbox-pi.yml inbox-claude-code.yml relay.yml; do gh workflow run "$wf" --ref main; done # one dispatched run per workflow; check headSha is the bump commit for wf in inbox-e2e.yml windows.yml inbox-pi.yml inbox-claude-code.yml relay.yml; do gh run list --workflow "$wf" --branch main --event workflow_dispatch --limit 1 --json databaseId,headSha,status done gh run watch <run-id> --exit-status # once per runDo not tag until all five runs succeeded on the bump commit. If one fails, fix it on main and run them again.
Create and push the tag:
git tag vX.Y.Z git push origin vX.Y.ZThe
v*tag push triggers the release pipeline (.github/workflows/release.yml).The pipeline handles everything else:
- Runs tests
- Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)
- Compiles paste service binaries (same 6 platforms)
- Packs the npm packages (
@plannotator/opencode,@plannotator/pi-extension,@plannotator/dsh,@plannotator/cline,@plannotator/openclaw) in a credential-free job, into the one artifact the security gate scans (NPM_SUBJECTSinscripts/release-security/release-evidence.mjs;tests/release-gate-subjects.test.tsfails when release.yml packs or publishes a tarball outside it) - Downloads pinned, checksum-verified Syft and Grype binaries; generates and schema-validates the release-wide CycloneDX SBOM after all shipped subjects exist
- Forces the repository-owned, suppression-free Grype configuration, retries the official database update up to three times, requires a valid/active schema-v6 database no more than 120 hours old with no pending update, and preserves the machine-readable scan/database/policy evidence as a workflow artifact
- Rejects every scanner-side ignored match, then blocks before any attestation or publication on CISA KEV or fixable Critical findings classified as shipped/runtime or unknown-applicability. High, development-only, and no-fix Critical findings are report-only but remain in the evidence
viewer-pin-live: requires guides.show (deployed for the same tag byguides-show-deploy.yml) to serve the guide viewer JS and CSS that thebuildandnpm-packagejobs pinned, retrying for about 5 minutes;attest,releaseandnpm-publishwait for it, so a failure attests, releases and publishes nothing. Recovery: deploy guides.show on the tag (gh workflow run guides-show-deploy.yml --ref vX.Y.Z), then "Re-run failed jobs" on the release run- Generates SLSA build provenance attestations for all 12 binaries via
actions/attest-build-provenance(signed through Sigstore, recorded in Rekor) - Uses the separate official
actions/attestSBOM path to bind the CycloneDX predicate to all 12 binaries and the@plannotator/opencode,@plannotator/pi-extension,@plannotator/dsh,@plannotator/clineand@plannotator/openclawtarballs through the same GitHub OIDC/Sigstore service. This is an inventory attestation, not a replacement for SLSA or npm provenance - Creates the GitHub Release with all binaries, SHA256 sidecars, the versioned CycloneDX SBOM, and its SHA256 sidecar attached
- Publishes
@plannotator/opencodeand@plannotator/pi-extensionto npm with provenance, then the gated@plannotator/dshand@plannotator/clinetarballs, and@plannotator/openclawlast; the@plannotator/dshand@plannotator/openclawsteps are allowed to fail until their trusted publishing is set up (a failure there shows as a warning; check it withnpm view)
SBOM scope: the public document is a release-wide Syft inventory of the monorepo's locked build inputs and dependencies. It is deliberately not described as exact binary runtime contents. Coverage testing found that Bun standalone executables hide bundled JavaScript dependency metadata from Syft. The OpenCode tarball is similarly opaque; the Pi tarball exposes only a partial view through nested package-lock files. The scope and limitations are also embedded in the CycloneDX metadata.
Exceptions: there is no active production exception file. If a future release baseline needs one, do not add a loose ignore. Add a repository-reviewed OpenVEX document and explicitly wire it through
PLANNOTATOR_RELEASE_VEX; each statement must match one exact package URL and vulnerability ID and carrynot_affectedstatus, an OpenVEX justification, impact statement, HTTPS evidence, owner, created date, and expiration date. The policy tests reject expired, malformed, broad, and nonmatching records.Note 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 6), 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> --logVerify:
- All jobs pass, including
release-security,viewer-pin-live,attest,release, andnpm-publish release-security-evidencerecords the Syft/Grype versions, active database schema/build/checksum/update status, all Grype matches, and anACCEPTpolicy decision- The GitHub Release was created with all binary artifacts, SHA256 sidecars, the versioned
plannotator-X.Y.Z-release-sbom.cdx.json, and its.sha256sidecar - npm packages published successfully (check with
npm view @plannotator/opencode version,npm view @plannotator/dsh version,npm view @plannotator/cline version,npm view @plannotator/openclaw versionandnpm view @plannotator/pi-extension version)
A pull request proves generation, schema/sentinel validation, database policy, Grype evaluation, least-privilege job wiring, and all report artifacts. GitHub OIDC issuance, publication to the artifact-attestation service, and final release-asset publication only run for a real eligible
v*tag. For the first release after this control lands, complete this bounded tag-only verification before calling the rollout complete:Before tagging that first release, update the canonical Mintlify page at
https://docs.plannotator.ai/open-source/start/installation#pin-or-verify-a-releasewith the SBOM scope/limitations, Grype policy, download/checksum commands, and both predicate-verification commands from the README. The legacy Astro files underapps/marketing/src/content/docs/are redirect-only/deprecated copies and are not the public documentation source. Confirm the live Mintlify page contains the material; do not let its publication lag the shipped control.tag=vX.Y.Z version="${tag#v}" gh release download "$tag" --pattern 'plannotator-linux-x64*' --pattern "plannotator-${version}-release-sbom.cdx.json*" --dir /tmp/plannotator-release-verify (cd /tmp/plannotator-release-verify && sha256sum --check plannotator-linux-x64.sha256) (cd /tmp/plannotator-release-verify && sha256sum --check "plannotator-${version}-release-sbom.cdx.json.sha256") gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \ --repo backnotprop/plannotator \ --source-ref "refs/tags/$tag" \ --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \ --predicate-type https://slsa.dev/provenance/v1 gh attestation verify /tmp/plannotator-release-verify/plannotator-linux-x64 \ --repo backnotprop/plannotator \ --source-ref "refs/tags/$tag" \ --signer-workflow backnotprop/plannotator/.github/workflows/release.yml \ --predicate-type https://cyclonedx.org/bomAlso extract the attested CycloneDX predicate with
gh attestation verify --format json --jq '.[0].verificationResult.statement.predicate', canonicalize both it and the downloaded release SBOM withjq -S, andcmpthem. Verify one npm tarball subject the same way if you download the exact published tarball. Record any tag-only discrepancy as a release blocker and ship a new version rather than mutating an immutable release.If anything fails, investigate the logs and report to the user before retrying.
- All jobs pass, including
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
Checklist
Before tagging, verify:
- All 11 version files bumped consistently,
.github/plugin/marketplace.jsonincluded (bun run check:release-versionpasses) -
bun scripts/feedback-search-index.tsrun, andpackages/inbox/feedbackSearch.data.jsonin the release commit - The published-package floor guard is green (
bun test tests/published-package-floors.test.ts), and noengines.node/npm/opencode/vscode/bun,os,cpu,libcor host peer was added or changed on a published package without anALLOWEDentry the owner signed off (engines.vscodeis pinned at^1.85.0: a raise stops updates for Cursor, Windsurf and older VS Code). npm silently installs an older version for anyone whose runtime misses such a field: 0.28.32's Pi Node floor kept older-Node users on 0.28.31 - Sibling dependencies resolve:
bun run check:sibling-deps @plannotator/opencode @plannotator/pi-extensionpasses (it reads npm). When@plannotator/coreand@plannotator/uiship, publish core before ui, and run it with every package going out (bun run check:sibling-deps @plannotator/core @plannotator/ui): ui pins an exact core, and a ui published first fails to install with ETARGET - Never
npm deprecatethe currentlatest: npm then picks the newest non-deprecated version for bare and range installs, so everyone silently stays behind. Ship a new version instead - Never reuse a version number once its bump commit is on
main, even if the tag or publish failed: Claude Code caches plugins by version string, so a second build under the same number never reaches users who fetched the first. Bump again - Release notes drafted and reviewed
- The notes start with a
### TL;DRof 3 to 5 labelled lines, directly under "What's New in vX.Y.Z" -
bun run build:reviewsucceeded -
bun run build:hooksucceeded -
bun run build:opencodesucceeded -
bun run build:dshsucceeded -
bun run build:clinesucceeded -
bun run build:openclawsucceeded -
bun run build:pisucceeded (or pi-specific build step) - Version bump committed
- Inbox window e2e, Windows, Inbox Pi, Inbox Claude Code and relay dispatched on main (
gh workflow run) and green on the bump commit - Pi parity gate passed (imports, vendor.sh, dry-run pack)
- No stale build artifacts (clean builds, no cache issues — run
bun installfirst if dependencies changed) - The PR-safe
release-securityjob generated a schema-valid, sentinel-complete SBOM and accepted the Grype policy with a fresh database - No scanner binary, database, generated SBOM/report, credential, or
DO_NOT_COMMITcontent is staged - For the first SBOM-enabled release, the canonical Mintlify install/verification page contains the README's SBOM scope, policy, checksum, SLSA, and CycloneDX commands (do not edit the deprecated Astro docs instead)
- If
scripts/install.sh(orinstall.ps1/install.cmd) changed since the last release, the owner syncs it to S3 by hand sohttps://plannotator.ai/install.shserves the new copy. Safe updates (from 0.28.33) depend on it: an update checks the binary against the checksums Plannotator fetched only when plannotator.ai serves aninstall.shthat readsPLANNOTATOR_EXPECTED_SHA256. Until it does, updates still work exactly as before (an older script ignores the variable), but without that check. Confirm withcurl -fsSL https://plannotator.ai/install.sh | grep -c PLANNOTATOR_EXPECTED_SHA256(non-zero). - The release publishes
plannotator-darwin-arm64.sha256,plannotator-darwin-x64.sha256,plannotator-linux-arm64.sha256andplannotator-linux-x64.sha256under exactly these names, with the binaries. Never rename, merge (for example into onechecksums.txt), drop or delay them: every binary from 0.28.33 on downloads these names before it updates, and fails to update without its own (packages/server/update-prepare.tscandidateAssets; guarded byupdate-prepare.test.ts).
After tagging, verify:
- Release workflow completed with
release-security,viewer-pin-live,attest,release, andnpm-publishgreen (ifviewer-pin-livefailed: deploy guides.show on the tag, then "Re-run failed jobs") - GitHub Release created with all binaries, sidecars, SBOM, and SBOM sidecar
- One native binary passes both the explicit SLSA and CycloneDX predicate checks pinned to the tag and signer workflow
- Downloaded SBOM checksum passes and canonical JSON matches the attested predicate
-
release-security-evidenceshows a fresh/active database and an accepted policy decision - npm packages published at correct version
- npm trusted-publishing provenance remains visible for both packages
- Release notes replaced via
gh release edit