What happens if GitHub Release is not configured?

The process logs GitHub Release: SKIP — not configured and stops after tag creation.

How are release notes sourced for the GitHub Release?

Notes are extracted from the [VERSION] section of CHANGELOG.md and used in gh release create.

How is VERSION determined if it isn't provided upfront?

In standalone path, VERSION is auto-detected from pyproject.toml. In pre-flight/legacy paths, it auto-detects by running git diff HEAD~1 pyproject.toml | grep version and extracting the new value.

pactkit-release

npx machina-cli add skill pactkit/claude-code-plugin/pactkit-release --openclaw

Files (1)

SKILL.md

1.8 KB

PactKit Release

Version release management — update versions, snapshot architecture, create Git tags, and publish GitHub Releases.

When Invoked

/project-release command: VERSION is passed explicitly from the command's pre-flight check.
Standalone / legacy path: VERSION is not provided — auto-detected from pyproject.toml.

Version Parameter

If VERSION is provided (e.g., by /project-release): use it directly, skip auto-detection.
If version is not provided: auto-detect by running git diff HEAD~1 pyproject.toml | grep version and extracting the new value.

Protocol

1. Version Update

Run update_version "$VERSION" via pactkit-board skill.
Update the project's package manifest (e.g., pyproject.toml, package.json).
Backfill Specs: scan docs/specs/*.md for Release: TBD and update completed ones.

2. Architecture Snapshot

Run visualize (all three modes: file, class, call).
Run snapshot "$VERSION" via pactkit-board skill.
Result: graphs saved to docs/architecture/snapshots/{version}_*.mmd.

3. Git Operations

Run archive via pactkit-board skill.
Commit: git commit -am "chore(release): $VERSION".
Tag: git tag $VERSION.

4. GitHub Release (Conditional)

Check config: Read pactkit.yaml for release.github_release.
- If release.github_release: true: proceed with GitHub Release creation.
- If release.github_release: false or section missing: log "GitHub Release: SKIP — not configured" and stop.
Extract the [$VERSION] section from CHANGELOG.md as release notes.
Create a GitHub Release: gh release create $VERSION --title "$VERSION" --notes "$NOTES".
Verify: gh release view $VERSION confirms the release exists and is marked Latest.

Source

git clone https://github.com/pactkit/claude-code-plugin/blob/main/pactkit-plugin/skills/pactkit-release/SKILL.mdView on GitHub

Overview

PactKit Release automates version management across manifests (e.g., pyproject.toml, package.json), backfills specs, creates architecture snapshots, and handles Git operations. It supports optional GitHub Release creation driven by pactkit.yaml and can auto-detect VERSION when not provided.

How This Skill Works

It updates the version via update_version, then updates project manifests and backfills docs/specs by scanning docs/specs/*.md for Release: TBD. Next it generates architecture snapshots using visualize in file, class, and call modes and saves them to docs/architecture/snapshots/{version}_*.mmd. Finally, it performs archive, commits with a chore(release) message, and tags the new version; if configured, it extracts release notes from the CHANGELOG.md [VERSION] section and creates a GitHub Release with gh release, otherwise it logs that the release is skipped.

When to Use It

When you explicitly want to release a new version using /project-release with a provided VERSION.
When running in Standalone / legacy path and relying on auto-detection from pyproject.toml.
When you need architecture snapshots for the new release to visualize changes.
When you want to publish a GitHub Release, conditioned on release.github_release in pactkit.yaml.
When you need to backfill and finalize docs/specs that were marked Release: TBD during the release.

Quick Start

Step 1: Provide a VERSION via /project-release or rely on auto-detection if VERSION is omitted.
Step 2: PactKit Release updates manifests, backfills specs, and creates architecture snapshots for the new version.
Step 3: Commit, tag the version, and optionally publish a GitHub Release using CHANGELOG notes; verify the release with gh release view.

Best Practices

Verify the VERSION is correct and does not collide with existing Git tags before release.
Keep version numbers in pyproject.toml and package.json in sync with the release.
Ensure CHANGELOG.md contains an [VERSION] section to be used as release notes.
Review docs/specs for Release: TBD and confirm they are updated as part of the release.
Test the GitHub Release path in a non-prod environment or CI to confirm notes extraction and release creation.

Example Use Cases

Releasing 1.3.0: update_version runs, architecture snapshots are created, git tag v1.3.0, and a GitHub Release is published with notes from CHANGELOG.
Auto-releasing 2.0.0-beta via the legacy path; version auto-detected from pyproject.toml; GitHub Release is skipped if not configured.
Snapshot for 2.1.0: architecture/snapshots/2.1.0_*.mmd are generated; commit and tag 2.1.0.
Release 0.9.5 with GitHub Release disabled: only local commit and tag are created.
Dry-run release: pactkit-release reports potential changes without pushing commits or creating a GitHub Release.

Frequently Asked Questions

Add this skill to your agents