release

name	release
description	Bump VibeFrame versions, regenerate release artifacts, run verification, and prepare a version commit.

Release

Use this skill when the user asks Codex to run a VibeFrame release bump or fix a missing version bump after feat: / fix: commits.

The bump is one of patch, minor, or major. Default to patch when no bump is specified or when there is any doubt.

Version Policy

VibeFrame is still in 0.x. patch is the default and by far the most common bump. minor is rare and must be explicitly justified — the shared push gate (scripts/pre-push-validate.sh) blocks a non-patch bump that lacks a Release-Type: trailer (see step 10).

• patch: bug fixes, docs/tooling, UX polish, internal refactors, and most ordinary feat: / fix: commits. Use this unless a rule below clearly applies.
• minor: new public CLI command namespace, new MCP tool family, public API contract additions, or a large product milestone.
• major: breaking changes or an intentional 1.0 milestone.

When unsure, use patch.

Steps

1. Read the current root version:

   jq -r '.version' package.json
   

2. Bump the root package:

   npm version <patch|minor|major> --no-git-tag-version
   

3. Read the exact new version:

   NEW_VERSION=$(jq -r '.version' package.json)
   

4. Set every workspace package to that exact version. Do not use pnpm -r exec npm version for this step because recursive pnpm includes the root package.

   for dir in packages/cli packages/core packages/ai-providers packages/mcp-server packages/ui apps/web; do
     (cd "$dir" && npm version "$NEW_VERSION" --no-git-tag-version)
   done
   

5. Verify all package versions match:

   for f in package.json packages/*/package.json apps/*/package.json; do
     jq -r '.version' "$f"
   done | sort -u
   

   The output must contain exactly one version.

6. Build, regenerate references, lint, and test:

   pnpm build
   pnpm gen:reference
   pnpm lint
   pnpm -F @vibeframe/cli exec vitest run --bail 1
   

7. Generate the changelog for the new version:

   git-cliff --tag v$NEW_VERSION -o CHANGELOG.md
   

8. Run the shared push gate:

   bash scripts/pre-push-validate.sh
   

9. Stage the release files:

   git add package.json packages/*/package.json apps/*/package.json CHANGELOG.md docs/cli-reference.md
   

10. Commit. For a patch bump, a plain message:

git commit -m "chore: bump version to $NEW_VERSION"

For a minor or major bump, the push gate requires a justification trailer in the commit body, or it blocks the push:

git commit -m "chore: bump version to $NEW_VERSION" -m "Release-Type: minor: <why this is not a patch>"

Do not create a local tag. Do not push unless the user explicitly asks.

11. The version commit reaches main via a PR, never a direct push (even though main allows admin bypass). Put it on a chore/release-$NEW_VERSION branch, open a PR, let CI go green, and merge:

git switch -c chore/release-$NEW_VERSION
git push -u origin chore/release-$NEW_VERSION
gh pr create --fill --base main

Publishing is manual. After the version commit lands on main (through the PR) and CI passes, run the Create release tag workflow to create vX.Y.Z, then run Publish to npm manually with that tag. A human-created git push origin vX.Y.Z tag also triggers publish.yml, but CI and the tag helper do not dispatch publishing automatically.