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

text

┌─────────────────────────────────────────────────────────────────┐
│                    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

text

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

bash

# 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

json

{
  "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:

markdown

# 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"
Git Auth	`git push --dry-run` or `gh auth status`	STOP and fix (check GITHUB_TOKEN conflict)
Version Match	Compare all version files	STOP and fix
Tests Pass	Run test suite	STOP and fix
Clean Workspace	`git status`	Commit or stash
Memory Hash	`scripts/memory_utils.py --verify-all`	STOP and update hashes
No Debug	Check for debug flags	Remove before release

Pre-Commit Cleanup

bash

# 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

bash

# 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` (or use `github_*` MCP tools)

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)

bash

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.