@fitlab-ai/agent-infra 0.3.2 → 0.4.1

package/templates/.agents/skills/refine-task/SKILL.zh-CN.md

@@ -1,92 +1,52 @@
 ---
 name: refine-task
-description: >
-  处理代码审查反馈并修复审查中发现的问题。按优先级（Blocker -> Major -> Minor）修复。
-  仅处理审查中标记的问题，不添加额外变更。当用户要求修复审查问题时触发。参数：task-id。
+description: "处理代码审查反馈并修复问题"
 ---
 
 # 修复审查问题
 
+修复审查发现的问题，并产出 `refinement.md` 或 `refinement-r{N}.md`。
+
 ## 行为边界 / 关键规则
 
-- 仅修复审查中标记的问题 —— 不要添加无关变更或额外的"改进"
-- 不要自动提交。绝不自动执行 `git commit` 或 `git add`
-- 执行本技能后，你**必须**立即更新 task.md 中的任务状态
+- 只修复审查产物中记录的问题
+- 绝不自动执行 `git add` 或 `git commit`
+- 执行本技能后，你**必须**立即更新 task.md
 
 ## 执行步骤
 
 ### 1. 验证前置条件
 
-检查必要文件：
-- `.agent-workspace/active/{task-id}/task.md` - 任务文件
+要求存在：
+- `.agents/workspace/active/{task-id}/task.md`
 - 至少一个审查产物：`review.md` 或 `review-r{N}.md`
 
-注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
-
-如果缺少 `task.md` 或没有任何审查产物，提示用户先完成前置步骤。
-
-随后执行以下发现与校验：
-1. 扫描任务目录中的审查产物文件（`review.md`、`review-r{N}.md`）
-2. 取最高轮次的审查产物作为本次修复输入，记为 `{review-artifact}`
-3. 扫描修复产物文件（`refinement.md`、`refinement-r{N}.md`）并确定本轮修复产物：
-   - 如果不存在 `refinement.md` 且不存在 `refinement-r*.md` → 本轮为第 1 轮，产出 `refinement.md`
-   - 如果存在 `refinement.md` 且不存在 `refinement-r*.md` → 本轮为第 2 轮，产出 `refinement-r2.md`
-   - 如果存在 `refinement-r{N}.md` → 本轮为第 N+1 轮，产出 `refinement-r{N+1}.md`
-   - 记录 `{refinement-round}` 和 `{refinement-artifact}`
-4. 扫描实现报告文件（`implementation.md`、`implementation-r{N}.md`），取最高轮次作为修复上下文的 `{implementation-artifact}`
-   - 记录 `{implementation-artifact}`
-5. **一致性校验**：检查 `task.md` 的 `## 活动日志` 中最近一条 Code Review 记录的轮次号和文件名，是否与步骤 2 扫描到的最新审查产物匹配
+在前置检查阶段必须记录 `{review-artifact}`、`{refinement-round}`、`{refinement-artifact}`，并从最新实现报告中记录 `{implementation-artifact}`。
 
-若 Activity Log 记录与实际文件不匹配，立即停止并提示：
+同时校验 Activity Log 中最近一条 Code Review 记录；如果引用了不存在的文件，立即停止并输出：
 `Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists.`
 
 ### 2. 阅读审查与实现上下文
 
-仔细阅读步骤 1 中确定的最新审查产物 `{review-artifact}` 和实现产物 `{implementation-artifact}` 以理解：
-- 所有阻塞项（必须修复）
-- 所有主要问题（应该修复）
-- 次要问题（可选优化）
-- 审查者的建议和推荐
-- 当前实现和之前修复的上下文
-
-### 3. 规划修复
-
-分类并确定优先级：
-1. **阻塞项优先**：必须解决所有阻塞项
-2. **然后是主要问题**：处理所有主要问题
-3. **最后是次要问题**：如有时间则处理（可选）
+在修改代码前先读取最新的 `{review-artifact}` 和 `{implementation-artifact}`。
 
-对于每个问题，确定：
-- 需要修改哪些文件
-- 具体要做哪些修改
-- 如何验证修复
+### 3. 规划并执行修复
 
-### 4. 执行代码修复
+按 Blocker -> Major -> Minor 的顺序处理，始终保持改动聚焦。
 
-按优先级顺序修复问题：
+> 详细修复流程、优先级和验证循环见 `reference/fix-workflow.md`。执行此步骤前先读取 `reference/fix-workflow.md`。
 
