/release

name: release
description: Bump VibeFrame versions, regenerate release artifacts, run verification, and prepare a version commit.
argument-hint: "<patch|minor|major>"
disable-model-invocation: true

<!-- GENERATED by `pnpm agent-sync` from .agents/skills/release/SKILL.md — DO NOT EDIT. -->

Release

Use this skill when the user asks Codex to cut a VibeFrame release.

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

When Bumps Happen

**Once per release, not once per PR.** Ordinary `feat:` / `fix:` PRs merge to `main` without a version bump. This skill runs when you decide to release, and the single bump it produces must cover *every* commit since the last tag - `git-cliff` handles that automatically in step 7.

Check what the release will cover before starting:

bash scripts/release-status.sh

That script is the single source of truth for release state. The push gate, the tag workflow, and the daily drift check all call it, so its answer is the same one CI will give.

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

12. Tagging is automatic. Once the version commit lands on `main` and CI passes, the `Create release tag` workflow creates `vX.Y.Z` on its own. Before tagging it re-runs `scripts/release-status.sh` and **refuses** if `feat:` / `fix:` commits landed after the bump, or if `CHANGELOG.md` has no `## [X.Y.Z]` entry. Do not create the tag by hand.

13. Publishing stays manual. Run the `Publish to npm` workflow with the new tag.

Tags pushed by a workflow cannot trigger another workflow, so the automatic tag never dispatches `publish.yml` - that is what keeps the "CI never publishes" policy intact. A human-created `git push origin vX.Y.Z` *does* trigger `publish.yml`, so do not push release tags manually.

If publishing is forgotten, the daily `Release drift check` workflow opens an issue comparing `main`, the latest tag, and the published npm versions.