Disentinel/grafema / .claude/skills/grafema-release
grafema-release
VerifiedGrafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version".
Grafema Release Procedure
Quick Reference
./scripts/release.sh patch --dry-run # Preview
./scripts/release.sh patch # Bump only
./scripts/release.sh 0.2.5-beta --publish # Bump and publish
Pre-Release Checklist
- On
mainbranch, clean working directory pnpm build— MUST run before tests (tests import fromdist/)pnpm test— verify tests passnpm whoami— verify npm auth
MANDATORY: @grafema/rfdb Binary Download
If releasing @grafema/rfdb, download prebuilt binaries BEFORE publishing:
- Check if Rust source changed since last rfdb tag:
git log $(git tag -l 'rfdb-v*' | sort -V | tail -1)..HEAD -- packages/rfdb-server/src/ - If changed — push new tag:
git tag rfdb-v0.X.Y && git push origin rfdb-v0.X.Y - Wait for CI (all 4 platforms: darwin-x64, darwin-arm64, linux-x64, linux-arm64)
- Download:
./scripts/download-rfdb-binaries.sh rfdb-v0.X.Y - Verify:
ls -la packages/rfdb-server/prebuilt/*/rfdb-server— must show 4 binaries
npm tags (v0.2.12-beta) and rfdb CI tags (rfdb-v0.2.12-beta) are independent. The release script doesn't check if binaries match current Rust source.
Version Types
| Type | npm dist-tag |
|---|---|
patch / minor / major / 0.3.0 | latest |
prerelease / 0.2.5-beta | beta |
Publish Order (automatic)
@grafema/types → @grafema/rfdb-client → @grafema/util → @grafema/mcp → @grafema/api → @grafema/cli → @grafema/rfdb
Known Pitfalls
"Uncommitted changes detected" for ignored files
.gitignore pattern .grafema/* is anchored to root. Use **/.grafema/graph.rfdb/ for nested matches.
100+ test failures during release (but CI passes)
Release script runs tests BEFORE building. dist/ is stale. Fix: run pnpm build manually first.
Snapshot tests fail cross-platform
macOS vs Linux rfdb-server may produce different graph output. Workaround: --skip-ci-check.
Stale rfdb-server binaries shipped
release.sh packages whatever is in prebuilt/. See "MANDATORY" section above.
CI/CD Integration
- Push version tag →
release-validate.ymlruns automatically (5-10 min) - After validation passes → trigger
release-publish.ymlmanually - Verify:
npx @grafema/cli@<version> --version
Rollback
npm unpublish @grafema/cli@0.2.5-beta # within 72 hours
# or
npm deprecate @grafema/cli@0.2.5-beta "Use 0.2.4-beta instead"
git revert HEAD && git push origin main stable
git tag -d v0.2.5-beta && git push origin :refs/tags/v0.2.5-beta
CHANGELOG.md Format
## [0.X.Y-beta] - YYYY-MM-DD
### Highlights
### Features
### Bug Fixes
### Infrastructure
### Known Issues
Post-Release
npx @grafema/cli@latest --version- Update Linear issues to Done
stablebranch auto-updated by release script
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |