archive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Archive a completed change. Checks completion, syncs features to living documentation, then moves to archive.

<HARD-GATE> After archive is complete: you MUST invoke superpowers:finishing-a-development-branch to guide merge/PR/cleanup. If unavailable (not installed), skip and show summary only — but NEVER skip because you judged the workflow complete without it. When gherkin status is `done`: you MUST sync features before archiving. Before sync: you MUST scan the features being synced for project-specific terms that are not yet defined in `beat/CONTEXT.md`, and prompt the user to add them. After sync, before moving to archive: you MUST run the last-mile ADR sweep — if zero ADRs were written for this change, prompt once before archiving. Do NOT skip any of these because the user wants speed. </HARD-GATE>

Prerequisites (invoke before proceeding)

Superpower	When	Priority
finishing-a-development-branch	After archive is complete	MUST

If unavailable (skill not installed), skip and show archive summary only.

归档已完成的变更。检查完成状态，将功能同步至活文档，然后移至归档。

<HARD-GATE> 归档完成后：你必须调用superpowers:finishing-a-development-branch来指导合并/PR/清理工作。若该功能不可用（未安装），则跳过此步骤仅显示摘要——但绝不能因为你认为工作流已完成而跳过此步骤。当gherkin状态为`done`时：你必须在归档前同步功能。同步前：你必须扫描待同步的功能，查找`beat/CONTEXT.md`中尚未定义的项目特定术语，并提示用户添加这些术语。同步完成后、移至归档前：你必须进行最后一步ADR扫描——若此变更未编写任何ADR，在归档前需提示用户一次。不得因用户追求速度而跳过任何上述步骤。 </HARD-GATE>

前置条件（执行前需调用）

超能力（Superpower）	时机	优先级
finishing-a-development-branch	归档完成后	必须（MUST）

若该功能不可用（技能未安装），则跳过此步骤仅显示归档摘要。

Rationalization Prevention

合理化规避

Thought	Reality
"The change is already archived, finishing-a-development-branch is optional cleanup"	Archive without branch guidance leaves orphan branches and uncommitted work. The skill ensures nothing is forgotten.
"I'll just tell the user to create a PR manually"	finishing-a-development-branch offers structured options (merge, PR, cleanup) tailored to the current state. Manual advice misses context.
"Skipping sync is fine, the user can run it later"	There is no separate sync skill. Archive is the only place features get synced. Skipping means features are lost from living documentation.
"The .orig backups can be cleaned up later"	Orphaned `.orig` files hide scenarios from BDD runners permanently. Cleanup is part of archive, not a separate step.
"Glossary terms can be added later, it's just docs"	Once the features sync into `beat/features/` , the undefined terms become user-facing living documentation. Future readers can't tell which terms are canonical vs. ad hoc. The scan-and-prompt is two minutes — do it before sync.
"We didn't write any ADRs but the design.md captures everything"	design.md gets archived with the change. Cross-change decisions need to live in `docs/adr/` . The last-mile sweep is one prompt; if nothing qualifies, it costs nothing.

想法	实际情况
"变更已归档，finishing-a-development-branch只是可选的清理工作"	未进行分支指导的归档会留下孤立分支和未提交的工作。该技能确保不会遗漏任何内容。
"我会直接告诉用户手动创建PR"	finishing-a-development-branch会根据当前状态提供结构化选项（合并、PR、清理）。手动建议会缺失上下文信息。
"跳过同步也没关系，用户之后可以再运行"	没有单独的同步技能。归档是功能同步至活文档的唯一途径。跳过同步意味着功能会从活文档中丢失。
".orig备份文件之后再清理也可以"	孤立的 `.orig` 文件会永久隐藏BDD运行器的场景。清理是归档流程的一部分，而非单独步骤。
"术语表可以之后再添加，只是文档而已"	一旦功能同步至 `beat/features/` ，未定义的术语会成为面向用户的活文档。未来的读者无法区分哪些术语是规范的，哪些是临时的。扫描并提示仅需两分钟——请在同步前完成。
"我们没有编写任何ADR，但design.md已记录所有内容"	design.md会随变更一起归档。跨变更的决策需要存放在 `docs/adr/` 中。最后一步扫描仅需一次提示；若没有符合条件的内容，不会产生任何成本。

Red Flags — STOP if you catch yourself:

