release-manager

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.

1. Finalize your features/fixes.
2. Run the orchestrator: pwsh .agent/skills/release-manager/scripts/release.ps1
3. 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:

1. Git Cleanliness: Ensure git status is clean (no uncommitted changes except release prep).
2. 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
   

3. Command Library Check: Verify that \.agent\skills\gsd\references\commands\ is populated with all migrated Skill documents (approx. 17+ files).
4. Tests: Run npm test if tests are defined.
5. Auth Check (GitHub):

   $ghPath = ".\.agent\skills\release-manager\bin\gh.exe"
   if (-not (Test-Path $ghPath)) { $ghPath = "gh" }
   & $ghPath auth status
   

6. 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.

1. Changelog: Ensure CHANGELOG.md is updated with all features, fixes, and the correct version number.
2. 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.
3. README: Update README.md version badges and release summary.
   • Action: Search for [![Release Version] and update the version string in the badge URL.
4. 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):

1. Get Version:

   $package = Get-Content package.json | ConvertFrom-Json
   $ver = $package.version
   

2. 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

1. Commit: Commit the version bump and doc updates: git commit -am "chore: release v$ver"
2. Tag: Create a git tag: git tag "v$ver"
3. 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

1. Orchestrated Publish: The release.ps1 script will attempt npm publish automatically at the end of the workflow.
2. 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

• Phase 0: Readiness Check
  • Git Cleanliness
  • GSD Sync (convert.py gsd)
  • Verify references/commands/ population
  • npm test (if applicable)
  • gh auth status
  • npm whoami
• Phase 1: Strategic Versioning
  • npm version patch --no-git-tag-version
• Phase 2: Documentation Synchronization (Automated)
  • Update CHANGELOG.md (Self-writing via release.ps1)
  • Update docs/DEV_KNOWLEDGEBASE.md (Fix summary via release.ps1)
  • Update README.md (Badge URL replacement via release.ps1)
• Phase 3: Archive & Package
  • Create ZIP archive: gsd-antigravity-kit_v1.0.X.zip
• Phase 4: Release Execution
  • Git Commit & Tag
  • Git Push
• Phase 5: GitHub Release
  • gh release create ... (with GODEBUG=http2client=0)
• Phase 6: NPM publication
  • npm publish
• Phase 7: Release Cleanup
  • Remove old local ZIPs

🔍 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.