-**对于每个修复**：
-1. 读取受影响的文件
-2. 应用修复
-3. 验证修复是否解决了审查意见
-4. 运行相关测试
+### 4. 运行测试验证
 
-**修复原则**：
-- 仅修复标记的问题 —— 不要添加无关变更
-- 不要添加超出要求的额外"改进"
-- 保持变更最小化和聚焦
+修复后运行项目测试命令，并把修复范围限制在审查结论内。
 
-### 5. 运行测试验证
+### 5. 编写修复报告
 
-执行项目的测试命令。参考 `test` 技能获取项目特定的测试命令。
+创建 `.agents/workspace/active/{task-id}/{refinement-artifact}`。
 
-确保修复后所有测试仍然通过。
+> 报告结构和示例章节见 `reference/report-template.md`。写报告前先读取 `reference/report-template.md`。
 
-### 6. 创建修复报告
-
-创建 `.agent-workspace/active/{task-id}/{refinement-artifact}`。
-
-### 7. 更新任务状态
+### 6. 更新任务状态
 
 获取当前时间：
 
@@ -94,115 +54,33 @@ description: >
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-更新 `.agent-workspace/active/{task-id}/task.md`：
-- `current_step`：refinement
-- `assigned_to`：{当前 AI 代理}
-- `updated_at`：{当前时间}
-- 记录本轮修复产物：`{refinement-artifact}`（Round `{refinement-round}`）
-- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
-  ```
-  - {yyyy-MM-dd HH:mm:ss} — **Refinement (Round {N}, for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues → {refinement-artifact}
-  ```
-
-### 8. 告知用户
-
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
-
-> **⚠️ 条件判断 — 在展示下面两个下一步之前，你必须先判断修复结果：**
->
-> - 如果本轮修复了任何 `Blocker` 或 `Major` 问题，或改动影响核心逻辑/测试范围较广，**默认推荐**先执行「重新审查」
-> - 如果仅修复 `Minor` 问题，且变更范围很小、风险可控，才可以把「直接提交」作为可选项
-> - 如果仍有未修复的 `Blocker` 或 `Major`，**不要**暗示可以直接提交；应明确提示继续修复或重新审查
->
-> **禁止把「直接提交」写成默认路径，除非你确认没有剩余高风险问题。**
-
-输出格式：
-```
-任务 {task-id} 修复完成。
-
-修复情况：
-- 阻塞项修复：{数量}/{总数}
-- 主要问题修复：{数量}/{总数}
-- 次要问题修复：{数量}/{总数}
-- 所有测试通过：{是/否}
-- 审查输入：{review-artifact}
-- 修复产物：{refinement-artifact}
-
-下一步 - 重新审查或提交：
-- 重新审查（默认推荐；修复了 Blocker/Major 时优先）：
-  - Claude Code / OpenCode：/review-task {task-id}
-  - Gemini CLI：/agent-infra:review-task {task-id}
-  - Codex CLI：$review-task {task-id}
-- 直接提交（仅限只修复 Minor 且风险可控）：
-  - Claude Code / OpenCode：/commit
-  - Gemini CLI：/agent-infra:commit
-  - Codex CLI：$commit
-```
+更新 task.md，并追加：
+`- {yyyy-MM-dd HH:mm:ss} — **Refinement (Round {N}, for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues → {refinement-artifact}`
 
-## 输出模板
+### 7. 告知用户
 
-```markdown
-# 修复报告
-
-- **修复轮次**：Round {refinement-round}
-- **产物文件**：`{refinement-artifact}`
-- **审查输入**：`{review-artifact}`
-- **实现上下文**：`{implementation-artifact}`
-
-### 审查反馈处理
-
-#### 阻塞项修复
-1. **{问题标题}**（来自 {review-artifact}）
-   - **修复**：{做了什么修改}
-   - **文件**：`{file-path}:{line-number}`
-   - **验证**：{如何验证}
-
-#### 主要问题修复
-1. **{问题标题}**（来自 {review-artifact}）
-   - **修复**：{做了什么修改}
-   - **文件**：`{file-path}:{line-number}`
-
-#### 次要问题处理
-1. **{问题标题}**（来自 {review-artifact}）
-   - **修复**：{做了什么修改}
-
-#### 未处理的问题
-- {问题}：{未处理的原因，例如不同意审查建议}
-
-### 修复后的测试结果
-- 所有测试通过：{是/否}
-- 测试输出：{摘要}
-```
+如果本轮修复了 Blocker 或 Major，默认推荐重新审查。只有在风险确实很低且只修复 Minor 时，才可把直接提交作为备选项。
 
 ## 完成检查清单
 
