Release Kilroy

Releasing Kilroy

When to Use

Invoke this skill before cutting a release. Never release without explicit user request.

Sanity Check

Before anything: if something seems off (discontinuous version jump like 0.5→2.0, failing tests, broken code), stop and confirm with the user.

Writing Release Notes

Release notes are user-facing, not code-facing. Write from the perspective of someone running Kilroy pipelines, not someone reading the git log.

Structure

Two sections, in this order:

"New things you can do" — Features that let users do something they couldn't before. Each item: what it is + why you'd care. Priority-ordered (most impactful first).

"Things that got better" — Improvements to existing functionality. Same format: what changed + why it matters. Priority-ordered.

Principles

• Feature, benefit. Not "add fan-out parallel handler to engine" but "Run pipeline stages in parallel — fan-out nodes execute concurrently and fan-in collects results."
• User verbs, not code verbs. Not "refactor edge selection to use cond evaluator" but "Conditional routing is more reliable — edge conditions are evaluated consistently."
• Skip internal-only changes. Test refactors, doc updates, reverts-then-re-lands — users don't care.
• Priority order within each section. The things that are most exciting, the things that change daily usage most, then the rest.
• Deep-dive the changelog in preparation. Read every commit since the last tag. Skim the files affected so you can tell if there may be changes beyond the commit note, and if so, read the diffs and source code. Group by user-visible impact. Many commits collapse into one release note line. Some commits (chore, test, docs) produce no release note at all.
• Read the code, not just the commit messages. Commit messages are often terse or misleading. When a commit touches engine behavior, CLI flags, provider support, or graph semantics, read the actual diff to understand what changed from the user's perspective.

Deriving Release Notes

# 1. Get the full commit list
git log v<PREV>..HEAD --oneline --no-merges

# 2. Get the diffstat for scope
git diff v<PREV>..HEAD --stat | tail -5

# 3. For commits that touch user-facing code, read the diffs
git show <hash> --stat   # what files changed?
git show <hash>          # read the diff if unclear from commit message

# 4. Walk through commits and ask: "What can the user now DO differently?"

For the first release (no previous tag), derive notes from the full project history or a user-specified starting commit.

Example

## What's New

### New things you can do

- **Run pipeline stages in parallel** — Fan-out nodes execute concurrently with
  deterministic fan-in collection. Halves wall-clock time for independent stages.
- **Resume from CXDB** — Interrupted runs can resume from the execution database,
  not just local logs. Works across machines.

### Things that got better

- **Conditional routing is more reliable** — Edge conditions evaluate consistently
  even when upstream stages produce unexpected output shapes.
- **Stale binary detection** — Kilroy warns before running if the binary doesn't
  match HEAD, preventing silent behavior mismatches.

Version Number

Kilroy uses semver. The canonical version lives in internal/version/version.go as var Version = "X.Y.Z". This is the version all builds see — source, binary, and Homebrew. goreleaser also injects it from the git tag at build time via ldflags (belt and suspenders).

Bump this file as part of release prep (step 5). The CI workflow verifies that version.go matches the git tag — a mismatch fails the release.

Decide the bump with the user, but offer a recommendation:

• Patch (0.x.Y): Bug fixes, minor improvements
• Minor (0.X.0): New capabilities, new providers, meaningful new features
• Major (X.0.0): Breaking changes to CLI flags, config format, or graph semantics

Update the README

This is the last step before mechanical release, and requires user approval.

Review README.md against the current state of the product. Read the relevant source code to verify claims — don't trust the README or your memory alone.

For each section:

• Is it still accurate? Read the implementing code if unsure. Update or remove if something changed or was removed.
• Is there a new capability from this release that belongs in the README? Propose adding it.
• Are any sections stale enough to warrant cleanup? Recommend changes to keep it tight.

Present the proposed README changes to the user for approval before proceeding to release steps.