name	release-procedures
description	Version management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.
license	MIT
metadata	{"author":"groupzer0","version":"1.0"}

Release Procedures

Systematic approach to packaging and releasing software. Use this skill when:

DevOps prepares a release for deployment
Implementer updates version files during milestones
Planner specifies version bumps in plans

Release Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Two-Stage Release Flow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  STAGE 1: Per-Plan (repeat for each plan in release)            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. QA Complete                                         │    │
│  │  2. UAT Approved                                        │    │
│  │  3. DevOps commits locally (NO PUSH)                    │    │
│  │  4. Update plan status: "Committed for vX.Y.Z"          │    │
│  │  5. Notify Roadmap of commit                            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  STAGE 2: Per-Release (once all plans committed)                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. All plans for release committed                     │    │
│  │  2. User approves release                               │    │
│  │  3. Git tag, push, publish                              │    │
│  │  4. Update all plan statuses: "Released"                │    │
│  │  5. Hand off to Retrospective                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

Bump	When	Examples
MAJOR	Breaking changes	API signature change, removed feature
MINOR	New features (backward compatible)	New command, added option
PATCH	Bug fixes (backward compatible)	Fixed crash, corrected behavior

Pre-Release Versions

1.2.3-alpha.1    # Early development
1.2.3-beta.1     # Feature complete, testing
1.2.3-rc.1       # Release candidate

When to Bump

Change Type	Version	Rationale
Fix typo in docs	PATCH	No code change
Fix bug	PATCH	Backward compatible
Add new feature	MINOR	New capability
Deprecate feature	MINOR	Still works
Remove deprecated	MAJOR	Breaking
Change API contract	MAJOR	Breaking

Version Consistency Checklist

All version references must match before release:

File	Field	Example
`package.json`	`version`	`"version": "1.2.3"`
`CHANGELOG.md`	Latest heading	`## [1.2.3] - 2024-12-19`
`README.md`	Badge/install (if versioned)	May be "latest"
Platform config	Varies	See platform-specific

Verification Command

# Extract and compare versions
PACKAGE_VERSION=$(jq -r .version package.json)
CHANGELOG_VERSION=$(grep -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md | head -1)

if [ "$PACKAGE_VERSION" != "$CHANGELOG_VERSION" ]; then
  echo "VERSION MISMATCH: package.json=$PACKAGE_VERSION, CHANGELOG=$CHANGELOG_VERSION"
  exit 1
fi

Platform-Specific Constraints

VS Code Extensions

Constraint	Requirement
Version format	3-part semver only (X.Y.Z)
Pre-release	Use odd minor version (e.g., 1.1.0)
Engine	Specify minimum VS Code version

{
  "version": "1.2.3",
  "engines": { "vscode": "^1.80.0" }
}

npm Packages

Constraint	Requirement
Version	Standard semver
Pre-release	`-alpha.1`, `-beta.1` allowed
Deprecation	Use `npm deprecate`

Python Packages (PyPI)

Constraint	Requirement
Version	PEP 440 compliant
Pre-release	`a1`, `b1`, `rc1` suffixes
Location	`setup.py`, `pyproject.toml`, or `__version__`

CHANGELOG Format

Follow Keep a Changelog:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.2.3] - 2024-12-19

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

### Deprecated
- Feature to be removed

### Removed
- Removed feature

### Security
- Security fix description

Categories Order

Added (new features)
Changed (changes to existing)
Deprecated (soon to be removed)
Removed (now removed)
Fixed (bug fixes)
Security (vulnerability fixes)

Pre-Release Verification

Mandatory Checks

Check	Command/Action	Fail Response
UAT Status	Read `agent-output/uat/`	STOP if not "APPROVED FOR RELEASE"
QA Status	Read `agent-output/qa/`	STOP if not "QA Complete"
Version Match	Compare all version files	STOP and fix
Tests Pass	Run test suite	STOP and fix
Clean Workspace	`git status`	Commit or stash
No Debug	Check for debug flags	Remove before release

Pre-Commit Cleanup

# Ensure no debug artifacts
grep -r "console.log" src/ --include="*.ts" && exit 1
grep -r "debugger" src/ --include="*.ts" && exit 1
grep -r "TODO: remove" src/ && exit 1

Release Execution

Git Tagging

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"

# Push tag
git push origin v1.2.3

Publication Commands

