Release

Agentero Release

Prepare evidence-backed bilingual Release notes and write them directly to the Draft GitHub Release. Use dry runs when the user explicitly requests read-only preview.

Establish the release range

1. Read git status, the current branch, local and remote tags, and the target Release state. Preserve unrelated working-tree changes.
2. Resolve both endpoints to immutable commits and verify that the base is an ancestor of the target.
3. For a stable target, default to the latest earlier published stable Release reachable from the target. For a prerelease, prefer the preceding prerelease in the same version series, then fall back to the latest stable Release.
4. Display the selected <base>..<target> range. Stop for user direction when the target, release channel, ancestry, or previous Release is ambiguous.
5. Never move or overwrite an existing remote tag. Treat a tag already observed by GitHub Actions or attached to a Release as immutable.

Collect evidence

Run the bundled collector from the repository root:

node .agents/skills/release/scripts/collect-release-context.mjs <base> <target>

Use merged pull requests as the main narrative units. Always inspect uncovered first-parent commits as a second source; the presence of one PR does not make other mainline commits disappear.

For each candidate change:

• Prefer the PR title, body, linked issues, labels, and changed behavior.
• Use the first-parent commit subject, body, and changed files when no merged PR covers the commit.
• Inspect the relevant diff or documentation when the public effect is unclear.
• Collect issues closed during the release range that are not already covered by a merged PR. Use gh issue list --state closed --search "closed:>={base-date}" or inspect Closes / Fixes references in commit messages.
• Exclude release bumps, formatting, tests, internal refactors, and routine documentation unless they change installation, compatibility, security, or visible behavior.
• Combine multiple commits that implement one user-visible outcome.
• Keep a PR, commit, or issue URL as evidence for every bullet.
• Include the first committer or PR author for each bullet so contributors are credited in the notes. Resolve GitHub usernames — the git commit author name (e.g. QiyuanChen) is not necessarily the GitHub handle (e.g. qychen2001). For PRs, use the PR author.login field directly. For uncovered commits, run gh api repos/poco-ai/Agentero/commits/<sha> and extract the author.login field. Fall back to the commit author.name only when the GitHub API returns null (e.g. unauthenticated local commits).
• Report uncertainty or conflicting evidence instead of inventing behavior.

Draft the notes

Write Chinese first and English second. Mirror the same groups, bullet count, order, meaning, and evidence links across both languages.

Use this shape:

## 概要

<一段简短文字，说明本次发布主题和用户影响。>

## 新功能

- **<关键词或短语>**: <一到两句具体介绍。>（[#123](...) by @author）

## 改进

- **<关键词或短语>**: <一到两句具体介绍。>（[commit](...) by @author）

## 修复

- **<关键词或短语>**: <一到两句具体介绍。>（[#124](...) by @author）

## 已解决问题

- **<关键词或短语>**: <一到两句具体介绍。>（[#125](...) by @author）

---

## Summary

<One short paragraph describing the release theme and user impact.>

## Features

- **<Keyword or short phrase>**: <One or two concrete sentences.> ([#123](...) by @author)

## Improvements

- **<Keyword or short phrase>**: <One or two concrete sentences.> ([commit](...) by @author)

## Fixes

- **<Keyword or short phrase>**: <One or two concrete sentences.> ([#124](...) by @author)

## Resolved Issues

- **<Keyword or short phrase>**: <One or two concrete sentences.> ([#125](...) by @author)

Apply these writing rules:

• Start the body exactly at ## 概要. Do not repeat the Release title, version, or date inside the body.
• Do not add English or 中文 wrapper headings or language navigation links. Separate the Chinese and English sections with a standalone Markdown horizontal rule (---), then begin English content at ## Summary.
• Keep Summary / 概要 as prose, not a bullet list.
• Start every grouped bullet with **<keyword or short phrase>**: . Keep the colon and following space outside the bold markers in both languages; never write **<keyword>:** or **<关键词>：**.
• Follow the keyword with one or two specific, user-facing sentences.
• Use Features / 新功能, Improvements / 改进, Fixes / 修复, and Resolved Issues / 已解决问题 when evidence exists. Resolved Issues is for issues closed during the release that are not already covered by a merged PR. Add mirrored groups such as Security / 安全性, Breaking Changes / 破坏性变更, or Known Limitations / 已知限制 only when needed.
• Omit empty groups.
• Describe shipped behavior, not implementation activity or test counts.
• Keep terminology and factual scope equivalent across languages; do not make one language a shortened translation of the other.
• End with a compare link when the repository and both refs are available.

Write the Release notes

After drafting the notes, write them directly to the Draft GitHub Release.

1. Verify the remote tag exists and the Release is a Draft.

2. Verify the required Release workflow completed successfully and expected assets exist.

3. Write the body to a temporary file and run:

   gh release edit "<tag>" \
     --repo poco-ai/Agentero \
     --verify-tag \
     --notes-file "<temporary-file>"
   

4. Fetch the Release again and confirm the stored body matches.

5. Remove the temporary file.

6. Return the selected range, evidence coverage, and the written body.

Do not publish the Draft, push commits, create or move tags, or change version files unless the user separately requests those actions. Publishing with gh release edit "<tag>" --draft=false requires explicit approval after the final body and assets have been reviewed.

Dry run

When the user explicitly requests a dry run, skip writing to GitHub. Return:

1. The selected range and evidence coverage: PR count, uncovered first-parent commit count, and any warnings.
2. The complete bilingual Release note candidate.
3. A statement that no version, commit, tag, push, workflow, or GitHub Release was changed.

Do not create a repository note file for a dry run unless requested.