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".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.1 KB |
SKILL.md
View on GitHub---
name: grafema-release
description: |
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".
author: Claude Code
version: 3.0.0
date: 2026-05-03
---
# Grafema Release Procedure
## Quick Reference
```bash
./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:
```bash
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
| 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
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
```bash
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
```markdown
## [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
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 |