-- [ ] 阅读并理解了所有审查发现
-- [ ] 修复了所有阻塞项
-- [ ] 修复了所有主要问题
-- [ ] 在适当情况下处理了次要问题
-- [ ] 修复后所有测试通过
-- [ ] 创建了 `{refinement-artifact}` 修复报告
-- [ ] 更新了 task.md 中的任务状态
-- [ ] 追加了 Activity Log 条目到 task.md
-- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，不要筛选）
+- [ ] 已读取最新审查与实现上下文
+- [ ] 已修复所有必需的 Blocker 和 Major 问题
+- [ ] 已写出 `{refinement-artifact}`
+- [ ] 已更新 task.md 并追加 Activity Log
+- [ ] 已根据剩余风险推荐正确的下一步
 
 ## 注意事项
 
-1. **前置条件**：必须有审查报告（`review.md` 或 `review-r{N}.md` 存在）
-2. **禁止自动提交**：不要自动执行 `git commit`。提醒用户手动提交
-3. **范围纪律**：仅修复审查中标记的问题 —— 不添加额外变更
-4. **不同意见**：如果不同意某个审查意见，在"未处理的问题"部分记录你的理由
-5. **重新审查**：修复阻塞项后，建议重新运行 review-task 技能进行验证
-6. **一致性要求**：最新审查产物、Activity Log 记录和修复报告标题必须引用同一轮次文件
-7. **版本化规则**：首轮修复使用 `refinement.md`；后续轮次使用 `refinement-r{N}.md`
+- 首轮修复使用 `refinement.md`，后续轮次使用 `refinement-r{N}.md`
+- 若不同意审查意见，要在报告的未解决问题中记录理由
+- 不要把范围扩展到审查项之外
 
 ## 停止
 
-完成检查清单后，**立即停止**。等待用户审查修复结果并决定重新审查还是提交。
+完成检查清单后立即停止。
 
 ## 错误处理
 
-- 任务未找到：提示 "Task {task-id} not found"
-- 缺少审查报告：提示 "Review report not found, please run the review-task skill first"
-- 审查产物不一致：提示 "Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists."
-- 修复后测试失败：输出测试错误，询问用户如何处理
+- 任务未找到：`Task {task-id} not found`
+- 缺少审查报告：`Review report not found, please run the review-task skill first`
+- 审查产物不一致：`Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists.`

package/templates/.agents/skills/refine-task/reference/fix-workflow.md

@@ -0,0 +1,76 @@
+# Fix Workflow
+
+Read this file before changing code during refinement.
+
+## Plan the Fixes
+
+Classify and prioritize work:
+1. **Blockers first**
+2. **Then major issues**
+3. **Finally minor issues**
+
+For each finding, determine:
+- which files must change
+- what specific fix is required
+- how the fix will be verified
+
+Detailed priority rules:
+- Blockers must all be fixed before anything else
+- Major issues should all be fixed in the same pass unless a blocker prevents progress
+- Minor issues are optional only after Blockers and Majors are resolved
+- If you disagree with a finding, record that disagreement under unresolved issues instead of silently skipping it
+
+## Execute the Fixes
+
+For each fix:
+1. read the affected files
+2. apply the smallest necessary change
+3. verify the change addresses the review feedback
+4. run the relevant tests
+
+## Run Test Verification
+
+Run the project test command from the `test` skill and confirm that all required tests still pass.
+
+## Choose the Next-Step Branch
+
+Decision rules:
+1. if this round fixed any `Blocker` or `Major`, recommend re-review by default
+2. only when this round fixed Minor issues only and the change is clearly low risk may direct commit be offered as an option
+3. if any `Blocker` or `Major` remains unresolved, do not suggest direct commit
+
+Prohibition:
+- never present direct commit as the only next step unless no high-risk issue remains
+
+Required output template:
+
+```text
+Task {task-id} refinement completed.
+
+Refinement status:
+- Blockers fixed: {fixed-blockers}/{total-blockers}
+- Major issues fixed: {fixed-majors}/{total-majors}
+- Minor issues fixed: {fixed-minors}/{total-minors}
+- All tests passing: {yes/no}
+- Review input: {review-artifact}
+- Refinement artifact: {refinement-artifact}
+
+Next step - re-review or commit:
+- Re-review (recommended by default when Blocker/Major issues were fixed):
+  - Claude Code / OpenCode: /review-task {task-id}
+  - Gemini CLI: /agent-infra:review-task {task-id}
+  - Codex CLI: $review-task {task-id}
+- Commit directly (Minor-only, low-risk changes only):
+  - Claude Code / OpenCode: /commit
+  - Gemini CLI: /agent-infra:commit
+  - Codex CLI: $commit
+```
+
+## Notes
+
+1. **Prerequisite**: a review artifact must exist (`review.md` or `review-r{N}.md`)
+2. **No auto-commit**: do not run `git commit`
+3. **Scope discipline**: only fix reviewed issues
+4. **Disagreement handling**: record any disagreement in the report
+5. **Re-review**: after fixing Blockers or Major issues, recommend `review-task`
+6. **Consistency**: the latest review artifact, Activity Log entry, and refinement report must reference the same round

