release-prep

发布准备技能

此技能可自动完成 MassGen 的发布准备工作，生成 CHANGELOG 条目、公告文本并验证文档。

使用时机

准备新版本发布时运行此技能：

• 将发布 PR 合并到 main 后
• 创建 git 标签前

用法

/release-prep v0.1.34

此技能的作用

1. 收集变更

读取自上一个标签以来的提交和 PR：

# Get last tag
git describe --tags --abbrev=0

# Get commits since last tag
git log v0.1.33..HEAD --oneline

# Get merged PRs (if using GitHub)
gh pr list --base main --state merged --search "merged:>2024-01-01"

2. 归档上一条公告

如果 docs/announcements/current-release.md 存在：

# Extract version from current-release.md
VERSION=$(grep -m1 "^# MassGen v" docs/announcements/current-release.md | sed 's/# MassGen v\([^ ]*\).*/\1/')

# Archive it
mv docs/announcements/current-release.md docs/announcements/archive/v${VERSION}.md

3. 生成 CHANGELOG 条目

更新 CHANGELOG.md 顶部的 Recent Releases 部分：

• 在顶部添加新版本摘要
• 此部分仅保留最新的 3 个版本
• 删除较早的条目（它们仍保留在下方的详细变更日志中）

按照 Keep a Changelog 格式创建结构化条目：

## [0.1.34] - YYYY-MM-DD

### Added
- **Feature Name**: Description
  - Implementation details

### Changed
- **Modified Feature**: What changed

### Fixed
- **Bug #123**: Description of fix

### Documentations, Configurations and Resources
- **Feature Guide**: New `docs/source/user_guide/feature.rst` for feature usage
- **Design Document**: New `docs/dev_notes/feature_design.md` for implementation details
- **Updated Docs**: Updated `docs/source/reference/cli.rst` with new commands
- **Skills**: New `massgen/skills/skill-name/SKILL.md` for automation

文档部分规则：

• 引用具体文件路径（.rst、.md、.yaml 文件）
• 新增文件使用“New”，修改过的文件使用“Updated”
• 运行 git diff <last-tag>..HEAD --name-only -- "*.md" "*.rst" "*.yaml" 查找变更的文档

分类规则：

• feat: 提交 → Added
• fix: 提交 → Fixed
• docs: 提交 → Documentation
• refactor:、perf: 提交 → Changed
• 重大变更 → 使用 ⚠️ 突出标示

贡献者：

• 运行 git shortlog -sn <last-tag>..HEAD 查找所有贡献者
• 在 Technical Details 部分按提交数列出贡献者

4. 更新 Sphinx 文档

更新 docs/source/index.rst 中的 Recent Releases 部分：

# Update Recent Releases section (keep latest 3 releases)
# Add new release at top, remove oldest (v0.1.X-3)

格式：

Recent Releases
---------------

**v0.1.44 (January 28, 2026)** - Execute Mode for Independent Plan Selection

New Execute mode for cycling through Normal → Planning → Execute modes via ``Shift+Tab``. Users can independently browse and select from existing plans with a plan selector popover. Context paths preserved between planning and execution phases. Enhanced case studies page with setup guides and quick start instructions.

**v0.1.43 (January 26, 2026)** - Tool Call Batching & Interactive Case Studies

...

**v0.1.42 (January 23, 2026)** - TUI Visual Redesign

...

此部分仅保留最近的 3 个版本。较早的版本仍保留在完整变更日志中。

5. 更新配置文档

更新 massgen/configs/README.md 中的 Release History 部分：

## Release History & Examples

### v0.1.44 - Latest
**New Features:** Execute Mode for Independent Plan Selection, Case Studies UX Enhancements

**Key Features:**
- **Execute Mode Cycling**: Navigate through Normal → Planning → Execute modes via `Shift+Tab`
- **Plan Selector Popover**: Browse and select from up to 10 recent plans with timestamps
- **Context Path Preservation**: Context paths automatically preserved between planning and execution
- **Enhanced Case Studies**: Setup guides and quick start instructions on case studies page

**Example Usage:**
```bash
# Use the TUI with plan mode cycling
massgen --config @examples/basic/multi/three_agents_default

# In the TUI:
# 1. Press Shift+Tab to enter Planning mode
# 2. Create a plan: "Create a Python web scraper for news articles"
# 3. Press Shift+Tab twice to enter Execute mode
# 4. Select your plan from the popover and press Enter to execute

### 6. Update README.md

#### 6.1 Latest Features Section

Update the "🆕 Latest Features" section:

```markdown
## 🆕 Latest Features (v0.1.44)

