stable-release

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Stable Release

Read `docs/operations/release-process.md` before every stable-release execution
or workflow change. Treat that runbook and the current release scripts as the
canonical command and asset contract. If this skill disagrees with them, stop
and report the drift instead of improvising.

Run commands from the repository root. For prerelease versions, use
`pa-brat-beta-release` instead.

## Resolve Intent

Classify the current request before changing state:

- `prepare`: inspect state and show the dry run. Do not create a release commit
  or tag, push anything, create a GitHub Release, or submit a hosted community
  review.
- `local-release`: prepare, then let release automation validate and create the
  local release commit and annotated tag. Do not push.
- `publish`: complete the local release when needed, push `master` and the tag,
  wait for the workflow, verify the GitHub Release, then verify official
  recognition through `Check for new releases` when needed.
- `verify`: inspect an already-published target and complete only the
  requested follow-up verification. Do not recreate its release commit or tag
  or push again. For official recognition, proceed to the section below after
  verifying the existing GitHub Release.

Treat an explicit current-turn request that names the target version and asks to
publish as authorization for the complete `publish` flow. Do not ask again only
because the dry run finished. Ask before mutation only when:

- the target version, branch, or requested intent is ambiguous;
- the proposed version or scope differs from what the user authorized;
- the dry run reveals unexpected commits, release notes, or risk;
- a blocking gate requires a product or risk-acceptance decision; or
- recovery would delete, rewrite, or move a release tag.

## Safety Boundaries

- Cut stable releases only from `master` with a clean worktree.
- Never publish without explicit publish intent in the current turn.
- Never delete, rewrite, or move release tags without an explicit maintainer
  decision.
- Stop on failed validation, unresolved hosted community `Error`, or workflow
  failure. Report the evidence; do not bypass the gate.
- Preserve unrelated user changes. Do not stash, clean, switch branches, or
  reconcile divergence without authorization.

## Inspect State

Run:

```bash
git status --short --branch
git branch --show-current
node -p "require('./package.json').version"
git tag --sort=-v:refname | sed -n '1,20p'
git fetch origin master
git rev-parse HEAD
git rev-parse origin/master
```

Stop if the worktree is dirty or the branch is not `master`.

Resolve one of these states:

- Fresh source state: the target is greater than `package.json`, its tag does
  not exist, and `HEAD` equals `origin/master`.
- Existing local-release state: `package.json` equals the target, the target tag
  points to `HEAD`, and `HEAD^` equals `origin/master`. Do not recreate the
  release commit.

Stop on any other local/remote or version/tag relationship and ask the user how
to reconcile it. If no version was supplied, use the read-only changelog preview
to propose one, then obtain approval before changing release state:

```bash
node scripts/changelog.mjs --target-version <candidate>
```

## Dry Run Fresh Releases

For a fresh source state, always run:

```bash
make release-dry-run VERSION=<target-version>
```

Report the current and target versions, changelog range, commit subjects, and
generated section. Continue directly when they match an already-authorized
`local-release` or `publish` request. A previously created local-release state
cannot be dry-run again with the same version; validate its release commit and
tag instead.

## Community Review Policy

Stable preparation and publication do not run a hosted source `Preview`,
including an optional preview. Release automation retains source validation,
eligible CI reuse and final tag/asset checks. Use `obsidian-community-check`
only in `release` mode after GitHub publication, as described below.

Hosted-only defects may therefore be discovered after GitHub publication.
Diagnose them and follow the recovery section; do not claim official recognition
while an `Error` remains unresolved.

## Create Local Release

For a fresh `local-release` or `publish` flow, run the release automation:

```bash
make release VERSION=<target-version>
```

Do not pass `SKIP_CHECKS=1` or `--skip-checks`. Do not use `make deploy` as a
substitute: `make release` owns its whitespace, notices and release-critical
docs checks. It reuses complete successful CI for the exact synchronized master
source when eligible; otherwise it runs local lint, build, coverage and bundle
audit. `RELEASE_LOCAL_CHECKS=1` forces the full local gate for diagnosis.
The final tag always builds versioned assets and runs artifact tests with valid

From edonyzpc/personal-assistant, AGPL-3.0.

More from edonyzpc/personal-assistant