swimmwatch / 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.

Validation

Before opening or merging the release PR, run:

npm run check:ci
npm run package:verify
npm run docker:build
npm run docker:smoke
npm run bridge:compare -- cloakbrowser-mcp:dev --report bridge-parity-report.json
docker run --rm -v "$PWD:/repo" --workdir /repo docker.io/rhysd/actionlint:1.7.12@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667 -color
python3 -m pipx run zizmor --min-severity high .
npm run docs:build
npm run docs:seo:validate

Remove bridge-parity-report.json after inspecting it. If a check fails, fix
the smallest release-relevant cause and rerun the relevant command.

PR And Release Flow

• After explicit commit authorization, commit release preparation as
  chore(release): prepare vX.Y.Z.

• For release PR creation or updates, also read and follow
  .agents/skills/project-pull-request/SKILL.md.

• After separate PR authorization, open a PR to main with a concise release
  summary and validation list.

• Call out security-sensitive release workflow changes, especially registry
  credentials, public image publishing, OIDC, or token behavior.

• Wait for required PR checks to pass before merging.

• After separate publication authorization, create a published GitHub Release
  for stable releases with:

  • tag vX.Y.Z;
  • target main;
  • title vX.Y.Z;
  • notes from the CHANGELOG.md section.

• Mark prerelease versions as GitHub prereleases. Stable releases publish npm
  latest and Docker latest; prereleases publish npm next and prerelease
  Docker tags only.

Post-Release Verification

Watch the unified Release workflow until metadata, npm, docker,
mcp-registry, docs-build, and docs-deploy complete. docs-deploy
must run only after npm, Docker, and MCP Registry publishing have succeeded.

Then verify:

npm view cloakbrowser-mcp@X.Y.Z version
docker pull swimmwatch/cloakbrowser-mcp:X.Y.Z
docker run --rm --init swimmwatch/cloakbrowser-mcp:X.Y.Z --help
docker pull ghcr.io/swimmwatch/cloakbrowser-mcp:X.Y.Z
npm run registry:check -- --version X.Y.Z

Confirm Docker Hub overview, short description, npm, GHCR, Docker Hub, docs,
and the official MCP Registry are current. GitHub /mcp visibility is curated
separately and may lag; treat it as a warning unless the user makes it a gate.

Recovery

• If Docker Hub overview update fails with Forbidden, the
  DOCKERHUB_TOKEN secret needs a Docker Hub personal access token with
  read/write/delete permissions for swimmwatch/cloakbrowser-mcp; rerun failed
  release jobs after the secret is updated.

• If npm, GHCR, Docker Hub, or MCP Registry already published artifacts, do not
  delete and retag the same release for code defects. Prepare a follow-up patch
  release instead.

• Rerun failed jobs only after confirming the failure is transient or caused by
  a fixed external configuration.

• Keep release recovery notes in the final status report, including published
  artifact state and any warnings.