Release Process Skill

Release Process Skill

Classification: Master-Only Skill | Process Automation Activation: release, publish, marketplace, vsix, version bump, pre-release Inheritance: master-only (contains PAT handling, marketplace credentials)

Purpose

Comprehensive knowledge for releasing Alex Cognitive Architecture to VS Code Marketplace and managing version lifecycle.

Quick Reference

Release Commands

# From repo root
.\scripts\release-vscode.ps1 -BumpType patch              # Stable release
.\scripts\release-vscode.ps1 -BumpType minor -PreRelease  # Pre-release
.\scripts\release-vscode.ps1 -BumpType patch -DryRun      # Test without publishing

Manual Publishing

cd platforms/vscode-extension
npx vsce publish --pre-release  # Pre-release
npx vsce publish                # Stable release

PAT (Personal Access Token) Setup

⚠️ IMPORTANT: PATs expire frequently and may only work for a single publish session. Always create a fresh PAT before each release to avoid 401 errors.

Creating a New PAT

1. Via Marketplace (Recommended):

   • Go to: https://marketplace.visualstudio.com/manage/publishers/
   • Click your publisher name
   • Click "..." menu → "Generate new token"
   • Copy the token immediately (shown only once)

2. Via Azure DevOps:

   • Go to: https://dev.azure.com/
   • Click User Settings (gear icon) → Personal Access Tokens
   • Click "New Token"
   • Name: vsce-marketplace (or similar)
   • Organization: All accessible organizations
   • Expiration: Set appropriate duration (max 1 year)
   • Scopes: Select Marketplace → Manage
   • Click Create, copy token

Storing the PAT

Option 1: Environment Variable (Session only)

$env:VSCE_PAT = "your-token-here"

Option 2: .env File (Persistent, gitignored)

# platforms/vscode-extension/.env
VSCE_PAT=your-token-here

Dual .env Warning: Both Alex_Plug_In/.env (root) AND platforms/vscode-extension/.env (heir) may contain a VSCE_PAT. The publish command runs from the heir directory and reads the heir's .env. If you update the root, also update the heir — or vice versa. PAT mismatch between these files has caused 401 errors across consecutive releases (v5.9.11, v5.9.12).

Option 3: System Environment (Persistent)

[Environment]::SetEnvironmentVariable("VSCE_PAT", "your-token", "User")

PAT Troubleshooting

Retry After PAT Fix

When publish fails with 401 and you've already built a valid .vsix, skip the full prepublish cycle:

# Set new PAT and publish pre-built package (skips sync/quality-gate/compile)
$env:VSCE_PAT = "new-token"; npx vsce publish --packagePath alex-cognitive-architecture-X.Y.Z.vsix

This saves ~2 minutes vs a full npx vsce publish which re-runs the entire prepublish pipeline.

Version Strategy

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes, docs
  │     └──────── New features, non-breaking
  └────────────── Breaking changes

Pre-Release vs Stable

VS Code Marketplace Rule: Pre-release versions must use the --pre-release flag, NOT semver suffixes like -beta.1.

Version Files to Update

When bumping version, these files need synchronization:

1. platforms/vscode-extension/package.json → version field
2. platforms/vscode-extension/.github/copilot-instructions.md → **Version**: line
3. CHANGELOG.md → New ## [X.Y.Z] section

The release-vscode.ps1 script handles all of these automatically.

Release Workflow

Automated (Recommended)

┌─────────────────────────────────────────────────────────────────┐
│  .\scripts\release-vscode.ps1 -BumpType patch -PreRelease       │
└─────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ 0. PAT Check    │───▶│ 1a. Sync Heir   │───▶│ 1b. Preflight   │
│ - Load .env     │    │ - build-pkg.ps1 │    │ - Version sync  │
│ - Validate      │    │ - Master→Heir   │    │ - Build/Lint    │
│                 │    │                 │    │ - Manifest check│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │
         ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ 2. Version Bump │───▶│ 3. CHANGELOG    │───▶│ 4. Git Commit   │
│ - package.json  │    │ - Add entry     │    │ - Commit        │
│ - heir version  │    │ - Date stamp    │    │ - Tag           │
│                 │    │                 │    │ - Push          │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │
         ▼
┌─────────────────┐
│ 5. Publish      │
│ - vsce publish  │
│ - --pre-release │
└─────────────────┘

Definition of Done Verification

Before publishing, verify ALL 8 criteria from ROADMAP-UNIFIED.md:

Pattern: Use regression checklist as DoD tracker:

• Create alex_docs/operations/VXXX-REGRESSION-CHECKLIST.md
• Track verification status for each criterion
• Document evidence (commit hashes, test counts, sync output)
• Automated tests provide objective quality signal (test count = confidence metric)

Quality Gate: If ANY criterion fails, DO NOT publish. Fix first.

Manual Checklist

If not using the script:

• Run preflight: .\scripts\release-preflight.ps1 -Package
• Bump version in package.json
• Update heir copilot-instructions.md version
• Add CHANGELOG entry
• Commit: git commit -m "chore: release vX.Y.Z"
• Tag: git tag vX.Y.Z
• Push: git push && git push --tags
• Publish: npx vsce publish [--pre-release]

Preflight Checks

The release-preflight.ps1 script validates:

File Structure

Alex_Plug_In/
├── scripts/
│   ├── release-preflight.ps1    # Pre-release validation
│   ├── release-vscode.ps1       # Full release automation
│   └── build-extension-package.ps1  # Heir sync
├── platforms/vscode-extension/
│   ├── package.json             # Version source of truth
│   ├── .env                     # PAT storage (gitignored)
│   ├── .github/
│   │   └── copilot-instructions.md  # Heir version
│   └── *.vsix                   # Built packages
└── CHANGELOG.md                 # Version history

Common Issues

"The pre-release version is not valid"

Cause: Used semver suffix like 3.7.4-beta.1

Solution: Use plain version 3.7.4 with --pre-release flag

"401 Unauthorized"

Cause: PAT expired, invalid, or wrong scope

Solution:

1. Create new PAT at marketplace.visualstudio.com/manage/publishers
2. Ensure "Marketplace (Manage)" scope
3. Update .env or environment variable

"Version already exists"

Cause: Trying to publish same version twice

Solution: Bump version first, or delete existing version from marketplace

Build succeeds but publish fails

Cause: Often network or auth issues

Solution:

1. Check internet connection
2. Verify PAT is valid
3. Try npx vsce login <publisher-name> first

Links

• VS Code Publishing Guide
• Marketplace Publisher Portal
• Azure DevOps PAT Docs
• VSCE CLI Reference