// Use when preparing a Kilroy release — writing release notes, tagging, and publishing via goreleaser on GitHub.
| name | release-kilroy |
| description | Use when preparing a Kilroy release — writing release notes, tagging, and publishing via goreleaser on GitHub. |
Invoke this skill before cutting a release. Never release without explicit user request.
Before anything: if something seems off (discontinuous version jump like 0.5→2.0, failing tests, broken code), stop and confirm with the user.
Release notes are user-facing, not code-facing. Write from the perspective of someone running Kilroy pipelines, not someone reading the git log.
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.
# 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.
## 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.
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:
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:
Present the proposed README changes to the user for approval before proceeding to release steps.
All work happens on a release branch in a worktree — main is untouched until the final atomic fast-forward.
# From the main repo
git fetch origin
git checkout main
git pull --ff-only origin main
git worktree add .worktrees/release-vX.Y.Z -b release/vX.Y.Z main
cd .worktrees/release-vX.Y.Z
go mod download
# In the worktree
go test ./...
All tests must pass. If any fail, fix them on the release branch before proceeding.
# Build from the release branch
go build -o ./kilroy ./cmd/kilroy
# Validate all demo pipelines still parse and pass validation
shopt -s globstar
for f in demo/**/*.dot; do
./kilroy attractor validate --graph "$f" || exit 1
done
scripts/e2e.sh
scripts/check-ergonomics-docs.sh
scripts/check-using-kilroy-skill.sh
All of these are committed to the release branch:
internal/version/version.go to the new versionRELEASE_NOTES.md in the repo root (following the guidelines above). The GitHub Actions workflow passes --release-notes=RELEASE_NOTES.md to goreleaser, which publishes it as the GitHub release body. This file is committed (not gitignored) so it is present at the tagged commit.release: vX.Y.Z# Back in the main repo working directory
git merge --ff-only release/vX.Y.Z
If --ff-only fails, go back to the worktree and rebase onto main until it can fast-forward.
git push origin main
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
# GoReleaser takes over from here via GitHub Actions:
# - Runs go test ./...
# - Builds cross-platform binaries (linux/darwin/windows x amd64/arm64)
# - Creates GitHub release with archives and checksums
# - Updates Homebrew formula in Formula/kilroy.rb
brew tap danshapiro/kilroy
brew install kilroy
kilroy --version # should print the new version
git worktree remove .worktrees/release-vX.Y.Z
git branch -d release/vX.Y.Z
go test ./... passes before mergingOperate Kilroy Attractor pipelines end-to-end: ingest English requirements into DOT graphs, validate graph semantics, run and resume pipelines with run config files, configure provider backends (cli/api), and debug runs from logs_root artifacts and checkpoints.
Use when authoring or repairing Kilroy Attractor DOT graphs from requirements, with template-first topology, routing guardrails, and validator-clean output.
Use when bootstrapping a new project repository for Kilroy Attractor from a clean directory using existing spec, DoD, graph, and run config artifacts.
To diagnose active, stuck, or failed Kilroy Attractor runs, inspect run artifacts (`manifest.json`, `live.json`, `checkpoint.json`, `final.json`, `progress.ndjson`), resolve run IDs/log roots, identify model/provider routing, and isolate failure causes. Includes CXDB operations for launching/probing CXDB, opening the CXDB UI, and querying run context turns. This skill is useful when investigating run status, debugging retries/failures, explaining model usage, or inspecting CXDB-backed event history.
Use when converting a spec, requirements document, or goal statement into a Definition of Done with acceptance criteria and integration test scenarios
Use when authoring or repairing Kilroy run config YAML/JSON files, including DOT-to-provider backend alignment and runtime policy defaults.