**🎉 Released: January 28, 2026**

**What's New in v0.1.44:**
- **🔄 Execute Mode** - Cycle through Normal → Planning → Execute modes via `Shift+Tab` to independently browse and execute existing plans
- **📋 Plan Selector** - Browse up to 10 recent plans with timestamps, view full task breakdowns, and execute with preserved context paths
- **📚 Enhanced Case Studies** - Interactive setup guides and quick start instructions on case studies page
- **⚡ TUI Performance** - Optimized timeline rendering with viewport-based scrolling for faster UI responsiveness
- **🔧 Plan Mode Fixes** - Fixed planning instruction injection bug in execute mode, improved tool tracking

**Try v0.1.44 Features:**
```bash
# Install or upgrade
pip install --upgrade massgen

# Experience Execute mode with plan cycling
uv run massgen --display textual

# In the TUI:
# 1. Press Shift+Tab to enter Planning mode
# 2. Create a plan: "Build a Python web scraper"
# 3. Press Shift+Tab twice to enter Execute mode
# 4. Select your plan and press Enter to execute

Also update the table of contents link from v0.1.43 → v0.1.44.

#### 6.2 Recent Achievements Section

Move the current "Recent Achievements" to "Previous Achievements" and add new release:

```markdown
### Recent Achievements (v0.1.44)

**🎉 Released: January 28, 2026**

#### Execute Mode for Independent Plan Selection
- **Mode Cycling**: Navigate through Normal → Planning → Execute modes via `Shift+Tab` or mode bar click
- **Plan Selector Popover**: Browse up to 10 recent plans with timestamps and original prompts
- **View Full Plan**: Modal displays complete task breakdown from selected plan
- **Empty Submission**: Press Enter to execute selected plan without additional input
- **Context Path Preservation**: Context paths (`@/path/to/file`) automatically restored from planning to execution phase

...

### Previous Achievements (v0.0.3 - v0.1.43)

✅ **Tool Call Batching & Interactive Case Studies (v0.1.43)**: Consecutive MCP tool calls grouped into collapsible tree views...

同时更新路线图目录链接：

• [Recent Achievements (v0.1.43)] → [Recent Achievements (v0.1.44)]
• [Previous Achievements (v0.0.3 - v0.1.42)] → [Previous Achievements (v0.0.3 - v0.1.43)]
• [v0.1.44 Roadmap] → [v0.1.45 Roadmap]

更新底部的路线图部分，使其指向下一个版本（v0.1.45）。

7. 更新 ROADMAP.md

更新主路线图文件：

7.1 版本和日期

**Current Version:** v0.1.44

**Last Updated:** January 28, 2026

7.2 发布表格

将所有发布版本下移，并添加新的下一版本：