package/templates/.agents/skills/refine-task/reference/fix-workflow.zh-CN.md

@@ -0,0 +1,76 @@
+# 修复工作流
+
+在修复阶段修改代码之前先读取本文件。
+
+## 规划修复
+
+按以下顺序分类并确定优先级：
+1. **先处理 Blocker**
+2. **再处理 Major**
+3. **最后处理 Minor**
+
+对每一个问题，都要明确：
+- 哪些文件必须修改
+- 具体需要怎样修复
+- 如何验证修复已经生效
+
+详细优先级规则：
+- 所有 Blocker 都必须最先修完
+- 只要没有被 Blocker 阻塞，所有 Major 都应在同一轮一并修复
+- 只有在 Blocker 和 Major 都解决后，Minor 才是可选项
+- 如果你不同意某条审查意见，不要静默跳过，而是把分歧记录到 unresolved issues
+
+## 执行修复
+
+对每一项修复：
+1. 读取受影响文件
+2. 施加最小必要改动
+3. 验证改动确实解决了审查反馈
+4. 运行相关测试
+
+## 运行测试验证
+
+运行项目测试命令。项目测试命令以 `test` skill 为准，并确认所有必需测试仍然通过。
+
+## 选择下一步分支
+
+判断规则：
+1. 如果本轮修复了任何 `Blocker` 或 `Major`，默认推荐重新审查
+2. 只有当本轮只修复了 Minor，且改动明显低风险时，才可以把直接提交作为一个可选项
+3. 如果仍有任何 `Blocker` 或 `Major` 未解决，就不要建议直接提交
+
+禁止规则：
+- 只要还存在高风险问题，绝对不要把直接提交写成唯一下一步
+
+必用输出模板：
+
+```text
+任务 {task-id} 修复完成。
+
+修复情况：
+- 阻塞项修复：{数量}/{总数}
+- 主要问题修复：{数量}/{总数}
+- 次要问题修复：{数量}/{总数}
+- 所有测试通过：{是/否}
+- 审查输入：{review-artifact}
+- 修复产物：{refinement-artifact}
+
+下一步 - 重新审查或提交：
+- 重新审查（默认推荐；修复了 Blocker/Major 时优先）：
+  - Claude Code / OpenCode：/review-task {task-id}
+  - Gemini CLI：/agent-infra:review-task {task-id}
+  - Codex CLI：$review-task {task-id}
+- 直接提交（仅限只修复 Minor 且风险可控）：
+  - Claude Code / OpenCode：/commit
+  - Gemini CLI：/agent-infra:commit
+  - Codex CLI：$commit
+```
+
+## 注意事项
+
+1. **前置条件**：必须存在审查产物（`review.md` 或 `review-r{N}.md`）
+2. **禁止自动提交**：不要执行 `git commit`
+3. **范围约束**：只修复审查中列出的问题
+4. **分歧处理**：如果不同意审查意见，要在报告里明确记录
+5. **重新审查**：修复了 Blocker 或 Major 后，推荐执行 `review-task`
+6. **一致性**：最新审查产物、Activity Log 记录和修复报告必须引用同一轮次

package/templates/.agents/skills/refine-task/reference/report-template.md

