Harness release

Harness Release (v3)

Harness v3 的统一发布技能。 整合了以下旧技能：

• release-har -- 通用发布自动化
• x-release-harness -- Harness 专用发布自动化
• handoff -- 向 PM 交接与汇报完成情况

Quick Reference

/release             # 交互式执行（会确认版本类型）
/release patch       # patch 版本提升（缺陷修复）
/release minor       # minor 版本提升（新功能）
/release major       # major 版本提升（破坏性变更）
/release --dry-run   # 仅预览，不实际执行
/release --announce  # 同时执行 X（Twitter）公告
/release --complete  # 标记发布完成（打 tag 后的收尾）

Release-only policy

• 普通 PR：不要改动 VERSION / .claude-plugin/plugin.json / 已版本化的 CHANGELOG.md 条目
• 普通 PR 的变更记录：追加到 CHANGELOG.md 的 [Unreleased] 区段
• 只有在执行 /release 时，才统一更新 version bump、已版本化 CHANGELOG 条目、tag / GitHub Release
• 即使是 /release --dry-run，也要跑与正式发布相同的 preflight，提前拦截风险信号

分支策略

• 单人开发：允许直接 push 到 main（CI 作为质量门禁）
• 协作开发：必须通过 PR 合并
• 始终禁止 force push（--force / --force-with-lease）

版本判定标准（SemVer）

基于 .claude/rules/versioning.md 的判断流程：

是否破坏现有行为？
├─ 是 → major
└─ 否 → 用户是否能因此做到新的事情？
    ├─ 是 → minor
    └─ 否 → patch

变更类型	版本	例子
技能定义文案修订或补充	patch	模板微调
hooks/scripts 的缺陷修复	patch	转义修复
新增技能/标志/agent	minor	--dual、新技能
适配 CC 新版本	minor	支持 CC v2.1.90
破坏性变更（废弃旧技能、格式不兼容）	major	删除 Plans.md v1

批量发布建议：同一天有多项变更时，合并到一个 minor 版本里；禁止同一天进行两次以上的 minor bump。

关于 NPM 分发

这个项目是 Claude Code 插件，不作为 npm 包发布。 仓库根目录没有 package.json（core/package.json 仅用于内部 TypeScript 构建）。 版本管理只涉及以下两个文件：

• VERSION -- 主版本来源
• .claude-plugin/plugin.json -- 插件清单

分发表面与 Mirror 同步

skills-v3/ 是 SSOT（Single Source of Truth）。以下 3 个分发表面会作为 mirror 同步：

分发表面	路径	目标用户
Claude	skills/harness-release/	Claude Code 用户
Codex	codex/.codex/skills/harness-release/	Codex CLI 用户
OpenCode	opencode/skills/harness-release/	OpenCode 用户

重要：编辑 skills-v3/ 后，发布前必须同步 mirror：

./scripts/sync-v3-skill-mirrors.sh

仅验证（不改写）：

./scripts/sync-v3-skill-mirrors.sh --check

多语言切换（i18n）

技能的 description 字段支持中 / 日 / 英切换。发布前请确认 locale 设置符合预期：

# 设置为简体中文（description-zh → description）
./scripts/i18n/set-locale.sh zh

# 设置为日文（description-ja → description，兼容模式）
./scripts/i18n/set-locale.sh ja

# 设置为英文（description-en → description）
./scripts/i18n/set-locale.sh en

当前默认建议为简体中文；description-en 作为英文回退保留，description-ja 作为旧日文兼容槽位保留。

执行流程

Phase 0: Pre-flight 检查（必需）

# 1. 检查必需工具
command -v gh &>/dev/null || echo "没有 gh：将跳过 GitHub Release"
command -v jq &>/dev/null || echo "没有 jq：更新 plugin.json 时需要它"

# 2. vendor-neutral preflight（正式执行 / dry-run 通用）
bash scripts/release-preflight.sh

# 3. 校验插件结构
bash tests/validate-plugin.sh

# 4. 一致性检查
bash scripts/ci/check-consistency.sh

# 5. 检查 mirror 同步状态
bash scripts/sync-v3-skill-mirrors.sh --check

scripts/release-preflight.sh 会检查以下内容：

• working tree 是否干净
• CHANGELOG.md 中是否存在 [Unreleased]
• .env.example 与 .env 的差异（在 managed secrets 模式下通常只记为 warning）
• healthcheck / preflight 命令（如果存在就执行）
• agents/ / core/ / hooks/ / scripts/ 的 shipped surface 中是否残留 debug / mock / placeholder
• CI 状态（若可获取）