| Release | Target | Feature | Owner | Use Case |
|---------|--------|---------|-------|----------|
| **v0.1.45** | 01/30/26 | Improve Subagent Display in TUI | @ncrispino | Stream and view subagents with full timeline in TUI ([#821](...)) |
| **v0.1.46** | 02/02/26 | Next feature | @owner | Use case |

7.3 添加已完成部分

将刚发布的版本标记为 COMPLETED：

## ✅ v0.1.44 - Execute Mode & Case Studies Enhancement (COMPLETED)

**Released: January 28, 2026**

### Features

- **Execute Mode**: Independent mode for browsing and executing existing plans ([#819](...))
  - Cycle through Normal → Planning → Execute modes via `Shift+Tab`
  - Plan selector popover shows up to 10 recent plans with timestamps
  - "View Full Plan" button opens modal with all tasks
  - Empty submission executes selected plan
  - Context paths preserved from planning to execution phase

...

### Bug Fixes
- Fixed planning instruction injection during execute mode
- Improved tool call spacing in TUI
- Enhanced timeline performance with viewport optimization

7.4 更新下一版本部分

更改即将发布版本的标题：

## 📋 v0.1.45 - Improve Subagent Display in TUI

### Features

**1. Subagent TUI Streaming** (@ncrispino)
- Issue: [#821](...)
- Stream and display subagents almost identically to main process in TUI
...

8. 创建下一版本路线图

创建 ROADMAP_v0.1.X+1.md，并列出详细里程碑：

# MassGen v0.1.45 Roadmap

## Overview

Version 0.1.45 focuses on [MAIN THEME].

- **Feature 1** (Required): Description
- **Feature 2** (Required): Description

## Key Technical Priorities

1. **Feature 1**: Details
   **Use Case**: Why this matters

2. **Feature 2**: Details
   **Use Case**: Why this matters

## Key Milestones

### Milestone 1: [Feature Name] (REQUIRED)

**Goal**: What we're building

**Owner**: @username (discord)

**Issue**: [#XXX](...)

#### 1.1 Research & Design
- [ ] Task 1
- [ ] Task 2

#### 1.2 Implementation
- [ ] Task 1
- [ ] Task 2

...

**Success Criteria**:
- Criteria 1
- Criteria 2

查看 GitHub issues，尤其是带有下一版本里程碑标签的 issue，以填充路线图。

9. 构建 Sphinx 文档

构建并验证 Sphinx 文档：

cd docs
make clean
make html

检查以下事项：

• ❌ 无构建错误
• ❌ 无失效链接
• ⚠️ 尽量减少警告（记录无法避免的警告）
• ✅ 新内容正确渲染

可选：运行链接检查器：

cd docs
make linkcheck

10. 编写发布说明

创建 RELEASE_NOTES_v0.1.X.md，遵循之前版本采用的格式。

**格式参考：**查看 GitHub 上的上一版本：

gh release view v0.1.43

模板结构：

# 🚀 Release Highlights — v0.1.X (YYYY-MM-DD)

### 🎯 [Feature Name](https://docs.massgen.ai/en/latest/path/to/docs.html)
- **Bullet Point**: Description
- **Bullet Point**: Description

### 📚 [Another Feature](https://docs.massgen.ai/en/latest/path/to/docs.html)
- **Bullet Point**: Description

### 🔧 Bug Fixes
- **Fix Description**: What was fixed

---

### 📖 Getting Started
- [**Quick Start Guide**](https://github.com/massgen/MassGen?tab=readme-ov-file#1--installation): Try the new features today
- **Try Feature Name**:

```bash
# Example command showing the new feature
uv run massgen [example command]

变更内容

• PR 标题，作者为 @author，链接：PR_URL
• PR 标题，作者为 @author，链接：PR_URL

完整变更日志：https://github.com/massgen/MassGen/compare/v0.1.X-1...v0.1.X

**Get PRs for What's Changed:**
```bash
gh pr list --base dev/v0.1.X --state merged --json number,title,url,author \
  | jq -r '.[] | "* \(.title) by @\(.author.login) in \(.url)"'

重要事项：

• 使用表情符号作为章节标题（🚀 🔄 📚 ⚡ 🔧 📖）
• 将功能名称链接到相关文档（确认链接准确！）
• 添加实用的示例命令
• 在“What's Changed”中列出所有已合并的 PR
• 添加“Full Changelog”比较链接

11. 生成公告

创建 docs/announcements/current-release.md：

# MassGen vX.X.X Release Announcement

## Release Summary

We're excited to release MassGen vX.X.X, adding [MAIN FEATURE]! 🚀

[2-3 sentences describing the key changes]

## Install

\`\`\`bash
pip install massgen==X.X.X
\`\`\`

## Links

- **Release notes:** https://github.com/massgen/MassGen/releases/tag/vX.X.X
- **X post:** [TO BE ADDED AFTER POSTING]
- **LinkedIn post:** [TO BE ADDED AFTER POSTING]

12. 验证文档

检查所需文档是否存在：

# Check for user guide updates (if new features)
ls docs/source/user_guide/

# Check capabilities.py updated (if new models)
git diff v0.1.33..HEAD -- massgen/backend/capabilities.py

# Check token_manager.py (if pricing changes)
git diff v0.1.33..HEAD -- massgen/token_manager/token_manager.py

# Check for case study
ls docs/source/examples/case_studies/

13. 检查字符数

确认公告符合 LinkedIn 约 3000 个字符的限制：

# Count characters
cat docs/announcements/current-release.md docs/announcements/feature-highlights.md | wc -m

# Should be < 3000

14. 建议截图/媒体

根据此版本中的更改，建议要截取的截图或 GIF：

功能与截图的对应关系：

更改类型	截图建议
新增后端/模型支持	终端显示 Agent 使用新模型并成功响应
多 Agent 协作	多个 Agent 并行工作，并显示彩色输出
投票/共识	显示投票阶段、Agent 的决策和最终选择
MCP 工具	工具执行及其可见结果（文件操作、搜索等）
上下文压缩	日志输出显示压缩统计信息和消息数量
记忆/持久化	Agent 回忆此前会话中的上下文
Web UI 更改	显示 Agent 活动或新增 UI 功能的仪表板
成本跟踪	汇总显示每个 Agent 的 token 用量和成本
错误处理	Agent 从故障中平稳恢复
性能改进	前后计时或吞吐量对比
新增配置选项	突出显示新增选项的 YAML 配置片段

分析方法：

1. 查看提交中的主要功能
2. 找出最具视觉吸引力的更改
3. 建议运行特定命令来展示该功能
4. 注明使用 VHS 制作 GIF 是否比静态截图更合适

输出示例：

### 📸 Suggested Screenshot for v0.1.34

Based on this release's changes, recommend capturing:

**Primary:** GPT-5 model support
- Run: `massgen --config massgen/configs/providers/openai/gpt5_demo.yaml "Explain quantum computing"`
- Capture: Terminal showing GPT-5 model name in agent output with response

**Alternative:** Context compression improvements
- Run: `massgen --automation --config [long-context-config] "question" | grep compression`
- Capture: Log output showing reduced token counts

**Media type:** Static screenshot is fine (no complex animation needed)

15. 输出摘要

打印一份清单：

## Release Prep Summary for v0.1.34

✅ Archived previous announcement → archive/v0.1.33.md
✅ Updated CHANGELOG.md with v0.1.34 entry
✅ Updated docs/source/index.rst Recent Releases
✅ Updated massgen/configs/README.md Release History
✅ Updated README.md Latest Features section
✅ Updated README.md Recent Achievements section
✅ Updated ROADMAP.md (current version, release table, completed section)
✅ Created ROADMAP_v0.1.35.md for next release
✅ Built Sphinx documentation successfully
✅ Created current-release.md
✅ Character count: 2847/3000

### Manual Steps Remaining:
1. Review all updated files for accuracy
2. Capture suggested screenshot (see below)
3. Stage and commit changes
4. Push and create PR to main
5. After merge: Create tag (git tag v0.1.34 && git push origin v0.1.34)
6. Publish GitHub Release (triggers PyPI publish)
7. Post to LinkedIn/X with screenshot, update links in current-release.md

### 📸 Screenshot Suggestion:
[Feature-specific suggestion based on changes]

### Validation Warnings:
⚠️ No case study found for this release
⚠️ capabilities.py was modified - verify docs updated
⚠️ README_PYPI.md will auto-sync via pre-commit hook

参考文件

文档文件

• 更新日志： CHANGELOG.md - 完整的版本发布历史
• Sphinx 文档主页： docs/source/index.rst - Recent Releases 部分
• 配置 README： massgen/configs/README.md - Release History & Examples
• 主 README： README.md - Latest Features and Recent Achievements
• 主路线图： ROADMAP.md - 当前版本、版本发布表、已完成的版本
• 下一版本路线图： ROADMAP_v0.1.X+1.md - 下一版本的详细里程碑

公告文件

• 公告目录： docs/announcements/
• 当前版本： docs/announcements/current-release.md
• 功能亮点： docs/announcements/feature-highlights.md
• 归档： docs/announcements/archive/ - 过往版本

流程文档

• 发布清单： docs/dev_notes/release_checklist.md - 完整的分步指南
• README 同步： README_PYPI.md - 通过 pre-commit hook 自动同步

提示

• 在创建 PR 前，在发布分支（例如 dev/v0.1.44）上运行此技能
• 提交前务必检查所有生成内容，确保准确无误
• 如果此版本新增了重要功能，请更新 feature-highlights.md
• 在社交媒体发布公告后，更新 current-release.md 中的链接
• README_PYPI.md 会通过 pre-commit hook 自动同步，只需提交 README.md 的更改
• Recent Releases 部分最多保留 3 条（Sphinx 文档、CHANGELOG 顶部部分）
• 在路线图更新中使用 GitHub issue 编号，以便追溯
• 构建 Sphinx 文档（cd docs && make html），尽早发现格式问题