openspec-archive

OpenSpec：归档

完成一项变更，并更新事实来源规范。

用法

/openspec-archive <change-id>

示例：

/openspec-archive add-user-search

此技能的作用

1. 验证所有任务均已完成
2. 将增量规范合并到主规范中
3. 为变更添加时间戳并移至归档
4. 更新完成状态

执行步骤

步骤 1：验证完成情况

检查 openspec/changes/{change-id}/tasks.md：

• 所有任务均已标记为 [x]
• 所有质量门禁均已通过
• 没有尚未解决的阻塞项

如果尚未完成，请报告缺少的内容并停止。

步骤 2：最终质量检查

运行项目的质量验证命令。归档前必须全部通过。

步骤 3：合并增量规范

针对 openspec/changes/{change-id}/specs/ 中的每个文件：

3.1 检查目标规范是否存在

• 如果 openspec/specs/{component}.md 存在 → 合并变更
• 如果不存在 → 创建新的规范文件

3.2 应用 ADDED 部分

将新要求复制到目标规范中：

# {Component} Specification

## Requirements

### {New Requirement from Delta}
{Description}

#### Scenario: {Name}
- GIVEN ...
- WHEN ...
- THEN ...

3.3 应用 MODIFIED 部分

使用新内容更新目标规范中的现有要求。

3.4 应用 REMOVED 部分

从目标规范中移除已弃用的要求。 将其添加到 ## Deprecated 部分以供参考：

## Deprecated

### {Removed Requirement} (Removed: {date})
Reason: {from delta spec}

步骤 4：归档变更

# Create archive directory with timestamp
mkdir -p openspec/archive/{change-id}

# Move all change files
mv openspec/changes/{change-id}/* openspec/archive/{change-id}/
rmdir openspec/changes/{change-id}

步骤 5：更新归档元数据

将完成信息添加到 openspec/archive/{change-id}/proposal.md：

---

## Archive Information

**Archived:** {YYYY-MM-DD HH:MM}
**Duration:** {days from creation to archive}
**Outcome:** Successfully implemented

### Files Modified
- `lib/feature/...`
- `test/...`

### Specs Updated
- `openspec/specs/{component}.md`

步骤 6：提交归档

git add openspec/
git commit -m "docs(openspec): archive {change-id}

- Merged delta specs into main specs
- Archived change history
- Implementation complete"

步骤 7：报告完成情况

## Archived: {change-id}

### Specs Updated
- `openspec/specs/{component}.md` - {summary of changes}

### Archive Location
- `openspec/archive/{change-id}/`

### Change History
- Created: {original date}
- Completed: {today}
- Duration: {X days}

### Summary
{Brief description of what was accomplished}

---

The OpenSpec workflow for this change is complete.
The specifications are now the source of truth.

合并策略

对于 ADDED 内容

• 将其追加到现有规范中的适当部分
• 保持格式一致
• 如有帮助，可添加创建日期注释

对于 MODIFIED 内容

• 替换现有要求
• 保留其在文档中的原位置
• 注明修改日期

对于 REMOVED 内容

• 移至 Deprecated 部分（不要立即删除）
• 注明移除原因和日期
• 可在之后的清理工作中彻底删除

故障排除

任务尚未完成

Cannot archive: {X} tasks still pending in tasks.md.
Please complete all tasks first or update tasks.md if they're done.

质量门禁未通过

Cannot archive: Quality checks failed.
Please fix issues before archiving.

规范合并冲突

如果目标规范自提案创建后已有变更：

1. 检查两个版本
2. 手动解决冲突
3. 确保最终规范一致
4. 继续归档