adopt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adopt — Brownfield Template Adoption

适配——遗留项目模板适配

This skill audits an existing project's artifacts for format compliance with the template's skill pipeline, then produces a prioritised migration plan.

This is not
/project-stage-detect
.

/project-stage-detect

answers: what exists?

/adopt

answers: will what exists actually work with the template's skills?

A project can have GDDs, ADRs, and stories — and every format-sensitive skill will still fail silently or produce wrong results if those artifacts are in the wrong internal format.

Output:

docs/adoption-plan-[date].md

— a persistent, checkable migration plan.

Argument modes:

Audit mode:

$ARGUMENTS[0]

(blank =

full

)

No argument /
full
: Complete audit — all artifact types
gdds
: GDD format compliance only
adrs
: ADR format compliance only
stories
: Story format compliance only
infra
: Infrastructure artifact gaps only (registry, manifest, sprint-status, stage.txt)

此Skill会审计现有项目的工件是否符合模板Skill流水线的格式规范，然后生成优先级明确的迁移计划。

这不是/project-stage-detect。

/project-stage-detect

回答的是：哪些工件存在？

/adopt

回答的是：现有工件是否能真正适配模板的Skill？

一个项目可能有GDD、ADR和用户故事，但如果这些工件的内部格式不正确，所有对格式敏感的Skill仍会静默失败或产生错误结果。

输出：

docs/adoption-plan-[date].md

——一个持久化、可检查的迁移计划。

参数模式：

审计模式：

$ARGUMENTS[0]

（留空则为

full

）

无参数 /
full
：完整审计——所有类型的工件
gdds
：仅审计GDD格式合规性
adrs
：仅审计ADR格式合规性
stories
：仅审计用户故事格式合规性
infra
：仅检查基础设施工件的缺失情况（注册表、清单、迭代状态、stage.txt）

Phase 1: Detect Project State

阶段1：检测项目状态

Emit one line before reading:

"Scanning project artifacts..."

— this confirms the skill is running during the silent read phase.

Then read silently before presenting anything else.

读取前输出一行：

"Scanning project artifacts..."

——用于确认Skill在静默读取阶段正在运行。

在展示任何内容前先完成静默读取。

Existence check

存在性检查

```
production/stage.txt
```
— if present, read it (authoritative phase)
```
design/gdd/game-concept.md
```
— concept exists?
```
design/gdd/systems-index.md
```
— systems index exists?
Count GDD files:
```
design/gdd/*.md
```
(excluding game-concept.md and systems-index.md)
Count ADR files:
```
docs/architecture/adr-*.md
```
Count story files:
```
production/epics/**/*.md
```
(excluding EPIC.md)
```
.claude/docs/technical-preferences.md
```
— engine configured?
```
docs/engine-reference/
```
— engine reference docs present?
Glob
```
docs/adoption-plan-*.md
```
— note the filename of the most recent prior plan if any exist

```
production/stage.txt
```
——如果存在则读取（权威阶段标识）
```
design/gdd/game-concept.md
```
——概念文档是否存在？
```
design/gdd/systems-index.md
```
——系统索引是否存在？
统计GDD文件数量：
```
design/gdd/*.md
```
（排除game-concept.md和systems-index.md）
统计ADR文件数量：
```
docs/architecture/adr-*.md
```
统计用户故事文件数量：
```
production/epics/**/*.md
```
（排除EPIC.md）
```
.claude/docs/technical-preferences.md
```
——引擎是否已配置？
```
docs/engine-reference/
```
——引擎参考文档是否存在？
匹配
```
docs/adoption-plan-*.md
```
——如果存在之前的计划，记录最新的文件名

Infer phase (if no stage.txt)

阶段推断（无stage.txt时）

Use the same heuristic as

/project-stage-detect

10+ source files in
```
src/
```
→ Production
Stories in
```
production/epics/
```
→ Pre-Production
ADRs exist → Technical Setup
systems-index.md exists → Systems Design
game-concept.md exists → Concept
Nothing → Fresh (not a brownfield project — suggest
```
/start
```
)

If the project appears fresh (no artifacts at all), use

AskUserQuestion

