cut-release

Cuts a release for one plugin this marketplace lists. Plugins are submodules, so a release is two commits that move together: one in the plugin's own repository, pushed to its main, then one in Foundry that pins that commit in every catalog listing the plugin.

Which plugins exist is not written down here. Plugins get added and retired, so read the current set from the catalogs. Never assume a plugin name — list them.

Copy this checklist into your reply and tick each step as it finishes:

- [ ] Step 0: plugin chosen, checkout state reported, suite green or go-ahead recorded
- [ ] Step 1: new version agreed
- [ ] Step 2: changelog entry and every manifest bumped
- [ ] Step 3: plugin release commit pushed and on origin/main, CI green
- [ ] Step 4: pins, gitlink and checks agree; Foundry commit pushed
- [ ] Step 5: release installed on each host it ships for, or marked not run
- [ ] Step 6: results reported

Where the version lives, and where the pin lives

Every manifest a plugin carries holds the same version. A catalog entry carries no version and must not gain one: only source.sha moves, together with the gitlink. A plugin missing from a catalog does not ship for that host; a release does not add it.

The gitlink and source.sha name the same commit, so the Foundry push in step 4 releases to every host the plugin ships for at once, and a push to the plugin's main reaches nobody until it is pinned. An Antigravity install is a copy: its user takes the release by pulling the Foundry clone, running git submodule update --init and running agy plugin install again.

Step 0 — which plugin, and is it ready

List what each catalog ships, and ask which plugin if the user did not say:

node -e "for (const c of ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) for (const p of require('./' + c).plugins) console.log(c, p.name, p.source.ref, p.source.sha.slice(0, 7))"

Then look at the plugin checkout. A release ships from its main, so the branch, the unpushed commits and the uncommitted edits all matter:

git -C <plugin> fetch origin
git -C <plugin> status --short --branch
git -C <plugin> log --oneline <pinned-sha>..origin/main
git -C <plugin> log --oneline origin/main..main

Report what is unpushed and what is uncommitted. A dirty checkout is not authorization to include everything in it; say what is coming along rather than sweeping it in silently.

Run the plugin's suite from inside its directory; Foreman's takes about 300 s. Stop and report if it is red; do not release over it without the user's explicit go-ahead:

node --test "tests/*.test.js"

Step 1 — pick the new version

Read the current version from <plugin>/.claude-plugin/plugin.json. Ask the user for the new one, or propose a semver bump from the Step 0 log: patch for fixes, minor for new user-facing behaviour, major for breaking changes.

Step 2 — changelog and manifests, in the plugin

1. Read <plugin>/docs/knowledge/changelog.md. Entries are ## <version> — <YYYY-MM-DD> followed by a short user-facing paragraph. Rename the top ## Unreleased heading to the new entry's heading, or add the entry at the top when there is none. State the effect, not the journey: no methodology, no counts, no design rationale.
2. Edit version in <plugin>/.claude-plugin/plugin.json and, when they exist, <plugin>/.codex-plugin/plugin.json and <plugin>/plugin.json. Then confirm every hit reads the same string:

grep -n '"version"' <plugin>/.claude-plugin/plugin.json <plugin>/.codex-plugin/plugin.json <plugin>/plugin.json

Step 3 — commit and push the plugin

Stage only the release surface: docs/knowledge/changelog.md, .claude-plugin/plugin.json and, when they exist, .codex-plugin/plugin.json and plugin.json. The plugin's own pre-commit hook reruns its suite.

git -C <plugin> commit -m "Release <plugin> <version>"
git -C <plugin> push origin main

Each plugin's main, like Foundry's, has a ruleset that requires a squash-only pull request and a status check. A squash merge lands the release under a new sha, so the local main and any pin taken from it no longer match origin/main. A direct push keeps the shas but succeeds only through the owner's admin bypass. Before either push, read the ruleset (gh api repos/V-Songbird/<repo>/rulesets) and ask the owner: name the bypassed rules and the required check next to the pull-request option.

The pin waits until the release commit is reachable from origin/main and the plugin's CI passed on it; that CI is the suite's only Linux run:

git -C <plugin> fetch origin
git -C <plugin> branch -r --contains <release-sha>

branch -r --contains proves only reachability. Read the CI result with:

