gh-release-package

name	gh-release-package
description	Cut a new package release for this repository with gh. Use when the user wants to release or publish a new package version through the repository's GitHub Release workflow. Support an explicit version like 0.2.0 or a bump keyword like patch, minor, major, prepatch, preminor, premajor, or prerelease. If the user does not specify a version, default to patch.

GH Package Release

Release the package through the repository's GitHub Release workflow, not by ad-hoc local publishing.

Inputs

• Accept an explicit semver version such as 0.2.0.
• Accept a bump keyword such as patch, minor, major, prepatch, preminor, premajor, or prerelease.
• If the user does not provide a version or bump type, default to patch and state that assumption.

Core Rules

• Follow the repository release flow from docs/publishing.md.
• Treat the default branch as the only safe source for a release tag unless the repo workflow explicitly says otherwise.
• Keep the worktree clean before bumping the version.
• If validation fails before commit, restore the original version and stop.
• Do not create a release if the target version already exists as a GitHub release or tag.

Workflow

1. Check prerequisites

Run:

gh auth status
gh repo view --json nameWithOwner,defaultBranchRef
git status --short
git remote show origin

Then enforce:

• current branch must be the default branch
• worktree must be clean
• origin must point to the repository you intend to release

If any of these checks fail, stop and explain the blocker.

2. Fetch and sync the default branch

Use a fast-forward-only path:

git fetch origin
git pull --ff-only origin <default-branch>

If the branch cannot fast-forward cleanly, stop.

3. Resolve the target version

1. Read the current version from package.json.
2. Determine the requested bump:
   • explicit semver if provided
   • otherwise the requested bump keyword
   • otherwise patch
3. Apply the bump without creating a git tag:

npm version <target> --no-git-tag-version

4. Read package.json again and store the resolved new version.
5. Generate the packaged release notes and manifest metadata:

pnpm release:prepare-notes

If the new version equals the old version, stop unless the user explicitly asked for the same version.

4. Guard against duplicate releases

Check whether v<new-version> already exists:

gh release view v<new-version>
git ls-remote --tags origin v<new-version>

If either check shows an existing release or remote tag, revert the version bump and stop.

5. Validate before release

Run the same checks the publish workflow runs:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

If any step fails:

1. restore the old version with npm version <old-version> --no-git-tag-version
2. report the failing validation
3. stop without committing

6. Commit and push the release bump

Commit the release version change together with the generated release-notes outputs and any expected lockfile update if one exists:

chore(release): v<new-version> [phase 1/1]

Then push the default branch:

git add package.json docs/release-notes.md src/manifest/releaseNotes.generated.ts pnpm-lock.yaml
git commit -m "chore(release): v<new-version> [phase 1/1]"
git push origin <default-branch>

If pnpm-lock.yaml did not change or does not exist, do not stage it.

7. Create the GitHub release

Tag the exact pushed commit, not a moving branch tip:

git rev-parse HEAD
gh release create v<new-version> --target <head-sha> --title "v<new-version>" --notes-file docs/release-notes.md --fail-on-no-commits

This repository's publish workflow runs on release.published, so creating the release is what triggers the package publish.

8. Watch the publish workflow

After creating the release, find the corresponding workflow run and wait for it:

gh run list --workflow "Publish Package" --event release --limit 1 --json databaseId,headSha,status,conclusion,url
gh run watch <run-id> --compact --exit-status

If the workflow fails, report the run URL and stop.

9. Confirm the final state

At the end, report:

• released version
• release URL
• publish workflow URL
• whether the publish workflow succeeded

Guardrails

• Do not release from a dirty worktree.
• Do not release from a feature branch unless the repository workflow is changed first.
• Do not skip validation just because GitHub Actions also validates; the goal is to avoid breaking releases.
• Do not skip pnpm release:prepare-notes; the package and the GitHub release body are expected to ship the same change summary.
• Do not use workflow_dispatch as the default path when the repo already has a release-driven publish flow.
• If the user asks for a prerelease, use the requested prerelease bump explicitly rather than guessing.
• Breaking changes are classified from conventional commits that use ! or a BREAKING CHANGE: footer. If the history does not mark them correctly, fix the generated notes before publishing.

Useful Commands

node -p "require('./package.json').version"
gh release view
gh run list --workflow "Publish Package" --limit 5

Recommended Companion Skills

• Use $persona-orchestration when the release includes architectural or contract-sensitive changes.
• Use $phase-commit-workflow for the release bump commit.
• Use $agent-notepad-capture after changing the release process.