Project Release

Project Release

Use this skill only for cloakbrowser-mcp release work. Require a confirmed target version such as v1.2.8, and decide whether it is stable or prerelease before preparing, publishing, or recovering a release. If the user has not provided a target version, propose one from the unreleased changes and ask the user through Prompt MCP to confirm it or choose a different tag before release execution.

Release tags use Semantic Versioning 2.0.0 with the repository's v prefix, for example v1.2.8 or v1.2.8-rc.1. The pinned specification URL is https://semver.org/spec/v2.0.0.html.

Authorization And Interview

• Start or reopen a persistent workspace Prompt MCP interview with a stable ID such as release:vX.Y.Z after inspecting the callable schemas.
• Record target tag and stable/prerelease selection as separate material decisions. Treat only committed answers as confirmation.
• Release preparation, commit, push, release PR creation/update, merge, tag or GitHub Release creation, npm publication, Docker publication, MCP Registry publication, workflow rerun, and recovery mutations are separate authorization gates.
• Never infer publish authorization from version confirmation, preparation approval, merged code, or passing checks.

Choosing The Target Version

• If the user provides a target tag, validate it before changing files.
• If no target tag is provided, fetch tags and inspect changes since the previous release tag:

git fetch origin --tags --prune
git describe --tags --abbrev=0
git log --oneline <previous-tag>..HEAD

• Also inspect [Unreleased] in CHANGELOG.md, merged PR titles, and Conventional Commit subjects when available.
• Propose the next tag using Semantic Versioning 2.0.0:
  • MAJOR for backward-incompatible public API, CLI, MCP protocol, config, or artifact contract changes;
  • MINOR for backward-compatible user-facing features;
  • PATCH for backward-compatible fixes, dependency updates, docs, CI, or packaging-only changes.
• Present the proposed tag and short rationale, then ask the user to confirm it or choose another tag through Prompt MCP. Do not run npm run version:apply until the tag is confirmed and release preparation is explicitly authorized.

Preconditions

• Start from a clean worktree; do not overwrite unrelated user changes.
• Fetch latest refs and branch from current main unless the user explicitly gives another base.
• Confirm no existing Git tag or GitHub Release already uses the target version.
• Before confirming the release tag, open and scan https://semver.org/spec/v2.0.0.html, then validate that the requested tag is the v-prefixed form of a SemVer 2.0.0 version.
• Exclude known failing or unrelated dependency PRs unless the user explicitly includes them.
• Before editing CHANGELOG.md, open and scan https://keepachangelog.com/en/1.1.0/.
• Before committing, open and scan https://www.conventionalcommits.org/en/v1.0.0/.

Version Preparation

Run the release version script with the exact tag:

npm run version:apply -- vX.Y.Z

The script updates:

• package.json
• package-lock.json
• server.json

Documentation release tags and pinned install examples are rendered at MkDocs build time from package.json through docs_macros.py; do not manually rewrite those values in Markdown sources.

Manual release updates still required:

• add one new row to docs/data/version-compatibility.json;
• run npm run docs:compatibility;
• verify README.md, docs/index.md, and docs/version-compatibility.md changed as expected;
• verify the new compatibility row records the actual @playwright/mcp, Playwright MCP Docker base, CloakBrowser dependency, supported transport, and platform;
• run npm run docs:compatibility:check;
• move current [Unreleased] entries in CHANGELOG.md into ## [X.Y.Z] - YYYY-MM-DD;
• add or update the empty [Unreleased] section above the new release;
• update changelog compare links so [Unreleased] compares vX.Y.Z...HEAD and [X.Y.Z] compares the previous tag to vX.Y.Z;
• update release docs examples only if they are intended to show the current release instead of a generic example.

Do not bump the package version outside release preparation.