gh run list --repo V-Songbird/<repo> --commit <release-sha> --json workflowName,status,conclusion

Pin only when every run listed shows status completed and conclusion success. If a run ends failure, cancelled or timed_out, stop and report it; pin only on the user's explicit go-ahead. An empty list means no run has started yet: rerun it once after a short wait, and if it stays empty, check that <release-sha> is on origin/main and that <repo> is right, then stop and report.

Step 4 — pin the commit in Foundry

1. Edit source.sha in the plugin's entry of .claude-plugin/marketplace.json and, when the plugin is listed there, .agents/plugins/marketplace.json. Both pins name the same full SHA.
2. The plugin checkout already sits on that commit, so stage the gitlink: git add <plugin>. In a worktree whose plugin folder is empty, git add <plugin> stages nothing; stage the full SHA directly with git update-index --cacheinfo 160000,<sha>,<plugin>.
3. Verify that pins, gitlinks and manifests agree and that the plugins' shared copies still match, then validate the Claude catalog:

node -e '
const fs = require("fs"), path = require("path"), { execFileSync } = require("child_process");
const root = process.argv[1] || ".";
const git = (args, cwd = ".") => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
const manifests = [".claude-plugin/plugin.json", ".codex-plugin/plugin.json", "plugin.json"];
for (const catalog of [".claude-plugin/marketplace.json", ".agents/plugins/marketplace.json"])
  for (const p of JSON.parse(fs.readFileSync(catalog, "utf8")).plugins) {
    const { sha, ref } = p.source, dir = path.join(root, p.name);
    const gitlink = git(["ls-files", "-s", p.name]).split(" ")[1] === sha;
    try { git(["cat-file", "-e", sha + "^{commit}"], dir); }
    catch { console.log(catalog, p.name, "COMMIT NOT IN " + dir + ": fetch it there, or pass the Foundry root"); process.exitCode = 1; continue; }
    const pushed = git(["branch", "-r", "--contains", sha], dir).includes("origin/" + ref);
    const versions = new Set(manifests.flatMap((m) => { try { return [JSON.parse(git(["show", sha + ":" + m], dir)).version]; } catch { return []; } }));
    console.log(catalog, p.name, [...versions].join("/"), versions.size === 1 ? "manifests agree" : "MANIFEST VERSIONS DIFFER", gitlink ? "gitlink ok" : "GITLINK DIFFERS", pushed ? "on origin/" + ref : "NOT ON origin/" + ref);
    if (versions.size !== 1 || !gitlink || !pushed) process.exitCode = 1;
  }' .
node scripts/check-shared-copies.js .
claude plugin validate .

The pin check prints every line and exits non-zero on any problem, so read each line: an uppercase word means stop and fix it before you push. MANIFEST VERSIONS DIFFER: bump every manifest together in step 2, then commit, push and pin the new commit. GITLINK DIFFERS: check the plugin out at the pinned commit and stage its gitlink, as in item 2. NOT ON origin/<ref>: push the plugin's main and fetch, as in step 3. COMMIT NOT IN <dir>: that plugin checkout lacks the pinned commit, so fetch it there or pass the right root.

The pin check and the shared-copy check read the gitlinks, staged ones included, of the checkout they run in, the pin check its catalogs too, and each plugin's history from the plugin checkouts under the Foundry root: the path after the pin check's closing quote and the shared-copy check's argument, . when you run them there. Run both from the root of the checkout that holds the release commit. From a worktree, whose plugin folders are empty or stale, replace both . with the Foundry root's path; the release commit must be fetched into the root's plugin checkout.

scripts/check-shared-copies.js compares the code after the header comment of Hush's and Razor's hooks/lib/safe-write.js and the FIXTURES array of their tests/turn_boundary_conformance.test.js, the Node.js and fnm lookup in Foreman's and Razor's hooks/windows-launcher.ps1, and the whole of the README nav check's seven files in Foreman, Hush and Razor: scripts/git-hooks/check-readme-nav.js, scripts/git-hooks/pre-commit, the two files under scripts/git-hooks/vendor/, tests/readme_nav.test.js, tests/pre_commit.test.js and tests/fixtures/github-slugger-fixtures.json. It reads every file at the commit each plugin's gitlink pins, including the gitlink you just staged, and names that commit; a checkout's branch and uncommitted edits do not count. A difference means one plugin ships a fix another lacks: land the missing change in that plugin before you push the pin. The check skips a plugin with no checkout and names it, fails when it compared nothing, and fails when a pinned commit is missing from its checkout. It also compares flint's output-styles/hush.md, at flint's gitlink, with Hush's at the commit flint's README.md names, not at Hush's pin, after cutting the plugin-only parts flint's AGENTS.md lists; any other difference, or a listed part Hush no longer has, fails. It skips flint, and names it, when flint or Hush has no checkout.