警示信号——若发现以下情况请立即停止：

Completing archive without invoking finishing-a-development-branch
Skipping the sync step without checking if gherkin is done
Moving to archive without asking user about capability mapping (when features exist)
Completing archive while
```
.feature.orig
```
files remain in
```
beat/features/
```
Syncing features without first scanning for project-specific terms missing from
```
beat/CONTEXT.md
```
Archiving a change with zero ADRs without running the last-mile sweep prompt

未调用finishing-a-development-branch就完成归档
未检查gherkin是否完成就跳过同步步骤
未询问用户关于能力映射（当存在功能时）就移至归档
```
beat/features/
```
中仍存在
```
.feature.orig
```
文件时完成归档
未先扫描
```
beat/CONTEXT.md
```
中缺失的项目特定术语就同步功能
未进行最后一步扫描提示就归档无ADR的变更

Process Flow

流程流程图

dot

digraph archive {
    "Select change" [shape=box];
    "Check artifact completion" [shape=diamond];
    "Warn incomplete" [shape=box];
    "Check task completion" [shape=diamond];
    "Warn incomplete tasks" [shape=box];
    "Gherkin done?" [shape=diamond];
    "Ask capability mapping" [shape=box];
    "Scan features for\nundefined terms" [shape=box, style=bold];
    "Sync features" [shape=box];
    "Skip sync" [shape=box];
    "Last-mile ADR sweep" [shape=box, style=bold];
    "Move to archive" [shape=box];
    "Invoke finishing-a-development-branch" [shape=box, style=bold];
    "Show summary" [shape=doublecircle];

    "Select change" -> "Check artifact completion";
    "Check artifact completion" -> "Warn incomplete" [label="pending found"];
    "Check artifact completion" -> "Check task completion" [label="all done/skipped"];
    "Warn incomplete" -> "Check task completion" [label="user confirms"];
    "Check task completion" -> "Warn incomplete tasks" [label="incomplete"];
    "Check task completion" -> "Gherkin done?" [label="all complete\nor no tasks"];
    "Warn incomplete tasks" -> "Gherkin done?" [label="user confirms"];
    "Gherkin done?" -> "Ask capability mapping" [label="done"];
    "Gherkin done?" -> "Skip sync" [label="skipped"];
    "Ask capability mapping" -> "Scan features for\nundefined terms";
    "Scan features for\nundefined terms" -> "Sync features";
    "Sync features" -> "Last-mile ADR sweep";
    "Skip sync" -> "Last-mile ADR sweep";
    "Last-mile ADR sweep" -> "Move to archive";
    "Move to archive" -> "Invoke finishing-a-development-branch";
    "Invoke finishing-a-development-branch" -> "Show summary";
}

Input: Optionally specify a change name. If omitted, infer from context or prompt.

Steps

Select the change

If no name provided:
- Look for
```
beat/changes/
```
  directories (excluding
```
archive/
```
  )
- If only one exists, use it
- If multiple exist, use AskUserQuestion tool to let user select
- Show only active (non-archived) changes
Check artifact completion
Read
```
beat/changes/<name>/status.yaml
```
(schema:
```
references/status-schema.md
```
). Check which artifacts are
```
done
```
vs
```
pending
```
(not
```
skipped
```
).
If any non-skipped artifacts are still
pending
:
- Display warning listing incomplete artifacts
- Use AskUserQuestion tool to confirm user wants to proceed
- Proceed if user confirms
Check task completion (if tasks.md exists)
Read
```
tasks.md
```
. Count
```
- [ ]
```
(incomplete) vs
```
- [x]
```
(complete).
If incomplete tasks found:
- Display warning: "N/M tasks incomplete"
- Use AskUserQuestion tool to confirm
- Proceed if user confirms

Sync features to living documentation

Check

status.yaml

If gherkin status is
skipped
: Skip sync (no features to sync). Proceed to Step 5.

If gherkin status is
done
:

Read from

beat/changes/<name>/

```
features/*.feature
```
(all Gherkin files)
```
proposal.md
```
(if exists)
```
design.md
```
(if exists)

If no feature files exist: skip sync, proceed to Step 5.

Read

beat/config.yaml

if it exists (schema:

references/config-schema.md

). Use

language

for README content language.

Determine capability mapping:

Use AskUserQuestion tool:

