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".

FileKindSize
SKILL.mdskill md3.1 KB
---
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
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