agy plugin validate <plugin> checks the Antigravity package of a plugin that ships one, when the Antigravity CLI is installed; report it as not run otherwise.

4. Commit and push:

git add .claude-plugin/marketplace.json .agents/plugins/marketplace.json <plugin>
git commit -m "Install <plugin> <version> from main"
git push origin main

Nothing here is pre-approved beyond reading and editing: every command in this skill goes through the usual permission prompt, and the two pushes are the ones you should read before allowing. Foundry's push meets the same ruleset as the plugin's, with the required validate check; ask about it as in step 3.

Step 5 — install the release as a user would

The pin is public now. Install from the catalog into a throwaway config home per host, so your own installs, settings and hook trust stay untouched. Each new home starts without a login: the lines marked owner login, and every model session after them, bill the owner's account, so ask before running them and let the owner pick the account. Keep both homes and a disposable project in one scratch folder. The project holds one open roadmap entry, so Foreman's session hook has something to say. It is its own Git repository, because Codex otherwise reads the AGENTS.md of any repository that encloses the scratch folder:

check="$(mktemp -d)" && mkdir "$check/project" "$check/claude-home" "$check/codex-home"
cd "$check/project" && git init -q
printf '%s\n' '{"id":"001","title":"Release hook check","status":"in_progress"}' > ROADMAP.jsonl

Claude Code. Install the released plugin, and Foreman too when another plugin is released, because the Task-event check needs it. Then run one short session with hook events in its output. A capture hook on the two Task events receives the same input as Foreman's task-created and task-completed hooks:

export CLAUDE_CONFIG_DIR="$check/claude-home"
claude --version
claude plugin marketplace add V-Songbird/foundry
claude plugin install <plugin>@foundry
claude plugin install foreman@foundry   # when <plugin> is not foreman
claude plugin list
claude                                  # owner login: sign in, then quit
cat > capture.js <<'EOF'
const fs = require("fs");
fs.appendFileSync("task-events.jsonl", fs.readFileSync(0, "utf8").trim() + "\n");
EOF
claude -p "Use TaskCreate to add one task, then mark it completed with TaskUpdate. Do nothing else." \
  --model haiku --allowedTools TaskCreate,TaskUpdate \
  --settings '{"hooks":{"TaskCreated":[{"hooks":[{"type":"command","command":"node capture.js"}]}],"TaskCompleted":[{"hooks":[{"type":"command","command":"node capture.js"}]}]}}' \
  --output-format stream-json --verbose --include-hook-events < /dev/null > session.jsonl
