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---5
6# Release Preflight Skill
7
8
9> Pre-checks, version consistency, and deployment discipline.
10
11## The Golden Rule
12
13> **NEVER publish without running the preflight checklist.**
14
15## Quick Start
16
17```bash
18# Full preflight check
19node scripts/release-preflight.cjs
20
21# With packaging test
22node scripts/release-preflight.cjs
23
24# Skip time-consuming tests
25node scripts/release-preflight.cjs
26```
27
28## Version Locations (Must Stay Synchronized)
29
30| # | Location | Field | Example |
31| --- | ------------------------------------------------------------ | ------------------- | ------------------------- |
32| 1 | `heir/platforms/vscode-extension/package.json` | `version` | `"8.2.1"` |
33| 2 | `heir/CHANGELOG.md` | Latest heading | `## [8.2.1] - 2026-04-22` |
34| 3 | `BUILD-MANIFEST.json` (if present) | `version` | `"8.2.1"` |
35| 4 | Git tag | Tag name | `v8.2.1` |
36
37## Preflight Gates
38
39| Gate | Check | Script Flag |
40| ---- | ------------------------------ | ----------- |
41| 0 | PAT configured | Always |
42| 1 | Version sync (all 7 locations) | Always |
43| 2 | VSIX exists | Always |
44| 3 | Git clean | Always |
45| 4 | Git tag available | Always |
46| 5 | VSCE_PAT available | Always |
47| 6 | Heir sync drift | Always |
48
49## Full Release Workflow
50
51```bash
52# VS Code Extension release
53node scripts/release-vscode.cjs
54
55# M365 Agent release
56node scripts/release-m365.cjs --validate
57```
58
59## Version Bump Only
60
61```powershell
62# 1. Bump
63npm version patch --no-git-tag-version
64
65# 2. Get version
66$v = (Get-Content package.json | ConvertFrom-Json).version
67
68# 3. Update CHANGELOG, commit, tag, push
69git add -A; git commit -m "release: v$v"; git tag "v$v"; git push --tags
70```
71
72## Common Mistakes
73
74| Mistake | Prevention |
75| ------------------------------ | -------------------------------- |
76| Published without version bump | Run preflight first |
77| CHANGELOG not updated | Script checks this |
78| Forgot to push tags | Script does this |
79| Version mismatch | Grep entire repo for old version |
80| PAT 401 error | Refresh PAT before release |
81
82## Go / No-Go Decision Table (RP3)
83
84After preflight runs, classify each finding to decide whether to proceed:
85
86| Finding | Severity | Decision | Rationale |
87|---------|----------|----------|-----------|
88| Version mismatch across locations | **Block** | Fix before publish | Silent version drift = wrong artifact on marketplace |
89| VSIX file missing or wrong version in filename | **Block** | Rebuild VSIX | Publishing a stale or misnamed artifact is irreversible |
90| Git working tree dirty | **Block** | Commit or stash | Tagged release must match a clean commit |
91| Git tag already exists for target version | **Block** | Bump version or delete tag | Duplicate tag = ambiguous release provenance |
92| VSCE_PAT missing or expired | **Block** | Refresh token | Publish will 401; partial state is worse than no-op |
93| Heir sync drift detected | **Warning** | Review diff, then decide | Drift may be intentional (master-only changes) or accidental |
94| CHANGELOG entry missing for version | **Warning** | Add entry, or proceed if patch-only fix | Users and future-you need the audit trail |
95| Test failures in extension | **Block** | Fix tests | Shipping known-broken code violates trust |
96| Brain-qa score below threshold | **Warning** | Review findings; proceed if cosmetic-only | Brain health affects heirs on next upgrade |
97| Frontmatter audit failures | **Warning** | Fix if quick; track as debt if not | New files may lack frontmatter; not a ship-blocker unless systemic |
98
99**Rule**: Any **Block** finding = hard stop. Fix first, re-run preflight, then proceed.
100**Warning** findings require explicit operator acknowledgment — the LLM should list them and ask "proceed despite these warnings?"
101
102## Changelog Voice QA Decision Table (RP2)
103
104After preflight passes, review `CHANGELOG.md` entries for the release version against these voice standards:
105
106| Condition | Verdict | Action |
107|-----------|---------|--------|
108| Entry uses past tense ("Added", "Fixed", "Removed") | Pass | Standard changelog convention |
109| Entry uses present/future tense ("Adds", "Will fix") | Fail | Rewrite to past tense |
110| Entry describes user-visible impact ("Users can now...") | Pass | Preferred framing |
111| Entry describes internal implementation ("Refactored the parser loop") | Warning | Rewrite to user impact; move internal detail to commit message |
112| Entry uses internal jargon ("brain-qa", "trifecta", "sidecar") | Fail | Replace with user-facing language ("health checks", "skill set", "config") |
113| Entry is a single vague line ("Bug fixes and improvements") | Fail | Expand to specific items |
114| Entry references a PLAN task ID ("FM4", "RP2") only | Fail | Add human-readable description alongside |
115| Entry groups related changes under a category header | Pass | Use: Added, Changed, Fixed, Removed, Security |
116| Breaking change is clearly marked with `**BREAKING**` | Pass | Required for major bumps |
117| Entry length proportional to change significance | Pass | One-liners for patches, paragraphs for features |
118| Links to related docs/issues included for complex changes | Pass | Helps users understand context |
119| Duplicate entries from cherry-pick or merge | Fail | Deduplicate; keep most descriptive version |
120
121## Related Scripts
122
123| Script | Purpose |
124| --------------------------------------------- | -------------------------------------- |
125| `scripts/release-preflight.cjs` | Pre-release validation |
126| `scripts/release-vscode.cjs` | Full VS Code release |
127| `scripts/release-m365.cjs` | M365 agent packaging |
128
129## Triggers
130
131- "release", "publish", "deploy"
132- "preflight", "pre-release check"
133- "version bump", "version sync"
134
135---
136
137_Scripts: `scripts/release-preflight.cjs`, `scripts/release-vscode.cjs`_
gabrielmoreira