可通过环境变量按仓库进行调整：

• HARNESS_RELEASE_PROJECT_ROOT
• HARNESS_RELEASE_HEALTHCHECK_CMD
• HARNESS_RELEASE_CI_STATUS_CMD

详情见：docs/release-preflight.md

Phase 1: 获取当前版本

CURRENT=$(cat VERSION 2>/dev/null)
echo "当前版本: $CURRENT"

Phase 2: 计算新版本

scripts/sync-version.sh 只支持 patch bump。minor / major 需要手动改写 VERSION：

# patch bump（x.y.Z → x.y.(Z+1)）
./scripts/sync-version.sh bump

# minor bump（手动：x.Y.z → x.(Y+1).0）
CURRENT=$(cat VERSION)
MAJOR=$(echo "$CURRENT" | cut -d. -f1)
MINOR=$(echo "$CURRENT" | cut -d. -f2)
NEW_VERSION="$MAJOR.$((MINOR + 1)).0"
echo "$NEW_VERSION" > VERSION
./scripts/sync-version.sh sync

# major bump（手动：X.y.z → (X+1).0.0）
CURRENT=$(cat VERSION)
MAJOR=$(echo "$CURRENT" | cut -d. -f1)
NEW_VERSION="$((MAJOR + 1)).0.0"
echo "$NEW_VERSION" > VERSION
./scripts/sync-version.sh sync

sync-version.sh sync 会把 VERSION 的值同步到 .claude-plugin/plugin.json。

Phase 3: CHANGELOG 更新

release entry 会把普通 PR 中积累在 [Unreleased] 下的变更，正式落到带版本号的区段中。

建议使用详细的 Before/After 格式（优先简体中文）。 将每个功能拆成编号小节，用“之前”和“现在”配合具体示例进行说明。

## [X.Y.Z] - YYYY-MM-DD

### 主题：[用一句话概括这次变更]

**[用 1 到 2 句话说明这次改动对用户的价值]**

---

#### 1. [功能名]

**之前**：[具体描述旧行为，写出用户真正会遇到的痛点]

**现在**：[具体描述新行为，以及解决了什么问题]

[实际输出示例或命令示例]

#### 2. [下一个功能名]

**之前**: ...

**现在**: ...

CC 版本整合时的写法：不要写成普通的“之前 / 现在”，而是改用“CC 更新了什么 → Harness 如何利用它”的形式。 详情请参考 .claude/rules/github-release.md 中“CC 版本整合时的 CHANGELOG 模式”。

写作规则：

规则	说明
言語	简体中文优先
每个功能独立成段	用 #### N. 功能名 编号
“之前”用于描述问题	具体写出用户实际感受到的不便
“现在”用于描述解决方案	说明变了什么，并附具体例子（代码 / 输出）
必须包含具体例子	如命令示例、输出示例、Plans.md 片段等
技术细节保持最少	文件名和步骤号只作为“现在”部分的补充
写长一点没关系	每个功能 3 到 10 行，以可读性优先

不要清空 [Unreleased] 区段，而是为下一次发布保留：

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD
...

Phase 4: 更新版本文件

# VERSION 已在 Phase 2 中更新
# 同步 plugin.json
./scripts/sync-version.sh sync

# 确认同步结果
./scripts/sync-version.sh check

Phase 5: Mirror 同步

# 将 skills-v3 同步到 skills、codex、opencode
./scripts/sync-v3-skill-mirrors.sh

# 检查同步结果
./scripts/sync-v3-skill-mirrors.sh --check

Phase 6: 提交与打标签

NEW_VERSION=$(cat VERSION)

# 暂存（显式指定目标文件）
git add VERSION .claude-plugin/plugin.json CHANGELOG.md
git add skills/ codex/.codex/skills/ opencode/skills/

git commit -m "chore: release v$NEW_VERSION"
git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"

Phase 7: Push

git push origin main --tags

注意：.github/workflows/release.yml 会检测 tag push；如果 GitHub Release 尚未创建，就会从 CHANGELOG 自动生成一个安全兜底版本。若你先手动创建了 GitHub Release，这个工作流会自动跳过。

Phase 8: 创建 GitHub Release

NEW_VERSION=$(cat VERSION)

gh release create "v$NEW_VERSION" \
  --title "v$NEW_VERSION - 标题" \
  --notes "$(cat <<'EOF'
