version-start · diff

git:20260908.d32431c to git:20260911.414b35f

3 added, 0 removed. Audit A to A.

---

disable-model-invocation: true

name: version-start

description: >

当项目需要规划或启动一个新的产品版本里程碑（如 v1.6、v2.0），明确版本目标、需求范围、

Spec 清单（含 feat/tech/debt/fix 四类平权）、依赖关系和整体验收条件时使用。

不要用于单个 Spec 需求的开发启动（用 spec-start）或项目首次初始化（用 spec-init）。

---

# Version Start

## 运行契约

| 项 | 本 Skill 的约定 |

|----|----------------|

| 输入 | 目标版本号（如 `v1.6`）、版本里程碑目标、计划纳入的 Spec 清单及其属性（`feat` / `tech` / `debt` / `fix`）、预期排期与整体验收标准 |

| 权限 | 创建 `spec/versions/<version>/` 目录，写入 `version-context.md`、`plan.html`，创建 `specs/` 与 `releases/` 子目录；在 `dev` 分支提交初始版本规划 |

| 验证 | 物理目录存在；`version-context.md` 包含完整 Spec 规划表格与依赖声明；`plan.html` 符合 HTML 报告规范且元数据双轨齐全 |

| 停止 | 版本规划与账本创建完成并获得用户确认（或 autopilot 下新鲜验证通过） |

| 升级 | 版本目标与范围存在重大分歧、或依赖跨团队外部前置无法闭环时，停下交由用户决策 |

## 核心原则

1. **Version 是管理与交付实体**：每个版本对一组原子 Spec 负责，统筹交付范围与验收边界。

2. **四类需求平权**：在规划时平等对待 `feat`（业务功能）、`tech`（技术基建/AI底座）、`debt`（技术债治理）与 `fix`（缺陷修复），打破隐性技术债积压。

3. **计划入版 vs 实际发布双轨**：`plan.html` 记录规划意向，实际发布由 `version-release` 严格按交付证据记录。

4. **统一 Git 集成基线**：版本在 `dev` 分支上记录初始规划，后续所有该版本 Spec 均以 `dev` 为开发集成目标。

## 工作流程

### 步骤 1：明确版本目标与范围

与用户对齐以下核心要素：

- **版本号**：符合语义化版本命名，主线版本使用 `vX.Y`（如 `v1.6`），补丁版本使用 `vX.Y.Z`。

- **里程碑目标**：本版本完成后，用户/业务能获得什么新能力？解决了什么核心问题？

- **Spec 规划清单**：列出首批计划纳入的需求项，每项标注属性：

- `feat`：业务/产品功能

- `tech`：技术基建、AI 核心能力（Prompt、Trace、Eval、ASR、模型治理等）

- `debt`：技术债治理、代码重构、性能优化

- `fix`：已知问题修复

- **依赖与关键路径**：哪些 Spec 之间存在时序依赖，哪些依赖外部团队。

- **发布条件**：整体集成测试范围、性能基准、交付物清单。

### 步骤 2：创建版本物理目录

```bash

mkdir -p "spec/versions/<version>/specs"

mkdir -p "spec/versions/<version>/releases"

```

### 步骤 3：创建版本运行账本 `version-context.md`

在 `spec/versions/<version>/version-context.md` 写入版本管理账本：

```markdown

---

version: <version>

status: 规划中

created: YYYY-MM-DD

updated: YYYY-MM-DD

target_freeze_date: YYYY-MM-DD

target_release_date: YYYY-MM-DD

owner: TeamLead

base_branch: dev

---

# Version 运行账本：<version>

## 1. 版本目标

{简明扼要的版本核心目标}

## 2. 规划 Spec 清单（需求性质平权）

| Spec 标识 | 属性 | 标题 / 目标 | 负责人 | 状态 | 依赖前置 |

|---|---|---|---|---|---|

| （待启动） | feat | 用户分析报告中心 | - | 待排期 | - |

| （待启动） | tech | Agent Trace 链路追踪建设 | - | 待排期 | - |

| （待启动） | debt | 数据库连接池与慢查询优化 | - | 待排期 | - |

| （待启动） | fix | 偶发跨租户查询异常修复 | - | 待排期 | - |

## 3. 依赖与风险记录

- **外部依赖**：...

- **技术风险**：...

## 4. 范围变更记录（Scope Change Log）

|---|---|---|---|---|

```

### 步骤 4：生成版本规划报告 `plan.html`

在 `spec/versions/<version>/plan.html` 生成版本规划大盘报告。必须使用 [html-report/templates/version-plan-template.html](../../html-report/templates/version-plan-template.html) 骨架，遵循 `html-report` 规范，声明 `rk:version="<version>"`、`rk:type="version-plan"`、`rk:role="TeamLead"`、`rk:base-branch="dev"`，引用 assets 必须为 3 层相对路径（`../../../html-report/assets/`），展示版本大盘。

### 步骤 5：Git 提交初始版本规划

在当前工作分支（默认开发集成线 `dev`）提交初始版本规划文档：

```bash

git add "spec/versions/<version>"

git commit -m "docs(version): 初始化 <version> 版本规划与运行账本"

```

### 步骤 6：确认与交接

通知用户版本已建立，状态进入 `规划中`（或首个 Spec 启动时进入 `执行中`），后续可通过 `/spec-start` 在该版本下创建具体需求 Spec。

+ ## AWR 运行时接入

+ Version 建立完成后，TeamLead 必须同步建立 AWR 运行视图：将 Version 目标映射为 AWR work group，将计划中的 Spec 映射为稳定的 `SPEC-<slug>` works，并登记 Spec 依赖。初始化前执行 `awr init`/`intake inspect`，确认映射后再接受；不得把 AWR SQLite 当作权威源。后续使用 `awr ready` 判断依赖是否满足，使用 `awr context compile --work <SPEC-ID>` 编译当前任务上下文。`ready` 不等于 R&K 门禁通过，Version 状态仍以 `version-context.md` 为准。详见 `.agents/rules/awr-integration.md`。