"This looks like a fresh project — no existing artifacts found.
```
/adopt
```
is for projects with work to migrate. What would you like to do?"
- "Run
```
/start
```
  — begin guided first-time onboarding"
- "My artifacts are in a non-standard location — help me find them"
- "Cancel"

Then stop — do not proceed with the audit regardless of which option the user picks (each option leads to a different skill or manual investigation).

Report: "Detected phase: [phase]. Found: [N] GDDs, [M] ADRs, [P] stories."

使用与

/project-stage-detect

相同的启发式规则：

```
src/
```
目录下有10个以上源文件 → 生产阶段
```
production/epics/
```
目录下有用户故事 → 预生产阶段
存在ADR → 技术搭建阶段
存在systems-index.md → 系统设计阶段
存在game-concept.md → 概念阶段
无任何工件 → 新项目（不属于遗留项目——建议使用
```
/start
```
）

如果项目看起来是新项目（无任何工件），调用

AskUserQuestion

：

“这看起来是一个新项目——未发现现有工件。
```
/adopt
```
适用于需要迁移的已有项目。您想怎么做？”
- “运行
```
/start
```
  ——开始引导式首次接入”
- “我的工件在非标准位置——帮我找到它们”
- “取消”

然后停止——无论用户选择哪个选项，都不要继续审计（每个选项指向不同的Skill或手动排查）。

报告：“检测到阶段：[阶段]。已发现：[N]个GDD，[M]个ADR，[P]个用户故事。”

Phase 2: Format Audit

阶段2：格式审计

For each artifact type in scope (based on argument mode), check not just that the file exists but that it contains the internal structure the template requires.

根据参数模式，对每个范围内的工件类型，不仅检查文件是否存在，还要检查其是否包含模板要求的内部结构。

2a: GDD Format Audit

2a：GDD格式审计

For each GDD file found, check for the 8 required sections by scanning headings:

Required Section	Heading pattern to look for
Overview	`## Overview`
Player Fantasy	`## Player Fantasy`
Detailed Rules / Design	`## Detailed` or `## Core Rules` or `## Detailed Design`
Formulas	`## Formulas` or `## Formula`
Edge Cases	`## Edge Cases`
Dependencies	`## Dependencies` or `## Depends`
Tuning Knobs	`## Tuning`
Acceptance Criteria	`## Acceptance`

For each GDD, record:

Which sections are present
Which sections are missing
Whether it has any content in present sections or just placeholder text (
```
[To be designed]
```
or equivalent)

Also check: does each GDD have a

**Status**:

field in its header block? Valid values:

In Design

Designed

In Review

Approved

Needs Revision

对每个找到的GDD文件，通过扫描标题检查8个必填章节：

必填章节	要匹配的标题模式
Overview	`## Overview`
Player Fantasy	`## Player Fantasy`
Detailed Rules / Design	`## Detailed` 或 `## Core Rules` 或 `## Detailed Design`
Formulas	`## Formulas` 或 `## Formula`
Edge Cases	`## Edge Cases`
Dependencies	`## Dependencies` 或 `## Depends`
Tuning Knobs	`## Tuning`
Acceptance Criteria	`## Acceptance`

对每个GDD，记录：

哪些章节存在
哪些章节缺失
存在的章节是否有实际内容，还是仅占位文本（
```
[To be designed]
```
或类似内容）

另外检查：每个GDD的头部块是否包含

**Status**:

字段？有效值：

In Design

、

Designed

、

In Review

、

Approved

、

Needs Revision

。

2b: ADR Format Audit

2b：ADR格式审计

For each ADR file found, check for these critical sections:

Section	Impact if missing
`## Status`	BLOCKING — `/story-readiness` ADR status check silently passes everything
`## ADR Dependencies`	HIGH — dependency ordering in `/architecture-review` breaks
`## Engine Compatibility`	HIGH — post-cutoff API risk is unknown
`## GDD Requirements Addressed`	MEDIUM — traceability matrix loses coverage
`## Performance Implications`	LOW — not pipeline-critical

For each ADR, record: which sections present, which missing, current Status value if the Status section exists.

对每个找到的ADR文件，检查以下关键章节：