"Where should each feature be synced? Existing capabilities: [list from beat/features/]. Or enter a new name."

If only one feature file and the mapping is obvious from context, suggest a default.

Scan features for undefined terms (Layer 1 living-doc enforcement):

Read

beat/CONTEXT.md

if it exists (schema:

references/context-format.md

). The glossary is lazy — it may not exist yet if this is the project's first synced change.

Scan the feature files being synced for bolded project-specific terms. For each term:

If it exists in
```
beat/CONTEXT.md
```
: OK, continue.
If it doesn't: use AskUserQuestion tool:
"Term '<term>' appears in scenarios but isn't in beat/CONTEXT.md. Add it now?"
- Yes (recommended): provide a one-sentence definition; Beat appends it
- Skip this term
- Skip all remaining (record the count for the summary)

When the user adds a term, append it to

beat/CONTEXT.md

following the structure in

references/context-format.md

(one-sentence definition, optional

_Avoid_

aliases). Create

beat/CONTEXT.md

lazily if it doesn't exist.

If no project-specific bolded terms appear in the scanned features, skip this sub-step silently.

Sync files:

beat/features/

doesn't exist, create it:

mkdir -p beat/features

Source (change)	Target (beat/features/)	Behavior
`features/*.feature`	`beat/features/<capability>/`	Add or update feature files
`proposal.md`	`beat/features/<capability>/proposal.md`	Copy to capability
`design.md`	`beat/features/<capability>/design.md`	Copy to capability

