# What Does the `make release` Command Do in Caveman?

> Automate your Caveman skill release with 'make release'. This command handles versioning, building, checksums, Git tagging, and CI triggers for npm and GitHub Releases.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The `make release` command automates the entire release lifecycle for the Caveman skill, handling version bumps, building the skill archive, regenerating security checksums, committing changes, pushing a Git tag, and triggering the CI pipeline that publishes to npm and GitHub Releases.**

The `make release` command in the JuliusBrussee/caveman repository is the canonical developer shortcut for shipping a new versioned release. This single command orchestrates the same steps executed by the CI pipeline, ensuring that the skill archive, npm package, and installer hooks remain perfectly synchronized for downstream users.

## Overview of the Release Automation

When you run `make release`, the command executes a six-step pipeline that transforms local changes into a fully published, immutable release. According to the source code in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) and the CI configuration, this process guarantees that downstream installers always fetch cryptographically verified files from a pinned release tag rather than mutable branches.

## Step-by-Step Breakdown of `make release`

### 1. Version Bump in package.json

The command first increments the **version** field in [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) (line 3). By default, it performs a patch bump (e.g., `v1.9.1` → `v1.9.2`), but you can override this behavior to target specific semver components. The new version string determines the Git tag name prefixed with `v`.

### 2. Build the Skill Archive

The build logic located in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (see the comment on line 1128) compresses the `skills/caveman/` directory into `dist/caveman.skill`. This ZIP archive serves as the binary payload that agents load when installing the "Caveman skill."

### 3. Regenerate Checksum Manifest

To ensure supply-chain integrity, the command regenerates `src/hooks/checksums.sha256`. As implemented in the "Pin remote fetches to an immutable release tag" block in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) (lines 30-34), this manifest contains SHA-256 hashes that allow the installer to verify hook files fetched from the release tag.

### 4. Commit, Tag, and Push

The updated [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json), the new `dist/` archive, and the refreshed checksum manifest are committed to the repository. The command then creates and pushes a Git tag matching the new version (e.g., `vX.Y.Z`). This push triggers the GitHub Actions workflow defined in [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml).

### 5. Publish to npm and GitHub Releases

The CI workflow automatically publishes the **caveman-shrink** npm package from `src/mcp-servers/caveman-shrink/` and attaches the `caveman.skill` ZIP to the GitHub Release assets. This dual publication ensures both the MCP middleware and the skill binary are available simultaneously.

### 6. Update the Installer Reference

Finally, because [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) uses the constant `PINNED_REF` (line 36) set to `CAVEMAN_REF`, the new tag immediately becomes the immutable source for all fresh installs. The installer pulls hook files from this specific tag, ensuring that `curl|bash` or `irm|iex` installations automatically receive the latest verified files without requiring code changes on the main branch.

## How to Use `make release`

From the repository root, execute the command with optional version specifications:

```bash

# Default: patch bump (v1.9.1 → v1.9.2)

make release

# Explicit version components

make release VERSION=minor   # creates v1.10.0

make release VERSION=major   # creates v2.0.0

```

After execution, you will observe:

- A new Git tag (`vX.Y.Z`) on GitHub
- A GitHub Release with `caveman.skill` attached as a binary asset
- An updated **caveman-shrink** package published to the npm registry
- A refreshed `src/hooks/checksums.sha256` manifest

## Key Files Involved in the Release Process

- **[`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json)** — Stores the version string that becomes the release tag name.
- **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)** — Contains the `PINNED_REF` logic (line 36) and checksum regeneration code (lines 30-34) that pins the installer to immutable tags.
- **[`src/mcp-servers/caveman-shrink/package.json`](https://github.com/JuliusBrussee/caveman/blob/main/src/mcp-servers/caveman-shrink/package.json)** — Defines the npm package published during the CI phase.
- **[`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml)** — The CI workflow triggered by tag pushes that handles npm publication and GitHub Release creation.
- **`dist/caveman.skill`** — The binary skill archive rebuilt on each release (referenced in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), line 1128).
- **`src/hooks/checksums.sha256`** — The integrity manifest verified by the installer during hook file fetching.

## Summary

- The `make release` command automates the complete Caveman release lifecycle from version bump to publication.
- It builds `dist/caveman.skill`, regenerates `src/hooks/checksums.sha256`, and commits both to the repository.
- The command pushes a Git tag (e.g., `vX.Y.Z`) that triggers [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml).
- The CI pipeline publishes the `caveman-shrink` npm package and attaches the skill ZIP to GitHub Releases.
- The installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) uses `PINNED_REF` to automatically serve the new release's hook files to all future installations.

## Frequently Asked Questions

### What happens if I don't specify a VERSION parameter?

If you run `make release` without arguments, the command defaults to a **patch** semver bump. This increments the third digit of the version string in [`package.json`](https://github.com/JuliusBrussee/caveman/blob/main/package.json) (e.g., changing `1.9.1` to `1.9.2`) and creates the corresponding Git tag.

### Where does the installer download files from after a release?

The installer ([`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)) downloads hook files from the **immutable release tag** specified by the `PINNED_REF` constant (line 36). When `make release` creates a new tag like `v1.9.2`, the installer automatically fetches files from that specific tag rather than the mutable `main` branch, ensuring cryptographic verification via `src/hooks/checksums.sha256`.

### Is the npm package the same as the skill archive?

No. The **caveman-shrink** npm package located in `src/mcp-servers/caveman-shrink/` is the MCP (Model Context Protocol) middleware, while `dist/caveman.skill` is the binary ZIP archive containing the actual skill logic. The `make release` command ensures both are built and published simultaneously, but they serve different architectural purposes.

### How does the checksum manifest protect users?

The `src/hooks/checksums.sha256` file contains SHA-256 hashes for all hook files. During installation, [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) validates downloaded files against these hashes (as implemented in the checksum verification logic). This prevents tampering and ensures that the installer only executes code that matches the cryptographically signed release artifacts.