From 638af205665c7a64379193a16c21ff4c1ad09bc5 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Tue, 28 Apr 2026 11:03:34 -0700 Subject: [PATCH] Document the release workflow in CLAUDE.md and AGENTS.md Covers the per-component tag prefixes, the changelog-label convention that the release script matches against, the cleanliness gates, the attached artifacts, and the manual post-release steps for the CLI (npm publish) and the extension (Chrome Web Store upload). Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 4 ++++ CLAUDE.md | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index dd38cc9f9..36e165c57 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,6 +51,10 @@ Conventions: wrap the identifying heading text in straight double quotes inside Recent history favors short, imperative subjects such as `Fix: ...`, `Add ...`, `Improve ...`, or `Bump ...`. Keep commits focused and explain the user-facing impact when it is not obvious. PRs should summarize what changed, list validation performed, and call out regenerated artifacts like `dist/` or `build/`. Include screenshots for visible `public/` changes and mention affected providers when transform behavior changes. +## Releases + +Tags are per-component because the three components ship independently: `skill-v` (`.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json`), `cli-v` (`package.json`), `ext-v` (`extension/manifest.json`). Flow: bump the relevant manifest, add a changelog entry to `public/index.html` (skill = bare `vX.Y.Z`; CLI = `CLI vX.Y.Z`; extension = `Extension vX.Y.Z` — the prefix is how `scripts/release.mjs` finds the right block), commit, push, then `bun run release:` (or `--dry-run` first). The script refuses on a dirty tree, an unpushed HEAD, a missing changelog entry, or stale build outputs; skill and extension reruns of `bun run build` / `bun run build:extension` must produce zero diff. Skill releases attach `dist/universal.zip`; extension releases attach `dist/extension.zip`. CLI ships to npm via a separate `npm publish`, and the extension zip uploads to the Chrome Web Store manually — both reminded at the end of the script. Fix already-shipped notes with `gh release edit --notes-file `. + ## Contributor Notes Do not edit generated provider files directly unless you are intentionally patching generated output as part of a build-system change. Prefer fixing the root source in `source/`, `scripts/`, or `src/`, then regenerate artifacts. diff --git a/CLAUDE.md b/CLAUDE.md index ef1d63b10..2462bc3dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -174,6 +174,25 @@ There are three independently versioned components. Only bump the one(s) that ac - Update for user-facing changes only, not internal build/tooling details - Use the most prominent version that changed (skills version is usually the right one) +After bumping, see **Releases** below for how to tag and publish. + +## Releases + +GitHub releases are tagged per-component, not per-version, since the three components ship independently. Tag prefixes: `skill-v`, `cli-v`, `ext-v`. + +Workflow for any component: + +1. Bump the manifest version (see Versioning above). +2. Add a changelog entry to `public/index.html`. Skill entries use a bare `vX.Y.Z` label; CLI and extension entries use the prefixed forms `CLI vX.Y.Z` and `Extension vX.Y.Z`. The release script extracts notes by matching this label, so the prefix matters. +3. Commit and push to `main`. +4. Run `bun run release:`. Preview first with `node scripts/release.mjs --dry-run`. + +The script refuses to run if: the working tree is dirty, HEAD is ahead of origin, the tag already exists, the matching changelog entry is missing, or (for skill/extension) `bun run build` / `bun run build:extension` produces uncommitted changes — meaning the harness output dirs or `extension/detector/` files weren't refreshed before the bump was committed. + +Skill releases attach `dist/universal.zip`. Extension releases run `bun run build:extension` first and attach `dist/extension.zip`. CLI releases print a reminder to run `npm publish` separately; extension releases print a reminder to upload the zip to the Chrome Web Store dashboard. + +If you need to fix release notes after the fact (typo, missing thank-you, formatting bug): `gh release edit --notes-file `. The release script's `htmlToMarkdown` function is the cleanest source for regenerating notes from the changelog. + ## Adding New Commands All commands live under `/impeccable`. To add a new one: