Release Preflight Skill
Pre-checks, version consistency, and deployment discipline.
The Golden Rule
NEVER publish without running the preflight checklist.
Quick Start
# Full preflight check
node scripts/release-preflight.cjs
# With packaging test
node scripts/release-preflight.cjs
# Skip time-consuming tests
node scripts/release-preflight.cjs
Version Locations (Must Stay Synchronized)
| # |
Location |
Field |
Example |
| 1 |
heir/platforms/vscode-extension/package.json |
version |
"8.2.1" |
| 2 |
heir/CHANGELOG.md |
Latest heading |
## [8.2.1] - 2026-04-22 |
| 3 |
BUILD-MANIFEST.json (if present) |
version |
"8.2.1" |
| 4 |
Git tag |
Tag name |
v8.2.1 |
Preflight Gates
| Gate |
Check |
Script Flag |
| 0 |
PAT configured |
Always |
| 1 |
Version sync (all 7 locations) |
Always |
| 2 |
VSIX exists |
Always |
| 3 |
Git clean |
Always |
| 4 |
Git tag available |
Always |
| 5 |
VSCE_PAT available |
Always |
| 6 |
Heir sync drift |
Always |
Full Release Workflow
# VS Code Extension release
node scripts/release-vscode.cjs
# M365 Agent release
node scripts/release-m365.cjs --validate
Version Bump Only
# 1. Bump
npm version patch --no-git-tag-version
# 2. Get version
$v = (Get-Content package.json | ConvertFrom-Json).version
# 3. Update CHANGELOG, commit, tag, push
git add -A; git commit -m "release: v$v"; git tag "v$v"; git push --tags
Common Mistakes
| Mistake |
Prevention |
| Published without version bump |
Run preflight first |
| CHANGELOG not updated |
Script checks this |
| Forgot to push tags |
Script does this |
| Version mismatch |
Grep entire repo for old version |
| PAT 401 error |
Refresh PAT before release |
Go / No-Go Decision Table (RP3)
After preflight runs, classify each finding to decide whether to proceed:
| Finding |
Severity |
Decision |
Rationale |
| Version mismatch across locations |
Block |
Fix before publish |
Silent version drift = wrong artifact on marketplace |
| VSIX file missing or wrong version in filename |
Block |
Rebuild VSIX |
Publishing a stale or misnamed artifact is irreversible |
| Git working tree dirty |
Block |
Commit or stash |
Tagged release must match a clean commit |
| Git tag already exists for target version |
Block |
Bump version or delete tag |
Duplicate tag = ambiguous release provenance |
| VSCE_PAT missing or expired |
Block |
Refresh token |
Publish will 401; partial state is worse than no-op |
| Heir sync drift detected |
Warning |
Review diff, then decide |
Drift may be intentional (master-only changes) or accidental |
| CHANGELOG entry missing for version |
Warning |
Add entry, or proceed if patch-only fix |
Users and future-you need the audit trail |
| Test failures in extension |
Block |
Fix tests |
Shipping known-broken code violates trust |
| Brain-qa score below threshold |
Warning |
Review findings; proceed if cosmetic-only |
Brain health affects heirs on next upgrade |
| Frontmatter audit failures |
Warning |
Fix if quick; track as debt if not |
New files may lack frontmatter; not a ship-blocker unless systemic |
Rule: Any Block finding = hard stop. Fix first, re-run preflight, then proceed.
Warning findings require explicit operator acknowledgment — the LLM should list them and ask "proceed despite these warnings?"
Changelog Voice QA Decision Table (RP2)
After preflight passes, review CHANGELOG.md entries for the release version against these voice standards:
| Condition |
Verdict |
Action |
| Entry uses past tense ("Added", "Fixed", "Removed") |
Pass |
Standard changelog convention |
| Entry uses present/future tense ("Adds", "Will fix") |
Fail |
Rewrite to past tense |
| Entry describes user-visible impact ("Users can now...") |
Pass |
Preferred framing |
| Entry describes internal implementation ("Refactored the parser loop") |
Warning |
Rewrite to user impact; move internal detail to commit message |
| Entry uses internal jargon ("brain-qa", "trifecta", "sidecar") |
Fail |
Replace with user-facing language ("health checks", "skill set", "config") |
| Entry is a single vague line ("Bug fixes and improvements") |
Fail |
Expand to specific items |
| Entry references a PLAN task ID ("FM4", "RP2") only |
Fail |
Add human-readable description alongside |
| Entry groups related changes under a category header |
Pass |
Use: Added, Changed, Fixed, Removed, Security |
Breaking change is clearly marked with **BREAKING** |
Pass |
Required for major bumps |
| Entry length proportional to change significance |
Pass |
One-liners for patches, paragraphs for features |
| Links to related docs/issues included for complex changes |
Pass |
Helps users understand context |
| Duplicate entries from cherry-pick or merge |
Fail |
Deduplicate; keep most descriptive version |
Related Scripts
| Script |
Purpose |
scripts/release-preflight.cjs |
Pre-release validation |
scripts/release-vscode.cjs |
Full VS Code release |
scripts/release-m365.cjs |
M365 agent packaging |
Triggers
- "release", "publish", "deploy"
- "preflight", "pre-release check"
- "version bump", "version sync"
Scripts: scripts/release-preflight.cjs, scripts/release-vscode.cjs
1---2name: release-preflight3description: Pre-checks, version consistency, and deployment discipline.4---56# Release Preflight Skill78> Pre-checks, version consistency, and deployment discipline.910## The Golden Rule1112> **NEVER publish without running the preflight checklist.**1314## Quick Start1516```bash17# Full preflight check18node scripts/release-preflight.cjs1920# With packaging test21node scripts/release-preflight.cjs2223# Skip time-consuming tests24node scripts/release-preflight.cjs25```2627## Version Locations (Must Stay Synchronized)2829| # | Location | Field | Example |30| --- | ------------------------------------------------------------ | ------------------- | ------------------------- |31| 1 | `heir/platforms/vscode-extension/package.json` | `version` | `"8.2.1"` |32| 2 | `heir/CHANGELOG.md` | Latest heading | `## [8.2.1] - 2026-04-22` |33| 3 | `BUILD-MANIFEST.json` (if present) | `version` | `"8.2.1"` |34| 4 | Git tag | Tag name | `v8.2.1` |3536## Preflight Gates3738| Gate | Check | Script Flag |39| ---- | ------------------------------ | ----------- |40| 0 | PAT configured | Always |41| 1 | Version sync (all 7 locations) | Always |42| 2 | VSIX exists | Always |43| 3 | Git clean | Always |44| 4 | Git tag available | Always |45| 5 | VSCE_PAT available | Always |46| 6 | Heir sync drift | Always |4748## Full Release Workflow4950```bash51# VS Code Extension release52node scripts/release-vscode.cjs5354# M365 Agent release55node scripts/release-m365.cjs --validate56```5758## Version Bump Only5960```powershell61# 1. Bump62npm version patch --no-git-tag-version6364# 2. Get version65$v = (Get-Content package.json | ConvertFrom-Json).version6667# 3. Update CHANGELOG, commit, tag, push68git add -A; git commit -m "release: v$v"; git tag "v$v"; git push --tags69```7071## Common Mistakes7273| Mistake | Prevention |74| ------------------------------ | -------------------------------- |75| Published without version bump | Run preflight first |76| CHANGELOG not updated | Script checks this |77| Forgot to push tags | Script does this |78| Version mismatch | Grep entire repo for old version |79| PAT 401 error | Refresh PAT before release |8081## Go / No-Go Decision Table (RP3)8283After preflight runs, classify each finding to decide whether to proceed:8485| Finding | Severity | Decision | Rationale |86|---------|----------|----------|-----------|87| Version mismatch across locations | **Block** | Fix before publish | Silent version drift = wrong artifact on marketplace |88| VSIX file missing or wrong version in filename | **Block** | Rebuild VSIX | Publishing a stale or misnamed artifact is irreversible |89| Git working tree dirty | **Block** | Commit or stash | Tagged release must match a clean commit |90| Git tag already exists for target version | **Block** | Bump version or delete tag | Duplicate tag = ambiguous release provenance |91| VSCE_PAT missing or expired | **Block** | Refresh token | Publish will 401; partial state is worse than no-op |92| Heir sync drift detected | **Warning** | Review diff, then decide | Drift may be intentional (master-only changes) or accidental |93| CHANGELOG entry missing for version | **Warning** | Add entry, or proceed if patch-only fix | Users and future-you need the audit trail |94| Test failures in extension | **Block** | Fix tests | Shipping known-broken code violates trust |95| Brain-qa score below threshold | **Warning** | Review findings; proceed if cosmetic-only | Brain health affects heirs on next upgrade |96| Frontmatter audit failures | **Warning** | Fix if quick; track as debt if not | New files may lack frontmatter; not a ship-blocker unless systemic |9798**Rule**: Any **Block** finding = hard stop. Fix first, re-run preflight, then proceed.99**Warning** findings require explicit operator acknowledgment — the LLM should list them and ask "proceed despite these warnings?"100101## Changelog Voice QA Decision Table (RP2)102103After preflight passes, review `CHANGELOG.md` entries for the release version against these voice standards:104105| Condition | Verdict | Action |106|-----------|---------|--------|107| Entry uses past tense ("Added", "Fixed", "Removed") | Pass | Standard changelog convention |108| Entry uses present/future tense ("Adds", "Will fix") | Fail | Rewrite to past tense |109| Entry describes user-visible impact ("Users can now...") | Pass | Preferred framing |110| Entry describes internal implementation ("Refactored the parser loop") | Warning | Rewrite to user impact; move internal detail to commit message |111| Entry uses internal jargon ("brain-qa", "trifecta", "sidecar") | Fail | Replace with user-facing language ("health checks", "skill set", "config") |112| Entry is a single vague line ("Bug fixes and improvements") | Fail | Expand to specific items |113| Entry references a PLAN task ID ("FM4", "RP2") only | Fail | Add human-readable description alongside |114| Entry groups related changes under a category header | Pass | Use: Added, Changed, Fixed, Removed, Security |115| Breaking change is clearly marked with `**BREAKING**` | Pass | Required for major bumps |116| Entry length proportional to change significance | Pass | One-liners for patches, paragraphs for features |117| Links to related docs/issues included for complex changes | Pass | Helps users understand context |118| Duplicate entries from cherry-pick or merge | Fail | Deduplicate; keep most descriptive version |119120## Related Scripts121122| Script | Purpose |123| --------------------------------------------- | -------------------------------------- |124| `scripts/release-preflight.cjs` | Pre-release validation |125| `scripts/release-vscode.cjs` | Full VS Code release |126| `scripts/release-m365.cjs` | M365 agent packaging |127128## Triggers129130- "release", "publish", "deploy"131- "preflight", "pre-release check"132- "version bump", "version sync"133134---135136_Scripts: `scripts/release-preflight.cjs`, `scripts/release-vscode.cjs`_
fabioc-aloha