Release Assistant | 發布助手
Guide the release process following Semantic Versioning and changelog best practices.
引導遵循語義化版本和變更日誌最佳實踐的發布流程。
Subcommands | 子命令
| Subcommand |
Mode |
Description |
說明 |
start |
All |
Start a release branch/process |
開始發布流程 |
finish |
CI/CD |
Finalize release (tag, merge) |
完成發布（標籤、合併） |
promote |
Manual/Hybrid |
Promote RC to Stable |
RC → Stable 晉升 |
deploy |
Manual/Hybrid |
Record deployment to environment |
記錄部署紀錄 |
manifest |
Manual/Hybrid |
Generate build-manifest.json |
產生打包資訊清單 |
verify |
Manual/Hybrid |
Verify manifest consistency |
驗證清單一致性 |
changelog |
All |
Generate or update CHANGELOG.md |
產生或更新變更日誌 |
check |
All |
Run pre-release verification |
執行發布前檢查 |
Release Modes | 發布模式
Configure via uds init or uds config --type release_mode:
| Mode |
Description |
說明 |
ci-cd |
Automatic publishing via CI/CD pipeline (default) |
CI/CD 自動發布（預設） |
manual |
Manual packaging + RC workflow |
手動打包 + RC 工作流程 |
hybrid |
CI builds artifact + manual deployment |
CI 建置 + 手動部署 |
Version Types | 版本類型
| Type |
Pattern |
npm Tag |
用途 |
| Stable |
X.Y.Z |
@latest |
Production release |
| Beta |
X.Y.Z-beta.N |
@beta |
Public testing |
| Alpha |
X.Y.Z-alpha.N |
@alpha |
Internal testing |
| RC |
X.Y.Z-rc.N |
@rc |
Release candidate |
Workflow | 工作流程
- Determine version - Decide version type based on changes (MAJOR/MINOR/PATCH)
- Triage open issues/PRs -
gh pr list + gh issue list; classify each bring-in vs defer (XSPEC-265) / 掃描 issue/PR、每項二分（帶上 vs backlog）
- Update version files - Update package.json and related version references
- Update CHANGELOG - Move [Unreleased] entries to new version section
- Run pre-release checks - Verify tests, lint, standards compliance, and issue/PR triage gate
- Create git tag - Tag with
vX.Y.Z format
- Commit and push - Commit version bump and push tags
Pre-release Issue/PR Triage Gate | 發版前 issue/PR triage 閘門 (XSPEC-265)
Before bumping, scan open issues/PRs and make a conscious decision per item — do not rely on memory:
| Class |
Action |
| Bring-in |
patch dependabot PR / release-blocking bug / fix relevant to this version's theme → merge before bump |
| Defer |
major PR, audit/enhancement issue, needs separate evaluation → record in signoff "deferred" + release-notes Known Issues |
- Confirm
cross-project/sub-project-triage.md snapshot is recent (≤7 days); refresh if stale.
- Record the result in the release sign-off (Tier-1):
Pre-release issue/PR triage | PASS | N PRs / M issues: X merged / Y deferred.
- Do not require emptying the backlog — only that every item has a conscious decision + a record. 不要求清空 backlog，只要求每項有意識決策 + 留紀錄。
Version Increment Rules | 版本遞增規則
| Change Type |
Increment |
Example |
| Breaking changes |
MAJOR |
1.9.5 → 2.0.0 |
| New features (backward-compatible) |
MINOR |
2.3.5 → 2.4.0 |
| Bug fixes (backward-compatible) |
PATCH |
3.1.2 → 3.1.3 |
Usage | 使用方式
CI/CD Mode (default)
/release start 1.2.0 - Start release process for v1.2.0/release changelog 1.2.0 - Update CHANGELOG for v1.2.0/release finish 1.2.0 - Finalize and tag v1.2.0/release check - Run pre-release verification
Manual Mode (RC workflow)
/release start 1.2.0-rc.1 - Create RC versionuds release manifest - Generate build-manifest.jsonuds release deploy staging - Record staging deploymentuds release deploy staging --result passed - Record test result/release promote 1.2.0 - Promote RC to stableuds release deploy production - Record production deploymentuds release verify - Verify manifest consistency
Next Steps Guidance | 下一步引導
After /release completes, the AI assistant should suggest:
發布流程完成。建議下一步 / Release process complete. Suggested next steps:
- 驗證 npm 發布狀態
npm view <pkg> dist-tags ⭐ Recommended / 推薦 — Verify npm publication status
- 建立 GitHub Release 並撰寫發布說明 — Create GitHub Release with notes
- 通知利害關係人新版本已發布 — Notify stakeholders of new release
Reference | 參考
AI Agent Behavior | AI 代理行為
完整的 AI 行為定義請參閱對應的命令文件：/release
For complete AI agent behavior definition, see the corresponding command file: /release
1---2name: release3scope: universal4description: |5 [UDS] Guide the release process — semantic versioning, release modes, and the start/finish/promote/deploy sequence.6 Use when: cutting a release, deciding a semantic version bump, promoting a release candidate to stable, recording a deployment.7 Not for: writing the changelog entries themselves — use /changelog; the deployment mechanics — use /deploy.8 Keywords: release, semantic versioning, version bump, release candidate, promote, 發布, 語意化版本, 發版流程.9allowed-tools: Read, Write, Grep, Bash(git:*), Bash(npm version:*)10argument-hint: "[version]"11prerequisites: ["release-check"]12status: stable13# 2026-08-18: `disable-model-invocation: true` removed, and a status recorded.14#15# The flag was applied by d415937e alongside the description rewrite and, like16# the two lifted on 2026-08-17, followed no stateable rule. These eight were17# left alone that day for a reason that was correct at the time: the rule18# settled on was "a reference is model-invocable", and none of them carried a19# `status` at all, so lifting them would have replaced one unruled state with20# one unruled action.21#22# Measured 2026-08-18, which is what closed it: all eight carry a full23# `Use when:` trigger and a `Not for:` exclusion, all eight describe an action24# rather than reference material, and all eight already have a slash command —25# which is exactly the shape of `code-review-assistant`, whose paired `/code-review`26# was ruled not to justify the flag. `journey-test-assistant` is the standing27# precedent: same "Generate X" shape, `status: stable`, never disabled.28#29# `stable` rather than a new value: `skills/` uses reference, stable and30# experimental, and inventing a fourth would be the same unruled-action mistake31# in different clothing.32#33# The cost of being wrong is asymmetric and observable in only one direction.34# Over-triggering shows up and is undone by deleting a line; a skill that is35# structurally unable to fire produces no signal at all. (XSPEC-378 R5)36---3738# Release Assistant | 發布助手3940Guide the release process following Semantic Versioning and changelog best practices.4142引導遵循語義化版本和變更日誌最佳實踐的發布流程。4344## Subcommands | 子命令4546| Subcommand | Mode | Description | 說明 |47|------------|------|-------------|------|48| `start` | All | Start a release branch/process | 開始發布流程 |49| `finish` | CI/CD | Finalize release (tag, merge) | 完成發布（標籤、合併） |50| `promote` | Manual/Hybrid | Promote RC to Stable | RC → Stable 晉升 |51| `deploy` | Manual/Hybrid | Record deployment to environment | 記錄部署紀錄 |52| `manifest` | Manual/Hybrid | Generate build-manifest.json | 產生打包資訊清單 |53| `verify` | Manual/Hybrid | Verify manifest consistency | 驗證清單一致性 |54| `changelog` | All | Generate or update CHANGELOG.md | 產生或更新變更日誌 |55| `check` | All | Run pre-release verification | 執行發布前檢查 |5657## Release Modes | 發布模式5859Configure via `uds init` or `uds config --type release_mode`:6061| Mode | Description | 說明 |62|------|-------------|------|63| `ci-cd` | Automatic publishing via CI/CD pipeline (default) | CI/CD 自動發布（預設） |64| `manual` | Manual packaging + RC workflow | 手動打包 + RC 工作流程 |65| `hybrid` | CI builds artifact + manual deployment | CI 建置 + 手動部署 |6667## Version Types | 版本類型6869| Type | Pattern | npm Tag | 用途 |70|------|---------|---------|------|71| Stable | `X.Y.Z` | `@latest` | Production release | 正式版 |72| Beta | `X.Y.Z-beta.N` | `@beta` | Public testing | 公開測試 |73| Alpha | `X.Y.Z-alpha.N` | `@alpha` | Internal testing | 內部測試 |74| RC | `X.Y.Z-rc.N` | `@rc` | Release candidate | 候選版本 |7576## Workflow | 工作流程77781. **Determine version** - Decide version type based on changes (MAJOR/MINOR/PATCH)792. **Triage open issues/PRs** - `gh pr list` + `gh issue list`; classify each **bring-in vs defer** (XSPEC-265) / 掃描 issue/PR、每項二分（帶上 vs backlog）803. **Update version files** - Update package.json and related version references814. **Update CHANGELOG** - Move [Unreleased] entries to new version section825. **Run pre-release checks** - Verify tests, lint, standards compliance, **and issue/PR triage gate**836. **Create git tag** - Tag with `vX.Y.Z` format847. **Commit and push** - Commit version bump and push tags8586### Pre-release Issue/PR Triage Gate | 發版前 issue/PR triage 閘門 (XSPEC-265)8788Before bumping, scan open issues/PRs and make a conscious decision per item — do **not** rely on memory:8990| Class | Action |91|-------|--------|92| **Bring-in** | patch dependabot PR / release-blocking bug / fix relevant to this version's theme → merge before bump |93| **Defer** | major PR, audit/enhancement issue, needs separate evaluation → record in signoff "deferred" + release-notes Known Issues |9495- Confirm `cross-project/sub-project-triage.md` snapshot is recent (≤7 days); refresh if stale.96- Record the result in the release sign-off (Tier-1): `Pre-release issue/PR triage | PASS | N PRs / M issues: X merged / Y deferred`.97- **Do not require emptying the backlog** — only that every item has a conscious decision + a record. 不要求清空 backlog，只要求每項有意識決策 + 留紀錄。9899### Version Increment Rules | 版本遞增規則100101| Change Type | Increment | Example |102|-------------|-----------|---------|103| Breaking changes | MAJOR | 1.9.5 → 2.0.0 |104| New features (backward-compatible) | MINOR | 2.3.5 → 2.4.0 |105| Bug fixes (backward-compatible) | PATCH | 3.1.2 → 3.1.3 |106107## Usage | 使用方式108109### CI/CD Mode (default)110- `/release start 1.2.0` - Start release process for v1.2.0111- `/release changelog 1.2.0` - Update CHANGELOG for v1.2.0112- `/release finish 1.2.0` - Finalize and tag v1.2.0113- `/release check` - Run pre-release verification114115### Manual Mode (RC workflow)116- `/release start 1.2.0-rc.1` - Create RC version117- `uds release manifest` - Generate build-manifest.json118- `uds release deploy staging` - Record staging deployment119- `uds release deploy staging --result passed` - Record test result120- `/release promote 1.2.0` - Promote RC to stable121- `uds release deploy production` - Record production deployment122- `uds release verify` - Verify manifest consistency123124## Next Steps Guidance | 下一步引導125126After `/release` completes, the AI assistant should suggest:127128> **發布流程完成。建議下一步 / Release process complete. Suggested next steps:**129> - 驗證 npm 發布狀態 `npm view <pkg> dist-tags` ⭐ **Recommended / 推薦** — Verify npm publication status130> - 建立 GitHub Release 並撰寫發布說明 — Create GitHub Release with notes131> - 通知利害關係人新版本已發布 — Notify stakeholders of new release132133## Reference | 參考134135- [Changelog Format Guide](./changelog-format.md) — Read it when writing or reviewing a changelog entry.136- [Release Workflow Guide](./release-workflow.md) — Read it when actually cutting a release, step by step.137- [Semantic Versioning Guide](./semantic-versioning.md) — Read it when deciding whether a change is major, minor or patch.138- Detailed guide: [guide.md](./guide.md)139- Core standard: [versioning.md](../../core/versioning.md)140141142## AI Agent Behavior | AI 代理行為143144> 完整的 AI 行為定義請參閱對應的命令文件：[`/release`](../commands/release.md#ai-agent-behavior--ai-代理行為)145>146> For complete AI agent behavior definition, see the corresponding command file: [`/release`](../commands/release.md#ai-agent-behavior--ai-代理行為)
AsiaOstrich