cut-release git:20260915.de490faA

Immutable. This exact content never changes and is served at /api/v1/blob/2675b2d41260d46e.

---
name: cut-release
description: Prepare and publish an explicitly requested Foundry plugin or edition release using its actual release branch, version owner and catalogs. Includes coordinated README and verification gates; never an automatic release trigger.
---

# Release a Foundry plugin or edition

Use this workflow only for an explicit release request. Establish the plugin,
edition and intended version from that request and the current repository state.
A package plugin, whose catalogs pin one main commit for both hosts, has no
edition to choose. Otherwise, if the edition is ambiguous, resolve it before
writing metadata. Running in a particular assistant does not by itself choose
the edition being released.

## Sources of truth

| Release | Plugin metadata | Catalog | Version owner |
| --- | --- | --- | --- |
| Claude edition | `<plugin>/.claude-plugin/plugin.json` on Claude | `.claude-plugin/marketplace.json` in Foundry | the Claude catalog entry |
| Codex edition | `<plugin>/.codex-plugin/plugin.json` on Codex | `.agents/plugins/marketplace.json` in Foundry | the native plugin manifest |
| Package | both `<plugin>` manifests on main | both Foundry catalogs, same main SHA | both plugin manifests, same version |

Both catalog entries identify the plugin repository, platform ref and full
validated commit SHA. Claude's version and source.sha move together. A Codex
release updates its native version and then pins that exact integrated commit;
do not introduce a Claude-style version field into the Codex catalog.

A package such as Foreman (ADR 0011) releases one main commit. Bump the same
version in both manifests, then pin that commit with `ref: "main"` in both
catalogs. Its Claude catalog entry carries no version, so only `source.sha`
moves in Foundry.

Hush/Codex is not installable until its package and validation exist. Do not
create a release or add it to the catalog merely because the branch exists.

## Prepare a reviewable release

1. Locate Foundry and the intended plugin checkout. Check its branch, HEAD,
   working tree and published refs. Confirm its physical working directory with
   `git rev-parse --show-toplevel`; worktree-list output alone can identify a
   submodule's gitdir instead. Preserve other working copies and unrelated edits.
2. Work on an appropriate non-main branch. On Windows, an existing Codex ref can
   prevent a codex/ prefix; use a non-conflicting maintenance branch. For a
   plugin with editions, main is its selector, never the implementation release
   destination; a package integrates into main.
3. Establish the exact release surface and inspect the changes since the last
   published pin for this edition or package. A dirty checkout is not
   authorization to include everything in it. Prepare the requested files and
   checks before requesting any genuinely missing publication approval.
4. Write a short user-facing CHANGELOG entry and update the release's version
   owner. Use the user's version when supplied; otherwise choose or clarify the
   bump according to the actual compatibility change. Keep unrelated metadata.
5. For a plugin with editions, use coordinate-readmes and check the actual
   candidate pair. The CLI supports `--pair <Claude-README> <Codex-README>` and
   `--git-pair <plugin-repo> <Claude-candidate-ref> <Codex-candidate-ref>`.
   Shared changes need both candidates; model-specific measurements must retain
   their own evidence. A package's single README needs its navigation check and
   a review of each host's evidence. Missing benchmarks stay explicitly unmeasured.
6. Run the relevant plugin, packaging, documentation and maintenance checks.
   Read the compatibility/validation guide for each host in the release. Do not
   run a Claude hook canary against a Codex package, invent hook events, or treat
   unit tests as installed activation. Paid benchmarks and installations need
   their own scope.

## Integrate and publish the release

Commit only the reviewed release surface. Use the repository's actual PR and
branch-protection process to integrate into Claude or Codex, or into main for a
package. Push the explicit reviewed branch/ref to its intended destination; never
substitute `origin main` for an edition branch. Preserve any separate acceptance
or merge requirement from the user. Do not bypass a failing check to force a
release through.

Once the release commit is integrated and remotely reachable, record its full
SHA in the correct Foundry catalog. Verify the remote branch contains that SHA.
For a Claude edition, update the catalog version in that same root change. For a
Codex edition, verify the pinned manifest contains the new effective version. For
a package, move `source.sha` in both catalogs to the same main commit and verify
that both manifests there carry the new version. A gitlink update alone does not
publish a package update.

Run `node scripts/git-hooks/check-platform-marketplaces.js` from Foundry and
the relevant documentation/integration checks. Integrate the reviewed root
catalog change through its normal PR process. For a plugin with editions,
publish destination branches before selector pages that link to them. Do not
fold unrelated local work into either repository's release commit.

## Report the outcome

Report the plugin and its edition or package, version, integrated plugin SHA,
root catalog SHA, actual push/check results and any remaining activation or
publication boundary. If a remote operation fails, inspect the result and report
its concrete state; do not silently broaden the push or retry with force. Do not
claim publication from a local commit, valid manifest or passing unit suite alone.