project-release-workflow

name	project-release-workflow
description	Create and push a release tag to trigger GitHub Release workflow.
argument-hint	<vX.Y.Z> [--dry-run] [--force-tag]
allowed-tools	Bash, Read, Edit, Write, Grep, Glob

Release Tag

Contract

Prereqs:

• Run inside this repository git work tree.
• git available on PATH.
• gh available on PATH and authenticated (gh auth status) for GitHub remotes.
• semantic-commit available on PATH (used for automated version-bump commit when needed).
• If tracked package*.json files are present: node available on PATH (used for JSON version sync).
• Remote origin configured and reachable.
• Release workflow listens on v* tags:
  • .github/workflows/release.yml
  • on.push.tags: ["v*"]

Inputs:

• Required:
  • <version> (for example v0.1.0)
• Optional:
  • --remote <name> (default origin)
  • --dry-run (validate and print planned actions only)
  • --force-tag (overwrite existing local/remote tag with same version)
  • --poll-seconds <n> (default 15)
  • --max-wait-seconds <n> (default 1800)

Outputs:

• Syncs version values to the provided input version (vX.Y.Z -> X.Y.Z) for:
  • explicit version = "..." entries in tracked Cargo.toml files
  • tracked workflows/*/workflow.toml manifests (excluding _template)
  • tracked root package.json and package-lock.json version fields
  • workflows/bangumi-search/src/info.plist.template BANGUMI_USER_AGENT placeholder (nils-bangumi-cli/X.Y.Z)
• Refreshes tracked Cargo.lock workspace package versions when present.
• Regenerates tracked root THIRD_PARTY_LICENSES.md when its inputs changed.
• Creates a version-bump commit when sync changes are needed.
• Pushes the version-bump commit to the current upstream branch.
• Waits until CI workflow (.github/workflows/ci.yml) for the release head commit is success (GitHub remotes).
• Creates an annotated git tag (Release <version>).
• Pushes tag to remote (git push <remote> refs/tags/<version>).
• Waits until the release workflow run for the pushed tag is success.
• Waits until release page exists for the pushed tag (GitHub remotes).
• Success is reported only after both checks above pass.

Exit codes:

• 0: success
• 1: operational failure (git/remote/tag push error)
• 2: usage error
• 3: precondition failure (not git repo, dirty tree, missing remote, duplicate tag)
• 124: timeout while waiting for release workflow/release page

Failure modes:

• Invalid version format (must start with v).
• Working tree not clean.
• Current branch has no upstream or is behind upstream.
• Tag already exists locally or on remote.
  • Use --force-tag when re-tagging an existing release version is intentional.
• origin (or provided remote) not configured.
• Push failed due to auth/permissions/network.
• CI workflow run failed for the release head commit.
• Release workflow run failed for the pushed tag.
• Release page did not appear before timeout.

Scripts (only entrypoints)

• <PROJECT_ROOT>/.agents/skills/project-release-workflow/scripts/project-release-workflow.sh

Workflow

1. Validate repository state (git repo, clean tree, remote exists, upstream branch ready).
2. Validate version format and tag uniqueness (local + remote).
3. Sync versions (Cargo.toml + workflow manifests + root package*.json + Bangumi User-Agent placeholder), refresh Cargo.lock and tracked THIRD_PARTY_LICENSES.md as needed, then commit/push when changes exist.
4. Wait CI workflow (.github/workflows/ci.yml) for the release head commit to complete with success.
5. Create annotated tag Release <version>.
6. Push tag to remote.
7. Wait release workflow for the tag to complete with success.
8. Wait release page to appear for the tag.
9. If CI/release workflow fails, fix root cause on branch, update/push fix commit, then recreate/re-push tag and repeat until green.

Boundary

This is a project-local skill scoped to cutting and publishing a release for this repository: version sync, release-head CI gating, annotated tag creation, and release-page verification on the configured remote. The broader allowed-tools set exists only to support the step 9 fix-and-retag loop on a failing release; it must not mutate runtime-kit manifests, rendered product output, global runtime homes, credentials, or sessions. Re-tagging an existing release version requires the explicit --force-tag flag.

Alternate entry points

This skill is also reachable through the Claude Code /release slash command, which dispatches here via <repo>/.agents/scripts/release.sh — a thin wrapper that execs the script above. Args forward unchanged; behaviour is identical whether you invoke the skill directly or type /release v0.1.0.

The skill script remains the canonical implementation per the multi-CLI mirror rule (see claude-kit's docs/dispatcher-commands.md): codex / opencode discover work through .agents/skills/, Claude Code reaches the same logic through the dispatcher convention.