章节	缺失的影响
`## Status`	阻塞性—— `/story-readiness` 的ADR状态检查会静默通过所有内容
`## ADR Dependencies`	高影响—— `/architecture-review` 中的依赖排序会失效
`## Engine Compatibility`	高影响——无法知晓截止后的API风险
`## GDD Requirements Addressed`	中影响——可追溯性矩阵会失去覆盖范围
`## Performance Implications`	低影响——不属于流水线关键项

对每个ADR，记录：哪些章节存在、哪些缺失，以及如果Status章节存在的话，当前的Status值。

2c: systems-index.md Format Audit

2c：systems-index.md格式审计

design/gdd/systems-index.md

exists:

Parenthetical status values — Grep for any Status cell containing parentheses:
```
"Needs Revision ("
```
,
```
"In Progress ("
```
, etc. These break exact-string matching in
```
/gate-check
```
,
```
/create-stories
```
, and
```
/architecture-review
```
. BLOCKING.
Valid status values — check that Status column values are only from:
```
Not Started
```
,
```
In Progress
```
,
```
In Review
```
,
```
Designed
```
,
```
Approved
```
,
```
Needs Revision
```
Flag any unrecognised values.
Column structure — check that the table has at minimum: System name, Layer, Priority, Status columns. Missing columns degrade skill functionality.

如果

design/gdd/systems-index.md

存在：

括号内的状态值——查找任何包含括号的状态单元格：
```
"Needs Revision ("
```
、
```
"In Progress ("
```
等。这些会破坏
```
/gate-check
```
、
```
/create-stories
```
和
```
/architecture-review
```
中的精确字符串匹配。阻塞性。
有效状态值——检查状态列的值是否仅来自以下选项：
```
Not Started
```
、
```
In Progress
```
、
```
In Review
```
、
```
Designed
```
、
```
Approved
```
、
```
Needs Revision
```
标记任何无法识别的值。
列结构——检查表中至少包含：系统名称、层级、优先级、状态列。缺失列会降低Skill的功能。

2d: Story Format Audit

2d：用户故事格式审计

For each story file found:

Manifest Version:
field — present in story header? (LOW — auto-passes if absent)
TR-ID reference — does story contain
```
TR-[a-z]+-[0-9]+
```
pattern? (MEDIUM — no staleness tracking)
ADR reference — does story reference at least one ADR? (check for
```
ADR-
```
pattern)
Status field — present and readable?
Acceptance criteria — does the story have a checkbox list (
```
- [ ]
```
)?

对每个找到的用户故事文件：

Manifest Version:
字段——是否存在于故事头部？（低影响——如果缺失则自动通过）
TR-ID引用——故事是否包含
```
TR-[a-z]+-[0-9]+
```
模式？（中影响——无法进行过期跟踪）
ADR引用——故事是否至少引用一个ADR？（检查是否有
```
ADR-
```
模式）
状态字段——是否存在且可读？
验收标准——故事是否包含复选框列表（
```
- [ ]
```
）？

2e: Infrastructure Audit

2e：基础设施审计

Artifact	Path	Impact if missing
TR registry	`docs/architecture/tr-registry.yaml`	HIGH — no stable requirement IDs
Control manifest	`docs/architecture/control-manifest.md`	HIGH — no layer rules for stories
Manifest version stamp	In manifest header: `Manifest Version:`	MEDIUM — staleness checks blind
Sprint status	`production/sprint-status.yaml`	MEDIUM — `/sprint-status` falls back to markdown
Stage file	`production/stage.txt`	MEDIUM — phase auto-detect unreliable
Engine reference	`docs/engine-reference/[engine]/VERSION.md`	HIGH — ADR engine checks blind
Architecture traceability	`docs/architecture/architecture-traceability.md`	MEDIUM — no persistent matrix

工件	路径	缺失的影响
TR注册表	`docs/architecture/tr-registry.yaml`	高影响——没有稳定的需求ID
控制清单	`docs/architecture/control-manifest.md`	高影响——没有用户故事的层级规则
清单版本标记	清单头部的 `Manifest Version:`	中影响——过期检查失效
迭代状态	`production/sprint-status.yaml`	中影响—— `/sprint-status` 会回退到markdown格式
阶段文件	`production/stage.txt`	中影响——阶段自动检测不可靠
引擎参考	`docs/engine-reference/[engine]/VERSION.md`	高影响——ADR引擎检查失效
架构可追溯性	`docs/architecture/architecture-traceability.md`	中影响——没有持久化的矩阵