@@ -0,0 +1,38 @@
+# Refinement Report Template
+
+Use this structure when writing `refinement.md` or `refinement-r{N}.md`.
+
+## Output Template
+
+```markdown
+# Refinement Report
+
+- **Refinement Round**: Round {refinement-round}
+- **Artifact File**: `{refinement-artifact}`
+- **Review Input**: `{review-artifact}`
+- **Implementation Context**: `{implementation-artifact}`
+
+### Review Feedback Handling
+
+#### Blocker Fixes
+1. **{issue-title}**
+   - **Fix**: {what changed}
+   - **File**: `{file-path}:{line-number}`
+   - **Validation**: {validation}
+
+#### Major Issue Fixes
+1. **{issue-title}**
+   - **Fix**: {what changed}
+   - **File**: `{file-path}:{line-number}`
+
+#### Minor Issue Handling
+1. **{issue-title}**
+   - **Fix**: {what changed}
+
+#### Unresolved Issues
+- {issue}: {reason}
+
+### Test Results After Refinement
+- All tests passing: {yes/no}
+- Test output: {summary}
+```

package/templates/.agents/skills/refine-task/reference/report-template.zh-CN.md

@@ -0,0 +1,38 @@
+# 修复报告模板
+
+编写 `refinement.md` 或 `refinement-r{N}.md` 时，使用以下结构。
+
+## 输出模板
+
+```markdown
+# 修复报告
+
+- **修复轮次**: Round {refinement-round}
+- **产物文件**: `{refinement-artifact}`
+- **审查输入**: `{review-artifact}`
+- **实现上下文**: `{implementation-artifact}`
+
+### 审查反馈处理
+
+#### 阻塞项修复
+1. **{issue-title}**
+   - **修复**: {what changed}
+   - **文件**: `{file-path}:{line-number}`
+   - **验证**: {validation}
+
+#### 主要问题修复
+1. **{issue-title}**
+   - **修复**: {what changed}
+   - **文件**: `{file-path}:{line-number}`
+
+#### 次要问题处理
+1. **{issue-title}**
+   - **修复**: {what changed}
+
+#### 未解决问题
+- {issue}: {reason}
+
+### 修复后的测试结果
+- 所有测试通过: {yes/no}
+- 测试输出: {summary}
+```

package/templates/.agents/skills/refine-title/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: refine-title
-description: >
-  Deeply analyze Issue or PR content and reformat the title to
-  Conventional Commits format. Triggered when the user requests
-  title optimization. Argument: issue or PR number.
+description: "Rewrite an Issue or PR title in Conventional Commits format"
 ---
 
 # Refine Title

package/templates/.agents/skills/refine-title/SKILL.zh-CN.md

@@ -1,8 +1,6 @@
 ---
 name: refine-title
-description: >
-  深度分析 Issue 或 PR 内容，并将其标题重构为 Conventional Commits 格式。
-  当用户要求优化标题时触发。参数：issue 或 PR 编号。
+description: "重构 Issue/PR 标题为 Conventional Commits 格式"
 ---
 
 # 重构标题

package/templates/.agents/skills/release/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: release
-description: >
-  Execute the version release workflow. Triggered when the user
-  requests a version release. Argument: version number (X.Y.Z).
+description: "Run the version release workflow"
 ---
 
 # Version Release
@@ -13,7 +11,7 @@ Execute the version release workflow for the specified version.
 
 ## Execution Flow
 
-### Step 1: Parse and Validate Version
+### 1. Parse and Validate Version
 
 Extract version from arguments. Must match `X.Y.Z` format.
 
@@ -23,7 +21,7 @@ Parse components:
 
 If format is invalid, error: "Version format incorrect, expected X.Y.Z (e.g. 1.2.3)"
 
