skill-release-runbook.md

Skill Release Runbook

Purpose

This runbook defines the supported release-facing behavior for the staged rust-cli skill family.

The final publish stage uses this runbook for:

• report_only readiness summaries
• repository-owned packaging reviews of generated package inputs
• local dry_run review
• exact-mirror rehearsal
• the supported GitHub Actions live_release path

Supported Baseline

• Source release branch: main
• Supported runtime: Node.js 22.x and npm 10.x
• semantic-release config: .releaserc.json
• Tracked release config: release/skill-release.config.json
• Destination path: repository root
• Publication mode: exact_mirror

Published repository paths:

• SKILL.md
• README.md
• constitution.md
• stages/
• instructions/
• templates/
• docs/release/skill-release-runbook.md
• .github/workflows/release.yml
• release/skill-release.config.json
• scripts/release/
• .releaserc.json
• package.json
• package-lock.json
• CHANGELOG.md

Generated-skill boundary:

• generated skills may include package-local packaging-ready metadata or support fixtures when the selected capability or packaging path requires them
• repository-owned CI workflows, release scripts, semantic-release config, and destination publish automation stay in this source package and are not copied into generated skill outputs

Required Inputs

• A clean release branch with Conventional Commit history.
• A current validation result for the latest substantive change.
• A configured destination repository in release/skill-release.config.json or the SKILL_RELEASE_DESTINATION_REPOSITORY environment variable.
• A destination write credential in DESTINATION_REPOSITORY_TOKEN for real cross-repository publication.

SKILL_RELEASE_DESTINATION_REPOSITORY only selects where a successful release is published. It does not bypass semantic-release: if semantic-release detects no new releasable version, the destination publish step does not run. In GitHub Actions, destination configuration is checked before semantic-release starts so missing destination inputs fail before a release tag is created, and the prepared publish tree is deployed through peaceiris/actions-gh-pages@v4.

Local Setup

1. Install the local tooling surface:

   npm install

2. Confirm the formatting baseline:

   npm run format:check

3. Ensure husky installed .husky/_ during npm install.

Packaging Boundary Review

Before any packaging-oriented mode, confirm which assets belong to which side of the boundary:

• generated package inputs:
  • the generated skill root files and directories
  • any package-local support fixtures or metadata required by the chosen path
• repository-owned packaging automation:
  • .github/workflows/release.yml
  • release/skill-release.config.json
  • scripts/release/
  • .releaserc.json
  • package.json

Packaging review should talk about both surfaces without implying the repository-owned automation is copied into every generated skill package.

Publish Modes

report_only

Use when the workflow has reached publish, but the user did not request a release action.

• summarize readiness, blockers, and next actions
• point to dry_run, rehearsal, and live_release as explicit follow-ups
• do not run release commands

dry_run

Run:

GITHUB_TOKEN=<valid GitHub token> \
npm run release:dry-run

Expected review points:

• semantic-release can distinguish release vs no-release outcomes
• an initial release is evaluated without a prior tag
• CHANGELOG.md, package.json, and package-lock.json are prepared in-memory before publish
• .work/release/publish/ is not pushed anywhere during the dry run

@semantic-release/github participates in the release pipeline, so local dry runs require either GITHUB_TOKEN or GH_TOKEN to authenticate the repository checks that happen before notes and release metadata are generated. A literal placeholder such as github_pat_or_actions_token will fail those repository auth checks until you replace it with a real token value.

rehearsal

You can rehearse the destination publish preparation step before using real credentials.

1. Point the publish preparation step at any non-placeholder destination slug or local path:

   SKILL_RELEASE_DESTINATION_REPOSITORY=owner/repo \
   node scripts/release/publish-skill-to-target-repo.mjs \
     0.0.0-local \
     v0.0.0-local \
     "$(git rev-parse HEAD)"

2. Inspect .work/release/publish/ and confirm:
   • SKILL.md, README.md, and constitution.md exist at the publish root
   • stages/, instructions/, and templates/ exist
   • docs/release/skill-release-runbook.md exists
   • .github/workflows/release.yml exists
   • release/skill-release.config.json exists
   • scripts/release/ exists
   • .releaserc.json, package.json, package-lock.json, and CHANGELOG.md exist
   • stale files were removed because the publish tree is rebuilt as an exact mirror
   • .release-manifest.json exists at the root of .work/release/publish/
   • the manifest clearly distinguishes repository-owned packaging evidence from final distributable artifacts or generated package inputs
