Release
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"From its SKILL.md
npx -y skills add ImBIOS/swarm-tools --skill releaseAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.8 KB, as published. Nobody here has run it
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, reservationsswarm-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:
- Detects changesets → runs
changeset version+bun update - Syncs
plugin.jsonversions (lifecycle hook at.changeset/config.json) - Opens/updates PR on
changeset-release/mainbranch - AI generates PR title via
vercel/ai-action
4. Merge release PR
gh pr merge <number> --squash --delete-branch
CI then:
- Builds all packages
- Verifies tarballs contain expected artifacts
- Runs
scripts/ci-publish.sh— packs withbun pm pack(resolvesworkspace:*), publishes vianpm publish - Tags releases
- 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:
- Check bun version —
packageManagerin rootpackage.jsonmust be >= 1.3.5 - Verify safety net ran — CI logs should show "resolving from monorepo" if workspace deps leaked
- 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) andclaude-code-swarm-plugin(thin wrapper, shells out toswarmCLI). Both register as plugin name "swarm". - Publish script (
scripts/ci-publish.sh): Iterates allpackages/*, 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.