openspec-sync-specs

用途

openspec-sync-specs 用于将某个变更（change）中的增量规格（delta specs）同步到主规格（main specs），且不归档该变更。当用户希望用增量规格中的改动更新主规格、但暂不归档变更时使用。

这是一个由智能体驱动的操作：智能体会读取增量规格，并直接编辑主规格来应用改动，从而实现智能合并（例如添加一个场景而无需复制整个需求）。

主要能力

从变更中读取增量规格并应用到主规格。
支持四类需求变更：ADDED（新增需求）、MODIFIED（修改现有需求）、REMOVED（移除需求）、RENAMED（重命名需求，使用 FROM:/TO: 格式）。
智能合并：增量代表意图而非整体替换，可只添加新场景而不复制已有场景，并保留增量中未提及的场景与内容。
当能力对应的主规格尚不存在时，创建新的主规格文件，包含 Purpose 段（可简短，标记为 TBD）和 Requirements 段。
操作具备幂等性：运行两次应得到相同结果。

使用方式

若未提供变更名称，提示用户选择：运行 openspec list --json 获取可用变更，使用 AskUserQuestion 工具让用户选择。展示带有增量规格（位于 specs/ 目录下）的变更。注意：不要猜测或自动选择变更，始终让用户选择。
查找增量规格：在 openspec/changes/<name>/specs/*/spec.md 中查找增量规格文件。每个增量规格文件包含如下区块：
- ## ADDED Requirements — 要添加的新需求
- ## MODIFIED Requirements — 对现有需求的更改
- ## REMOVED Requirements — 要移除的需求
- ## RENAMED Requirements — 要重命名的需求（FROM:/TO: 格式）若未找到增量规格，告知用户并停止。
对每个增量规格，将改动应用到主规格。对于每个在 openspec/changes/<name>/specs/<capability>/spec.md 有增量规格的能力： a. 读取增量规格以理解预期改动。 b. 读取主规格 openspec/specs/<capability>/spec.md（可能尚不存在）。 c. 智能应用改动：
- ADDED Requirements：若主规格中不存在该需求则添加；若已存在则更新以匹配（视为隐式 MODIFIED）。
- MODIFIED Requirements：在主规格中找到该需求并应用改动，可以是添加新场景（无需复制已有场景）、修改现有场景、更改需求描述；保留增量中未提及的场景/内容。
- REMOVED Requirements：从主规格中移除整个需求区块。
- RENAMED Requirements：找到 FROM 需求，重命名为 TO。 d. 若能力尚不存在则创建新的主规格：创建 openspec/specs/<capability>/spec.md，添加 Purpose 段（可简短，标记为 TBD），添加包含 ADDED 需求的 Requirements 段。
展示摘要：应用所有改动后，总结哪些能力被更新、做了哪些改动（新增/修改/移除/重命名的需求）。

增量规格格式参考

## 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 下包含该场景——不要复制已有场景。
增量代表意图，而非整体替换。
运用判断力合理地合并改动。

成功输出示例

## Specs Synced: <change-name>

Updated main specs:

**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)

**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"

Main specs are now updated. The change remains active - archive when implementation is complete.

适用场景

需要将变更中的增量规格同步到主规格，但暂不归档该变更。
希望以智能合并方式应用部分更新，而非整体替换主规格。
需要为尚不存在的能力创建新的主规格文件。

限制与护栏

在做出改动前，需同时读取增量规格和主规格。
保留增量中未提及的现有内容。
若有不清楚之处，请求澄清。
随操作进行展示正在更改的内容。
操作应具备幂等性：运行两次应得到相同结果。
若未提供变更名称，不要猜测或自动选择，始终让用户选择。
若未找到增量规格，告知用户并停止。

技能介绍

用途

主要能力

使用方式

增量规格格式参考

关键原则：智能合并

成功输出示例

适用场景

限制与护栏