Skip to main content
skill CX Codex

release-sidecar — Claude Code skill: what it does, how to install

release-sidecar walks a sidecar release from version pick to a published Homebrew formula: semver tag, dependency pins, changelog, GoReleaser build.

MIT 1 installs ★ 1,095 updated 2026-10-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add marcus/sidecar --skill release-sidecar -a claude-code
Open on GitHub

What release-sidecar does

This skill encodes how sidecar gets released. The short path is a single make target that reads the next version off the latest tag, rewrites the changelog heading, commits, pushes and tags, then leaves the rest to CI. You either pass BUMP or set RELEASE_VERSION=vX.Y.Z yourself.

Around it sit the checks. A preflight script queries gh run list --workflow=go-ci.yml and refuses to continue when tests or lint are red, still running, or missing. make sync-deps moves every github.com/marcus/* requirement to its newest tag, and the snapshot and dry-run targets show the plan without changing anything. Tag push fires verify, the GoReleaser release, and the tap job that turns packaging/homebrew/sidecar.rb.tmpl into Formula/sidecar.rb.

Come prepared: Go matching your go.mod, a clean tree with main level with origin/main, an authenticated gh allowed to push to marcus/homebrew-tap, the HOMEBREW_TAP_TOKEN secret on the repo, and no replace lines in go.mod. Keep the workspace file in mind, because go.work points sibling imports at local checkouts and a stale pin hides there; both the gate and the sync run with GOWORK=off.

What it helps with

  • cut a sidecar release with one make target instead of replaying a checklist
  • confirm Go CI is green on the commit about to be tagged
  • pin sibling github.com/marcus/* modules to their newest tags
  • finish only the Homebrew tap step when the tag already exists
  • check the published version installs into a throwaway GOBIN

Example prompts for the agent

  • Prep the sidecar release and tell me which BUMP to use
  • Start with a dry run: make release-dry-run BUMP=minor
  • The tag already exists, so finish just the tap: RELEASE_VERSION=vX.Y.Z make release-tap

How to install release-sidecar

1Skills CLI (Vercel)

npx skills add marcus/sidecar --skill release-sidecar -a claude-code

2Manually: put the files in place

~/.claude/skills/release-sidecar/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/release-sidecar/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about release-sidecar

How do I install release-sidecar in Claude Code?

Run npx skills add marcus/sidecar --skill release-sidecar -a claude-code. The skill file ends up at ~/.claude/skills/release-sidecar/SKILL.md.

What does release-sidecar do?

It carries a sidecar release through: semver version choice, dependency updates, changelog stamping, GoReleaser publishing and the Homebrew formula refresh, plus a check that the result installs.

Why does every step insist on GOWORK=off?

With go.work active, sibling modules resolve to local checkouts, so an outdated pin stays out of sight. The preflight gate and make sync-deps both run with the workspace switched off.

Source text

SKILL.md · MIT
---
name: release-sidecar
description: Release new versions of sidecar. Covers version tagging with semver, td dependency updates, go.mod validation, CHANGELOG updates, GoReleaser automation, Homebrew tap updates, and verification steps. Use when preparing or executing a release.
disable-model-invocation: true
---

# Releasing a New Version

Operator contract: **`docs/guides/active/releasing.md`**. Enforcement lives in `scripts/` and
`BUMP=minor make release` (or `RELEASE_VERSION=vX.Y.Z make release` for an explicit
version). Prefer the one-shot command over replaying this checklist by hand.

## Prerequisites

- Go matching `go.mod`
- Clean working tree; `main` identical to live `origin/main`
- Tests and **Go CI** green on the commit you will tag (tests *and* lint) —
  `check-release-state.sh` now checks this itself via `gh run list
  --workflow=go-ci.yml` and fails closed if it's red/running/missing, so you
  don't have to remember to look
- GitHub CLI authenticated with push access to `marcus/homebrew-tap`
- No `replace` directives in `go.mod`
- `HOMEBREW_TAP_TOKEN` secret present in the GitHub repo (CI tap job)

**Beware of go.work**: always use `GOWORK=off` when updating dependencies and
when validating install paths.

Local lint must match CI's golangci-lint **v2.12.2**, or trust CI:

```bash
gh run list --workflow=go-ci.yml --limit=1
```

## Prepare (sidecar-specific)

### 1. Version

```bash
git tag -l 'v*' | sort -V | tail -1
```

SemVer: major / minor / patch as usual.

### 2. Sibling dependencies (td, tasks)

```bash
make sync-deps   # pins every github.com/marcus/* requirement to its latest tag
```

`check-release-state.sh` enforces this and refuses to tag when one is behind.
`go.work` resolves those imports to the local checkouts, so drift is invisible
locally — both the gate and `sync-deps` use `GOWORK=off`. If a sibling jumped
several minors, decide deliberately (pin for a focused release vs take latest
and note it under Dependencies) and smoke its tab in the app.

### 3. CHANGELOG

```markdown
## [Unreleased]

### Features
- …

### Bug Fixes
- …

### Dependencies
- …
```

Commit the changelog (and any dependency bump) on `main`, then push so
`HEAD == origin/main`. Leave the heading as `## [Unreleased]` — `make release`
stamps it to `## [vX.Y.Z] - YYYY-MM-DD` for you.

## Publish

```bash
# Dry-run (optional but recommended for tooling changes)
make release-snapshot
./scripts/verify-release-archives.sh dist
./scripts/test-release-guards.sh dist
./scripts/test-release-publication.sh
make release-dry-run BUMP=minor   # prints the derived version + plan, no mutation

# Cut the release: derive the version, stamp the changelog, commit, push,
# then the fail-closed preflight → tag → CI → formula verify/publish
BUMP=minor make release
```

The version is stated exactly once — via `BUMP` derived from the latest tag, or
by setting `RELEASE_VERSION=vX.Y.Z` yourself (also works if you stamped the
CHANGELOG heading by hand). `scripts/release.sh` refuses an empty `[Unreleased]`
section, a tree dirty beyond `CHANGELOG.md`, a tag that already exists, and a
`RELEASE_VERSION` that contradicts an already-stamped heading, before handing off
to `scripts/publish-release.sh`. What it enforces and does end to end is
documented in `docs/guides/active/releasing.md`.

Resume only the tap step if the tag/release already exists:

```bash
RELEASE_VERSION=vX.Y.Z make release-tap
```

### CI jobs (on tag push)

1. **`verify`** — tag points at live `main`, tests, snapshot archives, release guards
2. **`release`** — GoReleaser publishes GitHub release + binaries
3. **`update-homebrew-tap`** — renders `packaging/homebrew/sidecar.rb.tmpl` and
   pushes `Formula/sidecar.rb` with downgrade/idempotency/race guards

td/nightshift formulas are **not** auto-bumped; edit them by hand when co-releasing.

## Verify

```bash
gh run list --workflow=release.yml --limit=1
gh release view vX.Y.Z --json assets -q '.assets[].name'

GOBIN=$(mktemp -d) GOWORK=off go install github.com/marcus/sidecar/cmd/[email protected]
"$GOBIN/sidecar" --version
```

`go install @vX.Y.Z` can 500 from the checksum DB for a minute or two after the
tag — wait and retry. Prefer a throwaway `GOBIN` so verification does not
clobber a dev machine's `sidecar`.

## Dev machine after release

```bash
# Return to the canonical main development build:
make install-local

# Or keep the released Homebrew build active:
make use-homebrew

# In either case, prove the managed link and both login-shell modes:
make install-status
```

## Recovery

Prefer a new patch release. Keep tags. Resume tap with `make release-tap`.
See `docs/guides/active/releasing.md`.

## Checklist

- [ ] Go CI green (tests + lint) on the commit to tag — enforced automatically by `check-release-state.sh`
- [ ] Working tree clean; `main` == `origin/main`
- [ ] td bump considered; td tab smoke if td moved
- [ ] No `replace` in go.mod; `GOWORK=off` build works
- [ ] Agent integration assets: if any bundled asset's bytes changed, its version constant, `internal/agentlifecycle/capabilities.json`, and the golden in `internal/agentintegration/asset_golden_test.go` all moved with it (the golden test fails if they did not)
- [ ] CHANGELOG bullets under `## [Unreleased]`
- [ ] `BUMP=minor make release` (or `RELEASE_VERSION=vX.Y.Z make release`) succeeded
- [ ] Release assets present; formula URL/sha match (automatic)
- [ ] `go install` verified into throwaway `GOBIN`
- [ ] `make install-status` proves the dev machine is on the intended binary

© marcus · MIT · marcus/sidecar

Similar skills

All skills for DevOps and infrastructure →

Project sponsors

Companies that keep this analytics open