openkata-ryu-release
Release a distributable artifact following Semantic
Versioning. The git tag is the single source of truth
for the current published version.
Trigger
Activate when the user says "release", "bump", "version",
"tag", or "publish" an artifact.
Determine Current Version
git tag -l '<type>/<name>/v*' | sort -V | tail -1
NEVER read the version from CHANGELOG.md or SKILL.md to
determine the current version. Those files may be ahead
of (or behind) the actual tagged release.
Determine Next Version
Follow Semantic Versioning:
- PATCH (x.y.Z): documentation additions, typo fixes,
non-functional changes (added RATIONALE.md, reformatted
ACKNOWLEDGMENTS.md, fixed examples)
- MINOR (x.Y.0): new features, new steps, new
references, behavioral changes that don't break
existing usage
- MAJOR (X.0.0): breaking changes to the skill's
interface (renamed triggers, removed steps, changed
output format that downstream consumers rely on)
When in doubt, ask the user.
Release Steps
Confirm the artifact has uncommitted changes vs its
latest tag:
git diff <latest-tag>..HEAD -- <type>/<name>/
If no diff, abort — nothing to release.
Run the badge update script to sync counts:
./scripts/update-readme-badges.sh
If README.md changed, stage it for the release commit.
Update CHANGELOG.md — add a version section after
[Unreleased] with today's date and what changed.
Bump version in the frontmatter of the main doc
(SKILL.md, RULE.md, or <name>.md).
Commit:
release(<type>): <name> vX.Y.Z
Assisted-by: <agent>:<model>
Tag:
git tag <type>/<name>/vX.Y.Z
Push (only with user confirmation):
git push origin main
git push origin <type>/<name>/vX.Y.Z
Ask the user: "Release to tessl registry as well? (y/n)"
If yes:
cd <type>/<name> && tessl tile publish --bump patch
If the tile doesn't exist yet, run tessl skill import
first, then tessl tile publish.
Validation
- Tag version must match SKILL.md frontmatter version
- Tag version must match latest CHANGELOG.md section
- Tag must point to the release commit (not an
earlier commit)
- CHANGELOG entry must not be empty
Renaming an Artifact
Renaming starts versioning from v1.0.0 under the new name.
Old git tags are preserved — old S3 artifacts are deleted.
Rename the directory:
git mv <type>/<old-name> <type>/<new-name>
Update frontmatter name: field.
Reset CHANGELOG.md to a fresh v1.0.0 entry. Mention
the old name:
## [1.0.0] - YYYY-MM-DD
### Changed
- Renamed from <old-name>
Commit, tag, push:
git commit -m 'refactor(<type>): rename <old-name> to <new-name>'
git tag <type>/<new-name>/v1.0.0
Publish new name, delete old S3 prefix:
gh workflow run publish.yaml -f tag=<type>/<new-name>/v1.0.0
aws s3 rm s3://openkata-artifacts/<type>/<old-name>/ --recursive
Add redirect in artifactRedirects map in handlers.go:
"<old-name>": "<new-name>",
Common Failures
- NEVER determine current version from CHANGELOG.md —
it may contain unreleased or untagged entries
- NEVER skip the diff check — releasing unchanged
artifacts creates noise
- NEVER use
git tag on a commit other than HEAD
- MUST push the tag separately from the commit if the
IAM trust policy doesn't allow tag-triggered workflows
(use
gh workflow run publish.yaml -f tag=... as
workaround)
- NEVER manually edit
.tessl-plugin/plugin.json version —
tessl manages it via tessl tile publish --bump. A
difference between SKILL.md version and plugin.json
version is expected (ADR 0006).
1---2name: openkata-ryu-release3description: Releases distributable artifacts (skills, rules, profiles) with proper versioning, changelog, git tags, and optional tessl registry publish.4---56# openkata-ryu-release78Release a distributable artifact following Semantic9Versioning. The git tag is the single source of truth10for the current published version.1112## Trigger1314Activate when the user says "release", "bump", "version",15"tag", or "publish" an artifact.1617## Determine Current Version1819```bash20git tag -l '<type>/<name>/v*' | sort -V | tail -121```2223NEVER read the version from CHANGELOG.md or SKILL.md to24determine the current version. Those files may be ahead25of (or behind) the actual tagged release.2627## Determine Next Version2829Follow [Semantic Versioning](https://semver.org/):3031- **PATCH** (x.y.Z): documentation additions, typo fixes,32 non-functional changes (added RATIONALE.md, reformatted33 ACKNOWLEDGMENTS.md, fixed examples)34- **MINOR** (x.Y.0): new features, new steps, new35 references, behavioral changes that don't break36 existing usage37- **MAJOR** (X.0.0): breaking changes to the skill's38 interface (renamed triggers, removed steps, changed39 output format that downstream consumers rely on)4041When in doubt, ask the user.4243## Release Steps44451. Confirm the artifact has uncommitted changes vs its46 latest tag:47 ```bash48 git diff <latest-tag>..HEAD -- <type>/<name>/49 ```50 If no diff, abort — nothing to release.51522. Run the badge update script to sync counts:53 ```bash54 ./scripts/update-readme-badges.sh55 ```56 If README.md changed, stage it for the release commit.57583. Update `CHANGELOG.md` — add a version section after59 `[Unreleased]` with today's date and what changed.60614. Bump version in the frontmatter of the main doc62 (`SKILL.md`, `RULE.md`, or `<name>.md`).63645. Commit:65 ```text66 release(<type>): <name> vX.Y.Z6768 Assisted-by: <agent>:<model>69 ```70716. Tag:72 ```bash73 git tag <type>/<name>/vX.Y.Z74 ```75767. Push (only with user confirmation):77 ```bash78 git push origin main79 git push origin <type>/<name>/vX.Y.Z80 ```81828. Ask the user: "Release to tessl registry as well? (y/n)"83 If yes:84 ```bash85 cd <type>/<name> && tessl tile publish --bump patch86 ```87 If the tile doesn't exist yet, run `tessl skill import`88 first, then `tessl tile publish`.8990## Validation9192- Tag version must match SKILL.md frontmatter version93- Tag version must match latest CHANGELOG.md section94- Tag must point to the release commit (not an95 earlier commit)96- CHANGELOG entry must not be empty9798## Renaming an Artifact99100Renaming starts versioning from v1.0.0 under the new name.101Old git tags are preserved — old S3 artifacts are deleted.1021031. Rename the directory:104 ```bash105 git mv <type>/<old-name> <type>/<new-name>106 ```1071082. Update frontmatter `name:` field.1091103. Reset CHANGELOG.md to a fresh v1.0.0 entry. Mention111 the old name:112 ```113 ## [1.0.0] - YYYY-MM-DD114115 ### Changed116117 - Renamed from <old-name>118 ```1191204. Commit, tag, push:121 ```bash122 git commit -m 'refactor(<type>): rename <old-name> to <new-name>'123 git tag <type>/<new-name>/v1.0.0124 ```1251265. Publish new name, delete old S3 prefix:127 ```bash128 gh workflow run publish.yaml -f tag=<type>/<new-name>/v1.0.0129 aws s3 rm s3://openkata-artifacts/<type>/<old-name>/ --recursive130 ```1311326. Add redirect in `artifactRedirects` map in handlers.go:133 ```go134 "<old-name>": "<new-name>",135 ```136137## Common Failures138139- NEVER determine current version from CHANGELOG.md —140 it may contain unreleased or untagged entries141- NEVER skip the diff check — releasing unchanged142 artifacts creates noise143- NEVER use `git tag` on a commit other than HEAD144- MUST push the tag separately from the commit if the145 IAM trust policy doesn't allow tag-triggered workflows146 (use `gh workflow run publish.yaml -f tag=...` as147 workaround)148- NEVER manually edit `.tessl-plugin/plugin.json` version —149 tessl manages it via `tessl tile publish --bump`. A150 difference between SKILL.md version and plugin.json151 version is expected (ADR 0006).
tovrleaf