Our workflow is PR-driven:

Development happens on feature branches
Releases happen on release branches created from main

1a. Ensure you're ready to release

Before creating a release branch, verify:

Check current branch: Must be on main (not a feature branch)
```
git branch --show-current
```

If on a feature branch: The PR must pass CI and be merged first

# Check PR status
gh pr status

# Monitor PR CI checks
gh pr checks --watch 2>&1 | tail -10

# After PR merges, switch to main
git checkout main && git pull

Verify working directory is clean:

git status  # Should show "nothing to commit, working tree clean"

1b. Run pre-release checks

Once on main with a clean working directory, verify the codebase is ready:

Stop if tests fail. Fix issues before proceeding.

Step 2: Determine Version Bump

Ask the user what type of release this is:

Type	When to Use	Example
`patch`	Bug fixes, small improvements	1.0.5 → 1.0.6
`minor`	New features, backward compatible	1.0.5 → 1.1.0
`major`	Breaking changes	1.0.5 → 2.0.0

Step 3: Bump Versions

Both files must have matching versions:

Read current version from package.json
Calculate new version based on bump type
Update package.json version field
Update .claude-plugin/plugin.json version field

# Get current version
cat package.json | jq -r '.version'

# After updating both files, verify they match
diff <(jq -r '.version' package.json) <(jq -r '.version' .claude-plugin/plugin.json)

Step 4: Update Docs

1: Update CHANGELOG

Add entry to CHANGELOG.md following Keep a Changelog format:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature descriptions

### Fixed
- Bug fix descriptions

### Changed
- Modification descriptions

Guidelines:

Use today's date
Group changes by type (Added, Fixed, Changed, Removed)
Write user-facing descriptions (what changed, not how)
Reference issue numbers if applicable

2: Update README (if needed)

If there are significant changes affecting usage, update README.md accordingly.

3: Update Website (if needed)

If there are significant changes affecting documentation, update the website docs accordingly. ~/Users/gannonhall~/dev/kata/kata-site/src

Step 5: Run Tests Again

After version bump, rebuild and test:

npm run build && npm test && npm run test:smoke

Step 6: Create Release PR

# Create release branch
git checkout -b release/vX.Y.Z

# Stage release files
git add package.json .claude-plugin/plugin.json CHANGELOG.md

# Commit with conventional format
git commit -m "chore: bump version to X.Y.Z"

# Push and create PR
git push -u origin release/vX.Y.Z
gh pr create --title "Release vX.Y.Z" --body "## Release vX.Y.Z

### Changes
- [List key changes from CHANGELOG]

### Checklist
- [ ] Version bumped in package.json
- [ ] Version bumped in plugin.json
- [ ] CHANGELOG updated
- [ ] Tests passing"

Step 7: Merge and Monitor CI

# Merge the PR (after review if required)
gh pr merge --merge --delete-branch

# Monitor CI workflows
gh run list --limit 5
gh run watch  # Watch the latest run

CI Pipeline:

plugin-release.yml triggers on push to main
Detects version change between plugin.json and marketplace
Runs tests → Builds → Creates GitHub Release → Pushes to marketplace

Step 8: Verify Release

After CI completes (~2-3 minutes), verify the release.

8a. Verify GitHub Release

# Verify GitHub Release created with tag
gh release view vX.Y.Z

8b. Verify Plugin Marketplace Updated

# Check marketplace version (bypasses CDN cache)
gh api repos/gannonh/kata-marketplace/contents/.claude-plugin/marketplace.json --jq '.content' | base64 -d | jq -r '.plugins[0].version'

# Verify plugin-release workflow ran successfully
gh run list --workflow=plugin-release.yml --limit 3

8c. Manual Plugin Installation Test

This is the one test that can't be fully automated. Test actual plugin installation:

# Create temporary test directory
mkdir -p /tmp/kata-plugin-test && cd /tmp/kata-plugin-test

# Start Claude Code and test interactively
claude

In Claude Code:

/plugin install kata@kata-marketplace
/kata-help
/kata-whats-new

Verify:

Plugin installs without errors
/kata-help shows all commands
/kata-whats-new shows new version changelog
No path resolution errors

# Cleanup
cd - && rm -rf /tmp/kata-plugin-test

Troubleshooting

See ./release-troubleshooting.md for common issues:

CI workflow failures
Plugin marketplace not updating
Version mismatch errors

Acceptance Criteria

Pre-release:

package.json version updated
plugin.json version matches package.json
CHANGELOG.md has entry for new version
All tests pass locally (npm test && npm run test:smoke)

Release:

PR merged to main
GitHub Release created with correct tag (gh release view vX.Y.Z)

Post-release verification:

GitHub Release created with tag (gh release view vX.Y.Z)
Marketplace shows new version (gh api check)
Manual plugin test passes (/plugin install kata@kata-marketplace + /kata-help)

releasing-kata

Releasing Kata

Release Flow Overview

Step 1: Pre-Release Verification