Add cut-release skill for automated versioning and release workflow (#115)

* Add cut-release skill adapted for codex-trace

Copy the cut-release skill from delexw/claude-code-trace and adapt it to this
repo: PixelPaw-Labs/codex-trace identity and commit links, "Codex Trace"
artifact names, the single test-reflection pre-commit hook (no spec hook), and
the absence of a GitHub Actions release pipeline yet -- Phase 7 now publishes
the release manually from the CHANGELOG slice, and project-shape documents the
target release.yml shape for when one is added.

Docs only: thirteen markdown files under .claude/skills/cut-release/.

* Add release pipeline and CHANGELOG; restore skill pipeline flow

Add .github/workflows/release.yml (guard -> notes -> build macOS/Linux/Windows
via tauri-action -> publish) triggered on v* tags, mirroring the shape the
cut-release skill expects. Add an inaugural CHANGELOG.md (Keep a Changelog
format) with a 0.1.0 section the workflow's notes job slices for release bodies.

With the pipeline now in place, restore the cut-release skill's pipeline-driven
narrative: Phase 6 verifies the workflow run starts, Phase 7 watches it with
gh run watch and verifies the published release, and project-shape/SKILL no
longer carry the "no pipeline yet" caveat.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: delexw

.claude/skills/cut-release/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: cut-release
+description: |
+  Cuts a new versioned release of codex-trace end-to-end without asking
+  any questions. Detects commits since the last ancestral tag, classifies them
+  with conventional-commit rules to pick the semver bump, bumps every
+  version-bearing file in sync, writes the CHANGELOG entry, commits and tags
+  on a release branch, pushes the tag to trigger the GitHub Actions release
+  pipeline, fast-forwards `main` onto the release commit and pushes it, then
+  cleans up the local branch. Use this skill whenever the user mentions
+  cutting, tagging, bumping, or shipping a release — including "cut a
+  release", "release v1.2.3", "tag and release", "bump version", "publish a
+  release", "do a patch release", or "make a new release". Trigger even when
+  the user does not name the version — the skill computes it. Also use
+  proactively when the user finishes a unit of work and asks to publish it.
+---
+
+# Cut a Release — `codex-trace`
+
+Turns "we should release this" into a tagged, pushed, pipeline-triggered, **publicly
+published** release with a curated CHANGELOG, in a way that survives the project's strict
+pre-commit hook and stays honest about what's actually shipping.
+
+The skill is project-local because the steps depend on this repo's specific shape (three
+version files, two lockfiles, GH Actions release on `v*` tag, the test-reflection
+pre-commit hook).
+
+## Operating mode
+
+The skill is **fully automated end-to-end** and **fully synchronous**. It never calls
+`AskUserQuestion`, never waits for "yes", never branches on user preference, and
+**never runs any command in the background**. Every Bash invocation runs in the
+foreground so the session holds continuously from Phase 1 through Phase 9 — no
+`run_in_background: true`, no trailing `&`, no `nohup`, no `disown`. This includes
+long-running steps like `gh run watch` in Phase 7; set the Bash `timeout` parameter to
+match the expected duration (e.g. 1800000 ms for the release pipeline) rather than
+detaching.
+
+Defaults are deterministic:
+
+- **Scope** — always linear: every commit since `git describe --tags --abbrev=0` ships.
+- **Bump tier** — highest conventional-commit tier in the subset (see
+  `${CLAUDE_SKILL_DIR}/references/conventional-commits.md`). `BREAKING CHANGE:` or `!:`
+  produces a **minor** bump while the version is `0.X.Y` (pre-1.0 caveat) and a **major**
+  bump otherwise; the skill never silently promotes to 1.0.0.
+- **CHANGELOG** — every Added/Fixed bullet is written from commit subjects + diff reads;
+  `chore:` / `docs:` / `test:` / `ci:` are always skipped.
+- **Push order** — tag first, then main (so CI sees the tag immediately; main catches up
+  after).
+
+The skill aborts (loudly) only on hard preconditions that would corrupt the release:
+
+- **Duplicate version** — the proposed `vX.Y.Z` tag already exists on `origin`. Abort
+  with `Error: vX.Y.Z already exists on origin (commit <sha>). Refusing to release the
+same version twice.` The user must delete the remote tag intentionally if they want a
+  re-release, or bump again.
+- **Dirty working tree** — uncommitted changes the skill didn't create. Abort with a
+  list of dirty files.
+- **`npm run check` fails** — abort and surface the failure verbatim.
+
+## Before you start
+
+Read these references on the first invocation in a session — they describe constants the
+phase files refer to.
+
+- `${CLAUDE_SKILL_DIR}/references/project-shape.md` — version files, lockfiles, pre-commit
+  hooks, release pipeline wiring.
+- `${CLAUDE_SKILL_DIR}/references/conventional-commits.md` — how commit prefixes map to
+  semver bump level.
+
+`${CLAUDE_SKILL_DIR}/references/changelog-template.md` is loaded when you reach Phase 4.
+
+## Execution
+
+### Phase 1 — Inspect and decide
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase1-inspect-and-scope.md` and follow all instructions.
+
+### Phase 2 — Build the release branch
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase2-build-release-branch.md` and follow all instructions.
+
+### Phase 3 — Bump version files
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase3-bump-versions.md` and follow all instructions.
+
+### Phase 4 — Write the CHANGELOG entry
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase4-changelog.md` and follow all instructions.
+
+### Phase 5 — Verify, commit, tag
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase5-verify-commit-tag.md` and follow all instructions.
+
+### Phase 6 — Push the tag (with duplicate-version preflight)
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase6-push-tag.md` and follow all instructions.
+
+### Phase 7 — Watch the pipeline and verify the release is public
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase7-publish-github-release.md` and follow all
+instructions.
+
+### Phase 8 — Push the release commit to `main`
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase8-back-to-main.md` and follow all instructions.
+
+### Phase 9 — Clean up
+
+Read `${CLAUDE_SKILL_DIR}/steps/phase9-cleanup.md` and follow all instructions.
+
+## What the skill will NOT do automatically
+
+- Bypass pre-commit hooks with `--no-verify` — always fix the underlying issue.
+- Force-push (`git push -f`) to `main`, the release tag, or any shared branch.
+- Delete a remote tag or remote branch.
+- Cut a **major** bump (`X.0.0`) while the version is still `0.X.Y` — pre-1.0 the skill
+  caps at minor even when a breaking change is detected.
+- Re-tag an existing version — the duplicate-version preflight in Phase 6 aborts first.
+
+The harness's auto-mode classifier may still intercept pushes to shared branches (e.g.
+`git push origin main`) — that is out of skill scope. When it does, surface the error
+and continue with the remaining phases; the user resolves the push themselves.

