Releases & Versioning

Consensus and Session release independently. Canonical skills also have their own versions. Choose the boundary you changed before updating a version or claiming release readiness.

Version boundaries

Any change under a canonical skill directory requires increasing its skill version, including instructions, runtime, tests, references, assets, and build declarations. Never edit generated skill versions directly. See Repository Conventions.

The version tool keeps the selected boundary together. For example, after choosing the appropriate new version:

pnpm exec tsx scripts/bump-version.ts 1.2.3 --skill session-handoff
pnpm exec tsx scripts/bump-version.ts 0.3.0 --plugin session

These are example target versions, not a statement of the current release. The plugin command does not bump member skills. Update the changelog and review the selected manifests along with the generated payloads.

Release evidence

Follow the complete release checklist. Keep these kinds of evidence separate:

1. Deterministic gates: build, type checks, output freshness, tests, structure validation, and mocked smoke behavior.
2. Isolated installation: the complete plugin or standalone payload works outside the checkout, without developer dependencies or sibling-source imports.
3. Live acceptance: the relevant provider discovers the installed skills, permissions behave correctly, and the affected workflow works. These checks need separate authorization and may spend real quota.

For Consensus, the checklist includes the live Refine/Evaluate runbook and resume, continuation, and provider-install checks. For Session, it includes an isolated complete-plugin check and executing the generated transcript exporter outside the checkout, with live discovery/permission evidence tracked separately.

Session Fork to Destination is distributed as an alpha guidance skill. Provider coverage and end-to-end verification remain incomplete; packaging it is not evidence that a native fork works. Keep those limits explicit until current capability evidence and authorized verification cover each claimed surface.

Tags and the release workflow

Repository release tags (vX.Y.Z) select the payload for the standalone installer's --ref. The Tag Main workflow creates them: whenever Validate passes for a push to main, it tags that commit with the next patch version after the newest vX.Y.Z tag. A run for a commit that a newer tag already covers does nothing. Do not push patch tags by hand; to bump the minor or major version, push that tag yourself, and later patches continue from it. To find the newest release:

git ls-remote --tags --refs --sort=-v:refname https://github.com/tkstang/skills.git 'v*' | head -n 1

Plugin releases use their own tags. The release workflow triggers on plugin-qualified tags, such as session-v0.3.0 or consensus-v0.2.0. It extracts the plugin and passes the v<version> portion to the version checker. To check the Session example before any tag push:

pnpm exec tsx scripts/bump-version.ts --check-tag v0.3.0 --plugin session

The release workflow rebuilds outputs, rejects generated drift, runs automated checks, and validates the selected manifests. It does not run live-provider acceptance or create a GitHub Release for you. Tagging, publishing, and claiming availability remain separate release actions.

Historical readiness evidence applies only to the revision and membership it tested; it does not establish readiness for newly added skills or another plugin. See CI & Quality Gates for trigger and verification details.