goal-release

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal Release

new_version = the user's request

This skill drives a release all the way to merge. It uses the `draft-release` skill to
open the release pull request (and create the draft GitHub release), waits for
the PR's CI checks to pass, runs the `merge-pr` skill to merge it, and finally
completes any post-release distribution update that can only happen once the
release assets are built.

## 1. Draft the Release

Use the `draft-release` skill with `new_version`.

- If `new_version` is provided (e.g. `v1.2.3` or `1.2.3`), it must match the
  semver shape `^v?\d+\.\d+\.\d+$` — if it does not, stop and report instead
  of passing it on. Pass a valid value through unchanged; the `draft-release` skill
  normalizes the `v` prefix itself.
- If `new_version` is empty, pass no argument; the `draft-release` skill determines the
  next version automatically via the `release-dry-run` skill.

When the `draft-release` skill finishes, it has:

- created a `release/v<version>` branch with the version-bump commits,
- opened a pull request against `main`, and
- created a draft GitHub release `v<version>` with the release notes.

If the `draft-release` skill failed partway (e.g. the PR exists but the draft release
was not created, or it stopped before opening the PR), stop here and report
the partial state to the user instead of continuing.

## 2. Resolve the Release PR

Use the PR number or URL that the `draft-release` skill's `gh pr create` printed in
Step 1 when available. Otherwise, identify the pull request from the current
`release/v<version>` branch:

```bash
gh pr view --json number,title,state,headRefName
```

Confirm that `headRefName` matches the `release/v<version>` branch created in
Step 1. This skill must only ever merge that release PR — if the resolved PR
is a different one, stop and report to the user instead of merging.

## 3. Wait for CI

Wait for the release PR's GitHub Actions checks to finish:

```bash
gh pr checks <pr_number> --watch
```

If the watch reports that no checks are registered yet, wait a moment and
retry — checks can take a few seconds to appear right after the PR is opened.

- If every check passes, proceed to Step 4.
- If a check fails, investigate and fix the failure on the release branch
  (run the project's CI check script locally — `pnpm cicheck` when it exists —
  then commit and push), and wait for the re-run.
  Never proceed to the merge while any check is `fail` or `pending`.
- Fixes must legitimately resolve the failure. Never make a check green by
  skipping or deleting tests, weakening lint or type-check configuration, or
  editing GitHub Actions workflows.
- Set a safety cap of **3** fix attempts. If CI is still red after the cap,
  stop and report the failing checks to the user instead of merging.

If any fix commit beyond the `draft-release` skill's own version-bump commits was
pushed, stop before merging and report the extra commits to the user for
confirmation. The release PR must reach the merge step containing only
reviewed, expected content.

## 4. Merge the Release PR

Use the `merge-pr` skill with the release PR number. It re-verifies the PR
state and CI status, merges with `gh pr merge --admin --merge`, posts a
thank-you comment, and cleans up the local branch.

Note: the `goal-pr` skill tells agents not to auto-merge PRs that touch `package.json`
or release configuration. That restriction does not apply here — merging the
version-bump release PR is this skill's explicit purpose, and the user opted
into it by invoking the `goal-release` skill.

## 5. Finish the Post-Release Distribution Update

Many projects publish release artifacts from a workflow that runs after the
release PR merges, and maintain a downstream distribution file that embeds the
checksums of those artifacts (a Homebrew tap formula, a package manifest for
another registry, and so on). Such a file can only be regenerated once the
assets exist.

First determine whether this project has such a step at all — check its release
documentation, `.github/workflows/**`, and any generator script under
`scripts/**`. **If it does not, skip straight to Step 6** and say so in the
report.

When it does:

1. Wait for the asset-publishing workflow run triggered by the merge to
   complete:

   ```bash
   gh run list --workflow "<asset workflow name>" --branch "release/v<version>" \
     --limit 1 --json databaseId,status,conclusion,headBranch
   gh run watch <run_id>
   ```

   Such workflows commonly trigger on every closed PR to `main` (non-release
   runs are job-level skipped but still listed), so filter by the release
   branch as shown. The run can take a few seconds to appear right after the
   merge — if the list is empty, wait and retry. Confirm the watched run
   belongs to this release (its `headBranch` is the `release/v<version>` branch
   of the PR merged in Step 4) and concluded with `success`. If it failed, stop
   and report — the distribution file must not be regenerated from stale
   assets.

2. Wait until the GitHub release is published (no longer a draft). Draft-release
   asset URLs return 404 for unauthenticated users, and package managers
   normally fetch the distribution file straight from `main`, so landing it

From dyoshikawa/skills, MIT.

More from dyoshikawa/skills