.claude/skills/cut-release/references/changelog-template.md

@@ -0,0 +1,93 @@
+# CHANGELOG Template
+
+The repo uses [Keep a Changelog](https://keepachangelog.com/) conventions.
+
+## First-time setup
+
+If `CHANGELOG.md` doesn't yet exist, create it with this header:
+
+```markdown
+# Changelog
+
+All notable changes to codex-trace are documented here. Versions follow
+[semantic versioning](https://semver.org/).
+```
+
+Then append the per-release section below.
+
+## Per-release section template
+
+```markdown
+## [X.Y.Z] — YYYY-MM-DD
+
+One paragraph framing what this release is fundamentally about. Speak to a user, not a
+maintainer — explain visible impact, not implementation.
+
+### Added
+
+- **Headline name** ([`<sha7>`](https://github.com/PixelPaw-Labs/codex-trace/commit/<sha>)).
+  Two or three sentences. Why it exists, what the user sees, any caveat. End with a
+  pointer to verification or docs if useful.
+
+### Fixed
+
+- **Headline name** ([`<sha7>`](https://github.com/PixelPaw-Labs/codex-trace/commit/<sha>)).
+  What was broken, when it surfaced, how it surfaces now. Avoid jargon-only entries like
+  "fix race condition" — say which user-visible behavior was wrong and is now right.
+
+### Changed
+
+- Internal refactors with no behavior change usually don't belong here. Only mention if
+  the user has to update their own integration (e.g. config file rename).
+
+### Removed
+
+- Anything a user could notice as gone (CLI flag, config key, exported function from a
+  consumed package).
+
+[X.Y.Z]: https://github.com/PixelPaw-Labs/codex-trace/releases/tag/vX.Y.Z
+```
+
+## Bucket rules
+
+- **Added** for `feat:` commits.
+- **Fixed** for `fix:` / `perf:` commits.
+- **Changed** for `refactor:` / config / build adjustments that the user must notice.
+- **Removed** for deletions of public surface.
+- **Breaking Changes** (new bucket, comes first, before Added) for major releases. Lead
+  with what broke and how the user migrates.
+
+Always skip `chore:` / `docs:` / `test:` / `ci:` — they clutter the CHANGELOG without
+informing users. The skill is non-interactive; never include these even if the count
+looks short.
+
+## Linking
+
+Each bullet **must** link to its commit so readers can dig in:
+
+```
+([`ebb2ca5`](https://github.com/PixelPaw-Labs/codex-trace/commit/ebb2ca5))
+```
+
+7-character SHAs are enough — git accepts the abbreviation.
+
+The reference-link at the bottom (`[X.Y.Z]: https://...releases/tag/...`) is what GitHub
+uses to make the version header a clickable link in rendered markdown. Keep it.
+
+## Style
+
+Write substantive bullets. Read the diff if the subject is terse — "fix off-by-one" is
+useless to a user, "the picker no longer skips the first session card after a refresh"
+is what they care about. Lean on the "what was broken / what is now right" frame for
+Fixed, "what's new and why" for Added.
+
+## After writing
+
+Always format:
+
+```bash
+npx oxfmt CHANGELOG.md
+```
+
+oxfmt enforces consistent table / code-fence formatting that survives the project's
+`fmt:check` gate.

.claude/skills/cut-release/references/conventional-commits.md

@@ -0,0 +1,39 @@
+# Conventional Commit → Semver Bump
+
+The bump level for a release is the highest tier among the commits in the release
+subset. One `feat:` upgrades the whole release to minor.
+
+| Prefix or marker in commit subject / body        | Bump tier                      | Notes                                                                                |
+| ------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------ |
+| `feat:` or `feat(scope):`                        | **minor**                      | new user-facing feature                                                              |
+| `fix:` `fix(scope):`                             | **patch**                      | bug fix                                                                              |
+| `perf:` `perf(scope):`                           | **patch**                      | observable performance improvement                                                   |
+| `refactor:` `refactor(scope):`                   | **patch**                      | internal restructure with no behavior change                                         |
+| `chore:` `docs:` `test:` `ci:` `build:` `style:` | **patch** (or "no release")    | usually skip in CHANGELOG; if the whole release is only these, still call it a patch |
+| `!` after type — e.g. `feat!:`, `fix!:`          | **major** (capped — see below) | breaking change in API or schema                                                     |
+| `BREAKING CHANGE:` footer (anywhere)             | **major** (capped — see below) | breaking change in API or schema                                                     |
+| Anything else / no convention                    | **patch**                      | default conservatively — most non-conventional commits are docs/chore-shaped         |
+
+## Algorithm (fully automated)
+
+1. List commits: `git log $LAST_TAG..HEAD --pretty=format:'%H %s%n%b' --no-merges`
+2. Classify each by the table above; pick the highest tier.
+3. Apply the pre-1.0 cap (next section).
+4. Compute the next version:
+   - **major**: `X+1.0.0` (e.g. `1.2.3` → `2.0.0`)
+   - **minor**: `X.Y+1.0` (e.g. `0.5.1` → `0.6.0`)
+   - **patch**: `X.Y.Z+1` (e.g. `0.5.0` → `0.5.1`)
+5. State the chosen bump inline (not as a question) and proceed.
+
+## Pre-1.0 cap (currently active — version is `0.X.Y`)
+
+While the major version is still `0`, the skill **caps the bump at minor** even when a
+`BREAKING CHANGE:` footer or `!:` marker is present. Rationale: `0.X.Y` semver does not
+imply API stability, so breaking changes are expected; promoting to `1.0.0` is a
+deliberate product decision, not an automated one.
+
+The cap is automatic — the skill never promotes to `1.0.0` without the user explicitly
+typing "release as 1.0.0" or similar in the same turn. If the user did, honor it.
+
+Remove this cap (in code review of this file, not at runtime) once the project
+intentionally crosses `1.0.0`.

.claude/skills/cut-release/references/project-shape.md

@@ -0,0 +1,81 @@
+# Project Shape — `codex-trace`
+
+The skill-specific facts the phase files rely on. For everything that's already in the
+codebase, this file points at the source of truth rather than repeating it.
+
+## Read these first if you don't know the codebase
+
+- `AGENTS.md` (with `CLAUDE.md` symlinked to it) — toolchain commands (`npm run check`,
+  `oxfmt`, `oxlint`, etc.) and the "format + lint + test before committing" rule.
+- `.claude/hooks/pre-commit.sh` — header comments describe exactly what the hook checks
+  (format, lint, tsc, Rust fmt/clippy) and how the per-session test-reflection flag
+  bypass works.
+- `.claude/settings.json` — the `Bash(*git commit*)` matcher that wires the hook into
+  `git commit` calls.
+
+## Version-bearing files (skill-specific rule)
+
+Three files must agree on the next-version string. Nothing in the codebase enforces this
+sync — the skill does.
+
+| File                        | Owns                                 | Bumps with                     |
+| --------------------------- | ------------------------------------ | ------------------------------ |
+| `package.json` (root)       | Node/TS workspace + binary entry     | the Rust crate (lockstep)      |
+| `src-tauri/Cargo.toml`      | Rust crate version                   | root `package.json` (lockstep) |
+| `src-tauri/tauri.conf.json` | Tauri bundle filenames + app version | the Rust crate (lockstep)      |
+
+Root + Cargo + `tauri.conf.json` move together because the desktop binary the user installs
+is built from all three — `tauri.conf.json`'s `version` field is what `tauri-action`
+templates into the released artifact filenames (`Codex.Trace_<version>_*.dmg`, etc., from
+the `productName` "Codex Trace"). Missing this file silently ships a release whose
+artifacts are stamped with the previous version.
+
+There is currently no separate sub-package (TUI or otherwise) with its own version
+manifest. If a versioned manifest is ever introduced (e.g. a `pyproject.toml` or a nested
+`package.json`), add it to the lockstep set and update the skill's Phase 3 step.
+
+## Lockfile regen after a version bump
+
+The lockfiles embed the local workspace's version, so they have to be regenerated after
+editing version files — `npm run check` won't fix this on its own. Run:
+
+```bash
+npm install --package-lock-only           # → package-lock.json
+( cd src-tauri && cargo check --offline ) # → src-tauri/Cargo.lock
+```
+
+`--package-lock-only` skips the full reinstall (nothing in `node_modules` needs to
+change) and `--offline` skips the registry round-trip — only the local crate's version
+moved.
+
+## Release pipeline (delegated to CI)
+
+`.github/workflows/release.yml` is the source of truth. Its job graph for `v*` tag
+pushes:
+
+1. `guard` — refuses to run if a non-draft GitHub release for the tag already exists.
+   This is the duplicate-release defence-in-depth complement to the skill's Phase 1
+   preflight; if a stale tag was pushed, the CI aborts before any artifact upload.
+2. `notes` — slices `CHANGELOG.md` for the version's section and exposes it as a
+   workflow output. Fails if the heading isn't in the exact `## [X.Y.Z] — YYYY-MM-DD`
+   format.
+3. `build-macos` / `build-linux` / `build-windows` — three parallel `tauri-action` runs
+   each creating / updating a draft release with platform artifacts.
+4. `publish` — flips the draft to public and marks it latest.
+
+`workflow_dispatch` mode is a dry-run for the notes job only; nothing is built or
+published. Use it to verify a CHANGELOG section parses correctly before tagging.
+
+If the pipeline changes, edit the workflow and update Phase 7's narrative, not this
+file.
+
+## GitHub repo identity
+
+Read once with `git remote get-url origin`; the URL template for commits and releases
+follows from there:
+
+- Commit: `<repo-url>/commit/<sha>`
+- Release: `<repo-url>/releases/tag/v<X.Y.Z>`
+
+The CHANGELOG template (`changelog-template.md`) hardcodes `PixelPaw-Labs/codex-trace`
+in the link format. If the repo moves, update that file once.