roadmap-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are helping the user create or restructure the repository roadmap.

你将协助用户创建或重构代码仓库的路线图。

Prerequisites

前置条件

The

.spec-driven/

directory must exist at the project root. Before proceeding, verify:

ls .spec-driven/

If this fails, the project is not initialized. Run

/spec-driven-init

first.

.spec-driven/roadmap/

is missing, repair the scaffold first:

node {{SKILL_DIR}}/scripts/spec-driven.js init

.spec-driven/

目录必须存在于项目根目录下。继续操作前，请先验证：

ls .spec-driven/

如果执行失败，说明项目未初始化，请先运行

/spec-driven-init

。

如果不存在

.spec-driven/roadmap/

目录，请先修复脚手架：

node {{SKILL_DIR}}/scripts/spec-driven.js init

Steps

操作步骤

Read roadmap context first — before proposing milestone structure, read:
- ```
.spec-driven/config.yaml
```
- ```
.spec-driven/roadmap/INDEX.md
```
  if it exists
- every existing file under
```
.spec-driven/roadmap/milestones/
```
- ```
.spec-driven/specs/INDEX.md
```
  and any main spec files that are clearly relevant to the user's planning scope
- active and archived changes under
```
.spec-driven/changes/
```
  as evidence of what is already in progress or complete
You MAY delegate bounded analysis-only work such as roadmap summarization, candidate milestone comparisons, or likely spec-path discovery to a sub-agent. The parent agent MUST keep user confirmation, roadmap shape selection, and final
```
.spec-driven/roadmap/
```
writes.
Understand the planning goal — determine:
- whether the user wants to create a brand-new roadmap or restructure an existing one
- what major phases or stage goals the roadmap should express
- whether there are existing changes that already belong to specific milestones
- whether any existing milestone files are still using a legacy structure, such as an extra
```
## Candidate Ideas
```
  section, a combined
```
## Dependencies / Risks
```
  section, or missing
```
## In Scope
```
  ,
```
## Out of Scope
```
  , or
```
## Notes
```
  sections
Converge on milestone boundaries before writing — help the user settle:
- milestone names and ordering
- each milestone's goal and done criteria
- which concrete
```
Planned Changes
```
  belong in each milestone
- key dependencies, risks, and sequencing
- any non-obvious legacy-migration interpretation needed to rewrite older milestone files into the canonical format
Confirm the roadmap shape — before editing files, summarize the intended milestone structure and ask for explicit confirmation. If legacy milestone migration is in scope, include any non-obvious content reinterpretation you plan to make while converting older milestone files.
Write roadmap assets — update:
- ```
.spec-driven/roadmap/INDEX.md
```
- ```
.spec-driven/roadmap/milestones/<milestone>.md
```
  for each milestone in scope When a milestone is in a legacy format, rewrite it into the canonical section set while preserving clearly recoverable meaning. Use the legacy milestone wording itself as migration evidence.
Preserve roadmap rules — in every milestone file:
- use these standard section headings:
  - ```
  ## Goal
```
- ```
## In Scope
```
  - ```
  ## Out of Scope
```
- ```
## Done Criteria
```
  - ```
  ## Planned Changes
```
- ```
## Dependencies
```
  - ```
  ## Risks
```
- ```
## Status
```
  - ```
  ## Notes
```
- milestone declared statuses are limited to:
  - ```
  proposed
```
- ```
active
```
  - ```
  blocked
```
- ```
complete
```
- write each
```
Planned Changes
```
  item with a canonical first line,
```
- \
```
  <change-name>` - Declared: <status> - <summary>`
- planned change declared statuses are limited to:
  - ```
  planned
```
- ```
complete
```
- keep each planned change description on that same line; do not add indented continuation lines below the bullet
- default new or unfinished planned changes to
```
Declared: planned
```
- put extra milestone-local context in another section such as
```
## Notes
```
  instead of attaching multiline detail under
```
## Planned Changes
```
- treat
```
Planned Changes
```
  as the milestone's only work list and keep it limited to concrete approved change work
- derive milestone completion from archived planned changes rather than manual toggles
- when migrating a legacy milestone, map content conservatively:
  - move clearly approved executable work into
```
## Planned Changes
```
  - split a combined
```
## Dependencies / Risks
```
    section only when the source distinction is clear enough to preserve confidently
  - infer
```
## In Scope
```
    or
```
## Out of Scope
```
    only when the old milestone wording makes those boundaries clear
  - preserve useful leftover context in
```
## Notes
```
    instead of dropping it
  - surface ambiguity to the user instead of silently inventing an exact migration
