Release Skill

Structured workflow for shipping code: PR creation, automated policy review, merge, and cleanup. Process each step in order — do not skip ahead.

Step 1 — Verify Readiness

• Confirm you're on a feature branch (not main/master)
• Run the test suite — all tests must pass
• Run the linter — no warnings or errors
• If anything fails, fix it before proceeding

Step 2 — Create PR

• Push the branch: git push -u origin <branch>
• Create the PR with gh pr create:
  • Title: <type>(<scope>): <imperative summary>
  • Body:

    ## Summary
    <what changed and why — 1-3 bullet points>
    
    ## Test plan
    - [ ] <verification steps>

Proceed immediately to Step 3 — do not wait for reviews before reasoning about version.

Step 3 — Reason About Versioning

Decide the version bump:

• Patch (default): bug fixes, internal changes. Handled automatically by tesslio/patch-version-publish — no manifest update needed
• Minor: new features, backward-compatible additions. Update the version in the project manifest
• Major: breaking changes. Update the version in the project manifest

Step 4 — Policy Review Fires Automatically

Pushing the PR branch triggers the runnable GitHub Actions workflow .github/workflows/review.lock.yml ("PR Policy Review") on the pull_request event. The .github/workflows/review.md file is the gh-aw source that compiles into that lock file via gh aw compile. The workflow runs on every opened, synchronize, and reopened — no explicit request mutation. The review is submitted by github-actions[bot] and uses OpenAI gpt-5.4 via the gh-aw Codex engine, checking the diff against the in-tree rules/*.md from the PR head.

Proceed immediately to Step 5 — do not stop after creating the PR. The skill runs end-to-end: once gh pr create succeeds, the next action is always to start watching.

Trial — keep Copilot in parallel. During gh-aw validation, also request Copilot:

skills/release/request-copilot-review.sh <owner> <repo> <pr-number>

Uses GraphQL (REST drops bot reviewers), falls back to discovering the bot ID from recent reviews if the pinned BOT_kgDOCnlnWA goes stale, verifies Copilot is in requested_reviewers. Exits non-zero on failure; emits a JSON summary on success. Both reviews gate the merge. This paragraph and the script are retired in a cleanup PR once gh-aw is validated on 1–2 PRs.

Step 5 — Poll PR State

Capture a single JSON snapshot of CI status, bot review states, and inline comment counts:

skills/release/poll-pr-reviews.sh <owner> <repo> <pr-number>

The script returns:

• ci.status — pending | success | failure | none (the gh-aw workflow appears here as a check once it has run)
• reviews.gh_aw.state and reviews.copilot.state — latest review per bot (APPROVED | CHANGES_REQUESTED | COMMENTED | none)
• inline_comments.gh_aw and inline_comments.copilot — top-level inline comment counts

Interpreting review states (per bot independently):

• APPROVED — no issues
• CHANGES_REQUESTED — comments need addressing
• COMMENTED — observations; read and decide per thread

Loop until ci.status is success (or none if no checks are configured) and neither review state is CHANGES_REQUESTED. If the gh-aw review check ran but no review was posted, inspect logs with gh run view --log-failed. Do not retry via GraphQL — gh-aw is event-triggered, not request-triggered.

Step 6 — Address Feedback; No Re-request Needed

• CI failures: Fix every one, no exceptions
• Review suggestions: Apply what's right and reasonable. Push back on anything that misreads scope or over-engineers — but cite concrete evidence (file:line, log line, spec quote) when declining; never hand-wave
• Reply on EVERY thread — nothing left dangling:
  • Accepted: "Fixed in <sha>"
  • Declined: "Declining — <reason with cited evidence>"
• Push fixes to the same branch
• Re-run is automatic: pull_request: synchronize re-triggers the gh-aw workflow on every push — no manual re-request. During the trial, Copilot still needs a re-request via skills/release/request-copilot-review.sh (same args as Step 4).
• Repeat Step 5 until every active bot review is APPROVED or COMMENTED with no blocking items, and every thread has a reply.

Step 7 — Merge + Cleanup

Only proceed when CI is green AND the latest gh-aw review has zero blocking comments AND (during trial) the latest Copilot review has zero comments AND all review threads have replies.

# Merge
gh pr merge <N> --merge --delete-branch

# Update local
git checkout main && git pull --ff-only

# Clean up local branch
git branch -d <branch>

# Prune stale remote refs
git remote prune origin

After merge:

• Verify the merge landed on main
• Check that the publish CI workflow was triggered
• Report the outcome: merged PR URL, version published (if applicable)

Finish here — the skill is complete.