| name | releasing-kata |
| description | Use this skill when releasing Kata Desktop, Kata CLI, Kata Context, Symphony, or the Pi Symphony extension, bumping versions, updating changelogs, or creating release PRs. Triggers include "release", "bump version", "publish", "create release PR", "ship it", "cut a release". |
Releasing Kata
Kata has five active independently versioned release targets. Ask which target if not clear from context.
| Target | Package | Tag Format | Reference |
|---|
| Desktop | Desktop app (not npm package) | desktop-vX.Y.Z | references/desktop-release.md |
| CLI | @kata-sh/cli | cli-vX.Y.Z | references/cli-release.md |
| Context | @kata/context | context-vX.Y.Z | references/context-release.md |
| Symphony | symphony (Rust binary) | symphony-vX.Y.Z | references/symphony-release.md |
| Pi Symphony Extension | @kata-sh/pi-symphony-extension | pi-symphony-vX.Y.Z | references/pi-symphony-extension-release.md |
@kata-sh/orc / Orchestrator is legacy-only. Do not cut new Orchestrator releases; update the CLI skill-platform, Desktop, Context, Symphony, or Pi Symphony extension release target instead.
Root package.json version is 0.0.0 — never touch it. The root may contain Pi package manifest metadata for monorepo git installs, but it is not the version source for any release. Each app or package owns its own version. Versions are independent and do not need to match.
Version semantics
| Type | When | Example |
|---|
patch | Bug fixes, small improvements | 0.4.9 → 0.4.10 |
minor | New features, backward compatible | 0.4.9 → 0.5.0 |
major | Breaking changes | 0.4.9 → 1.0.0 |
Workflow
Once the target is identified, read the corresponding reference file for the full release steps, CI behavior, and acceptance criteria. Then follow it.
Troubleshooting
For build failures, code signing, notarization, and CI issues, read release-troubleshooting.md.
Quick checks:
- CI didn't trigger: Version in
package.json must differ from existing git tags
- Desktop CI fails:
gh run list --workflow=desktop-release.yml --limit 3
- CLI publish fails: Ensure
NPM_TOKEN secret is set and private: false in apps/cli/package.json
- Context CI didn't trigger: Changes must be under
apps/context/**; version must differ from existing context-v* tags
- Context publish fails: Ensure
NPM_TOKEN secret is set; check apps/context/package.json has no private: true
- Symphony CI didn't trigger: Changes must be under
apps/symphony/**; version in Cargo.toml must differ from existing symphony-v* tags
- Symphony build fails: Ensure Rust toolchain is installed; check
cargo build --release locally first
- Pi Symphony extension release didn't trigger: Changes must be under
apps/symphony/pi-extension/**; version in apps/symphony/pi-extension/package.json must differ from existing pi-symphony-v* tags and npm versions
- Pi Symphony extension npm publish fails: Ensure
NPM_TOKEN secret is set, package is private: false, and runtime dependencies are in dependencies
- Pi Symphony extension git install fails: Ensure root
package.json has a pi manifest pointing at the extension and root runtime deps include extension runtime deps such as ws
- macOS notarization fails: Verify
APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID secrets