Handle .orig backups (when

status.yaml

has

gherkin.modified

For each path in

gherkin.modified

The modified version is in
```
changes/<name>/features/
```
— sync it to
```
beat/features/<capability>/
```
(same as new features, unified flow)
Delete the
```
.feature.orig
```
backup from
```
beat/features/
```
If the project uses pytest-bdd: update
```
@scenario
```
decorator paths in test files (from
```
beat/changes/.../x.feature
```
→
```
beat/features/<capability>/x.feature
```
)

Verify no

.feature.orig

files remain in

beat/features/

before proceeding.

Create

beat/features/<capability>/README.md

if it doesn't exist (placeholder description). Create or update

beat/features/README.md

with global navigation.

Update

status.yaml

phase to

sync

Last-mile ADR sweep (Layer 2 living-doc enforcement):

Count ADR files written or referenced during this change:

Check
```
docs/adr/
```
for files created since this change started (git diff against the change's base commit)
Scan
```
design.md
```
and
```
tasks.md
```
for
```
docs/adr/NNNN-
```
cross-references

If at least one ADR exists for this change: skip the sweep silently. Earlier triggers (in

/beat:design

/beat:plan

/beat:apply

) already caught the candidates.

If zero ADRs exist for this change: prompt once using AskUserQuestion tool:

"No ADRs recorded for this change. Was there any hard-to-reverse + surprising + real-trade-off decision worth recording before archiving?"

No, none qualified

Yes, let me describe it now

If user describes one, run the three-condition gate from

references/adr-format.md

. If all three hold, write the ADR under

docs/adr/

with the next sequential number. If not all three hold, note the skip.

Either way, proceed to archive.

Perform the archive
Update
```
status.yaml
```
: set phase to
```
archive
```
.
bash
```
mkdir -p beat/changes/archive
```
Generate target name:
```
YYYY-MM-DD-<change-name>
```
Check if target already exists:
- If yes: fail with error, suggest renaming
- If no: move the directory
bash
```
mv beat/changes/<name> beat/changes/archive/YYYY-MM-DD-<name>
```

Show summary

## Archive Complete

**Change:** <change-name>
**Archived to:** beat/changes/archive/YYYY-MM-DD-<name>/
**Features:** Synced to beat/features/ (or "Sync skipped" or "No features to sync")
**Glossary:** N terms added to beat/CONTEXT.md (or "no changes" / "M terms skipped")
**ADRs:** N written to docs/adr/ (or "none recorded — last-mile sweep declined")
**Artifacts:** N done, M skipped
**Tasks:** X/Y complete (or "No tasks file")

Finish the development branch
After showing the summary, invoke
```
superpowers:finishing-a-development-branch
```
(if available) to guide the user through merge, PR creation, or cleanup. If not available, skip this step.

Guardrails

Always prompt for change selection if not provided
Don't block archive on warnings -- inform and confirm
Sync features inline before archiving
Show clear summary of what happened
If archive target already exists, don't overwrite

dot

digraph archive {
    "Select change" [shape=box];
    "Check artifact completion" [shape=diamond];
    "Warn incomplete" [shape=box];
    "Check task completion" [shape=diamond];
    "Warn incomplete tasks" [shape=box];
    "Gherkin done?" [shape=diamond];
    "Ask capability mapping" [shape=box];
    "Scan features for\nundefined terms" [shape=box, style=bold];
    "Sync features" [shape=box];
    "Skip sync" [shape=box];
    "Last-mile ADR sweep" [shape=box, style=bold];
    "Move to archive" [shape=box];
    "Invoke finishing-a-development-branch" [shape=box, style=bold];
    "Show summary" [shape=doublecircle];

    "Select change" -> "Check artifact completion";
    "Check artifact completion" -> "Warn incomplete" [label="pending found"];
    "Check artifact completion" -> "Check task completion" [label="all done/skipped"];
    "Warn incomplete" -> "Check task completion" [label="user confirms"];
    "Check task completion" -> "Warn incomplete tasks" [label="incomplete"];
    "Check task completion" -> "Gherkin done?" [label="all complete\nor no tasks"];
    "Warn incomplete tasks" -> "Gherkin done?" [label="user confirms"];
    "Gherkin done?" -> "Ask capability mapping" [label="done"];
    "Gherkin done?" -> "Skip sync" [label="skipped"];
    "Ask capability mapping" -> "Scan features for\nundefined terms";
    "Scan features for\nundefined terms" -> "Sync features";
    "Sync features" -> "Last-mile ADR sweep";
    "Skip sync" -> "Last-mile ADR sweep";
    "Last-mile ADR sweep" -> "Move to archive";
    "Move to archive" -> "Invoke finishing-a-development-branch";
    "Invoke finishing-a-development-branch" -> "Show summary";
}

输入：可选择指定变更名称。若未指定，则从上下文推断或提示用户输入。

步骤

选择变更

若未提供名称：
- 查找
```
beat/changes/
```
  目录（排除
```
archive/
```
  ）
- 若仅存在一个目录，则使用该目录
- 若存在多个目录，则使用AskUserQuestion工具让用户选择
- 仅显示活跃（未归档）的变更
检查工件完成状态
读取
```
beat/changes/<name>/status.yaml
```
（schema:
```
references/status-schema.md
```
）。检查哪些工件处于
```
done
```
状态，哪些处于
```
pending
```
状态（非
```
skipped
```
）。
若存在未跳过且仍处于
pending
状态的工件：
- 显示包含未完成工件的警告信息
- 使用AskUserQuestion工具确认用户是否要继续
- 若用户确认则继续
检查任务完成状态（若tasks.md存在）
读取
```
tasks.md
```
。统计
```
- [ ]
```
（未完成）和
```
- [x]
```
（已完成）的数量。
若发现未完成任务：
- 显示警告："N/M项任务未完成"
- 使用AskUserQuestion工具确认
- 若用户确认则继续

将功能同步至活文档

检查

status.yaml

：

若gherkin状态为
skipped
：跳过同步（无功能可同步）。继续执行步骤5。

若gherkin状态为
done
：

从

beat/changes/<name>/

读取以下内容：

```
features/*.feature
```
（所有Gherkin文件）
```
proposal.md
```
（若存在）
```
design.md
```
（若存在）

若不存在功能文件：跳过同步，继续执行步骤5。

若

beat/config.yaml

存在则读取（schema:

references/config-schema.md

）。使用

language

字段确定README内容的语言。

确定能力映射：

使用AskUserQuestion工具：

"每个功能应同步至何处？现有能力：[来自beat/features/的列表]。或输入新名称。"

若仅存在一个功能文件且映射关系可从上下文明显推断，则建议默认映射。

扫描功能中的未定义术语（第一层活文档强制要求）：

若

beat/CONTEXT.md

存在则读取（schema:

references/context-format.md

）。术语表是延迟创建的——若这是项目首次同步变更，该文件可能尚未存在。

扫描待同步的功能文件中的加粗项目特定术语。对于每个术语：

若该术语已存在于
```
beat/CONTEXT.md
```
中：正常，继续。
若不存在：使用AskUserQuestion工具：
"术语'<term>'出现在场景中，但未在beat/CONTEXT.md中定义。是否现在添加？"
- 是（推荐）：提供一句定义；Beat会将其追加到文件中
- 跳过该术语
- 跳过所有剩余术语（记录跳过数量至摘要）

当用户添加术语时，按照

references/context-format.md

中的结构将其追加到

beat/CONTEXT.md

中（一句定义，可选

_Avoid_

别名）。若

beat/CONTEXT.md

不存在，则延迟创建该文件。

若扫描的功能中未出现项目特定的加粗术语，则静默跳过此子步骤。

同步文件：

若

beat/features/

不存在，创建该目录：

mkdir -p beat/features

源（变更）	目标（beat/features/）	行为
`features/*.feature`	`beat/features/<capability>/`	添加或更新功能文件
`proposal.md`	`beat/features/<capability>/proposal.md`	复制至对应能力目录
`design.md`	`beat/features/<capability>/design.md`	复制至对应能力目录

处理.orig备份文件（当

status.yaml

中存在

gherkin.modified

时）：

对于

gherkin.modified

中的每个路径：

修改后的版本位于
```
changes/<name>/features/
```
中——将其同步至
```
beat/features/<capability>/
```
（与新功能流程一致）
从
```
beat/features/
```
中删除
```
.feature.orig
```
备份文件
若项目使用pytest-bdd：更新测试文件中的
```
@scenario
```
装饰器路径（从
```
beat/changes/.../x.feature
```
→
```
beat/features/<capability>/x.feature
```
）

继续执行前需确认

beat/features/

中无

.feature.orig

文件残留。

若

beat/features/<capability>/README.md

不存在则创建（占位描述）。创建或更新

beat/features/README.md

以添加全局导航。

将

status.yaml

中的阶段更新为

sync

。

最后一步ADR扫描（第二层活文档强制要求）：

统计此变更期间编写或引用的ADR文件数量：

检查
```
docs/adr/
```
中自变更开始以来创建的文件（与变更的基准提交进行git diff）
扫描
```
design.md
```
和
```
tasks.md
```
中是否存在
```
docs/adr/NNNN-
```
交叉引用

若此变更至少存在一个ADR： 静默跳过扫描。早期触发条件（在

/beat:design

、

/beat:plan

、

/beat:apply

中）已捕获符合条件的内容。

若此变更无ADR： 使用AskUserQuestion工具提示一次：

"此变更未记录任何ADR。是否存在任何难以逆转、令人意外且涉及实际权衡的决策值得在归档前记录？"

否，没有符合条件的决策

是，我现在描述它

若用户描述了一个决策，运行

references/adr-format.md

中的三条件检查。若全部满足，则将ADR写入

docs/adr/

目录，并使用下一个序号。若未全部满足，则记录跳过情况。

无论哪种情况，继续执行归档。

执行归档
更新
```
status.yaml
```
：将阶段设置为
```
archive
```
。
bash
```
mkdir -p beat/changes/archive
```
生成目标名称：
```
YYYY-MM-DD-<change-name>
```
检查目标是否已存在：
- 若存在：报错失败，建议重命名
- 若不存在：移动目录
bash
```
mv beat/changes/<name> beat/changes/archive/YYYY-MM-DD-<name>
```

显示摘要

## 归档完成

**变更：** <change-name>
**归档至：** beat/changes/archive/YYYY-MM-DD-<name>/
**功能：** 已同步至beat/features/（或"同步已跳过"或"无功能可同步"）
**术语表：** 已向beat/CONTEXT.md添加N个术语（或"无变更" / "已跳过M个术语"）
**ADR：** 已写入docs/adr/ N个（或"未记录任何ADR——最后一步扫描已拒绝"）
**工件：** N个已完成，M个已跳过
**任务：** X/Y已完成（或"无任务文件"）

完成开发分支
显示摘要后，若
```
superpowers:finishing-a-development-branch
```
可用，则调用它来指导用户完成合并、PR创建或清理工作。若不可用，则跳过此步骤。

防护措施

若未提供变更名称，始终提示用户选择
不要因警告而阻止归档——告知用户并确认
归档前内联同步功能
清晰显示已执行操作的摘要
若归档目标已存在，请勿覆盖