-### Step 2: Verify Clean Workspace
+### 2. Verify Clean Workspace
 
 ```bash
 git status --short
@@ -31,7 +29,26 @@ git status --short
 
 If there are uncommitted changes, error: "Workspace has uncommitted changes. Please commit or stash first."
 
-### Step 3: Update Version References
+### 3. Pre-release Verification
+
+<!-- TODO: Replace with your project's pre-release verification steps -->
+
+Run any checks that must pass before preparing a release:
+
+```bash
+git branch --show-current
+# TODO: Replace with your project's test/build verification commands
+```
+
+Verification guidance:
+- Confirm the release is being prepared from the correct branch for your project
+- Run the full validation commands required by your release process
+
+Handling rules:
+- If the current branch is unexpected, print a warning or exit based on your policy
+- If any verification command fails, stop the release process and fix the issue first
+
+### 4. Update Version References
 
 <!-- TODO: Replace with your project's version update steps -->
 
@@ -45,6 +62,7 @@ Search for version references in project files and update them:
 
 **Common files to update**:
 - `package.json` (Node.js)
+- `package-lock.json` (Node.js; run `npm install --package-lock-only` after updating `package.json`)
 - `pom.xml` (Maven)
 - `setup.py` / `pyproject.toml` (Python)
 - `version.go` (Go)
@@ -52,22 +70,39 @@ Search for version references in project files and update them:
 - `SECURITY.md` / `SECURITY.zh-CN.md` (supported version table)
 
 **Exclude from version replacement**:
-- `.agents/`, `.agent-workspace/`, `.claude/`, `.codex/`, `.gemini/`, `.opencode/` (AI tool configs)
+- `.agents/`, `.agents/workspace/`, `.claude/`, `.codex/`, `.gemini/`, `.opencode/` (AI tool configs)
+
+If the project uses `package-lock.json`, run `npm install --package-lock-only` after updating `package.json` so the lockfile version stays in sync.
+
+### 5. Rebuild Artifacts
 
-### Step 4: Create Release Commit
+<!-- TODO: Replace with your project's artifact rebuild steps -->
+
+If version updates affect generated files, embedded metadata, or bundled assets, rebuild them now:
+
+```bash
+# TODO: Replace with your project's rebuild command(s)
+```
+
+Execution guidance:
+- Run this after updating version references so generated artifacts pick up the new version
+- If your project has no generated artifacts, document that explicitly in the project-specific skill
+- If the rebuild fails, stop the release process and fix the build first
+
+### 6. Create Release Commit
 
 ```bash
 git add -A
 git commit -m "chore: release v{version}"
 ```
 
-### Step 5: Create Git Tag
+### 7. Create Git Tag
 
 ```bash
 git tag v{version}
 ```
 
-### Step 6: Manage Milestones
+### 8. Manage Milestones
 
 Close the milestone for the released version when it exists, and create the missing planning milestones for the next cycle.
 
@@ -84,7 +119,7 @@ The script is responsible for:
 - When `PATCH=0`, also ensuring `{MAJOR}.{MINOR+1}.0` and `{MAJOR}.{MINOR+1}.x`
 - Printing a milestone summary with the released milestone action and new milestone count
 
-### Step 7: Output Summary
+### 9. Output Summary
 
 > **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
 
@@ -100,12 +135,12 @@ Files updated: {count}
 
 Next steps (manual):
 
-1. Push tag:
-   git push origin v{version}
-
-2. Push branch:
+1. Push branch:
    git push origin {current-branch}
 
+2. Push tag:
+   git push origin v{version}
+
 3. (Optional) Generate release notes:
    - Claude Code / OpenCode: /create-release-note {version}
    - Gemini CLI: /{{project}}:create-release-note {version}
@@ -130,13 +165,17 @@ git checkout -- .
 
 1. **Clean workspace required**: Must have no uncommitted changes
 2. **No auto-push**: All operations are local only; user pushes manually
-3. **No build verification**: Run the test skill before releasing to verify
-4. **Version replacement scope**: Search determines which files to update; exclude AI tool directories
-5. **Adapt to your project**: The version update steps above are generic; customize for your project's versioning scheme
-6. **Milestone coordination**: Releases should create the next planning milestones automatically; initialize the taxonomy first with `init-milestones` when needed
+3. **Pre-release verification**: Replace the Step 3 TODOs with the branch, test, and validation commands your release process requires
+4. **Generated artifacts**: Replace the Step 5 TODOs when version changes affect generated files, bundled assets, or embedded metadata
+5. **Release automation**: If pushing a tag triggers CI/CD or package publishing, confirm the required credentials and pipeline settings first
+6. **Version replacement scope**: Search determines which files to update; exclude AI tool directories
+7. **Adapt to your project**: The version update and rebuild steps above are generic; customize them for your project's versioning scheme
+8. **Milestone coordination**: Releases should create the next planning milestones automatically; initialize the taxonomy first with `init-milestones` when needed
 
 ## Error Handling
 
 - Invalid version format: Prompt correct format and exit
 - Dirty workspace: Prompt to commit or stash
+- Verification failure: Display the failing check and stop the release
+- Artifact rebuild failure: Display the build error and stop the release
 - Git operation failure: Display error and provide rollback instructions