create-vortex-tooling-release-notes

name	create-vortex-tooling-release-notes
description	Use when preparing release notes for the 'drevops/vortex-tooling' Composer package, published as a read-only mirror of '.vortex/tooling/' from the Vortex monorepo. Builds a tooling-only changelog from the previous release tag (or a commit) up to the current state, enriches each entry from its monorepo pull request and issue, and writes consumer-facing notes. Releases are manually gated and rarely align with Vortex releases, so the range is driven by the previous tooling tag, not by a Vortex tag. Triggers on phrases like 'tooling release notes', 'vortex-tooling release notes', 'release notes for vortex-tooling'.
user-invocable	true

Create Vortex Tooling Release Notes

Generate consumer-facing release notes for the drevops/vortex-tooling Composer package.

drevops/vortex-tooling is a read-only mirror of the .vortex/tooling/ directory in the drevops/vortex monorepo. A publishing workflow copies that directory to the mirror repository on every push to main, so the mirror's git history is mostly noise: it contains one commit per monorepo commit, including empty commits for monorepo commits that did not touch the tooling at all. Tooling releases are manually gated and almost never align with Vortex template releases, so "what changed since the last tooling release" cannot be read off a Vortex tag. This skill reconstructs that set reliably from the monorepo and turns it into release notes.

When to use

• A new drevops/vortex-tooling release is about to be cut and needs notes.
• An existing tooling release has empty or missing notes that need backfilling.
• You want to see what tooling changes have accumulated since the last release.

Run it from inside a drevops/vortex monorepo clone with git and the GitHub CLI (gh) available and authenticated. It produces notes only; it does not tag, publish, or otherwise modify the drevops/vortex-tooling repository.

How the reconciliation works

Every commit published to drevops/vortex-tooling records its origin in the commit body as Source: drevops/vortex@<SHA>. Each release tag therefore points back to an exact monorepo commit. That is the anchor: given the previous tooling release tag, resolve it to its source SHA, then list the monorepo commits from that SHA to now that actually changed shipped tooling files.

Only part of .vortex/tooling/ ships to consumers. tests/, playground/, and the dotfiles are export-ignored from the Composer archive; src/, composer.json, README.md, and LICENSE are what consumers receive. Filtering the log to the shipped paths is what removes both the empty mirror commits and every unrelated monorepo commit in one step.

Inputs

The skill takes a lower bound and an optional upper bound that define the range. Each bound is a tooling release tag or a monorepo commit SHA.

Bound	Default	Meaning
Lower (FROM)	latest published drevops/vortex-tooling release tag	Start of the range - the previous release.
Upper (TO)	current HEAD	End of the range - the release being prepared.

Two common shapes:

• Next release (the usual case): give only the lower bound, or nothing. The range is "previous tag to HEAD" and you choose the new version in Step 4.
• Backfill an already-published release: give both bounds as tags, for example 1.1.0 and 1.2.0. The range is "1.1.0 to 1.2.0", and the new version is simply the upper tag - nothing to choose.

Process

Step 1: Resolve the range bounds to monorepo source SHAs

Resolve the lower bound to FROM_SHA and the upper bound to TO_SHA. The rule is the same for each bound:

• A tag (including the latest release tag when no lower bound was given - find it with gh release list -R drevops/vortex-tooling --limit 1): read its source SHA from the mirror commit body.

  gh api repos/drevops/vortex-tooling/commits/1.2.0 --jq '.commit.message'
  

  Parse the Source: drevops/vortex@<SHA> line from the output; that <SHA> is the bound.

• A commit SHA: use it directly.

• No upper bound given: TO_SHA is HEAD.

Confirm each resolved SHA exists locally:

git cat-file -t <SHA>

If git cat-file fails, the local clone is behind; run git fetch origin and retry, and stop with a clear message if it still cannot be found.

Step 2: Build the tooling-only changelog

List the monorepo commits between FROM_SHA and TO_SHA that changed a shipped tooling file, newest first:

