openspec-sync-specs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sync delta specs from a change to main specs.

This is an agent-driven operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

If no change name provided, prompt for selection
Run
```
openspec list --json
```
to get available changes. Use the AskUserQuestion tool to let the user select.
Show changes that have delta specs (under
```
specs/
```
directory).
IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.
Find delta specs
Look for delta spec files in
```
openspec/changes/<name>/specs/*/spec.md
```
.
Each delta spec file contains sections like:
- ```
## ADDED Requirements
```
  - New requirements to add
- ```
## MODIFIED Requirements
```
  - Changes to existing requirements
- ```
## REMOVED Requirements
```
  - Requirements to remove
- ```
## RENAMED Requirements
```
  - Requirements to rename (FROM:/TO: format)
If no delta specs found, inform user and stop.
For each delta spec, apply changes to main specs
For each capability with a delta spec at
```
openspec/changes/<name>/specs/<capability>/spec.md
```
:
a. Read the delta spec to understand the intended changes
b. Read the main spec at
```
openspec/specs/<capability>/spec.md
```
(may not exist yet)
c. Apply changes intelligently:

ADDED Requirements:
- If requirement doesn't exist in main spec → add it
- If requirement already exists → update it to match (treat as implicit MODIFIED)
MODIFIED Requirements:
- Find the requirement in main spec
- Apply the changes - this can be:
  - Adding new scenarios (don't need to copy existing ones)
  - Modifying existing scenarios
  - Changing the requirement description
- Preserve scenarios/content not mentioned in the delta
REMOVED Requirements:
- Remove the entire requirement block from main spec
RENAMED Requirements:
- Find the FROM requirement, rename to TO
d. Create new main spec if capability doesn't exist yet:
- Create
```
openspec/specs/<capability>/spec.md
```
- Add Purpose section (can be brief, mark as TBD)
- Add Requirements section with the ADDED requirements
Show summary

After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)

Delta Spec Format Reference

markdown

undefined

将变更中的delta规格同步到主规格中。

这是一个Agent驱动的操作——你需要读取delta规格并直接编辑主规格以应用变更。这支持智能合并（例如，添加一个场景而无需复制整个需求）。

输入：可选择性指定变更名称。如果未指定，请检查是否可以从对话上下文推断。如果模糊或有歧义，你必须提示用户选择可用的变更。

步骤

如果未提供变更名称，提示用户选择
运行
```
openspec list --json
```
以获取可用变更。使用AskUserQuestion工具让用户选择。
展示包含delta规格的变更（位于
```
specs/
```
目录下）。
重要提示：请勿猜测或自动选择变更。务必让用户选择。
查找delta规格
在
```
openspec/changes/<name>/specs/*/spec.md
```
路径下查找delta规格文件。
每个delta规格文件包含以下部分：
- ```
## ADDED Requirements
```
  - 要添加的新需求
- ```
## MODIFIED Requirements
```
  - 对现有需求的变更
- ```
## REMOVED Requirements
```
  - 要移除的需求
- ```
## RENAMED Requirements
```
  - 要重命名的需求（格式为FROM:/TO:）
如果未找到delta规格，告知用户并停止操作。
针对每个delta规格，将变更应用到主规格
对于每个在
```
openspec/changes/<name>/specs/<capability>/spec.md
```
路径下有delta规格的功能：
a. 读取delta规格以理解预期的变更
b. 读取主规格，路径为
```
openspec/specs/<capability>/spec.md
```
（可能尚未存在）
c. 智能应用变更：

ADDED Requirements（新增需求）:
- 如果需求在主规格中不存在 → 添加该需求
- 如果需求已存在 → 更新该需求以匹配delta规格（视为隐式的MODIFIED）
MODIFIED Requirements（修改需求）:
- 在主规格中找到对应需求
- 应用变更，包括：
  - 添加新场景（无需复制现有场景）
  - 修改现有场景
  - 更改需求描述
- 保留delta规格中未提及的现有场景/内容
REMOVED Requirements（移除需求）:
- 从主规格中移除整个需求块
RENAMED Requirements（重命名需求）:
- 找到FROM对应的需求，将其重命名为TO指定的名称
d. 如果功能不存在，创建新的主规格:
- 创建
```
openspec/specs/<capability>/spec.md
```
  文件
- 添加Purpose（用途）部分（可简短，标记为TBD）
- 添加Requirements（需求）部分，包含新增的需求
展示摘要

应用所有变更后，生成摘要：
- 哪些功能已更新
- 进行了哪些变更（新增/修改/移除/重命名需求）

Delta规格格式参考

markdown

undefined

ADDED Requirements

Requirement: New Feature

The system SHALL do something new.

Scenario: Basic case

WHEN user does X
THEN system does Y

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

WHEN user does A
THEN system does B

REMOVED Requirements

Requirement: Deprecated Feature

RENAMED Requirements

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


**Key Principle: Intelligent Merging**

Unlike programmatic merging, you can apply **partial updates**:

- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
- The delta represents *intent*, not a wholesale replacement
- Use your judgment to merge changes sensibly

**Output On Success**

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


**核心原则：智能合并**

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

- 要添加场景，只需在MODIFIED下包含该场景即可——无需复制现有场景
- delta规格代表*意图*，而非完全替换
- 运用你的判断合理合并变更

**成功时的输出**

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.


**Guardrails**

- Read both delta and main specs before making changes
- Preserve existing content not mentioned in delta
- If something is unclear, ask for clarification
- Show what you're changing as you go
- The operation should be idempotent - running twice should give same result

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.


**注意事项**

- 在进行变更前，务必读取delta规格和主规格
- 保留delta规格中未提及的现有内容
- 如果有不明确的地方，请求澄清
- 随时展示你正在进行的变更
- 操作应具备幂等性——运行两次应得到相同结果