node -e '
const fs = require("fs");
const read = (f) => fs.readFileSync(f, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
const ok = read("session.jsonl").filter((e) => e.subtype === "hook_response" && e.outcome === "success");
const fired = (event, text) => ok.some((e) => e.hook_event === event && e.stdout.includes(text));
console.log("foreman SessionStart:", fired("SessionStart", "[Foreman]"));
console.log("razor SessionStart:", fired("SessionStart", "RAZOR ACTIVE"));
console.log("hush UserPromptSubmit:", fired("UserPromptSubmit", "hush:"));
for (const event of ["TaskCreated", "TaskCompleted"]) console.log(event, "hooks that ran:", ok.filter((e) => e.hook_event === event).length);
for (const e of read("task-events.jsonl"))
  console.log(e.hook_event_name, ["task_id", "task_subject", "task_description"].map((k) => k + (typeof e[k] === "string" ? " ok" : " MISSING")).join(", "));
'

claude plugin list must show the new version, and every plugin you installed must print true. Each Task event must show two hooks that ran, the capture hook and Foreman's, and all three fields ok. A MISSING field means Claude Code changed the Task-event input, which silently turns Foreman's task hooks off: report it as a Foreman bug with the Claude Code version. A plugin that prints false only in the first session of a new home may have hit its hook timeout on a cold start; run the session once more before reporting it.

Codex. Skip it when the release is Hush, which has no Codex package. When the codex CLI is not installed, report the Codex check as not run. Otherwise install the released plugin and trust its hooks the way a user does:

export CODEX_HOME="$check/codex-home"
codex --version
codex login                             # owner login
codex plugin marketplace add V-Songbird/foundry
codex plugin add <plugin>@foundry
codex plugin list --marketplace foundry --json

The listing must show the new version. The owner's sign-in also syncs their account plugins into the new home; an AuthRequired error their MCP servers print on stderr is not a release failure. Start codex --no-daemon in the same project and open /hooks; without the flag the TUI fails when CODEX_HOME sits under a long path. Record whether Codex asked you to review and trust the plugin's hooks before they ran; in a fresh home it should. Trust them, quit, and start codex --no-daemon again. Ask the new session to quote the first line of each note it received at session start: Razor's begins RAZOR ACTIVE, and Foreman's [Foreman] Roadmap entries still open. A NODE_OPTIONS preload that logs which hook ran must read process.execArgv, not process.argv: Foreman's hooks start as node -e "require(...)", so their argv names no script.

Existing Codex users keep their trust unless a hook definition changed. This command compares the pin step 0 printed with the release; when it prints anything, record that existing users must review and trust the hooks again:

git -C <plugin> diff --stat <pinned-sha> <release-sha> -- hooks/codex-hooks.json

Antigravity. Skip it for a plugin without a root plugin.json, such as Hush. Antigravity has no config-home setting: agy plugin install writes into ~/.gemini/config/plugins of the user who runs it. So run it in a throwaway user profile, with HOME, USERPROFILE, APPDATA and LOCALAPPDATA relocated into the scratch folder, and install from a Foundry clone at the pin, as a user would:

git clone -q --recurse-submodules https://github.com/V-Songbird/foundry.git "$check/foundry"
profile="$(cd "$check" && { pwd -W 2>/dev/null || pwd; })/agy-profile"
mkdir -p "$profile/AppData/Roaming" "$profile/AppData/Local"
in_profile() { HOME="$profile" USERPROFILE="$profile" APPDATA="$profile/AppData/Roaming" LOCALAPPDATA="$profile/AppData/Local" "$@"; }
ls ~/.gemini/config/plugins > "$check/gemini-before.txt" 2>/dev/null
in_profile agy --version
in_profile agy plugin install "$check/foundry/<plugin>"
in_profile agy plugin list
diff -r --exclude=.git "$check/foundry/<plugin>" "$profile/.gemini/config/plugins/<plugin>"
ls ~/.gemini/config/plugins 2>/dev/null | diff "$check/gemini-before.txt" -

Record the agy version and that agy plugin list names the plugin with its skills and hooks. Both diff commands must print nothing: the installed copy equals the clone, and your own ~/.gemini/config/plugins did not change. The relocated profile has no Antigravity sign-in, so it cannot show a hook firing in a live conversation. That check is owner login: with the owner's go-ahead, sign in inside the relocated profile, start a conversation in $check/project, and ask it to quote the first line of each note it received at its first model call; Razor's begins RAZOR ACTIVE. Report it as not run otherwise.

Delete the scratch folder afterwards, which removes both homes, the relocated profile, the clone and the project:

cd && rm -rf "$check" && unset CLAUDE_CONFIG_DIR CODEX_HOME

Step 6 — confirm

Report the plugin, the version, the plugin release SHA, the Foundry commit SHA and both push results. Add step 5's results: the Claude Code and Codex versions, which hook fired for each plugin on each host, whether Codex asked to trust the hooks and whether existing users must trust them again, the Task-event fields, and Antigravity's version, listing and live check, each as run or not run. A local commit, a valid catalog or a green suite is not publication; if a push failed, surface that rather than retrying silently.

What this skill does not do

• Write or edit plugin source, skills, agents or hooks.
• Add a version to a catalog entry, or a plugin to a catalog that does not list it.
• Pin a commit that is not reachable from the plugin's origin/main.
• Decide the bump size without asking, unless the user already stated it.
• Force-push, skip hooks, or release over a red suite without explicit confirmation.