openspec-sync-specs

name	openspec-sync-specs
description	将变更中的增量规范同步到主规范。当用户想要用增量规范的变更更新主规范，而不归档变更时使用。
license	MIT
compatibility	Requires openspec CLI.
metadata	{"author":"openspec","version":"1.0","generatedBy":"1.4.1"}

将变更中的增量规范同步到主规范。

这是一个代理驱动的操作 - 你将读取增量规范并直接编辑主规范来应用变更。这允许智能合并（例如，添加一个场景而无需复制整个需求）。

输入：可选指定变更名称。如果省略，检查是否可以从对话上下文推断。如果模糊或不明确，你必须提示用户选择可用变更。

步骤

1. 如果未提供变更名称，提示用户选择

   运行 openspec-cn list --json 获取可用变更。使用 AskUserQuestion tool 让用户选择。

   显示有增量规范的变更（在 specs/ 目录下）。

   重要：不要猜测或自动选择变更。始终让用户选择。

2. 解析变更上下文

   运行：

   openspec-cn status --change "<name>" --json
   

   如果状态报告 actionContext.mode: "workspace-planning"，说明工作区规范同步在当前版本中不支持并停止。不要回退到仓库本地路径或编辑链接的仓库。

3. 查找增量规范

   使用状态 JSON 中的 artifactPaths.specs.existingOutputPaths 作为增量规范文件列表。

   每个增量规范文件包含如下章节：

   • ## ADDED Requirements - 要添加的新需求
   • ## MODIFIED Requirements - 对现有需求的变更
   • ## REMOVED Requirements - 要删除的需求
   • ## RENAMED Requirements - 要重命名的需求（FROM:/TO: 格式）

   如果未找到增量规范，通知用户并停止。

4. 对每个增量规范，将变更应用到主规范

   对 CLI 返回的每个仓库本地能力增量规范路径：

   a. 读取增量规范 了解预期的变更

   b. 读取主规范 位于 openspec/specs/<capability>/spec.md（可能尚不存在）

   c. 智能应用变更：

   新增需求（ADDED Requirements）：

   • 如果需求在主规范中不存在 → 添加它
   • 如果需求已存在 → 更新它以匹配（视为隐式修改）

   修改需求（MODIFIED Requirements）：

   • 在主规范中找到该需求
   • 应用变更 - 可以是：
     • 添加新场景（不需要复制现有的）
     • 修改现有场景
     • 更改需求描述
   • 保留增量规范中未提及的场景/内容

   删除需求（REMOVED Requirements）：

   • 从主规范中删除整个需求块

   重命名需求（RENAMED Requirements）：

   • 找到 FROM 需求，重命名为 TO

   d. 创建新主规范 如果能力还不存在：

   • 创建 openspec/specs/<capability>/spec.md
   • 添加目的章节（可以简短，标记为待定）
   • 添加需求章节，包含新增的需求

5. 显示摘要

   应用所有变更后，总结：

   • 更新了哪些能力
   • 做了什么变更（需求的新增/修改/删除/重命名）

增量规范格式参考

## ADDED Requirements

### Requirement: New Feature
The system SHALL do something new.

#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y

## MODIFIED Requirements

### Requirement: Existing Feature
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B

## REMOVED Requirements

### Requirement: Deprecated Feature

## RENAMED Requirements

- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`

核心原则：智能合并

与程序化合并不同，你可以应用部分更新：

• 要添加一个场景，只需在 MODIFIED 下包含该场景 - 不要复制现有场景
• 增量规范代表意图，不是整体替换
• 使用你的判断力合理地合并变更

成功输出

## 规范已同步：<change-name>

已更新主规范：

**<capability-1>**：
- 新增需求："New Feature"
- 修改需求："Existing Feature"（添加了 1 个场景）

**<capability-2>**：
- 创建了新规范文件
- 新增需求："Another Feature"

主规范已更新。变更仍为活跃状态 - 实现完成后再归档。

护栏

• 修改前读取增量规范和主规范
• 保留增量规范中未提及的现有内容
• 如果有不清楚的地方，询问确认
• 进行中展示你在修改什么
• 操作应该是幂等的 - 运行两次应该得到相同结果