release

name	release
description	Cut a new ArcKit release — bump versions in lockstep, regenerate non-Claude formats, validate plugin/marketplace agreement, tag, and push to standalone repos. Use when the user says 'cut a release', 'release ArcKit', 'ship vX.Y.Z', 'bump the version and release', 'do the release flow', 'tag and publish', or 'push the extensions'. This is a manual, high-consequence workflow: it never runs automatically.
disable-model-invocation	true
argument-hint	[X.Y.Z]

Release ArcKit

Drive the ArcKit release flow end to end. This skill is the executable companion to docs/RELEASING.md — that doc is the source of truth; if the two disagree, trust RELEASING.md and update this skill.

The target version is $ARGUMENTS (e.g. /release 5.10.0). If no version was given, ask for it before doing anything — never guess a version.

This workflow tags and publishes to public GitHub repos. Do NOT run any step that pushes, tags, or publishes without the user confirming the version and that the PR is already merged to `main`. Show the plan and the computed version first, then proceed step by step.

Preconditions

Confirm all of these before touching version files:

1. The feature PR is merged to main — releases are cut from main, never from a branch.
2. Working tree is on main and clean: git checkout main && git pull && git status.
3. The version $ARGUMENTS is valid semver (X.Y.Z) and greater than the current plugin version (cat plugins/arckit-claude/VERSION) and CLI version (cat VERSION).
4. GH_TOKEN is set in the environment (needed by push-extensions.sh).

If any precondition fails, stop and surface it. Do not work around it.

Release flow

Run these in order. Each script is idempotent or safe to re-run except the git tag/git push steps. Pause after step 6 (the commit) and after step 8 before tagging to let the user confirm.

# 1. Edit CHANGELOGs by hand — both of them:
#    CHANGELOG.md (CLI) and plugins/arckit-claude/CHANGELOG.md (plugin).
#    Preview what shipped since the last tag to seed the entries:
./scripts/generate-release-notes.sh

# 2. Bump every version file in lockstep (15 locations: VERSION files,
#    manifests, README badges, docs, plugin.json):
./scripts/bump-version.sh X.Y.Z

# 3. Regenerate Codex/OpenCode/Gemini/Copilot/Paperclip formats from the
#    plugin source — MUST run after the bump so the extensions carry the
#    new version:
python scripts/converter.py

# 4. Validate generated extension outputs before committing:
pytest tests/codex/test_codex_extension.py \
  tests/gemini tests/opencode tests/copilot \
  tests/vibe/test_vibe_extension.py \
  tests/paperclip/test_commands_json.py \
  tests/plugin/test_release_process.py

# 5. Sanity-check the tree (no stray edits, counts/versions consistent):
git status && git diff --stat

# 6. Commit the bump — a clean tree is required for `claude plugin tag`:
git add -A && git commit -m "chore: bump version to X.Y.Z"

# 7. Validate EVERY plugin manifest against the marketplace entry.
#    Discover plugins dynamically — do NOT hardcode the list (it grows).
#    Search from `plugins`, not `.`: from the repo root the manifests sit at
#    depth 4, so `find . -maxdepth 3` matches nothing and the loop below
#    "passes" having validated not one plugin.
mapfile -t manifests < <(find plugins -maxdepth 3 -path '*/.claude-plugin/plugin.json' | sort)

(( ${#manifests[@]} > 0 )) || { echo "No plugin manifests found — check the find path"; exit 1; }
echo "Validating ${#manifests[@]} plugin manifests..."

for manifest in ; 
  =   
  claude plugin tag  --dry-run || {  ;  1; }



claude plugin prune --dry-run





git tag -a vX.Y.Z -m 
git push && git push origin vX.Y.Z



./scripts/tag-plugins.sh X.Y.Z






./scripts/push-extensions.sh

After step 11, confirm the GitHub Release was created (the release.yml workflow runs on the vX.Y.Z tag push). Also confirm every standalone repo has a vX.Y.Z tag and GitHub Release, then report the release URLs and which standalone repos were pushed.

Then write the release article for the major features — docs/articles/YYYY-MM-DD-<slug>.md plus a hero generator script, force-added past the drafts-folder gitignore. No Markdown tables — LinkedIn and Medium do not render them; write comparisons as prose. See "Release article" in RELEASING.md for the full conventions (voice, hero style, community block, contributor credits).

Common Gotchas

The highest-signal failures — collected from real releases. Read these before running anything.

• Releasing from a feature branch. Releases are cut from main after the PR is merged. Tagging a branch ships an unmerged tree. Always git checkout main && git pull first.
• Forgetting the converter (step 3). bump-version.sh updates the plugin source, but the Codex/OpenCode/Gemini/Copilot/Paperclip copies are generated. Skip converter.py and the extensions ship the old version. The converter must run after the bump and before the commit, so the regenerated files are included.
• Skipping extension tests. Run the step 4 extension suite after converter.py. It validates Codex, Gemini, OpenCode, Copilot, Vibe, Paperclip, release inventory, version alignment, and platform-specific command rewrites before anything is tagged.
• Releasing from a Mac. bump-version.sh runs on stock macOS (BSD sed, bash 3.2) and asserts every substitution lands — a does not contain "…" after edit error is pattern drift, not a sed-flavour problem. tag-plugins.sh and push-extensions.sh still need bash ≥ 4: brew install bash, then /opt/homebrew/bin/bash scripts/…. Full macOS notes (uv commands for the converter and tests, the http.postBuffer fix for protocol error: bad line length pushes, GH_TOKEN via gh auth token) live in RELEASING.md's "Releasing from macOS" section.
• Hardcoding the plugin list. The Claude marketplace now ships 16 plugins (core plus regional, sector, method, agent-architecture, tooling, and supplier overlays) and keeps growing. Older examples listed only 7, silently skipping newer plugins. Discover plugins dynamically (step 7) -- this is the exact bug that shipped arckit-uk-nhs untagged mid-v5.4.0, which is why tag-plugins.sh now auto-discovers. Never copy a static plugin array.
• A for loop over an empty glob exits 0. Step 7's discovery searched from . while the manifests sit at depth 4, so -maxdepth 3 matched nothing and the validation reported a clean pass having checked not one plugin -- through every release from v6.0.0 to v6.7.4. Dynamic discovery only helps if you assert it found something, hence the count check and the Validating N plugin manifests... line. Treat any loop whose body might never run as unvalidated until it prints what it covered.

Reference

• docs/RELEASING.md — full release documentation and rationale
• scripts/bump-version.sh — version bump across all files
• scripts/generate-release-notes.sh — changelog preview from git log
• scripts/tag-plugins.sh — native per-plugin tags (auto-discovers)
• scripts/push-extensions.sh — pushes distribution dirs to standalone repos
• .github/workflows/release.yml — creates the GitHub Release on v* tag push