用途
Roadmap Conventions 用于在编写、定位或更新路线图文件时提供统一约定。路线图是带阶段划分、含多个检查点、以 Markdown 复选框跟踪的计划，典型位于 docs/<feature-slug>/ 目录下。该约定本身不负责具体编写或执行，而是叠加在 superpowers:writing-roadmaps（路线图编写流程）、writing-prd（PRD 内容与格式）之上，并被 executing-roadmap-checkpoints（从已有路线图中选取并完成任务）消费。
工作流
一个路线图规模的功能分三个阶段，每阶段由已有技能完整处理，不需要单独的编排技能：
- 阶段 1 — 路线图：按原样使用 superpowers:writing-roadmaps，分析功能、分解为检查点（核心原则：每一步之后应用仍可构建），编写路线图与功能级 PRD。
- 阶段 2 — 每步 PRD 与规格并验证：对路线图清单执行 batch-plan-validate，将每任务起草技能设为 brainstorming、design-only（见 batch-plan-validate → Input），此时不产出实现计划。结果为每一步得到经过验证的步骤级 PRD（writing-prd）和经过验证的设计/规格（brainstorming），二者都通过标准的 EnterPlanMode → ExitPlanMode → Plannotator 循环评审。
- 阶段 3 — 每步实现计划，即时生成：某一步真正开始处理时调用 executing-roadmap-checkpoints，找到该步已批准的 PRD+规格，此时才用 superpowers:writing-plans 编写实现计划，而非更早，以便计划反映工作开始时的仓库状态。
明确不要在阶段 2 提前编写每一步的实现计划，阶段 2 的 design-only 模式正是为了防止这一点。
存储
位置为仓库根目录的 docs/<feature-slug>/，由 Git 跟踪，永久保留作为迁移/发布历史，绝不放在 tmp/，也不在检查点交付后立即删除。在此写入需先进入原生 Plan Mode，与 brainstorming/writing-plans/writing-prd 相同。
存储优先级：上述步骤文件夹存储（docs/<feature-slug>/steps/<step-slug>/...，永久、Git 跟踪）优先于项目级对 writing-plans/brainstorming 的通用存储覆盖（例如“把计划/规格存到项目根目录，实现后删除”），前提是工件属于路线图步骤。项目的计划/规格存储覆盖仍原样适用于路线图步骤上下文之外的独立计划与规格；此优先级规则只专门为路线图步骤工件开例外。writing-roadmaps 原本规定项目自身约定冲突时优先于其默认值，本节是步骤级工件的明确例外。
功能级 PRD（必需）
每个路线图恰好有一份功能级 PRD，用 writing-prd 编写，存放于 docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-prd.md。路线图文件在其上下文/引言部分链接到它。先写路线图，再基于它写功能级 PRD——路线图是范围与分解的真相来源，PRD 记录已写好的路线图所描述的目标状态与需求。有步骤但没有链接功能级 PRD 的路线图是不完整的。
文件命名
- docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-roadmap.md：路线图本身。每个检查点/步骤为顶级复选框：- [ ] <TICKET> <short name>。使用项目真实问题跟踪器前缀（如 SCB-NNN）；票据尚不存在时用字面占位符 TBD。链接到下方功能级 PRD。
- docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-prd.md：功能级 PRD，格式按 writing-prd。
- docs/<feature-slug>/roadmap-state.json：每个检查点的机器可读进度状态。
- docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<step-slug>-prd.md：步骤级 PRD，含该步范围、需求与成功标准，按 writing-prd。
- docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<step-slug>-design.md：步骤规格，当该步需要自己的架构决策时（来自 brainstorming）。
- docs/<feature-slug>/steps/<step-slug>/YYYY-MM-DD-<ticket>-<name>.md：该步的详细实现计划（来自 writing-plans）。
每个步骤在 docs/<feature-slug>/steps/ 下有独立文件夹，以步骤自身 slug 命名（如 steps/general-information/），而非纯数字。步骤的三份文档（PRD、规格、计划）都放在该文件夹中；无需架构决策的步骤仍有 PRD 和计划，只是没有 -design.md。
状态文件
docs/<feature-slug>/roadmap-state.json 跟踪整个路线图的进度——哪些检查点已有 PRD、已验证规格、计划、已实现或已关闭——使进度不只依赖 Markdown 复选框。存储策略与路线图相同：Git 跟踪、永久保留，直到路线图本身被删除才删除。
结构包含 feature、roadmapPath、featurePrdPath、updatedAt（ISO-8601）和 steps 数组；每个步骤条目含 id、title、ticket、dependsOn、stepFolder、status、prdPath、specPath、planPath。status 依次为：not-started → prd-drafted → spec-drafted → spec-validated → plan-drafted → implemented → closed。若某步阶段 2 直接选用 writing-plans（而非 design-only），则跳过 spec-* 阶段，状态从 prd-drafted 直接到 plan-drafted。
更新者与时机：
- writing-roadmaps 在保存路线图与功能级 PRD 后立即创建该文件——每检查点一条，status: "not-started"，仅对立即获得文件夹的检查点填写 stepFolder（多数保持扁平，待阶段 2/3 处理）。
- batch-plan-validate 在每个阶段转换后更新：阶段 1 PRD 起草 → prd-drafted + prdPath；阶段 1 设计/计划起草 → spec-drafted + specPath，或直接选 writing-plans 则 plan-drafted + planPath；阶段 2 批准 → spec-validated（若直接验证计划则保持 plan-drafted）。同时若 stepFolder 仍为空则补填。
- executing-roadmap-checkpoints 在步骤被拾取时（阶段 3）更新：写完实现计划 → plan-drafted + planPath；实现最终验证通过 → implemented；收尾（勾选复选框、删除计划文件）→ closed，planPath: null。
依赖
检查点的 Markdown 行可以以机器可读依赖标签结尾：(depends: <id>[, <id>...])，列出同一路线图中必须先关闭的其他检查点 id。无内部依赖时完全省略该标签——多数检查点如此，尤其是不同步骤中只等待自身设计完成的检查点。外部依赖（另一路线图、认证/用户前置条件等）保留为检查点自身行或路线图 Context/Зависимости от ... 部分的自由文本；(depends: ...) 只引用同一路线图内的 id。
示例：- [ ] 1.1b — [backend] ... (Jira: ACD-59) (depends: 1.1a)
roadmap-state.json 以机器可读方式镜像同一信息：每个步骤条目有 "dependsOn": string[] 字段（检查点 id 数组，无内部依赖时为空数组），writing-roadmaps 在创建状态文件时直接从 Markdown 标签填充。
当检查点未勾选（- [ ]）且其 dependsOn 中每个 id 在 roadmap-state.json 中均为 status: "closed" 时，该检查点即可拾取。多个检查点可同时就绪——这正是安全并行化的原因。executing-roadmap-checkpoints 据此决定可提供哪些检查点，而非总假设严格自上而下顺序。
提交策略
绝不自动提交路线图/规格/计划文件——仅在用户明确要求时提交，与其他工件相同。
路线图全部勾选后
一旦路线图中每个复选框均为 - [x]，路线图文件——以及此时若已空的 docs/<feature-slug>/ 文件夹——会被删除，而不作为死重量保留。具体触发时机见 executing-roadmap-checkpoints。