3. Inspect .work/release/last-publication-receipt.json and confirm it records the source version, source tag, destination repository, destination branch, and destination path that the workflow will hand to the gh-pages action

live_release

The supported real release path is GitHub Actions in .github/workflows/release.yml.

1. Push a releasable commit to main, or use workflow_dispatch.
2. The workflow installs tooling with npm ci.
3. node scripts/release/verify-release-config.mjs checks destination repository resolution and required credentials.
4. npm run release:ci runs semantic-release.
5. semantic-release updates release metadata in the runner workspace, creates the source Git tag and GitHub Release, and prepares .work/release/publish plus .work/release/last-publication-receipt.json.
6. node scripts/release/prepare-destination-commit-message.mjs builds the target-repository commit message with the version number as the title and the current version's changelog section as the body.
7. peaceiris/actions-gh-pages@v4 publishes the prepared single-skill tree to the repository root of the configured external repository.
8. The workflow ends after the destination repository publish; it does not create a matching destination tag or destination GitHub Release.

The GitHub Actions workflow is repository-owned packaging automation. It may package or verify generated package inputs, but it is not itself a generated skill output.

Commit Policy

• Allowed planning scopes: plan, spec, tasks
• Planning scopes must not create a release.
• docs, style, test, build, ci, and revert commits create patch releases unless blocked by a planning scope.
• chore(deps) creates a patch release.
• feat, fix, and perf follow semantic-release defaults unless blocked by a non-releasing scope such as plan, spec, or tasks.

Local Contribution Gates

• Pre-commit hook: .husky/pre-commit Runs npm run lint-staged so only staged md, json, yml, yaml, cjs, and mjs files are formatted.
• Commit-message hook: .husky/commit-msg Runs npx commitlint --edit "$1" and blocks non-conforming Conventional Commit messages.

Destination Repository Setup

Choose one of the following configuration patterns:

• Tracked config update: Edit release/skill-release.config.json and replace REPLACE_WITH_OWNER/REPO with the real destination repository slug.
• Environment override: Keep the tracked placeholder and set SKILL_RELEASE_DESTINATION_REPOSITORY in GitHub Actions as a repository variable or secret.
• Manual dispatch override: Use the workflow_dispatch input destination_repository for a one-off release override without editing tracked config.

Destination resolution precedence in GitHub Actions is: workflow_dispatch input destination_repository > SKILL_RELEASE_DESTINATION_REPOSITORY repository variable > SKILL_RELEASE_DESTINATION_REPOSITORY repository secret > release/skill-release.config.json.

The tracked destination branch is main. If the destination repository uses a different publication branch, update release/skill-release.config.json.

Required secrets and variables:

• Secret: DESTINATION_REPOSITORY_TOKEN
• Optional variable: SKILL_RELEASE_DESTINATION_REPOSITORY
• Optional secret: SKILL_RELEASE_DESTINATION_REPOSITORY

Failure Recovery

• Missing destination credential: Set DESTINATION_REPOSITORY_TOKEN and re-run the workflow. The gh-pages publish step uses this token as the external-repository credential.
• Local dry-run authentication failed: Replace placeholder GITHUB_TOKEN or GH_TOKEN values with a real GitHub token that can authenticate the source repository, then re-run npm run release:dry-run.
• Placeholder destination repository: Replace REPLACE_WITH_OWNER/REPO in release/skill-release.config.json or define SKILL_RELEASE_DESTINATION_REPOSITORY.
• Missing runtime destination configuration: Set the workflow_dispatch input destination_repository, define SKILL_RELEASE_DESTINATION_REPOSITORY as a repository variable or secret, or update release/skill-release.config.json. The workflow fails in the preflight check before semantic-release creates a release tag.
• No release-worthy commits: Confirm commit scope and type, then use a releasable commit such as docs: refresh release runbook.
• semantic-release reported Found 0 commits since last release or There are no relevant changes, so no new version is released: This is a no-release outcome, so publish-skill-to-target-repo.mjs is skipped and nothing is pushed to the destination repository.

Timed First-Release Verification

The first-release rehearsal should fit inside 15 minutes:

1. npm install
2. Configure the destination repository or variable
3. Run npm run format:check
4. Run GITHUB_TOKEN=<valid GitHub token> npm run release:dry-run
5. Rehearse scripts/release/publish-skill-to-target-repo.mjs and inspect .work/release/publish/ plus .work/release/last-publication-receipt.json
6. Confirm the destination publish tree contains the staged workflow assets and .release-manifest.json as a reviewable metadata surface