Versioning

Change type	Bump
Bug fix	patch (x.y.Z)
New feature, backward compatible	minor (x.Y.0)
Breaking change	major (X.0.0)

Pre-release checklist

npm run typecheck passes
npm run lint passes
npm test passes (includes version sync test)
npm run build succeeds
New commands added to src/commands/metadata.ts (completion test will fail otherwise)

Release steps

1. Commit feature/fix changes first

Do NOT mix feature commits with version bump commits.

2. Bump version

npm version <version> --no-git-tag-version

3. Sync all version-tracked files

node --import tsx scripts/sync-command-docs.ts

This updates:

docs/commands.md quick reference table
skills/clickup-cli/SKILL.md version header (line 6)
skills/clickup-cli/SKILL.md version check hint (line 10)
.claude-plugin/plugin.json version field

The version synchronization test in tests/unit/ verifies these stay in sync.

4. Commit and tag

git add package.json package-lock.json .claude-plugin/plugin.json docs/commands.md skills/clickup-cli/SKILL.md
git commit -m "bump v<version>"
git tag v<version>
git push origin main --tags

5. Wait for CI

gh run watch --repo krodak/clickup-cli --exit-status $(gh run list --repo krodak/clickup-cli --workflow release.yml --limit 1 --json databaseId -q '.[0].databaseId')

The release workflow runs: typecheck, test, build, npm publish (OIDC), GitHub Release creation.

6. If CI fails

Common failures:

npm ci fails: peer dep conflict (typescript-eslint vs TypeScript 6). .npmrc has legacy-peer-deps=true.
Completion test fails: metadata.ts is missing a new command or flag. Add it, amend, re-tag, force push.
npm publish fails "already published": Version already exists on npm from a previous attempt. Bump to next version.

Fix, then:

git commit --amend --no-edit   # or new commit
git tag -d v<version>
git tag v<version>
git push origin main --tags --force

7. Write release notes

gh release edit v<version> --repo krodak/clickup-cli --notes "$(cat <<'EOF'
## Heading

Description and code examples.

Test count.
EOF
)"

Style: H2 per feature, code block with 2-3 examples, test count at bottom, no emojis.

8. Update Homebrew

SHA=$(curl -sL https://registry.npmjs.org/@krodak/clickup-cli/-/clickup-cli-<version>.tgz | shasum -a 256 | cut -d' ' -f1)

Then update ~/repositories/homebrew-tap/Formula/clickup-cli.rb:

Change version in URL
Change sha256

git -C ~/repositories/homebrew-tap add Formula/clickup-cli.rb
git -C ~/repositories/homebrew-tap commit -m "clickup-cli <version>"
git -C ~/repositories/homebrew-tap push origin main

9. Install updated skill

cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md

Common mistakes to avoid

Running git commit before node --import tsx scripts/sync-command-docs.ts (use the script to sync everything)
Not adding new commands to src/commands/metadata.ts
Bumping version in the same commit as feature changes
Force-pushing tags without deleting old tag first

releasing-clickup-cli