Platform	Command
VS Code	`vsce publish`
npm	`npm publish`
PyPI	`twine upload dist/*`
GitHub	`gh release create v1.2.3`

Post-Publication Verification

Check	Method
Version visible	Check marketplace/registry
Installable	Fresh install test
Changelog visible	Check release notes
No errors	Check for publish warnings

Agent Responsibilities

DevOps Agent (Two-Stage Release)

Stage 1 (Per-Plan): After UAT approval, commit changes locally with detailed message. Do NOT push.
Stage 2 (Per-Release): After all plans committed and user approves release, push and publish.
Track which plans are committed for current release
Coordinate with Roadmap agent to maintain release→plan mappings
Never push without explicit release approval
Document in agent-output/deployment/

Implementer Agent

Update package.json version during milestones
Update CHANGELOG.md with changes
Commit version updates as part of implementation
Follow plan's specified version bump

Planner Agent

Specify target release version in plan header
Multiple plans may share the same target release
Coordinate with Roadmap agent for release assignments
Include version update in final milestone

Roadmap Agent

Maintain Active Release Tracker section
Track current working release version
Monitor plan→release mappings
Notify when all plans for a release are committed

Rollback Procedure

If release fails:

Unpublish (if platform allows)
- npm: npm unpublish package@version (within 72h)
- VS Code: Unpublish via dashboard

Delete tag (if needed)

git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

Document in deployment log
Notify stakeholders of rollback

See references/release-templates.md for deployment document templates.

name	release-procedures
description	Version management, release verification, and deployment procedures for software releases. Includes semver guidance, version consistency checks, and platform-specific constraints.
license	MIT
metadata	{"author":"groupzer0","version":"1.0"}

Release Procedures

Systematic approach to packaging and releasing software. Use this skill when:

DevOps prepares a release for deployment
Implementer updates version files during milestones
Planner specifies version bumps in plans

Release Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Two-Stage Release Flow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  STAGE 1: Per-Plan (repeat for each plan in release)            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. QA Complete                                         │    │
│  │  2. UAT Approved                                        │    │
│  │  3. DevOps commits locally (NO PUSH)                    │    │
│  │  4. Update plan status: "Committed for vX.Y.Z"          │    │
│  │  5. Notify Roadmap of commit                            │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  STAGE 2: Per-Release (once all plans committed)                │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  1. All plans for release committed                     │    │
│  │  2. User approves release                               │    │
│  │  3. Git tag, push, publish                              │    │
│  │  4. Update all plan statuses: "Released"                │    │
│  │  5. Hand off to Retrospective                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

Bump	When	Examples
MAJOR	Breaking changes	API signature change, removed feature
MINOR	New features (backward compatible)	New command, added option
PATCH	Bug fixes (backward compatible)	Fixed crash, corrected behavior

Pre-Release Versions

1.2.3-alpha.1    # Early development
1.2.3-beta.1     # Feature complete, testing
1.2.3-rc.1       # Release candidate

When to Bump

Change Type	Version	Rationale
Fix typo in docs	PATCH	No code change
Fix bug	PATCH	Backward compatible
Add new feature	MINOR	New capability
Deprecate feature	MINOR	Still works
Remove deprecated	MAJOR	Breaking
Change API contract	MAJOR	Breaking

Version Consistency Checklist

All version references must match before release:

File	Field	Example
`package.json`	`version`	`"version": "1.2.3"`
`CHANGELOG.md`	Latest heading	`## [1.2.3] - 2024-12-19`
`README.md`	Badge/install (if versioned)	May be "latest"
Platform config	Varies	See platform-specific

Verification Command

# Extract and compare versions
PACKAGE_VERSION=$(jq -r .version package.json)
CHANGELOG_VERSION=$(grep -oP '## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md | head -1)

if [ "$PACKAGE_VERSION" != "$CHANGELOG_VERSION" ]; then
  echo "VERSION MISMATCH: package.json=$PACKAGE_VERSION, CHANGELOG=$CHANGELOG_VERSION"
  exit 1
fi

Platform-Specific Constraints

VS Code Extensions

Constraint	Requirement
Version format	3-part semver only (X.Y.Z)
Pre-release	Use odd minor version (e.g., 1.1.0)
Engine	Specify minimum VS Code version

{
  "version": "1.2.3",
  "engines": { "vscode": "^1.80.0" }
}

npm Packages

Constraint	Requirement
Version	Standard semver
Pre-release	`-alpha.1`, `-beta.1` allowed
Deprecation	Use `npm deprecate`

Python Packages (PyPI)

Constraint	Requirement
Version	PEP 440 compliant
Pre-release	`a1`, `b1`, `rc1` suffixes
Location	`setup.py`, `pyproject.toml`, or `__version__`

CHANGELOG Format

Follow Keep a Changelog:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.2.3] - 2024-12-19

