Context
The skill-distribution work (product/specs/skill-distribution-spec.md) leans
heavily on the release pipeline — it extends the existing GoReleaser release to
attach .skill artifacts, and the skills' shared bootstrap fetches the CLI
archive from the latest GitHub Release. Working through that spec surfaced that
we have a release pipeline but no documentation of how releases work, which
makes the release process hard to reason about and easy to get wrong.
What exists today (undocumented)
.github/workflows/release.yml — fires on v* tags, permissions: contents: write, runs GoReleaser..goreleaser.yml — builds the cross-platform matrix
(linux/darwin/windows × amd64/arm64), publishes archives named
katalyst_<version>_<os>_<arch>.tar.gz (.zip on Windows) plus
checksums.txt, with prerelease: auto.cmd.Version is stamped via ldflags at build time.
.github/workflows/AGENTS.md mentions release.yml in one line but does not
explain the process, conventions, or failure modes.
What to document
A page (likely under docs/content/contributing/, e.g. how-we-release.md, or
a release section in the workflows AGENTS.md) covering:
- How to cut a release — the exact steps (tag naming/
v*, git tag +
push), who can do it, and what gets published.
- Versioning convention — semver expectations, how
prerelease: auto
treats pre-release tags, how cmd.Version is set.
- What the release produces — the asset names and shapes (so anything that
fetches them, like the skills bootstrap, has a documented contract to target).
- Failure modes — e.g.
GITHUB_TOKEN capped to read-only at the org/repo
level 403s the upload (fix is the repo-admin Workflow-permissions toggle);
how to dry-run.
- Relationship to CI — the
test/docs jobs in ci.yml are a separate
build/lint gate and publish nothing.
Why separate from skill-distribution
The skill-distribution spec consumes the release contract but shouldn't own
documenting it. This is general project infrastructure that stands on its own,
and the asset-name contract is something the bootstrap depends on regardless of
whether skills ship.
🤖 Generated with Claude Code
Context
The skill-distribution work (
product/specs/skill-distribution-spec.md) leansheavily on the release pipeline — it extends the existing GoReleaser release to
attach
.skillartifacts, and the skills' shared bootstrap fetches the CLIarchive from the latest GitHub Release. Working through that spec surfaced that
we have a release pipeline but no documentation of how releases work, which
makes the release process hard to reason about and easy to get wrong.
What exists today (undocumented)
.github/workflows/release.yml— fires onv*tags,permissions: contents: write, runs GoReleaser..goreleaser.yml— builds the cross-platform matrix(linux/darwin/windows × amd64/arm64), publishes archives named
katalyst_<version>_<os>_<arch>.tar.gz(.zipon Windows) pluschecksums.txt, withprerelease: auto.cmd.Versionis stamped via ldflags at build time..github/workflows/AGENTS.mdmentionsrelease.ymlin one line but does notexplain the process, conventions, or failure modes.
What to document
A page (likely under
docs/content/contributing/, e.g.how-we-release.md, ora release section in the workflows
AGENTS.md) covering:v*,git tag+push), who can do it, and what gets published.
prerelease: autotreats pre-release tags, how
cmd.Versionis set.fetches them, like the skills bootstrap, has a documented contract to target).
GITHUB_TOKENcapped to read-only at the org/repolevel 403s the upload (fix is the repo-admin Workflow-permissions toggle);
how to dry-run.
test/docsjobs inci.ymlare a separatebuild/lint gate and publish nothing.
Why separate from skill-distribution
The skill-distribution spec consumes the release contract but shouldn't own
documenting it. This is general project infrastructure that stands on its own,
and the asset-name contract is something the bootstrap depends on regardless of
whether skills ship.
🤖 Generated with Claude Code