2f: Technical Preferences Audit

2f：技术偏好审计

Read

.claude/docs/technical-preferences.md

. Check each field for

[TO BE CONFIGURED]

Engine, Language, Rendering, Physics → HIGH if unconfigured (ADR skills fail)
Naming conventions → MEDIUM
Performance budgets → MEDIUM
Forbidden Patterns, Allowed Libraries → LOW (starts empty by design)

读取

.claude/docs/technical-preferences.md

。检查每个字段是否为

[TO BE CONFIGURED]

：

引擎、语言、渲染、物理 → 未配置则为高影响（ADR Skill会失败）
命名规范 → 中影响
性能预算 → 中影响
禁止模式、允许的库 → 低影响（默认为空设计）

Phase 3: Classify and Prioritise Gaps

阶段3：分类并优先处理差距问题

Organise every gap found across all audits into four severity tiers:

BLOCKING — Will cause template skills to silently produce wrong results right now. Examples: ADR missing Status field, systems-index parenthetical status values, engine not configured when ADRs exist.

HIGH — Will cause stories to be generated with missing safety checks, or infrastructure bootstrapping will fail. Examples: ADRs missing Engine Compatibility, GDDs missing Acceptance Criteria (stories can't be generated from them), tr-registry.yaml missing.

MEDIUM — Degrades quality and pipeline tracking but does not break functionality. Examples: GDDs missing Tuning Knobs or Formulas sections, stories missing TR-IDs, sprint-status.yaml missing.

LOW — Retroactive improvements that are nice-to-have but not urgent. Examples: Stories missing Manifest Version stamps, GDDs missing Open Questions section.

Count totals per tier. If zero BLOCKING and zero HIGH gaps: report that the project is template-compatible and only advisory improvements remain.

将所有审计中发现的差距问题分为四个严重等级：

阻塞性——会导致模板Skill立即静默产生错误结果。示例：ADR缺失Status字段、systems-index包含括号内的状态值、当存在ADR时引擎未配置。

高影响——会导致生成的用户故事缺失安全检查，或基础设施引导失败。示例：ADR缺失Engine Compatibility章节、GDD缺失Acceptance Criteria（无法从中生成用户故事）、tr-registry.yaml缺失。

中影响——降低质量和流水线跟踪能力，但不会破坏功能。示例：GDD缺失Tuning Knobs或Formulas章节、用户故事缺失TR-ID、sprint-status.yaml缺失。

低影响——可追溯的改进，属于锦上添花但不紧急的内容。示例：用户故事缺失Manifest Version标记、GDD缺失Open Questions章节。

统计每个等级的总数。如果没有阻塞性和高影响差距问题：报告项目符合模板规范，仅剩下建议性改进。

Phase 4: Build the Migration Plan

阶段4：构建迁移计划

Compose a numbered, ordered action plan. Ordering rules:

BLOCKING gaps first (must fix before any pipeline skill runs reliably)
HIGH gaps next, infrastructure before GDD/ADR content (bootstrapping needs correct formats)
MEDIUM gaps ordered: GDD gaps before ADR gaps before story gaps (stories depend on GDDs and ADRs)
LOW gaps last

For each gap, produce a plan entry with:

A clear problem statement (one sentence, no jargon)
The exact command to fix it, if a skill handles it
Manual steps if it requires direct editing
A time estimate (rough: 5 min / 30 min / 1 session)
A checkbox
```
- [ ]
```
for tracking

Special case — systems-index parenthetical status values: This is always the first item if present. Show the exact values that need changing and the exact replacement text. Offer to fix this immediately before writing the plan.

Special case — ADRs missing Status field: For each affected ADR, the fix is:

/architecture-decision retrofit docs/architecture/adr-[NNNN]-[slug].md

List each ADR as a separate checkable item.

Special case — GDDs missing sections: For each affected GDD, list which sections are missing and the fix:

/design-system retrofit design/gdd/[filename].md

Infrastructure bootstrap ordering — always present in this sequence:

Fix ADR formats first (registry depends on reading ADR Status fields)
Run
```
/architecture-review
```
→ bootstraps
```
tr-registry.yaml
```
Run
```
/create-control-manifest
```
→ creates manifest with version stamp
Run
```
/sprint-plan update
```
→ creates
```
sprint-status.yaml
```
Run
```
/gate-check [phase]
```
→ writes
```
stage.txt
```
authoritatively

Existing stories — note explicitly:

"Existing stories continue to work with all template skills — all new format checks auto-pass when the fields are absent. They won't benefit from TR-ID staleness tracking or manifest version checks until they're regenerated. This is intentional: do not regenerate stories that are already in progress."

编写编号的有序行动计划。排序规则：

先处理阻塞性差距问题（必须修复，否则流水线Skill无法可靠运行）
接下来处理高影响差距问题，先处理基础设施问题，再处理GDD/ADR内容（引导需要正确的格式）
中影响差距问题排序：GDD问题优先于ADR问题，ADR问题优先于用户故事问题（用户故事依赖于GDD和ADR）
最后处理低影响差距问题

对每个差距问题，生成计划条目，包含：

清晰的问题陈述（一句话，无行话）
如果有Skill可处理，给出修复的精确命令
如果需要直接编辑，给出手动步骤
时间估算（大致：5分钟 / 30分钟 / 1个会话）
用于跟踪的复选框
```
- [ ]
```

特殊情况——systems-index中的括号状态值： 如果存在，这始终是第一个条目。显示需要修改的精确值和替换文本。在编写计划前，主动提出立即修复此问题。

特殊情况——ADR缺失Status字段： 对每个受影响的ADR，修复命令是：

/architecture-decision retrofit docs/architecture/adr-[NNNN]-[slug].md

将每个ADR列为单独的可检查条目。

特殊情况——GDD缺失章节： 对每个受影响的GDD，列出缺失的章节和修复命令：

/design-system retrofit design/gdd/[filename].md

基础设施引导顺序——始终按以下顺序呈现：

先修复ADR格式（注册表依赖于读取ADR的Status字段）
运行
```
/architecture-review
```
→ 引导生成
```
tr-registry.yaml
```
运行
```
/create-control-manifest
```
→ 创建带版本标记的清单
运行
```
/sprint-plan update
```
→ 创建
```
sprint-status.yaml
```
运行
```
/gate-check [phase]
```
→ 权威写入
```
stage.txt
```

现有用户故事——明确说明：

“现有用户故事可继续与所有模板Skill兼容——当字段缺失时，所有新格式检查会自动通过。在重新生成之前，它们无法受益于TR-ID过期跟踪或清单版本检查。这是有意设计的：不要重新生成已在进行中的用户故事。”

Phase 5: Present Summary and Ask to Write

阶段5：展示摘要并询问是否写入

Present a compact summary before writing:

undefined

在写入前展示简洁的摘要：

undefined

Adoption Audit Summary

适配审计摘要

Phase detected: [phase] Engine: [configured / NOT CONFIGURED] GDDs audited: [N] ([X] fully compliant, [Y] with gaps) ADRs audited: [N] ([X] fully compliant, [Y] with gaps) Stories audited: [N]

Gap counts: BLOCKING: [N] — template skills will malfunction without these fixes HIGH: [N] — unsafe to run /create-stories or /story-readiness MEDIUM: [N] — quality degradation LOW: [N] — optional improvements

Estimated remediation: [X blocking items × ~Y min each = roughly Z hours]


Before asking to write, show a **Gap Preview**:
- List every BLOCKING gap as a one-line bullet describing the actual problem
  (e.g. `systems-index.md: 3 rows have parenthetical status values`,
  `adr-0002.md: missing ## Status section`). No counts — show the actual items.
- Show HIGH / MEDIUM / LOW as counts only (e.g. `HIGH: 4, MEDIUM: 2, LOW: 1`).

This gives the user enough context to judge scope before committing to writing the file.

If a prior adoption plan was detected in Phase 1, add a note:
> "A previous plan exists at `docs/adoption-plan-[prior-date].md`. The new plan will
> reflect current project state — it does not diff against the prior run."

Use `AskUserQuestion`:
- "Ready to write the migration plan?"
  - "Yes — write `docs/adoption-plan-[date].md`"
  - "Show me the full plan preview first (don't write yet)"
  - "Cancel — I'll handle migration manually"

If the user picks "Show me the full plan preview", output the complete plan as a
fenced markdown block. Then ask again with the same three options.

---

检测到的阶段：[阶段] 引擎：[已配置 / 未配置] 已审计GDD：[N]个（[X]个完全合规，[Y]个存在差距）已审计ADR：[N]个（[X]个完全合规，[Y]个存在差距）已审计用户故事：[N]个

差距数量：阻塞性：[N]个——不修复这些问题，模板Skill会故障高影响：[N]个——运行/create-stories或/story-readiness存在风险中影响：[N]个——质量下降低影响：[N]个——可选改进

预估修复时间：[X个阻塞项 × ~Y分钟/项 = 约Z小时]


在询问是否写入前，展示**差距预览**：
- 将每个阻塞性差距问题列为一行项目符号，描述实际问题
  （例如：`systems-index.md: 3行包含括号内的状态值`，`adr-0002.md: 缺失## Status章节`）。不要只显示数量——展示实际条目。
- 高/中/低影响仅显示数量（例如：`高影响：4个，中影响：2个，低影响：1个`）。

这能让用户在决定写入文件前充分了解范围。

如果在阶段1中检测到之前的适配计划，添加说明：
> “之前的计划存在于`docs/adoption-plan-[prior-date].md`。新计划会反映当前项目状态——不会与之前的运行结果对比差异。”

调用`AskUserQuestion`：
- “准备好写入迁移计划了吗？”
  - “是——写入`docs/adoption-plan-[date].md`”
  - “先给我展示完整的计划预览（暂不写入）”
  - “取消——我会手动处理迁移”

如果用户选择“先给我展示完整的计划预览”，将完整计划输出为围栏式markdown块。然后再次用相同的三个选项询问。

---

Phase 6: Write the Adoption Plan

阶段6：写入适配计划

If approved, write

docs/adoption-plan-[date].md

with this structure:

markdown

undefined

如果获得批准，写入

docs/adoption-plan-[date].md

，结构如下：

markdown

undefined

Adoption Plan

适配计划

Generated: [date] Project phase: [phase] Engine: [name + version, or "Not configured"] Template version: v1.0+

Work through these steps in order. Check off each item as you complete it. Re-run

/adopt

anytime to check remaining gaps.

生成时间：[日期] 项目阶段：[阶段] 引擎：[名称+版本，或“未配置”] 模板版本：v1.0+

按顺序完成以下步骤。完成后勾选每个条目。随时重新运行

/adopt

以检查剩余差距问题。

Step 1: Fix Blocking Gaps

步骤1：修复阻塞性差距问题

[One sub-section per blocking gap with problem, fix command, time estimate, checkbox]

[每个阻塞性差距问题对应一个子章节，包含问题、修复命令、时间估算、复选框]

Step 2: Fix High-Priority Gaps

步骤2：修复高优先级差距问题

[One sub-section per high gap]

[每个高影响差距问题对应一个子章节]

Step 3: Bootstrap Infrastructure

步骤3：引导基础设施

3a. Register existing requirements (creates tr-registry.yaml)

3a. 注册现有需求（创建tr-registry.yaml）

Run

/architecture-review

— even if ADRs already exist, this run bootstraps the TR registry from your existing GDDs and ADRs. Time: 1 session (review can be long for large codebases)

tr-registry.yaml created

运行

/architecture-review

——即使ADR已存在，此运行会从现有GDD和ADR引导生成TR注册表。时间：1个会话（大型代码库的审核可能耗时较长）

tr-registry.yaml已创建

3b. Create control manifest

3b. 创建控制清单

Run

/create-control-manifest

Time: 30 min

docs/architecture/control-manifest.md created

运行

/create-control-manifest

时间：30分钟

docs/architecture/control-manifest.md已创建

3c. Create sprint tracking file

3c. 创建迭代跟踪文件

Run

/sprint-plan update

Time: 5 min (if sprint plan already exists as markdown)

production/sprint-status.yaml created

运行

/sprint-plan update

时间：5分钟（如果迭代计划已以markdown格式存在）

production/sprint-status.yaml已创建

3d. Set authoritative project stage

3d. 设置权威项目阶段

Run

/gate-check [current-phase]

Time: 5 min

production/stage.txt written

运行

/gate-check [当前阶段]

时间：5分钟

production/stage.txt已写入

Step 4: Medium-Priority Gaps

步骤4：中优先级差距问题

[One sub-section per medium gap]

[每个中影响差距问题对应一个子章节]

Step 5: Optional Improvements

步骤5：可选改进

[One sub-section per low gap]

[每个低影响差距问题对应一个子章节]

What to Expect from Existing Stories

现有用户故事的预期表现

Existing stories continue to work with all template skills. New format checks (TR-ID validation, manifest version staleness) auto-pass when the fields are absent — so nothing breaks. They won't benefit from staleness tracking until regenerated. Do not regenerate stories that are in progress or done.

现有用户故事可继续与所有模板Skill兼容。当字段缺失时，新格式检查（TR-ID验证、清单版本过期）会自动通过——因此不会出现故障。在重新生成之前，它们无法受益于过期跟踪。不要重新生成已在进行中或已完成的用户故事。

Re-run

重新运行

Run

/adopt

again after completing Step 3 to verify all blocking and high gaps are resolved. The new run will reflect the current state of the project.

---

完成步骤3后，再次运行

/adopt

以验证所有阻塞性和高影响差距问题已解决。新的运行会反映项目的当前状态。

---

Phase 6b: Set Review Mode

阶段6b：设置审核模式

After writing the adoption plan (or if the user cancels writing), check whether

production/review-mode.txt

exists.

If it exists: Read it and note the current mode — "Review mode is already set to

[current]

." — skip the prompt.

If it does not exist: Use

AskUserQuestion

Prompt: "One more setup step: how much design review would you like as you work through the workflow?"
Options:
- ```
Full
```
  — Director specialists review at each key workflow step. Best for teams, learning the workflow, or when you want thorough feedback on every decision.
- ```
Lean (recommended)
```
  — Directors only at phase gate transitions (/gate-check). Skips per-skill reviews. Balanced for solo devs and small teams.
- ```
Solo
```
  — No director reviews at all. Maximum speed. Best for game jams, prototypes, or if reviews feel like overhead.

Write the choice to

production/review-mode.txt

immediately after selection — no separate "May I write?" needed:

```
Full
```
→ write
```
full
```
```
Lean (recommended)
```
→ write
```
lean
```
```
Solo
```
→ write
```
solo
```

Create the

production/

directory if it does not exist.

写入适配计划后（或用户取消写入后），检查

production/review-mode.txt

是否存在。

如果存在：读取并记录当前模式——“审核模式已设置为

[当前模式]

。”——跳过提示。

如果不存在：调用

AskUserQuestion

：

提示：“最后一个设置步骤：在您完成工作流的过程中，您希望进行多少设计审核？”
选项：
- ```
Full
```
  ——在每个关键工作流步骤都有主管专家审核。最适合团队、学习工作流或希望对每个决策获得全面反馈的场景。
- ```
Lean (recommended)
```
  ——仅在阶段 gate 转换时（/gate-check）进行主管审核。跳过每个Skill的审核。为独立开发者和小团队提供平衡的方案。
- ```
Solo
```
  ——完全没有主管审核。速度最快。最适合游戏 jam、原型开发或认为审核是负担的场景。

选择后立即将选项写入

production/review-mode.txt

——无需单独询问“是否可以写入？”：

```
Full
```
→ 写入
```
full
```
```
Lean (recommended)
```
→ 写入
```
lean
```
```
Solo
```
→ 写入
```
solo
```

如果

production/

Phase 7: Offer First Action

阶段7：提供首个操作建议

After writing the plan, don't stop there. Pick the single highest-priority gap and offer to handle it immediately using

AskUserQuestion

. Choose the first branch that applies:

If there are parenthetical status values in systems-index.md: Use

AskUserQuestion

"The most urgent fix is
```
systems-index.md
```
— [N] rows have parenthetical status values (e.g.
```
Needs Revision (see notes)
```
) that break /gate-check, /create-stories, and /architecture-review right now. I can fix these in-place."
- "Fix it now — edit systems-index.md"
- "I'll fix it myself"
- "Done — leave me with the plan"

If ADRs are missing
## Status
(and no parenthetical issue): Use

AskUserQuestion

"The most urgent fix is adding
```
## Status
```
to [N] ADR(s): [list filenames]. Without it, /story-readiness silently passes all ADR checks. Start with [first affected filename]?"
- "Yes — retrofit [first affected filename] now"
- "Retrofit all [N] ADRs one by one"
- "I'll handle ADRs myself"

If GDDs are missing Acceptance Criteria (and no blocking issues above): Use

AskUserQuestion

"The most urgent gap is missing Acceptance Criteria in [N] GDD(s): [list filenames]. Without them, /create-stories can't generate stories. Start with [highest-priority GDD filename]?"
- "Yes — add Acceptance Criteria to [GDD filename] now"
- "Do all [N] GDDs one by one"
- "I'll handle GDDs myself"

If no BLOCKING or HIGH gaps exist: Use

AskUserQuestion

"No blocking gaps — this project is template-compatible. What next?"
- "Walk me through the medium-priority improvements"
- "Run /project-stage-detect for a broader health check"
- "Done — I'll work through the plan at my own pace"

Adoption plan saved to
docs/adoption-plan-[date].md
. Re-run
/adopt
at any time to re-check remaining gaps as you complete them.

写入计划后，不要停止。选择优先级最高的单个差距问题，调用

AskUserQuestion

立即处理。按以下顺序选择第一个适用的分支：

如果systems-index.md中存在括号内的状态值： 调用

AskUserQuestion

：

“最紧急的修复是
```
systems-index.md
```
——[N]行包含括号内的状态值（例如
```
Needs Revision (see notes)
```
），这会立即破坏/gate-check、/create-stories和/architecture-review。我可以就地修复这些问题。”
- “立即修复——编辑systems-index.md”
- “我会自己修复”
- “完成——只留下计划”

如果ADR缺失
## Status
（且无括号问题）：调用

AskUserQuestion

：

“最紧急的修复是为[N]个ADR添加
```
## Status
```
：[列出文件名]。没有此字段，/story-readiness会静默通过所有ADR检查。从[第一个受影响的文件名]开始？”
- “是——立即适配[第一个受影响的文件名]”
- “逐个适配所有[N]个ADR”
- “我会自己处理ADR”

如果GDD缺失验收标准（且无上述阻塞性问题）： 调用

AskUserQuestion

：

“最紧急的差距是[N]个GDD缺失验收标准： [列出文件名]。没有这些标准，/create-stories无法生成用户故事。从[优先级最高的GDD文件名]开始？”
- “是——立即为[GDD文件名]添加验收标准”
- “逐个处理所有[N]个GDD”
- “我会自己处理GDD”

如果没有阻塞性或高影响差距问题： 调用

AskUserQuestion

：

“无阻塞性差距问题——此项目符合模板规范。接下来做什么？”
- “带我了解中优先级改进内容”
- “运行/project-stage-detect进行更全面的健康检查”
- “完成——我会按自己的节奏完成计划”

适配计划已保存到
docs/adoption-plan-[date].md
。您可以随时重新运行
/adopt
，在完成修复后检查剩余的差距问题。

Collaborative Protocol

协作协议

Read silently — complete the full audit before presenting anything
Show the summary first — let the user see scope before asking to write
Ask before writing — always confirm before creating the adoption plan file
Offer, don't force — the plan is advisory; the user decides what to fix and when
One action at a time — after handing off the plan, offer one specific next step, not a list of six things to do simultaneously
Never regenerate existing artifacts — only fill gaps in what exists; do not rewrite GDDs, ADRs, or stories that already have content

静默读取——在展示任何内容前完成完整审计
先展示摘要——让用户在询问是否写入前了解范围
写入前询问——创建适配计划文件前始终确认
提供选择而非强制——计划是建议性的；用户决定修复内容和时间
一次一个操作——移交计划后，提供一个具体的下一步操作，而非六个同时要做的事情
绝不重新生成现有工件——仅填补现有工件的差距；不要重写已有内容的GDD、ADR或用户故事",