release-notes

Release Notes Skill

Use this skill when the user wants to create release notes for a new version. This skill gathers all changes since a previous release, writes structured release notes following the project's established format, tags the repo, and pushes.

Input

The skill takes a version tag as input:

• Format: {major}.{minor}.{patch} (e.g., 1.24.0) - no v prefix, semver only
• Older releases (pre-1.23.0) used a v prefix (e.g., v1.0.22) - existing artifacts under docs/release-notes/v*.md and tags v1.0.x are preserved as-is, but new releases must use the bare-semver convention
• If the user provides a v-prefixed version for a new release, strip the prefix and confirm

Output

Creates a release notes file in docs/release-notes/ and tags the repo:

• docs/release-notes/{version}.md - Release notes markdown file (e.g., docs/release-notes/1.24.0.md)
• Git tag {version} pointing to the commit that includes the release notes

Workflow

Step 0: Confirm the Pre-Release Smoke Test Was Run (Gate)

Before doing any release-notes work, confirm the end-to-end release smoke test (tests/e2e_release_test.py) has been run against a live gateway and passed. This suite exercises the surface a release must not break: the registry is up, the built-in airegistry-tools server is healthy and its search tool works, servers/agents/skills support full CRUD, semantic search returns results, security scans run, and one real external MCP server (AWS knowledge base) is reachable end to end through the gateway proxy.

1. Ask the user, using AskUserQuestion, whether they have already run the release smoke test and it passed. Offer these options:

   • "Yes, it passed" (proceed to Step 1)
   • "No, run it now" (Recommended - run it for them, see below)
   • "Skip it" (proceed, but see the warning below)

2. If the user asks you to run it, run against the target gateway. It needs an admin/M2M bearer token file (Keycloak tokens expire in ~5 minutes, so regenerate first if unsure):

   # Local gateway with an admin token at ./.token
   uv run python tests/e2e_release_test.py --token-file .token --registry-url http://localhost
   
   # Remote gateway
   uv run python tests/e2e_release_test.py \
     --registry-url https://<gateway-host> --token-file .oauth-tokens/ingress.json
   

   The runner prints a pass/fail table and exits non-zero if any test fails.

   • If it exits non-zero (any FAILED), STOP. Do not proceed with the release. Report which tests failed and their messages, and help the user investigate. A release must not be cut with a failing smoke test.
   • SKIPPED is acceptable (e.g. the external AWS test skips on a network outage rather than failing) - only FAILED is a hard block.