release

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# brooks-lint — Release

Target version comes from the user request (e.g. `1.4.0`). If empty, ask the maintainer
for the semver bump before doing anything.

**Before accepting that version, read the backlog.** Run
`npm run changelog:audit` and look at what is actually unreleased — the bump is decided by the whole range, not by the change
that prompted the release. If the range contains a feature or a new platform and
the maintainer asked for a patch, stop and say so: v1.5.1 was published, then
deleted and re-cut as v1.6.0 because twenty unreleased commits (including a new
platform) had been swept into a patch.

Execute these steps in order. `bump-version.mjs` reads the version FROM
`package.json` and does NOT touch the changelog — so the version edit and the
CHANGELOG entry are manual; the script only fans the version out to the manifests
and every version-bearing text file.

1. **Set the source of truth.** `npm version <version> --no-git-tag-version`
   (the `--no-git-tag-version` flag is required — plain `npm version` would create
   its own commit + tag and collide with the manual commit in step 5).
2. **Propagate.** `npm run bump` — writes the version into
   `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`,
   `.codex-plugin/plugin.json`, `gemini-extension.json`, and every version-bearing
   text file discovered by `scripts/version-refs.mjs` (all six README badges and action `uses:` pins,
   the JSON-LD `softwareVersion` on the docs landing page, and
   `docs/github-action-example.yml`). Do not maintain a list
   here — the script's is authoritative.
3. **Write the changelog.** Add a new section at the top of `CHANGELOG.md` with
   categorized notes (Added / Fixed / Changed) summarizing the commits since the
   last release tag. The heading MUST be `## [<version>] - YYYY-MM-DD` —
   `npm run validate` parses that exact shape and fails on a bare `## <version>`.
3a. **Audit the range — every commit, no sampling.** Run:

   ```bash
   npm run changelog:audit
   ```

   It derives the range from the last release tag, applies the only three
   exemptions (the release bump, a merge commit whose branch commits are listed
   separately, and the star-history refresh — a bot commit touching only the
   chart's own two files) and prints the rest as a checklist.
   Walk it: each line gets an entry you just wrote, or a reason it needs none.
   **Nothing else is exempt** — internal hardening with no user-visible change
   earns an entry, and so does an outside contributor's maintainer-facing fix,
   which also earns an `@handle` credit. A `Changelog:` trailer on a commit is
   surfaced as a flag; that commit's entry is the one you are writing now.

   The script exits non-zero on the gap it can prove — a pull request in the
   range whose `#N` the section never cites. That same check runs inside
   `npm run validate` while a release is in progress, so it cannot be skipped,
   and validate prints one line whenever it stands down. The rest of the
   checklist is judgment and is not enforced. A green audit is not proof of a
   complete changelog: a bare `#N` anywhere in the section clears the gate, a
   rebase-merged PR leaves nothing to match, and anything staged into the
   release bump itself is never audited. See AGENTS.md's Release Process.

4. **Validate.** `npm run validate` — fails if any manifest, any version-bearing
   text file, or the CHANGELOG entry is out of sync. Fix and re-run until clean.
   Then `npm test`.
5. **Commit & push.** Stage everything `npm run bump` rewrote plus `CHANGELOG.md` —
   read `git status` rather than naming files, because the version-bearing set is
   discovered from disk and is more than one README; commit
   with a conventional message (`chore(release): bump version to <version>`); push
   to `main` (direct-to-main repo — no PR).
5a. **Synchronize release surfaces and approval.** Check all six README translations,
   CHANGELOG, plugin manifests, website and installation guides against the release
   state. Run `npm run github:metadata -- --apply` and then `--check` to synchronize
   About, homepage, topics, and managed labels. Preserve unrelated labels. Honor
   explicit publication holds; completed preparation and green CI are not approval.
   Withdrawn npm versions cannot be reused, even when GitHub tags are deleted.
5b. **Wait for remote CI on the exact release commit.** After pushing, resolve
   `git rev-parse HEAD`, find the `Validate` workflow run whose `headSha` matches
   that commit, and wait for it with `gh run watch <run-id> --exit-status`.
   Inspect every matrix job. A missing, queued, cancelled, or failed run is not
   a pass. Local checks do not replace this gate. Do not create the GitHub release
   or publish to npm until this exact-commit run has completed successfully.
   If CI fails, diagnose and commit the fix, then wait for the new commit's CI.
6. **Tag & publish.** Only after the remote gate passes, create the GitHub release:
   `gh release create v<version> --title "v<version>" --notes "<changelog section>"`.

Report the released version and the GitHub release URL when done.

From hyhmrright/brooks-lint, MIT.

More from hyhmrright/brooks-lint