## What's Changed

**[变更摘要（英文）]**

### Before / After

| Before | After |
|--------|-------|
| Previous state | New state |

---

## Added

- **Feature**: Description

## Changed

- **Change**: Description

## Fixed

- **Fix**: Description

---

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

GitHub Release Notes 规则：

• 语言：英文（因为这是公开仓库）
• 必须包含：## What's Changed、加粗摘要、Before / After 表格、页脚
• 详细格式：参考 .claude/rules/github-release.md

校验 Release Notes：

./scripts/validate-release-notes.sh "v$NEW_VERSION"

Phase 9: 标记发布完成

git commit --allow-empty -m "chore: mark v$NEW_VERSION release complete"
git push origin main

这个空提交是一个明确标记，用来表示“发布工作已全部完成”。

Phase 10: 公告（仅在指定 --announce 时）

调用 /x-announce 技能，为 X（Twitter）生成公告线程：

Skill: x-announce
Args: v$NEW_VERSION

一次性输出 5 条帖子文案 + 5 张 Gemini 图片。

--dry-run 模式

--dry-run 会执行以下步骤，但不会真正修改任何内容：

1. 完整执行 Pre-flight 检查（Phase 0）
2. 显示版本计算结果（不写入）
3. 显示 CHANGELOG 草稿（不写入）
4. 显示 GitHub Release Notes 草稿（不创建）
5. 显示 mirror 同步 diff（不写入）

会跳过的内容：改写 VERSION / plugin.json、git commit / tag / push、创建 GitHub Release、发布公告

--complete 模式

在创建 tag 之后，只执行“发布完成”标记：

/release --complete

只执行 Phase 9。确认没有漏建 GitHub Release 后，再补打完成提交。

回归检查清单

发布前请确认以下回归项：

检查项	检查方法	备注
插件结构	tests/validate-plugin.sh	校验 plugin.json、技能、hook、脚本
一致性	scripts/ci/check-consistency.sh	检查模板、版本、mirror、CHANGELOG
Mirror 同步	scripts/sync-v3-skill-mirrors.sh --check	确认 skills-v3 与 3 个分发表面一致
Preflight	scripts/release-preflight.sh	检查 working tree、CHANGELOG、CI、残留垃圾
发布说明	scripts/validate-release-notes.sh vX.Y.Z	校验 GitHub Release 格式
VERSION 同步	scripts/sync-version.sh check	确认 VERSION 与 plugin.json 一致
Guardrails	core/src/guardrails/rules.ts 的 R01-R13	确保 TypeScript 规则健康
Tag 连续性	git tag --sort=-version:refname | head -5	确认没有缺号
Locale	description 与当前目标 locale 一致	scripts/i18n/set-locale.sh 可切换

CI 安全兜底

.github/workflows/release.yml 会在 tag push 时自动执行：

1. 检测 v* tag 的 push
2. 检查同名 GitHub Release 是否已存在
3. 若不存在，则从 CHANGELOG 自动生成（安全兜底）
4. 若已存在，则不做任何事

推荐流程仍然是先手动创建 GitHub Release，再执行 push。 这个安全兜底只负责弥补“忘了创建 Release”这一类问题。

PM 交接

发布后给 PM 的完成报告：

## 发布完成报告

**版本**: v{{NEW_VERSION}}
**发布日期**: {{DATE}}

### 实施内容
{{CHANGELOG 的内容}}

### GitHub Release
{{URL}}

### 下一步动作
- 由 PM 确认发布说明
- 部署到生产环境（如果适用）

禁止事项

• 删除或回滚 tag（公开版本应视为不可变）
• 同一天进行两次以上 minor bump
• 用 patch 级别的改动去做 minor bump
• 使用 --force / --force-with-lease 执行 force push
• 在 release commit 中混入 VERSION / plugin.json / CHANGELOG 以外的实现改动

相关技能

• harness-review -- 在发布前执行代码评审
• harness-work -- 实现发布后的下一个任务
• harness-plan -- 制定下个版本的计划
• x-announce -- 生成发往 X（Twitter）的发布公告线程
• harness-setup -- 进行 mirror 同步与插件配置初始化

相关规则

• .claude/rules/versioning.md -- SemVer 判定标准与批量发布建议
• .claude/rules/github-release.md -- GitHub Release Notes 格式（英文）
• .claude/rules/cc-update-policy.md -- 跟进 CC 更新时的 Feature Table 质量标准