release-openspec

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 6cfcf327ccd6 · 29 Oct 2026Report an issue or request a re-scan

• Publisherfission-ai GitHub organizationOwner of the repository this skill is read from
• Source folderfission-ai/openspec/.agents/skills/release-openspecThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict6cfcf327ccd6A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use this skill when releasing OpenSpec: audit merged work and changeset coverage, decide whether a catch-up changeset PR is needed, prepare or resume the Changesets Version Packages PR, cut a beta or stable release,…

---
name: release-openspec
description: >-
  Use this skill when releasing OpenSpec: audit merged work and changeset
  coverage, decide whether a catch-up changeset PR is needed, prepare or resume
  the Changesets Version Packages PR, cut a beta or stable release, verify
  publishing, and polish GitHub release notes. Also use when asked whether an
  open release PR is complete, what the next release step is, or to continue a
  release paused for human approval.
---

# 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:

   ```bash
   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.

   ```bash
   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:

   ```bash
   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:

   ```bash
   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 w

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/fission-ai/openspec
git -C openspec checkout 6cfcf327ccd6

Works in

1. 2026-10-29
   ✓SAFE B 89 / 100

   first audit · source 6cfcf327ccd6

Questions about release-openspec

• github.com/fission-ai/openspec/tree/main/.agents/skills/release- — the audited source at commit 6cfcf327ccd6 and every finding aboveObserved · 29 Oct 2026

Spotted something wrong? Report a correction · Methodology