| name | release |
| description | Release ai-memex-cli to npm. Bumps version, syncs bilingual READMEs and the website docs/, runs tests, publishes, tags, and creates a GitHub Release. Supports beta channel and dry-run. Trigger when the user says 发版 / release / publish / 发新版本 / "上传新包". |
Release ai-memex-cli
This skill drives the full publish pipeline for ai-memex-cli. It is invoked by the user (never proactively): npm publish is irreversible after 72h, GitHub Releases are public, and git tags propagate fast.
When to use
- User explicitly asks to release / publish / cut a new version
- Triggers (zh): "发版"、"发个新版本"、"上传新包"、"发布到 npm"、"打 tag"
- Triggers (en): "release", "publish", "ship a new version", "cut v0.3.0"
Do NOT trigger for: "ready to release?", "what's left before release?" — those are status questions, not commands.
Architecture
11 independent phase scripts under scripts/, each a Node .mjs runnable on its own. An orchestrator (scripts/orchestrator.mjs) chains them with confirmation prompts. pnpm release invokes the orchestrator.
Each phase prints a trailing line ::summary:: <json> on stdout — both the orchestrator and a driving agent can parse it to make decisions.
scripts/
├── orchestrator.mjs # pnpm release entry
├── 01-preflight.mjs # read-only checks
├── 02-sync-docs.mjs # invokes `claude -p` to update CHANGELOG/README/website
├── 03-bump-version.mjs # writes package.json
├── 04-build-all.mjs # pnpm build + (conditional) website → docs/
├── 05-test.mjs # pnpm test:run
├── 06-pack-preview.mjs # pnpm pack --dry-run + content audit
├── 07-git-finalize.mjs # commit + tag, local only
├── 08-publish.mjs # pnpm publish [--tag beta]
├── 09-git-push.mjs # push HEAD + tag
├── 10-github-release.mjs # gh release create (skipped for beta)
├── 11-verify.mjs # npm view + gh release view
└── _shared/ # log / shell / pkg / changelog helpers
Quick reference
| Goal | Command |
|---|
| patch stable | pnpm release |
| minor stable | pnpm release --bump minor |
| major stable | pnpm release --bump major |
| start a beta cycle | pnpm release --bump prepatch --beta |
| beta continuation | pnpm release --beta |
| graduate beta → stable | pnpm release --bump release |
| dry-run preview | pnpm release --dry-run |
| docs already match | pnpm release --manual-docs |
| CI / unattended | pnpm release --yes --push |
Workflow
| # | Phase | Writes? | dry-run | Pause after? |
|---|
| 1 | preflight | no | runs | no |
| 2 | sync-docs | yes | runs (real edits) | yes — review agent diff |
| 3 | bump-version | yes | computes only | no |
| 4 | build-all | yes | skipped | no |
| 5 | test | no | runs unless --skip | no |
| 6 | pack-preview | no | skipped | yes — review tarball |
| 7 | git-finalize | yes | skipped | yes before — final review |
| 8 | publish | yes | --dry-run flag | no |
| 9 | git-push | yes | skipped | yes (unless --push) |
| 10 | github-release | yes | skipped | no |
| 11 | verify | no | skipped | no |
Decision points (when an agent drives this manually)
When you (the agent) drive the release without pnpm release, you MUST stop and ask the user at these checkpoints:
- Before phase 1 — bump level (patch / minor / major / beta?), dry-run vs live
- After phase 2 — show
git status --porcelain, confirm agent's doc edits look right
- After phase 6 — show tarball file list, confirm no missing / no leaked files
- Before phase 7 — final
git status review before writing git history
- Before phase 9 — confirm push (unless user said
--push upfront)
Skip a checkpoint only if the user explicitly said --yes or equivalent.
Beta channel semantics
- Version:
0.3.0-beta.0 → 0.3.0-beta.1 → ... → 0.3.0
- npm tag:
--tag beta (so npm i ai-memex-cli keeps pointing at the latest stable)
- Git tag: yes,
v0.3.0-beta.1 (preserves history)
- GitHub Release: skipped (avoid clutter; the git tag is enough)
See reference/beta-flow.md for the full state machine and examples.
Failure recovery
Things that can go wrong and how to recover are catalogued in reference/rollback.md. Common cases:
- preflight fails → fix env, re-run from phase 1
- sync-docs fails →
--manual-docs and re-run
- publish fails after tag →
git tag -d v... locally, retry phase 8 only
- publish succeeds but push fails → re-run phase 9 + 10 individually
Reference files
Direct invocation cheat sheet
If an agent wants to run one phase in isolation (e.g. retry only phase 8 after a publish failure):
node .claude/skills/release/scripts/01-preflight.mjs
node .claude/skills/release/scripts/02-sync-docs.mjs --new-version 0.3.0
node .claude/skills/release/scripts/03-bump-version.mjs --bump minor
node .claude/skills/release/scripts/04-build-all.mjs
node .claude/skills/release/scripts/05-test.mjs
node .claude/skills/release/scripts/06-pack-preview.mjs
node .claude/skills/release/scripts/07-git-finalize.mjs --version 0.3.0
node .claude/skills/release/scripts/08-publish.mjs
node .claude/skills/release/scripts/09-git-push.mjs --version 0.3.0
node .claude/skills/release/scripts/10-github-release.mjs --version 0.3.0
node .claude/skills/release/scripts/11-verify.mjs --version 0.3.0
Each script also accepts --help.