git log <FROM_SHA>..<TO_SHA> --no-merges --pretty=format:'%H%x09%s' -- .vortex/tooling/ ':(exclude).vortex/tooling/tests' ':(exclude).vortex/tooling/playground' ':(exclude).vortex/tooling/.gitattributes' ':(exclude).vortex/tooling/.gitignore'

The path filter is the heart of the skill: it keeps only commits that touched files consumers actually receive, automatically discarding the empty mirror commits and every non-tooling monorepo commit.

If the command returns nothing, there is nothing to release. Tell the user "No tooling changes shipped since <lower-bound>; no release needed" and stop. Do not write an empty notes file.

Each output line is a commit: a full SHA, a tab, then the subject. The subject already carries the entry shape these notes use - an optional [#ISSUE] prefix and a trailing (#PR) reference, for example:

f8e1361b…	[#2643] Hardened the host-side database-download tooling scripts. (#2648)

Step 3: Enrich each entry from its pull request

For each commit, you need enough context to write an accurate paragraph. The pull requests and issues live in drevops/vortex, never in drevops/vortex-tooling (the mirror has none). Follow this order and stop as soon as you have enough:

1. Use the subject if it is already specific enough. Skip the fetch entirely in that case.

2. Fetch the pull request named by the trailing (#NNN):

   gh pr view 2648 --repo drevops/vortex --json title,body,labels,author
   

   Use author.login for the @author attribution.

3. Fetch the linked issue named by a [#NNN] prefix when the pull request body is still ambiguous:

   gh issue view 2643 --repo drevops/vortex --json title,body
   

4. Inspect the change itself only when the descriptions are uninformative. The actual diff is in the monorepo, so read it locally rather than over the API:

   git show <SHA> -- .vortex/tooling/src
   

   Read only enough to understand intent. New or renamed VORTEX_* environment variables, changed defaults, and added or removed scripts are the signals that matter most.

Batch independent gh calls in parallel - issue several Bash tool calls in a single message, targeting 8-10 at a time, so a release with many entries resolves in a few waves rather than one call at a time. Pull request bodies often contain auto-generated review-bot sections; skim past them and rely on the human-written summary.

If gh is unavailable or auth fails, fall back to writing conservative paragraphs from the commit subjects alone, and tell the user which entries lack deep context so they can review them.

Step 4: Determine the version

PREVIOUS_VERSION is the lower-bound tag (or the latest release tag when a bare commit was given).

• Backfill (the upper bound is an existing tag): NEW_VERSION is that upper tag - nothing to choose.

• Next release (the upper bound is HEAD or a bare commit): suggest NEW_VERSION from the nature of the changes, then confirm it with the user before writing. The version only labels the notes; no tag is created.

• Major (e.g. 2.0.0): a shipped script was removed or renamed; an environment variable consumers set was removed or renamed; a default behaviour changed in a way that breaks existing usage; the PHP requirement in composer.json was raised in a breaking way.

• Minor (e.g. 1.3.0): a new script or a new opt-in capability, flag, or environment variable was added; new behaviour that existing projects are unaffected by.

• Patch (e.g. 1.2.1): a bug fix, a hardening or robustness change, an internal refactor with no contract change, or documentation fixes.

Step 5: Write and display the notes

Write the file to .artifacts/release-notes-tooling-<NEW_VERSION>.md (for example release-notes-tooling-1.2.1.md) using the structure and rules below, then display its full contents to the user in a fenced markdown code block for review.

Output structure

## What's new since PREVIOUS_VERSION

### Breaking changes

- **[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph: what used to work, the new behaviour, and the exact migration step consumers must take.

### Highlights

- **[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph: why this matters to someone running the scripts - the capability it unlocks or the pain it removes.

### All changes

- **[#NNN](https://github.com/drevops/vortex/issues/NNN) Original subject. @author (https://github.com/drevops/vortex/pull/NNN)**<br>Paragraph (1-3 sentences) explaining what the change does and why it is valuable.

**Full Changelog**: https://github.com/drevops/vortex-tooling/compare/PREVIOUS_VERSION...NEW_VERSION

Formatting rules

Sections

• Breaking changes: include only if at least one entry is breaking; omit the heading entirely otherwise. An entry is breaking when consumers upgrading may have to change their own setup, or when observable behaviour changes automatically on upgrade. The tooling's public surface is the script contract: script names under src/, the environment variables they read, their arguments, their observable side effects, and the composer.json platform requirement. An opt-out flag makes a breaking change recoverable, not non-breaking - still list it and explain the escape hatch in the migration step.
• Highlights: pick the 5-7 most consumer-relevant entries, favouring new scripts and new capabilities over internal hardening, refactors, and doc fixes. Omit the heading if the release is too small to have meaningful highlights. Every highlight must also appear under All changes - it is a curated view, not a separate set.
• All changes: list every entry from Step 2, newest first, preserving the commit subject text verbatim. Do not reword, reorder, merge, or drop entries.

Entries

• No hand-wrapping. Every bullet, including its paragraph, is a single line in the file regardless of length. GitHub renders the markdown - let the browser wrap. (This is the opposite of how this SKILL file itself is written; the deliverable is renderer-bound, the skill is source.) Tables and code fences keep their structure.
• Format exactly: wrap the original subject in **...**, immediately follow it with <br>, then the paragraph on the same line - no blank line between them, no indentation.
• Render every issue and pull-request reference as a full drevops/vortex URL, never a bare #NNN - the notes are published to the drevops/vortex-tooling mirror, where a bare #NNN mis-links to that repository's own numbering. Transform the commit subject so the leading [#NNN] issue reference becomes the markdown link [#NNN](https://github.com/drevops/vortex/issues/NNN), and the trailing (#NNN) pull-request reference becomes the bare URL (https://github.com/drevops/vortex/pull/NNN). When a commit has no [#NNN] issue prefix, start with the subject text; when it has no (#NNN) pull-request reference (a direct push), omit the trailing reference and enrich from the commit and its diff. Keep the @author handle (a global GitHub mention resolves correctly anywhere) and the subject's punctuation and capitalisation.
• Paragraphs are 1-3 sentences of plain prose. For fixes: name what was broken, the user-visible symptom, and the corrected behaviour. For features: name what you can now do that you could not before, and the environment variable or flag that controls it with its default. Never invent details the source does not support.
• Entries authored by dependency bots (@renovate[bot], @dependabot[bot]) or whose subject begins with Update dependency, Update all dependencies, or Bump stay as bare list items with no bold and no paragraph. These are rare here, since the package only requires PHP.
• Do not insert blank lines between consecutive list items.

Footer

The **Full Changelog** line points at the mirror repository, drevops/vortex-tooling, using PREVIOUS_VERSION...NEW_VERSION. The link resolves once the NEW_VERSION tag is later created on that repository.

Validation checklist

Before displaying the output, verify:

• File saved to .artifacts/release-notes-tooling-<NEW_VERSION>.md.
• First line is ## What's new since <PREVIOUS_VERSION>.
• ### Breaking changes appears only if there is at least one breaking entry.
• ### All changes lists every commit from Step 2, verbatim, newest first.
• Every non-bot entry is **subject**<br>paragraph on a single line, no blank line, no indentation.
• Every reference is a full https://github.com/drevops/vortex/... URL - the leading issue as [#NNN](.../issues/NNN), the trailing pull request as (.../pull/NNN). No bare #NNN remains.
• Pull request and issue lookups used --repo drevops/vortex.
• The **Full Changelog** URL targets drevops/vortex-tooling.
• No invented details beyond the commit subject, linked issue, pull request body, or diff.

Command rules - CRITICAL

Every Bash tool call must contain exactly ONE simple command. No &&, ||, ;, |, command substitution $(...), herestrings, or heredocs. When you need several commands, make several separate Bash calls. This applies to every git and gh invocation above.