openprose__prose/RELEASE.md

OpenProse Release Process

This document covers the SKILL / plugin release. Two other trains exist and are out of scope here:

• The @openprose/reactor* packages release on their own reactor-v* tag train (see their flow).
• @openprose/prose-cli has been removed from the repo. The Reactor SDK
  • reactor CLI + replay devtools replaced it, so there is no prose-cli release train: its package, npm publish flow ("OpenProse Release" workflow, release preflight, and CLI release checks) are all gone.

The single remaining track here is skill — the open-prose SKILL plus the Claude + Codex plugin manifests that deliver it (skills/open-prose/SKILL.md, .claude-plugin/plugin.json, .codex-plugin/plugin.json). These move together: the Claude Code marketplace deduplicates by manifest version, so a skill change only reaches plugin users when the manifest version advances. Machine compatibility is a separate signal — SKILL.md's runtime_contract — not this X.Y.Z.

./scripts/bump-version.sh --track skill X.Y.Z   # bump the skill track's files
./scripts/bump-version.sh --check               # the track is internally consistent
./scripts/bump-version.sh --list                # print the track's version

Releasing the skill / plugin track

The skill ships from the repository (the skills CLI reads it directly) and through the plugin marketplace (which reads the manifests). There is no npm publish for this track, so its release is a version bump + tag + marketplace resubmission — independent of any CLI release.

1. Land the skill changes on main, then bump the skill track:

   ./scripts/bump-version.sh --track skill X.Y.Z
   ./scripts/bump-version.sh --check
   

   Bump the major of runtime_contract in SKILL.md as well only when the skill's machine contract changes incompatibly (it is independent of X.Y.Z).

2. Add a ## [X.Y.Z] section to CHANGELOG.md and the migration notes to skills/open-prose/changelog.md (the deferred upgrade brain consumed by prose upgrade).

3. Merge the PR. The Plugin Manifest workflow enforces --check and the manifest structure on every PR.

4. Tag and publish a GitHub Release for provenance (this tag triggers no workflow — it is a marker, kept distinct from the CLI's v* tags):

   git tag -a "skill-vX.Y.Z" -m "open-prose skill X.Y.Z"
   git push origin "skill-vX.Y.Z"
   gh release create "skill-vX.Y.Z" --title "open-prose skill X.Y.Z" \
     --notes-file <(./scripts/extract-changelog.sh X.Y.Z)
   

5. Resubmit the plugin to the marketplaces (manual — see below), referencing the skill-vX.Y.Z tag SHA. Until the manifest version advances in the marketplace, plugin users stay on the previous cached copy.

Marketplace Submission

Marketplace publication remains manual after the GitHub Release exists.

Claude Code marketplace:

• Repo URL: https://github.com/openprose/prose
• Plugin path: leave blank; .claude-plugin/ is auto-detected
• Marketplace name: openprose
• Plugin name: open-prose
• Version: the skill-vX.Y.Z tag SHA

Codex Plugin Directory submission is staged through .codex-plugin/, .agents/plugins/marketplace.json, and assets/plugin/ once the public submission flow opens.