### Added
- New feature description

### Changed
- Modified behavior description

### Fixed
- Bug fix description

### Deprecated
- Feature to be removed

### Removed
- Removed feature

### Security
- Security fix description

Categories Order

Added (new features)
Changed (changes to existing)
Deprecated (soon to be removed)
Removed (now removed)
Fixed (bug fixes)
Security (vulnerability fixes)

Pre-Release Verification

Mandatory Checks

Check	Command/Action	Fail Response
UAT Status	Read `agent-output/uat/`	STOP if not "APPROVED FOR RELEASE"
QA Status	Read `agent-output/qa/`	STOP if not "QA Complete"
Version Match	Compare all version files	STOP and fix
Tests Pass	Run test suite	STOP and fix
Clean Workspace	`git status`	Commit or stash
No Debug	Check for debug flags	Remove before release

Pre-Commit Cleanup

# Ensure no debug artifacts
grep -r "console.log" src/ --include="*.ts" && exit 1
grep -r "debugger" src/ --include="*.ts" && exit 1
grep -r "TODO: remove" src/ && exit 1

Release Execution

Git Tagging

# Create annotated tag
git tag -a v1.2.3 -m "Release v1.2.3"

# Push tag
git push origin v1.2.3

Publication Commands

Platform	Command
VS Code	`vsce publish`
npm	`npm publish`
PyPI	`twine upload dist/*`
GitHub	`gh release create v1.2.3`

Post-Publication Verification

Check	Method
Version visible	Check marketplace/registry
Installable	Fresh install test
Changelog visible	Check release notes
No errors	Check for publish warnings

Agent Responsibilities

DevOps Agent (Two-Stage Release)

Stage 1 (Per-Plan): After UAT approval, commit changes locally with detailed message. Do NOT push.
Stage 2 (Per-Release): After all plans committed and user approves release, push and publish.
Track which plans are committed for current release
Coordinate with Roadmap agent to maintain release→plan mappings
Never push without explicit release approval
Document in agent-output/deployment/

Implementer Agent

Update package.json version during milestones
Update CHANGELOG.md with changes
Commit version updates as part of implementation
Follow plan's specified version bump

Planner Agent

Specify target release version in plan header
Multiple plans may share the same target release
Coordinate with Roadmap agent for release assignments
Include version update in final milestone

Roadmap Agent

Maintain Active Release Tracker section
Track current working release version
Monitor plan→release mappings
Notify when all plans for a release are committed

Rollback Procedure

If release fails:

Unpublish (if platform allows)
- npm: npm unpublish package@version (within 72h)
- VS Code: Unpublish via dashboard

Delete tag (if needed)

git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

Document in deployment log
Notify stakeholders of rollback

See references/release-templates.md for deployment document templates.

release-procedures

Release Procedures

Release Workflow

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

Pre-Release Versions

When to Bump

Version Consistency Checklist

Verification Command

Platform-Specific Constraints

VS Code Extensions

npm Packages

Python Packages (PyPI)

CHANGELOG Format

Categories Order

Pre-Release Verification

Mandatory Checks

Pre-Commit Cleanup

Release Execution

Git Tagging

Publication Commands

Post-Publication Verification

Agent Responsibilities

DevOps Agent (Two-Stage Release)

Implementer Agent

Planner Agent

Roadmap Agent

Rollback Procedure

Release Procedures

Release Workflow

Semantic Versioning (SemVer)

Version Format: MAJOR.MINOR.PATCH

Pre-Release Versions

When to Bump

Version Consistency Checklist

Verification Command

Platform-Specific Constraints

VS Code Extensions

npm Packages

Python Packages (PyPI)

CHANGELOG Format

Categories Order

Pre-Release Verification

Mandatory Checks

Pre-Commit Cleanup

Release Execution

Git Tagging

Publication Commands

Post-Publication Verification

Agent Responsibilities

DevOps Agent (Two-Stage Release)

Implementer Agent

Planner Agent

Roadmap Agent

Rollback Procedure