calver
starsforks
How to install calver?
soul-brews-studio/arra-oracle-skills-cli/calver
$npx -y skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill calverShow 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,
SKILL.md
| 1 | # /calver |
| 2 | |
| 3 | Compute / bump the CalVer version for arra-oracle-skills-cli. |
| 4 | |
| 5 | > ⚠️ **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. |
| 6 | > |
| 7 | > | Want to… | Use | |
| 8 | > |---|---| |
| 9 | > | See the next target version | `/calver` (default = `--check`) | |
| 10 | > | Just bump `package.json` and stop | `/calver --apply` | |
| 11 | > | Cut a soak release (alpha pre-release) | `/release-alpha` | |
| 12 | > | Cut a stable release on main | `/release-stable` | |
| 13 | > | Land a code fix without releasing | regular branch + PR — keep `package.json` version untouched | |
| 14 | > |
| 15 | > **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. |
| 16 | |
| 17 | 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. |
| 18 | |
| 19 | 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". |
| 20 | |
| 21 | ## Step 0: Locate arra-oracle-skills-cli |
| 22 | |
| 23 | Always resolve repo via `ghq` so the skill works from any cwd: |
| 24 | |
| 25 | ```bash |
| 26 | ARRA=$(ghq list -p --exact Soul-Brews-Studio/arra-oracle-skills-cli 2>/dev/null | head -1) |
| 27 | if [ -z "$ARRA" ]; then |
| 28 | echo "❌ arra-oracle-skills-cli not found via ghq. Run: ghq get github.com/Soul-Brews-Studio/arra-oracle-skills-cli" |
| 29 | exit 1 |
| 30 | fi |
| 31 | echo "🕐 $(date '+%H:%M %Z (%A %d %B %Y)')" |
| 32 | echo "📁 $ARRA" |
| 33 | ``` |
| 34 | |
| 35 | ## Modes |
| 36 | |
| 37 | ### Default — dry-run check (show next target) |
| 38 | |
| 39 | ```bash |
| 40 | TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --check |
| 41 | ``` |
| 42 | |
| 43 | Shows the next target version (`max(tag-walk, package.json) + 1` for today's date+channel). No files modified. |
| 44 | |
| 45 | ### `--apply` — bump package.json |
| 46 | |
| 47 | ```bash |
| 48 | TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" |
| 49 | ``` |
| 50 | |
| 51 | Writes the next version to `package.json`. Caller then: |
| 52 | |
| 53 | ```bash |
| 54 | git -C "$ARRA" add package.json && git -C "$ARRA" commit -m "bump: v<version>" |
| 55 | ``` |
| 56 | |
| 57 | Do NOT auto-commit — hand off to user so they can bundle with other changes. |
| 58 | |
| 59 | ### `--stable` — cut stable (no alpha/beta suffix) |
| 60 | |
| 61 | ```bash |
| 62 | TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --stable |
| 63 | ``` |
| 64 | |
| 65 | ### `--beta` — cut beta (parallel channel, independent counter) |
| 66 | |
| 67 | ```bash |
| 68 | TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --beta |
| 69 | ``` |
| 70 | |
| 71 | `--stable` and `--beta` are mutually exclusive (script exits 2). |
| 72 | |
| 73 | ### `--hour N` — REMOVED |
| 74 | |
| 75 | 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. |
| 76 | |
| 77 | ### `--help` — print calver.ts help |
| 78 | |
| 79 | ```bash |
| 80 | TZ=Asia/Bangkok bun "$ARRA/scripts/calver.ts" --help |
| 81 | ``` |
| 82 | |
| 83 | ## After apply |
| 84 | |
| 85 | **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. |
| 86 | |
| 87 | If the user wants to ship the bump, they invoke a release skill: |
| 88 | |
| 89 | ``` |
| 90 | Next steps (user runs one of these — not /calver): |
| 91 | /release-alpha — soak channel, PR to alpha, calver-release.yml cuts pre-release on merge |
| 92 | /release-stable — stable channel (planned), PR to main, calver-release.yml cuts stable on merge |
| 93 | ``` |
| 94 | |
| 95 | 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. |
| 96 | |
| 97 | ## Notes |
| 98 | |
| 99 | - The calver.ts script is authoritative. Do NOT hand-compute versions. |
| 100 | - 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). |
| 101 | - Spec: `ψ/inbox/2026-04-18_proposal-calver-skills-cli.md` (mawjs-oracle vault). |
| 102 | - Umbrella issue: #526 (maw-js — original); #284 (arra-oracle-skills-cli — this port). |
| 103 | - Related changes today (2026-04-28): #775 (monotonic counter), PR #783 (--beta channel for #754), PR #786 (package.json walk for #784). |
| 104 | |
| 105 | --- |
| 106 | |
| 107 | ARGUMENTS: $ARGUMENTS |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
