Skip to content

Disentinel/grafema / .claude/skills/grafema-release

grafema-release

Verified

Grafema 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

  1. On main branch, clean working directory
  2. pnpm build — MUST run before tests (tests import from dist/)
  3. pnpm test — verify tests pass
  4. npm whoami — verify npm auth

MANDATORY: @grafema/rfdb Binary Download

If releasing @grafema/rfdb, download prebuilt binaries BEFORE publishing:

  1. 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/
    
  2. If changed — push new tag: git tag rfdb-v0.X.Y && git push origin rfdb-v0.X.Y
  3. Wait for CI (all 4 platforms: darwin-x64, darwin-arm64, linux-x64, linux-arm64)
  4. Download: ./scripts/download-rfdb-binaries.sh rfdb-v0.X.Y
  5. 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

Typenpm dist-tag
patch / minor / major / 0.3.0latest
prerelease / 0.2.5-betabeta

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

  1. Push version tag → release-validate.yml runs automatically (5-10 min)
  2. After validation passes → trigger release-publish.yml manually
  3. 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

  1. npx @grafema/cli@latest --version
  2. Update Linear issues to Done
  3. stable branch auto-updated by release script
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall