# Release Publish

> Publish a new AlphaClaw release to npm and GitHub. Use when the user asks to cut a release, publish a version, write release notes, draft a release tweet, or close issues addressed in a release. Covers git history analysis, release note drafting, npm publishing, GitHub release creation, issue closing, and tweet drafting.

- Skill: `chrysb/release-publish` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chrysb/release-publish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chrysb/release-publish/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chrysb (https://skillmd.com/u/chrysb)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chrysb/release-publish

---


# Release Publish

End-to-end workflow for publishing an AlphaClaw release. Produces release notes
in the [OpenClaw release format](https://github.com/openclaw/openclaw/releases),
publishes to npm, creates a GitHub release, closes addressed issues, and drafts
a tweet.

## Workflow

### Phase 1: Gather History

1. Identify the previous stable tag (`git tag --sort=-v:refname`).
2. Determine the target version. If on a beta prerelease, the stable version is
   the base (e.g. `0.6.0-beta.3` → `0.6.0`). Confirm with the user if unclear.
3. Collect all commits since the last stable tag:
   ```
   git log v<prev>..HEAD --oneline --no-merges
   git log v<prev>..HEAD --no-merges --format="----%nCommit: %h%nSubject: %s%n%b"
   ```
4. Identify external contributors:
   ```
   git log v<prev>..HEAD --all --format="%an" | sort | uniq -c | sort -rn
   ```
5. Find merged PRs and contributor credits:
   ```
   git log v<prev>..HEAD --all --merges --format="%s"
   ```
6. Check open issues on the repo that may be addressed:
   ```
   gh issue list --repo chrysb/alphaclaw --state open
   ```
   Cross-reference issue descriptions against the commit log to identify fixes.

### Phase 2: Draft Release Notes

Present a draft to the user **before** publishing. Use this structure:

```markdown
## AlphaClaw <version>

### What's New
* **Feature name**: concise description of what it does and why it matters.

### Fixes
* **Short label**: what was broken and how it's fixed. Reference issues
  (`Fixes #N`) and PRs (`(#N)`) inline. Credit external contributors
  (`Thanks @handle.`).

### Contributors
* @handle
```

#### Style rules

- Each bullet starts with a **bold short label** followed by a colon.
- Describe the *what and why*, not the implementation details.
- Keep **What's New** and **Fixes** user-facing: describe behavior, not code
  structure (no "decomposed into folder-based components", "co-located hooks",
  etc.). Omit implementation-only changes from the release notes.
- Use active voice ("add", "fix", "remove"), not past tense.
- Reference GitHub issues with `Fixes #N` (auto-closes) or `#N` (link only).
- Reference PRs with `(#N)`.
- Credit external contributors with `Thanks @handle.` at the end of the bullet.
- List all credited contributors in a **Contributors** section at the bottom.
- Fold reverted commits into their replacement — don't list revert + re-land.

#### Deciding what goes where

| Commit type | Section |
|---|---|
| New user-facing capability | What's New |
| Bug fix, regression fix | Fixes |
| Dependency bump (OpenClaw, etc.) | What's New (last bullet) |
| Refactor, test backfill, code split, tooling-only change | Skip |
| Version bump commits (`0.6.0-beta.N`) | Skip |
| Merge commits | Skip |

### Phase 3: Review

Present the full draft to the user and wait for approval or edits before
proceeding. Do not publish without explicit confirmation.

### Phase 4: Publish

Once approved, execute in order:

1. **Ensure clean state**: `git status` should show no uncommitted changes.
   Switch to `main` if not already there.
2. **Preflight stable template access**: for a stable release, run the Render
   repository permission and remote checks in Phase 4.5 before changing the
   AlphaClaw version. Abort if the authenticated user cannot push to Render's
   template; all deployment templates must remain in sync with the release.
3. **Run tests**: `npm test` — abort if any fail.
4. **Verify the OpenClaw dependency**: if AlphaClaw depends on a pinned
   `openclaw` version, confirm `package-lock.json` and the local install resolve
   to the same version before publishing.
   ```
   node -p "require('./package.json').dependencies.openclaw"
   node -p "require('./package-lock.json').packages['node_modules/openclaw'].version"
   node -p "require('./node_modules/openclaw/package.json').version"
   ```
   When the release relies on a specific upstream OpenClaw fix, verify it in the
   installed package rather than carrying local OpenClaw edits. For example:
   ```
   grep -R -n "allowConversationAccess" node_modules/openclaw/dist/zod-schema-* node_modules/openclaw/dist/runtime-schema-*
   ```
5. **Bump version**: `npm version <version>` (creates commit + tag).
6. **Push**: `git push && git push --tags`.
7. **Publish to npm**: `npm publish` (publishes to `latest` tag).
8. **Create GitHub release**:
   ```
   gh release create v<version> --title "AlphaClaw <version>" --notes "<body>"
   ```
   Use a HEREDOC for the body to preserve formatting.

### Phase 4.5: Sync Deployment Templates (mandatory for stable releases)

After every **stable** `npm publish` to `latest`, update **all three** deployment
templates so Railway, Render, and Apex stay pinned to the same AlphaClaw and
OpenClaw versions (deterministic Docker installs, no drift from `@chrysb/alphaclaw`
`latest`).

Repos:

- `~/Projects/openclaw-railway-template` (typically `main` for production; `beta`
  only when cutting a beta — see release-beta skill; merge `main` into `beta`
  after stable pins when you want `beta` to match production pins)
- `~/Projects/openclaw-render-template` (typically `main`; this checkout must
  track `https://github.com/render-examples/openclaw-render-template.git`)
- `~/Projects/openclaw-apex-template` (typically `main`)

For **each** repo:

1. Switch to the intended branch (confirm with the user if unclear).
2. Set `@chrysb/alphaclaw` in `package.json` to the released version. Do not add
   `overrides` for `openclaw` in templates unless you are doing one-off debugging —
   OpenClaw should resolve transitively from AlphaClaw’s declared dependency (same
   resulting version across templates unless you intentionally diverge).
3. Run `npm install` to refresh or create `package-lock.json`.
4. Verify the template install resolved the expected OpenClaw version and includes
   any upstream OpenClaw fixes AlphaClaw depends on:
   ```
   node -p "require('./node_modules/@chrysb/alphaclaw/package.json').dependencies.openclaw"
   node -p "require('./node_modules/openclaw/package.json').version"
   grep -R -n "allowConversationAccess" node_modules/openclaw/dist/zod-schema-* node_modules/openclaw/dist/runtime-schema-*
   ```
   If this fails, stop: the template resolved the wrong OpenClaw package or is
   missing an upstream fix required by AlphaClaw.
5. Commit and push (include both `package.json` and `package-lock.json` when the
   lockfile exists or was added).

Before updating the Render template, verify that the authenticated GitHub user
can push to Render's repository and that the local checkout targets it:

```
gh api repos/render-examples/openclaw-render-template --jq '.permissions.push'
git -C ~/Projects/openclaw-render-template remote get-url origin
```

The permission check must return `true`, and `origin` must be
`https://github.com/render-examples/openclaw-render-template.git` (or the SSH
equivalent). If the checkout still targets the former `chrysb` repository,
update it before syncing:

```
git -C ~/Projects/openclaw-render-template remote set-url origin https://github.com/render-examples/openclaw-render-template.git
git -C ~/Projects/openclaw-render-template fetch origin
```

Stop before changing or publishing any template if push access is missing; ask
an administrator of `render-examples/openclaw-render-template` to grant the
authenticated user write access, then repeat the preflight.

Do not skip Render or Apex: pinning only one template while others stay on
`latest` causes drift and non-reproducible installs between platforms.

### Phase 5: Close Issues

For each issue referenced with `Fixes #N` in the release notes:

```
gh issue close <N> --repo chrysb/alphaclaw --comment "Fixed in v<version>."
```

If an issue is partially addressed or only improved (not fully resolved), leave
it open and add a comment instead:

```
gh issue comment <N> --repo chrysb/alphaclaw --body "Improved in v<version> — <brief description>. Leaving open for remaining work."
```

### Phase 6: Draft Tweet

Draft a tweet following the OpenClaw announcement style:

```
AlphaClaw <version> 🐺

<emoji> <headline feature or fix — one line>
<emoji> <second highlight>
<emoji> <third highlight>
<emoji> <fourth highlight (optional)>

<witty one-liner or tagline>
```

#### Tweet style rules

- Keep under 280 characters.
- Use one emoji per line to set the tone (feature type, not decoration).
- Headline the biggest user-facing change first.
- End with a short memorable line — personality over formality.
- Do not include a link; the user will attach the GitHub release card.
- Offer 2–3 alternative closing lines for the user to choose from.

## Emergency / Hotfix Releases

For hotfix versions (e.g. `0.6.1`) that fix a critical bug:

1. Follow the same workflow but scope the history to the previous released tag.
2. The release notes can be shorter — a single Fixes section is fine.
3. Skip the tweet unless the fix is noteworthy.

## Pre-release / Beta Publishes

For beta iterations during development:

```
npm version prerelease --preid=beta
git push && git push --tags
npm publish --tag beta
```

Beta publishes do not need GitHub releases, issue closing, or tweets. They are
used for testing via the `openclaw-railway-template` beta branch.

After each beta publish, remind the user to update the Railway template's
`package.json` on the `beta` branch to pin the exact beta version. If you also
ship betas through Render or Apex, pin those templates the same way on the
branch they use for prereleases.