Validate roadmap size before finish — run:
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-roadmap
```
- If validation reports a milestone is too large, stop and tell the user to split it into smaller milestones
- Do not present the roadmap as ready while size validation fails
Summarize the result — report the milestone structure created or changed, what planned work was assigned to each milestone, and any remaining planning gaps.

优先读取路线图上下文 — 在提出里程碑结构之前，请先读取以下内容：
- ```
.spec-driven/config.yaml
```
- 如果存在
```
.spec-driven/roadmap/INDEX.md
```
  也需读取
- ```
.spec-driven/roadmap/milestones/
```
  目录下的所有现有文件
- ```
.spec-driven/specs/INDEX.md
```
  以及所有与用户规划范围明显相关的主要规范文件
- ```
.spec-driven/changes/
```
  目录下的活跃和已归档变更，作为已在进行中或已完成工作的依据
你可以将有限的纯分析工作（例如路线图汇总、候选里程碑对比、可能的规范路径发现）委派给子Agent。父Agent必须保留用户确认、路线图结构选择和最终
```
.spec-driven/roadmap/
```
写入的权限。
明确规划目标 — 确定以下内容：
- 用户是想要创建全新的路线图，还是重构现有路线图
- 路线图需要体现哪些主要阶段或阶段目标
- 是否有现有变更已经归属到特定里程碑
- 是否有现有里程碑文件仍在使用旧结构，例如额外的
```
## Candidate Ideas
```
  章节、合并的
```
## Dependencies / Risks
```
  章节，或者缺少
```
## In Scope
```
  、
```
## Out of Scope
```
  或
```
## Notes
```
  章节
编写前先对齐里程碑边界 — 协助用户确定：
- 里程碑名称和排序
- 每个里程碑的目标和完成标准
- 每个里程碑包含哪些具体的「计划变更」
- 关键依赖、风险和排期顺序
- 将旧里程碑文件重写为规范格式所需的所有非显而易见的旧版本迁移解读规则
确认路线图结构 — 在编辑文件前，汇总拟采用的里程碑结构并请求用户明确确认。如果涉及旧里程碑迁移，请包含你在转换旧里程碑文件时计划做的所有非显而易见的内容重释说明。
写入路线图资源 — 更新：
- ```
.spec-driven/roadmap/INDEX.md
```
- 范围内每个里程碑对应的
```
.spec-driven/roadmap/milestones/<milestone>.md
```
  当里程碑采用旧格式时，将其重写为规范的章节集合，同时保留所有可明确还原的含义，使用旧里程碑的原始表述作为迁移依据。
遵守路线图规则 — 在所有里程碑文件中：
- 使用以下标准章节标题：
  - ```
  ## Goal
```
- ```
## In Scope
```
  - ```
  ## Out of Scope
```
- ```
## Done Criteria
```
  - ```
  ## Planned Changes
```
- ```
## Dependencies
```
  - ```
  ## Risks
```
- ```
## Status
```
  - ```
  ## Notes
```
- 里程碑声明状态仅限以下取值：
  - ```
  proposed
```
- ```
active
```
  - ```
  blocked
```
- ```
complete
```
- 每个「计划变更」项的第一行必须采用规范格式：
```
- \
```
  <change-name>` - Declared: <status> - <summary>`
- 计划变更的声明状态仅限以下取值：
  - ```
  planned
```
- ```
complete
```
- 每个计划变更的描述都保持在同一行，不要在列表项下添加缩进的续行
- 新增或未完成的计划变更默认设置为
```
Declared: planned
```
- 将额外的里程碑本地上下文放在
```
## Notes
```
  等其他章节中，不要在
```
## Planned Changes
```
  下附加多行详情
- 将「计划变更」作为里程碑的唯一工作列表，仅保留具体的已批准变更工作
- 根据已归档的计划变更推导里程碑完成状态，不要手动切换
- 迁移旧里程碑时，请保守映射内容：
  - 将明确获批的可执行工作移入
```
## Planned Changes
```
  - 仅当源文件中的区分足够明确可以放心保留时，才拆分合并的
```
## Dependencies / Risks
```
    章节
  - 仅当旧里程碑的表述明确了边界时，才推导
```
## In Scope
```
    或
```
## Out of Scope
```
    内容
  - 将有用的剩余上下文保留在
```
## Notes
```
    中，不要直接丢弃
  - 向用户反馈歧义点，不要悄无声息地编造精确的迁移方案
完成前验证路线图规模 — 运行：
```
node {{SKILL_DIR}}/scripts/spec-driven.js verify-roadmap
```
- 如果验证报告某个里程碑过大，请停止操作并告知用户将其拆分为更小的里程碑
- 当规模验证未通过时，不要宣称路线图已就绪
汇总结果 — 报告创建或变更的里程碑结构、分配到每个里程碑的计划工作，以及所有剩余的规划缺口。

Rules

规则

This is a planning/documentation skill only — do not change product code
Read roadmap files and relevant change history before restructuring anything
Do not collapse multiple milestones into one oversized roadmap document
Do not mark a milestone complete manually if its planned changes are not all archived
Do not let a sub-agent own the confirmation step or final roadmap file edits

这是仅用于规划/文档的技能 — 不要修改产品代码
重构任何内容前先读取路线图文件和相关变更历史
不要将多个里程碑合并为一个过大的路线图文档
如果里程碑的计划变更未全部归档，不要手动将里程碑标记为完成
不要让子Agent负责确认步骤或最终的路线图文件编辑