Release Lanes

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.

One invocation is permission to run the lane until completion. Ask again only for hard stops.

Autogoal Contract

This is a derived autogoal skill.

Default flow mode: one-shot execution.

Use:

node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \
  --template release-lanes \
  --title "release lane maintenance"

Create or continue a goal before mutating remote release branches. The goal is complete only when the requested lane state is true and the template gates pass.

Lanes

• main publishes stable packages with npm tag latest.
• next publishes prerelease packages with npm tag beta.
• .changeset/pre.json belongs on next only.
• main must never publish while .changeset/pre.json exists.
• Major changesets target next for beta before stable promotion.
• Minor changesets target main, not next.
• Patch changes may target main; use next patch changes only for active beta-lane fixes or direct-sync beta metadata.

Modes

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/main SHA
• origin/next SHA
• whether origin/next:.changeset/pre.json exists and has tag beta
• latest GitHub release
• npm platejs dist-tags for latest and beta
• open promote PR, if any
• stale sync/main-to-next PRs, if any

Sync Main To Next

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:

node tooling/scripts/release-branch-prs.mjs sync-main-to-next --push

The script must:

• fetch main and next
• refuse real direct sync when the checkout has local tracked or untracked changes
• create a merge commit on next
• keep next beta package versions over main stable versions
• keep .changeset/pre.json from next, or create beta pre mode in the same sync commit when next is out of pre mode after promotion
• insert or refresh stable changelog sections from main
• create patch changesets for public packages changed by the synced main commits so the beta lane can publish those fixes
• run pnpm ci:version before committing when beta changesets are generated, so next receives 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

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.

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

Merging the promote PR is allowed when the user asked for full automation or merge. 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.

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 latest or beta points 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

Do not stop to ask whether to run the next obvious lane step. The goal plan is the authorization boundary.

Handoff

Report:

• main SHA and next SHA
• promote PR URL or N/A
• direct sync result and pushed commit
• beta pre mode state
• release run URLs
• npm latest and beta versions
• stale PR cleanup
• residual risk or none