Release Lanes
Use this when the user asks to maintain Plate latest and beta, promote beta
to stable, sync main into next, recover release lane drift, verify npm
dist-tags, or run the release lane after a stable release.
Core Take
CI owns publishing. This skill owns lane maintenance.
Do not create a routine main -> next sync PR. That path creates review churn
for deterministic release metadata conflicts. Sync directly with a merge commit,
repair known release metadata automatically, push next, then let release.yml
publish beta.
Lanes
mainpublishes stable packages with npm taglatest.nextpublishes prerelease packages with npm tagbeta. While the repository variableSKIP_NEXT_CIistrue,release.ymlskips onnext, so nothing publishes until someone deletes the variable..changeset/pre.jsonbelongs onnextonly.mainmust never publish while.changeset/pre.jsonexists.
Plite Release Claims
Package publication runs pnpm plite:release:packages and does not imply broad
Plite behavior readiness. No CI workflow runs the Plite browser lanes, so a
release-ready claim needs each lane run locally from a clean checkout at the
exact release commit, the browser matrix (pnpm check:plite:browser-matrix)
included, with each lane's log cited. Make that claim only when the user
explicitly asks for it. Do not infer broad readiness from source tests,
historical artifacts, or package proof.
Modes
These are skill arguments, not subcommands of release-branch-prs.mjs.
| Invocation | Action |
|---|---|
release-lanes status |
Read branch, workflow and npm state. |
release-lanes sync |
Dry-run, then perform and push the direct main-to-next sync. |
release-lanes sync dry-run |
Inspect the direct sync without committing or pushing. |
release-lanes promote or promote dry-run |
Dispatch the promotion workflow with dry_run=true. |
release-lanes promote execute |
Dispatch with dry_run=false; verify the generated next-to-main PR. Merge only with merge authority. |
release-lanes verify |
Read release workflows, npm tags and GitHub releases. |
release-lanes full <scope> |
Status, the explicitly requested promotion/merge or sync steps, then verification. No unrelated release operation is implied. |
Status
Read state only:
git fetch origin main next
gh pr list --base main --head next --state open --json number,title,url,state
gh run list --workflow release.yml --branch main --limit 5 \
--json databaseId,status,conclusion,createdAt,url
gh run list --workflow release.yml --branch next --limit 5 \
--json databaseId,status,conclusion,createdAt,url
npm view platejs dist-tags --json
Record:
origin/mainSHAorigin/nextSHA- whether
origin/next:.changeset/pre.jsonexists and has tagbeta - latest GitHub release
- npm
platejsdist-tags forlatestandbeta - open promote PR, if any
- stale
sync/main-to-nextPRs, if any
Sync Main To Next
This fast mode is the whole direct sync recipe. It skips planning and panel review unless a planning artifact was requested.
Run after a stable release, after merging a promote PR, or whenever main has
commits missing from next.
Dry run first:
node tooling/scripts/release-branch-prs.mjs sync-main-to-next --dry-run
Then run the direct sync from a clean detached worktree, never from the shared checkout. The real sync checks out origin/next detached in whatever checkout runs it, and it refuses local changes. Create the worktree with git worktree add --detach ../plate-sync origin/next, run pnpm install there, and run the sync from it. Remove it afterward with git worktree remove ../plate-sync.
For an explicit dry-run request, stop after the dry run and report it.
node tooling/scripts/release-branch-prs.mjs sync-main-to-next --push
The script must:
- fetch
mainandnext - refuse real direct sync when the checkout has local tracked or untracked changes
- create the merge commit on a detached checkout of
origin/next, leaving local branches and the git identity unchanged - keep
nextbeta package versions overmainstable versions - keep
.changeset/pre.jsonfromnext, or create beta pre mode in the same sync commit whennextis out of pre mode after promotion - insert or refresh stable changelog sections from
main - create patch changesets for public packages changed by the synced
maincommits so the beta lane can publish those fixes - run
pnpm ci:versionbefore committing when beta changesets are generated, sonextreceives versioned beta package metadata instead of a pending Version Packages PR - use a
[skip release]sync commit only when no beta changesets were generated - verify the merge commit with
verify-main-to-next-sync - push directly to
origin/next; a push you type yourself starts withPSTACK_RELEASE=1, becauseguard.mjsdenies every other agent push tonextoutsideland.mjs
If the script stops on files outside known release metadata, do not guess. Resolve only when source ownership is obvious; otherwise stop with exact files.
Then watch only the workflows created by the pushed sync commit:
gh run list --branch next --limit 10 \
--json databaseId,name,workflowName,headSha,status,conclusion,displayTitle,url
gh run watch <release-run-id> --exit-status
gh run watch <ci-run-id> --exit-status
- Do not re-run broad release status commands once the pushed SHA is known.
- Do not wait on unrelated old workflow runs.
Re-Enter Beta
After a beta-to-stable promotion, next may be out of prerelease mode. The
direct main -> next sync restores beta pre mode in the same unskipped merge
commit, so the next release workflow can publish the generated beta changesets.
Use a standalone beta re-entry commit only when no direct sync is needed and no beta changesets need publication:
git switch next
git pull --ff-only origin next
pnpm changeset pre enter beta
git add .changeset/pre.json
git commit -m "chore: enter beta pre-release mode [skip release]"
PSTACK_RELEASE=1 git push origin next
If .changeset/pre.json already exists with { "mode": "pre", "tag": "beta" },
record N/A and do not create a duplicate commit.
Promote Beta To Stable
Run dry first unless the user explicitly asks for the real promotion:
gh workflow run promote.yml --ref next -f dry_run=true
gh run watch <run-id> --exit-status
For a real promotion:
gh workflow run promote.yml --ref next -f dry_run=false
gh run watch <run-id> --exit-status
Then review the generated next -> main PR:
- base
main - head
next - no
.changeset/pre.json - package versions are stable, not
-beta.* - body tells maintainers to use Create a merge commit
Merge the promote PR only when the user explicitly authorized that merge as part of the release request. Use a merge commit, not squash or rebase.
Verify Releases
Watch release workflows:
gh run list --workflow release.yml --branch main --limit 5 \
--json databaseId,status,conclusion,createdAt,url
gh run list --workflow release.yml --branch next --limit 5 \
--json databaseId,status,conclusion,createdAt,url
Verify npm:
npm view platejs dist-tags --json
npm view platejs@latest version
npm view platejs@beta version
Verify GitHub releases:
gh release list --limit 10
Stale PR Cleanup
Close stale sync/main-to-next PRs after direct sync succeeds:
gh pr list --base next --head sync/main-to-next --state open --json number,url
gh pr close <number> --comment "Closing because release-lanes synced main directly into next."
Do this only after direct sync and verification pass and the active request authorizes closing the stale PRs and posting the cleanup message.
Hard Stops
Stop only for:
- missing GitHub or npm auth needed for the requested live action
- real source conflicts outside package manifests, changelogs, and
.changeset/pre.json - release workflow failure after one clear retry or repair attempt
- npm
latestorbetapoints at an unexpected version after publication - branch protection rejects the required merge or push
- local tracked or untracked changes are present before a real direct sync