| name | release-manager |
| description | Orchestrate the transition from "ready" to "released" for GSD-Antigravity. Manage version numbers in package.json, update changelogs, build release artifacts, and trigger Git tagging, GitHub releases, and NPM package publishing. Triggers on keywords like 'release', 'tagging', 'versioning', 'changelog update', and intents like 'perform a release' or 'prepare v1.0.1'. |
Release Manager (Zero-Manual Automation)
Comprehensive automation engine for managing the software release lifecycle for gsd-antigravity-kit. The orchestrator handles data integrity, automated documentation synchronization (Changelog/KB/README), and a one-click Git/NPM distribution process.
⚡ Zero-Manual Execution
This skill is designed for full automation. Initiating a release handles versioning, changelog generation, and publication in a single pass.
- Finalize your features/fixes.
- Run the orchestrator:
pwsh .agent/skills/release-manager/scripts/release.ps1
- The system will sync GSD, update docs, tag, push, and publish automatically.
Purpose
To provide a deterministic, multi-phase procedure for transitioning the codebase from a "ready" state to a "tagged and released" state on GitHub and as a published package on NPM.
Prerequisites
- GitHub CLI (
gh):
- Check for local install:
.agent\skills\release-manager\bin\gh.exe
- Check for global install:
gh
- Authenticated: Must be logged in (
.\.agent\bin\gh.exe auth login or gh auth login).
- NPM: Must be logged in to publish (
npm whoami).
🚀 Release Workflow
Phase 0: Readiness Check (CRITICAL)
Before starting a release, ensure the following:
- Git Cleanliness: Ensure
git status is clean (no uncommitted changes except release prep).
- GSD Sync: Run the converter to ensure
.agent/skills/gsd is up-to-date with the latest gsd-tools discovery logic.
py .agent/skills/gsd-converter/scripts/convert.py gsd
- Command Library Check: Verify that
\.agent\skills\gsd\references\commands\ is populated with all migrated Skill documents (approx. 17+ files).
- Tests: Run
npm test if tests are defined.
- Auth Check (GitHub):
$ghPath = ".\.agent\skills\release-manager\bin\gh.exe"
if (-not (Test-Path $ghPath)) { $ghPath = "gh" }
& $ghPath auth status
- Auth Check (NPM):
npm whoami
Phase 1: Strategic Versioning (Auto-Increment)
Determine the next version number. If not provided by the user, default to PATCH (e.g., 1.0.0 -> 1.0.1).
Command:
# Bump version in package.json without creating a git tag yet
npm version patch --no-git-tag-version
Phase 2: Documentation Synchronization (MANDATORY)
STOP: You must ensure the release is fully documented before proceeding to GitHub.
- Changelog: Ensure
CHANGELOG.md is updated with all features, fixes, and the correct version number.
- Knowledgebase (KB): Update
docs/DEV_KNOWLEDGEBASE.md using the Knowledgebase Update Protocol:
- Input: Read
CHANGELOG.md and git log for "Fixed" items.
- Analysis: For each fix, identify Context, Issue, Root Cause, and Technical Fix.
- Output: Append details under the version header in
docs/DEV_KNOWLEDGEBASE.md.
- README: Update
README.md version badges and release summary.
- Action: Search for
[![Release Version] and update the version string in the badge URL.
- Verification: Do not run Git commits or
gh release until these files are saved and verified.
Phase 3: Archive & Package
Create the release artifact for GitHub (Source Zip):
- Get Version:
$package = Get-Content package.json | ConvertFrom-Json
$ver = $package.version
- Archive: Zip the repository content. We exclude local project data (
.planning, .antigravity, __tobedeleted), temporary Git files, and the local gh.exe binary to keep the release lightweight.
$packageName = $package.name
$excludes = @("node_modules", ".git", "__tobedeleted", "*.zip", ".antigravity", ".planning", "*.bak", "gh.exe", ".agent/skills/release-manager/bin/gh.exe")
$files = Get-ChildItem -Path . -Exclude $excludes
Compress-Archive -Path $files -DestinationPath "$packageName_v$ver.zip" -Force
Phase 4: Release Execution
- Commit: Commit the version bump and doc updates:
git commit -am "chore: release v$ver"
- Tag: Create a git tag:
git tag "v$ver"
- Push: Push commits and tags:
git push && git push --tags
Phase 5: GitHub Release (Automatic upload)
Automatically create the release and upload the archive zip file.
Fix for Upload Issues:
We disable HTTP/2 ($env:GODEBUG="http2client=0") to prevent "request body larger than specified content length" errors.
Command:
$ghPath = ".\.agent\skills\release-manager\bin\gh.exe"
if (-not (Test-Path $ghPath)) { $ghPath = "gh" }
$package = Get-Content package.json | ConvertFrom-Json
$ver = $package.version
$packageName = $package.name
$env:GODEBUG="http2client=0"
& $ghPath release create "v$ver" "$packageName`_v$ver.zip" --generate-notes
Phase 6: NPM Publication
- Orchestrated Publish: The
release.ps1 script will attempt npm publish automatically at the end of the workflow.
- Manual Fallback: If the script is run with
--skipNpm or fails, you can publish manually:
# For public packages
npm publish
Verification:
npm info gsd-antigravity-kit version
Phase 7: Release Cleanup
Remove old ZIP files from the project root.
$package = Get-Content package.json | ConvertFrom-Json
$packageName = $package.name
Get-ChildItem "$packageName`_v*.zip" | Sort-Object LastWriteTime -Descending | Select-Object -Skip 2 | Remove-Item -Force
🛠️ Interactive Checklist
🔍 Troubleshooting
| Issue | Potential Cause | Fix |
|---|
gh command not found | GitHub CLI missing. | Ensure .agent\skills\release-manager\bin\gh.exe exists or gh is in PATH. |
| Auth Error (GitHub) | Token expired or not logged in. | Run gh auth login. |
| Auth Error (NPM) | Not logged in. | Run npm login. |
| Upload Error (HTTP/2) | request body larger... | Ensure $env:GODEBUG="http2client=0" is set. |
| NPM Name Conflict | Package name taken. | Update name in package.json. |
