Release and compatibility policy

The repository uses stable SemVer tags vMAJOR.MINOR.PATCH for the whole repository. A tagged release includes every .skill archive from that tag, its matching workflows/ and skillsets/ source, release notes, and SHA256SUMS. Skill packages have no separate versions. Prerelease tags are not published by the automated workflow; GitHub’s latest Release therefore points to a stable version.

Increase MAJOR for incompatible skill inputs/outputs, metadata, or workflow contracts; MINOR for backward-compatible skills or workflows; PATCH for backward-compatible fixes and documentation. While major is zero, explain any incompatible change explicitly in the migration guide. Preserve a dated version section in CHANGELOG.md with Skills, Workflows, and Breaking metadata entries, even when a category has no changes.

The CHANGELOG must be UTF-8 and use exactly ## [X.Y.Z] - YYYY-MM-DD (no v in the heading), with a valid ISO date. Each release must contain one nonempty subsection headed exactly ### Skills, ### Workflows, and ### Breaking metadata. Fourth-level headings and bold labels do not substitute for these headings. For example:

## [1.2.3] - 2026-10-12

### Skills
- Fixed input validation.

### Workflows
- No changes.

### Breaking metadata
- No changes.

Package and manifest compatibility

Release .skill assets workflows/ and skillsets/ Support rule
Unreleased (main) Unreleased (main) Unreleased (main) Development snapshot only; use one commit for all components.

Add a concrete vX.Y.Z row before creating each tag, with that exact tag in the first three columns. The release builder refuses a tag without its row. It reads only this rendered four-column table: the Release header row, then a --- separator row, then contiguous rows. Rows inside HTML comments, code fences, or indented code blocks do not count. Escape a literal pipe in a cell as \|. For a release, use all .skill assets and workflow/skillset manifests from the same tag. Cross-version mixing is unverified and unsupported unless a future row explicitly documents and tests it. The Python/OS support matrix is separate: compatibility-matrix.md.

Release procedure

  1. Finish the production verification gates, including live high-severity Issue review. The first v1.0.0 waits for the P0 CI/provider work tracked in Issues #293 and #332. This PR creates release tooling only; it does not create a tag or a Release.
  2. Update CHANGELOG.md and the table above for the chosen stable tag. Record skill additions/changes/deprecations, workflow changes, and breaking metadata changes. Add migration instructions for every incompatible or renamed skill.
  3. Merge the release metadata changes to main, require normal CI green, then create and push the tag on that reviewed main commit. Do not tag an unmerged branch.
  4. The tag workflow checks main ancestry and that the remote tag did not move; validates every committed .skill against its source, including ZIP member safety; then prepares sorted assets, SHA256SUMS, and release notes. It creates a draft GitHub Release, downloads the uploaded assets, compares their bytes and checksums, and publishes only after verification. An interrupted or failed run leaves a draft for manual investigation; it does not overwrite an existing Release.
  5. Download an asset and SHA256SUMS from the latest Release. Verify locally with sha256sum -c SHA256SUMS (Linux) or shasum -a 256 -c SHA256SUMS (macOS) before installing. Run from a directory containing all downloaded .skill assets, or verify a selected line with the matching asset. GitHub source archives are generated by GitHub and are not listed in SHA256SUMS.

Deprecation and migration template

For each removed, renamed, or incompatible skill/workflow, add a guide linked from the relevant CHANGELOG release entry. Use this structure:

# Migrate from <old name> to <new name> in vX.Y.Z

- Affected assets and workflow IDs:
- Last compatible release:
- Input, output, metadata, or configuration change:
- Steps to move local files and settings (including backup):
- How to verify with fictional or paper data:
- Rollback: install the prior tag's matching .skill assets and manifests together.

Keep old release assets available for rollback. Never silently rename a package or imply that swapping only a .skill archive preserves compatibility with a different-tag workflow manifest.