name: "Release Process Skill" description: "Complete release automation for VS Code Marketplace publishing" disable-model-invocation: true

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

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)
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

Error	Cause	Solution
401 Unauthorized	PAT expired or invalid	Create new PAT
401 Unauthorized	Wrong scope	Ensure "Marketplace (Manage)" scope
401 Unauthorized	Wrong `.env` updated	Ensure `platforms/vscode-extension/.env` has the token
403 Forbidden	Not publisher owner	Check publisher membership
Token not found	.env not loaded	Check file path, run preflight

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

Type	Flag	Visibility	Use Case
Pre-release	`--pre-release`	Opt-in only	Beta testing
Stable	(none)	Everyone	Production ready

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:

platforms/vscode-extension/package.json → version field
platforms/vscode-extension/.github/copilot-instructions.md → **Version**: line
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:

#	Criterion	Validation Method
1	Builds clean	`npm run compile` exits 0 with zero errors
2	No dead code	All imports resolve, no orphaned modules
3	Counts match reality	Slash commands, tools, skills, trifectas in docs = actual code
4	F5 smoke test passes	Extension activates, welcome view renders, 3 random commands work
5	Version aligned	package.json = CHANGELOG = copilot-instructions
6	Heir sync clean	`sync-architecture.js` runs with 0 errors, no contamination
7	No non-functional features	If in UI/command palette, it works. If broken, removed.
8	CHANGELOG documents delta	Every user-visible change has a line item

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:

Check	What It Does
PAT	Verifies VSCE_PAT is available in env or .env
Version Sync	package.json = CHANGELOG = Master instructions = heir instructions
BUILD-MANIFEST	Checks heir was synced recently (warns if > 24h old)
README Skill Count	Verifies documented skill count matches actual
ROADMAP Version	Warns if ROADMAP-UNIFIED.md version differs
Build	`npm run compile` succeeds
Lint	`npm run lint` passes
Tests	`npm test` passes (can skip with `-SkipTests`)
Git Status	Shows uncommitted changes
Git Tags	Warns if tag already exists
Package	Creates VSIX (with `-Package` flag)

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:

Create new PAT at marketplace.visualstudio.com/manage/publishers
Ensure "Marketplace (Manage)" scope
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