Release Openspec

Release OpenSpec

Run the OpenSpec release workflow as a resumable state machine. Inspect live GitHub state on every invocation and take only the next safe action. Do not assume an earlier invocation completed.

Principles

• Treat Fission-AI/OpenSpec and origin/main as the release source of truth.
• Default to a read-only audit when the user asks for status, readiness, or advice.
• Treat a request to release, prepare a release, continue, or resume as authorization to perform the applicable release actions.
• Preserve the user's checkout. Never discard unrelated changes or switch their current branch just to prepare a changeset.
• Use a temporary worktree from current origin/main for release-authored commits when the checkout is dirty or not on main.
• Never approve your own PR. Human review is a deliberate gate.
• Treat merge-queue entry as an intermediate state, not a merge. Advance only after GitHub reports mergedAt and the commit is present on main.
• Never create the automated Version Packages PR manually. The Changesets action owns it.
• Never push an empty commit merely to retrigger CI. Diagnose the failed or missing run first.
• Report URLs, the state reached, and the exact human action needed whenever pausing.

Know the two PR types

Keep these distinct in output and decisions:

• Changeset PR: A normal human-authored PR that adds one or more .changeset/*.md files. Prefer adding a changeset to the feature/fix PR; create a catch-up changeset PR only for already-merged work that should be included.
• Version Packages PR: The automated changeset-release/main PR titled chore(release): version packages. Merging or adding changesets to main updates this same PR. Merging it publishes the stable release.

An open Version Packages PR does not prohibit a catch-up changeset PR. It means a catch-up PR is useful only when the audit finds missing release-worthy work. Once that PR merges, wait for the existing Version Packages PR to update.

Start with a release audit

1. Verify the repository and tools:

   • Resolve the GitHub repository with gh repo view --json nameWithOwner,url.
   • Require authenticated gh, git, and pnpm before write actions.
   • Stop before release mutations if the canonical repository is not Fission-AI/OpenSpec.

2. Refresh without modifying the worktree:

   git fetch origin main

   Do not fetch every tag indiscriminately. This repository may contain a conflicting historical local tag, which can make git fetch --tags fail even though origin/main fetched successfully.

3. Find the latest stable GitHub release. Exclude drafts and prereleases; do not use git describe, because a beta tag may be newer than the stable baseline.

   gh release list --repo Fission-AI/OpenSpec \
     --exclude-drafts --exclude-pre-releases --limit 100 \
     --json tagName,publishedAt \
     --jq 'max_by(.publishedAt) | {tagName, publishedAt}'

   Ensure that exact stable tag resolves locally before using it as a git log boundary. Fetch only that tag if it is missing. If a same-named local tag disagrees with the canonical remote, report the mismatch and use a separately resolved canonical commit; never force-rewrite the user's tag as part of an audit.

4. Find open release-related PRs:

   gh pr list --repo Fission-AI/OpenSpec --state open \
     --head changeset-release/main \
     --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup

   Identify the Version Packages PR by headRefName == "changeset-release/main", not title alone. Separately list likely changeset PRs and inspect their files; require positive additions to .changeset/*.md. Do not mistake the Version Packages PR's changeset deletions for authored changesets, and do not rely on titles because a feature/fix PR may add release tracking.

5. Read the live release policy in .changeset/README.md, pending .changeset/*.md files on origin/main, and the Version Packages PR body/files when it exists.

6. List first-parent commits since the latest stable tag:

   git log --first-parent --date=short \
     --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main

7. Map release-worthy merged PRs to existing changesets. Use PR files and changeset history; do not infer coverage from similar wording alone.

8. Classify the audit as:

   • missing-tracking: user-facing work intended for this release lacks a changeset;
   • awaiting-changeset-review: a suitable changeset PR already exists;
   • awaiting-merge-queue: an approved changeset or Version Packages PR is queued but has not landed on main;
   • awaiting-version-update: required changesets are on main, but the Version Packages PR has not incorporated them;
   • awaiting-version-review: the Version Packages PR is current but lacks approval;
   • ready-to-publish: the Version Packages PR is current, approved, and green;
   • publishing: the Version Packages PR merged but artifacts are incomplete;
   • needs-finalization: npm, tag, and GitHub Release exist but notes are still raw;
   • complete: package, tag, GitHub Release, and polished notes agree.

Present a compact audit with the stable baseline, proposed version, covered changes, possible omissions, intentionally skipped internal/docs work, open PRs, and next action.

Decide changeset coverage

Follow .changeset/README.md rather than assuming every merged PR needs a changeset.

Include work selected for release tracking, especially:

• new user-facing features or commands;
• notable fixes or hotfixes;
• breaking changes or deprecations;
• user-visible performance improvements.

Normally skip documentation-only work, tests, CI/tooling, and internal refactors. Flag ambiguous user-visible changes instead of silently excluding them. Ask the user only when the ambiguity materially changes release scope or the semantic version; otherwise use best judgment and let PR review be the approval gate.

Create or continue a changeset PR

Do this only for missing-tracking.

1. If an open changeset PR already covers the missing work, reuse it. Inspect its headRefName, head repository, and maintainerCanModify; fetch that exact head branch from its owning repository into a temporary worktree, make the update there, and push back to the same PR head. Stop if the branch is not writable. Do not create a duplicate PR or replacement branch.

2. Read .changeset/README.md immediately before authoring.

3. Only when no suitable PR exists, create a short changeset-<scope> branch from current origin/main. Use a temporary worktree so the operator's checkout remains untouched.

4. Prefer one changeset per coherent release unit. A single catch-up changeset may summarize several small items selected for the same release.

5. Use the exact package name "@fission-ai/openspec", the highest required semantic bump, only relevant headings, and user-focused descriptions.

6. Validate before pushing:

   pnpm exec changeset status

7. Commit, push, and open a PR whose body lists the covered merged PRs and explains why the catch-up is needed.

8. Stop after returning the PR URL and request human approval. Do not approve it yourself.

On a later invocation, if the PR is approved and checks are green, merge or enqueue it only when the user asked to continue or complete the release. If GitHub uses a merge queue, inspect mergeQueueEntry, queue checks, and mergedAt; remain in awaiting-merge-queue until the PR actually lands on main. Then wait for the Changesets action on main to update the existing Version Packages PR. Poll with concise progress updates; do not push an empty commit or another branch update, because that can dismiss approval and restart the queue.