Show or bump the project's CalVer version. Use when user says "calver", "bump version", "what version", or wants to check or set the skills version. For the full release flow (commit + push + PR) use /release-alpha or /release-stable instead — /calver alone never commits, pushes, or PRs.
SKILL.md
/calver
Compute / bump the CalVer version for arra-oracle-skills-cli.
⚠️ Pair with the right skill. This skill is --check (read-only) or --apply (writes package.json and stops). It does NOT commit, push, or PR — that's deliberate so a bump can never accidentally cut a release.
Want to…
Use
See the next target version
/calver (default = --check)
Just bump package.json and stop
/calver --apply
Cut a soak release (alpha pre-release)
/release-alpha
Cut a stable release on main
/release-stable
Land a code fix without releasing
regular branch + PR — keep package.json version untouched
Never combine a package.json bump with a code fix in the same commit on this repo — calver-release.yml auto-tags on push to main, so a fix-PR with a bump = automatic stable release.
CalVer scheme: v{yy}.{m}.{d}[-(alpha|beta).{HMM}] — HMM is the wall-clock as decimal H*100 + M with no leading zero (e.g. 09:37 → 937, 23:59 → 2359). Each minute is a unique slot — no merge-order collisions. Alpha and beta are independent channels (#754 / PR #783). Walks git tags AND package.json.version for source-of-truth (#784 / PR #786). TZ fixed to Asia/Bangkok. HMM replaced monotonic counter (#766/#775) in #923.
Day-of-month D may exceed 31 — used as a stable counter once natural date is exhausted (#930). E.g. v26.4.50 is the 50th stable cut in the period, not "April 50".
Step 0: Locate arra-oracle-skills-cli
Always resolve repo via ghq so the skill works from any cwd:
ARRA=$(ghq list -p --exact Soul-Brews-Studio/arra-oracle-skills-cli 2>/dev/null | head -1)
if [ -z "$ARRA" ]; then
echo "❌ arra-oracle-skills-cli not found via ghq. Run: ghq get github.com/Soul-Brews-Studio/arra-oracle-skills-cli"
exit 1
fi
echo "🕐 $(date '+%H:%M %Z (%A %d %B %Y)')"
echo "📁 $ARRA"
Modes
Default — dry-run check (show next target)
TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --check
Shows the next target version (max(tag-walk, package.json) + 1 for today's date+channel). No files modified.
--apply — bump package.json
TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts"
Writes the next version to package.json. Caller then:
TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --beta
--stable and --beta are mutually exclusive (script exits 2).
--hour N — REMOVED
The --hour flag is deprecated as of #766 and will exit 2. CalVer now uses a monotonic counter walked from git tags + package.json — there is no hour-bucket to override.
--help — print calver.ts help
TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --help
After apply
Stop. Hand off to the user. Do NOT auto-commit, do NOT push, do NOT open a PR. The whole point of /calver being read-only-or-stop-after-write is so a bump can never accidentally turn into a release.
If the user wants to ship the bump, they invoke a release skill:
Next steps (user runs one of these — not /calver):
/release-alpha — soak channel, PR to alpha, calver-release.yml cuts pre-release on merge
/release-stable — stable channel (planned), PR to main, calver-release.yml cuts stable on merge
If the user is doing code-only work (no release), tell them to revert the package.json change before opening the PR. Bumping in a non-release branch is the exact failure mode /release-alpha was built to prevent.
Notes
The calver.ts script is authoritative. Do NOT hand-compute versions.
Release workflow: calver-release.yml tags on push to main when package.json version differs from latest tag. Post-#767, alphas merge to alpha branch (no tags created until stable cut to main); the script handles this by walking package.json (#784 / PR #786).
