Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

release-cut

Cut a new pi-agent-dashboard release: promote `## [Unreleased]` in CHANGELOG.md, bump every workspace package.json per SemVer, commit, tag `v<version>`, and push — triggering the Release workflow that publishes every non-private workspace, builds the Electron artifacts, and creates a GitHub Release. Use on "cut a release", "release vX.Y.Z", "publish a new version", "tag a release".

BlackBeltTechnology · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add BlackBeltTechnology/pi-agent-dashboard --skill release-cut

About this skill


name: release-cut description: 'Cut a new pi-agent-dashboard release: promote ## [Unreleased] in CHANGELOG.md, bump every workspace package.json per SemVer, commit, tag v<version>, and push — triggering the Release workflow that publishes every non-private workspace, builds the Electron artifacts, and creates a GitHub Release. Use on "cut a release", "release vX.Y.Z", "publish a new version", "tag a release".' license: MIT metadata: author: pi-dashboard version: "1.0"

Cut a pi-agent-dashboard Release

Canonical reference: docs/release-process.md. This skill automates steps 1–5 of that doc. Production tags (vX.Y.Z) publish the GitHub Release automatically — electron-updater's default GitHub provider only resolves published, non-draft releases, so a draft would silently block auto-update. Pre-release tags (vX.Y.Z-rc.N) stay drafts so a maintainer can eyeball artifacts before flipping to published. See change: fix-electron-auto-update-pipeline.

Pre-flight (MUST pass before touching anything)

Run these in order. If any fails, stop and report — do not continue.

  1. Clean working tree

    git status --porcelain
    

    Must be empty. If not, ask the user to commit or stash.

  2. On the release branch

    git rev-parse --abbrev-ref HEAD
    

    Must be develop (this repo has no main). If elsewhere, ask user to confirm before continuing.

  3. Up to date with origin

    git fetch origin && git status -sb
    

    Branch must NOT be "behind". If behind, ask user to pull first.

  4. Tests pass

    pnpm test
    
  5. Build succeeds

    pnpm run build
    
  6. Dependency-shape gate (introduced by enable-standalone-npm-install to prevent regressions of v0.5.3 publish-time bugs)

    node scripts/verify-release-deps.mjs
    

    Asserts critical runtime deps (jiti, pinned node-pty, etc.) are still declared in the publishable workspace package.json files. Failure means the next published tarball would be broken — STOP and fix the workspace before cutting.

    Known false-positive (substring gate). verify-release-deps.mjs checks the declared range with a naive String.includes(minVersion) — NOT semver math. So a legitimate pi bump ABOVE the floor (e.g. floor 0.74.0, pin ^0.80.10) fails the gate because "^0.80.10" does not contain the substring "0.74.0". When this fires and the pin is genuinely newer than the rule's minVersion, the FIX is to bump that rule's minVersion (+ its evidence note in the RULES array, and the scripts/AGENTS.md row) to the new floor — do NOT downgrade the pin. This recurs on every pi version bump. See change: fix-release-lockfile-drift (gate lives in scripts/verify-release-deps.mjs).

  7. Dispatch ci-smoke.yml against develop (recommended; catches installer regressions BEFORE the tag exists)

    The release pipeline (publish.yml) gates publish on a release-gate that runs the full 7-leg standalone-install-smoke matrix. If that gate fails on workflow_dispatch, tag-and-push is skipped — clean abort, no commit, no tag. But on a git push --tags cut, the tag already exists when the gate fires; failure leaves a dangling tag requiring release-revoke.

    Operators SHOULD run the smoke matrix first against develop:

    gh workflow run ci-smoke.yml --ref develop
    gh run watch  # or open the Actions UI
    

    All 7 legs must be green before cutting. If any leg fails, fix the regression on develop first — do NOT cut a tag that you know will fail the gate. Skip this step only when the change since the last release is provably installer-irrelevant (no lockfile, bundle-server, native dep, or preload-fastify touch). See change: gate-publish-on-smoke-and-tests.

If any pre-flight step fails, stop and surface the exact error to the user.

Step 1 — Read current state

git describe --tags --abbrev=0        # last tag, e.g. v0.2.9
node -p "require('./package.json').version"   # current pkg version

Confirm they match (e.g. tag v0.2.9 ↔ pkg 0.2.9). If they diverge, surface the mismatch and ask the user how to proceed.

Step 2 — Curate ## [Unreleased]

  1. List commits since last tag:
    git log <last-tag>..HEAD --oneline
    
  2. Read CHANGELOG.md and extract the current ## [Unreleased] section.
  3. Cross-check: every feat: / fix: commit should have a corresponding user-visible bullet under Added / Changed / Fixed.
  4. If gaps exist, use AskUserQuestion to list missing items and confirm whether the user wants to add them now. If yes, draft bullets in end-user language (not commit-subject shorthand) and insert them.
  5. Never invent behaviour — only summarise what the commits actually did.

Far-behind escape hatch (long release cycle). If [Unreleased] was not maintained per-change and the tag→HEAD span is huge (v0.6.0 was a 2-month, 906-commit release with only 24 of ~234 feat/fix changes documented), do NOT re-audit hundreds of commits by hand and do NOT dump raw commit subjects. Generate the deduped input set — git log <last-tag>..HEAD --oneline filtered to feat|fix|perf, minus the change-tags already in [Unreleased] — then delegate grouped drafting to a subagent (keeps quality high + your context focused). Merge the returned bullets under the existing headings programmatically (existing bullets first, new appended), scoped to the [Unreleased] section only, and cap the long tail with one rolled-up "Additional fixes" line. This is the exact path that worked for v0.6.0.

Step 3 — Decide next version (SemVer)

Propose per this decision tree, then use AskUserQuestion to confirm:

## [Unreleased] containsBump
Any breaking change / removal (call it out)m
Read the complete source ↗