/release

name: release
description: |
  Handles version bumps and npm releases for the swarm-tools monorepo (opencode-swarm-plugin,
  claude-code-swarm-plugin, swarm-mail, swarm-queue). Use when: creating changesets, bumping
  versions, preparing releases, checking release status, debugging publish failures, verifying
  npm packages, or merging release PRs.
  Triggers: "release", "publish", "changeset", "bump version", "ship it", "new version",
  "create a release", "check npm", "verify publish", "/release"

Release Workflow

Standard Release (CI-driven)

All releases go through changesets → CI → npm. Never publish manually unless CI is broken.

1. Create changeset

cat > .changeset/<descriptive-name>.md << 'EOF'
---
"opencode-swarm-plugin": patch
---

fix: description of what changed and why
EOF

**Bump levels**: `patch` (bug fixes), `minor` (features), `major` (breaking changes).

**Which packages to include** — only packages with actual changes:

• `opencode-swarm-plugin` — main plugin (CLI, MCP server, swarm orchestration)
• `claude-code-swarm-plugin` — thin Claude Code wrapper (commands, agents, hooks, skills)
• `swarm-mail` — agent messaging, memory, reservations
• `swarm-queue` — task queue

**Use pdf-brain for commit quotes:**

pdf-brain search "<relevant topic>" --limit 1 --expand 500

2. Commit and push

git add .changeset/<name>.md <changed-files>
git commit -m "feat: description"
git push origin main

3. CI creates release PR

CI (`publish.yml`) runs on push to main: 1. Detects changesets → runs `changeset version` + `bun update` 2. Syncs `plugin.json` versions (lifecycle hook at `.changeset/config.json`) 3. Opens/updates PR on `changeset-release/main` branch 4. AI generates PR title via `vercel/ai-action`

4. Merge release PR

gh pr merge <number> --squash --delete-branch

CI then: 1. Builds all packages 2. Verifies tarballs contain expected artifacts 3. Runs `scripts/ci-publish.sh` — packs with `bun pm pack` (resolves `workspace:*`), publishes via `npm publish` 4. Tags releases 5. Generates and posts release tweet to @swarmtoolsai

5. Verify

npm view opencode-swarm-plugin@latest dependencies
npm view claude-code-swarm-plugin@latest version

**Critical check**: Verify no `workspace:*` in published deps. If found, the publish script's safety net failed — see Troubleshooting.

Version Touchpoints

CI handles all of these via changesets. For manual bumps, ALL must be updated:

| Package | Files | |---------|-------| | opencode-swarm-plugin | `packages/opencode-swarm-plugin/package.json`, `claude-plugin/.claude-plugin/plugin.json` | | claude-code-swarm-plugin | `packages/claude-code-swarm-plugin/package.json`, `.claude-plugin/plugin.json` | | swarm-mail | `packages/swarm-mail/package.json` | | swarm-queue | `packages/swarm-queue/package.json` |

Manual bump script: `./scripts/bump-version.sh <version>`

Troubleshooting

`workspace:*` in published npm package

The `scripts/ci-publish.sh` uses `bun pm pack` (resolves workspace protocol) + a python3 safety net that rewrites any remaining `workspace:*` to actual versions. If this still fails:

1. Check bun version — `packageManager` in root `package.json` must be >= 1.3.5 2. Verify safety net ran — CI logs should show "resolving from monorepo" if workspace deps leaked 3. Nuclear option: bump the broken package (patch changeset), push, merge release PR

CI publish fails with E403

Already-published version. Normal when re-running publish — `|| true` catches it. Only a problem if the VERSION wasn't bumped (changeset not applied).

Plugin.json version mismatch

CI lifecycle hook should sync these. If not, manually:

VERSION=$(jq -r .version packages/opencode-swarm-plugin/package.json)
jq ".version = \"$VERSION\"" packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json > /tmp/p.json
mv /tmp/p.json packages/opencode-swarm-plugin/claude-plugin/.claude-plugin/plugin.json

Release PR not created/updated

Changesets action only runs when `.changeset/*.md` files exist (excluding README.md). If no changesets, it skips version PR creation and goes straight to publish (for any packages with unpublished versions).

Architecture Notes

• **Two Claude Code plugins**: `opencode-swarm-plugin` (full, bundles MCP server + CLI) and `claude-code-swarm-plugin` (thin wrapper, shells out to `swarm` CLI). Both register as plugin name "swarm".
• **Publish script** (`scripts/ci-publish.sh`): Iterates all `packages/*`, skips private, packs, resolves workspace deps, publishes tarball.
• **Changeset config** (`.changeset/config.json`): Public access, GitHub changelog, ignores `@swarmtools/web`.
• **Tweet bot**: CI generates release tweet via claude-opus and posts to X via OAuth. Cloudflare retry logic included.