Menu
把"大到塞不进单个 feature"的需求做成完整事前规划：概设 + 接口契约 + 子 feature 拆解清单，放在 `.kflow/roadmap/{slug}/`。两种模式 new / update。触发：用户说"我想要一个 X 系统"、"帮我把这块需求拆一下"、"开一份 roadmap"，或 feature-design 阶段发现需求太大。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
维护 `.kflow/architecture/` 这份只记现状的系统地图，三种模式 update / check / backfill。触发：用户说"刷新 architecture"、"做架构检查"、"补这个模块的架构文档"、"方案和代码对得上吗"，或 feature 阶段需要先做架构动作。不写未来规划（走 k-roadmap）。
feature 流程阶段 3——验收闭环：对照 design 核实现 + 回写 architecture / requirement / roadmap，最后产出 {slug}-acceptance.md。触发：用户说"功能写完了验收一下"、"做最后检查"、"准备 merge"、"出验收报告"。前置依赖 k-feat-impl 完成。
feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。
feature 流程阶段 2——按 {slug}-checklist.yaml 里 design 切好的 paradigm 维度 steps 推进，每步具体改哪个文件由 implement 自决，写完用统一格式汇报。触发：用户说"方案确认了开始实现"、"按方案写代码"、"开工"。前提是 design 已 approved 且有 checklist。遇到方案外情况要回方案谈不要硬冲。
issue 流程阶段 2——读 report + 读代码定位根因、评估风险，给用户 2-3 个修复方案让 TA 拍板。这一步不改代码。触发：用户说"分析这个 bug"、"找根因"、"定位问题"，且已有 {slug}-report.md。
issue 流程阶段 3——按已确认根因和方案定点修复、验证、写 {slug}-fix-note.md 落档。两个入口：标准路径从 analyze 来，快速通道从 report 直接来。触发：用户说"开始修 bug"、"按分析修"、"动手改代码"。只动方案声明的文件，不顺手优化。
| name | k-roadmap |
| description | 把"大到塞不进单个 feature"的需求做成完整事前规划：概设 + 接口契约 + 子 feature 拆解清单，放在 `.kflow/roadmap/{slug}/`。两种模式 new / update。触发：用户说"我想要一个 X 系统"、"帮我把这块需求拆一下"、"开一份 roadmap"，或 feature-design 阶段发现需求太大。 |
开始任何判断或动作前，先读取 .kflow/attention.md；缺失则视为骨架不完整，提示先补齐或运行 k-onboard。
.kflow/roadmap/ 是项目的"规划层"——每个子目录承载一块大需求，主文档由三块构成：
三块一起作为这块大需求所有子 feature 的共同约束——每条子 feature 进 k-feat-design 时，roadmap 第 2 块的接口契约就是它的硬约束输入（不能违反，要改先回 roadmap update）。
为什么 roadmap 承载架构方案不放进 architecture/：k-arch 守"只记现状不记计划"。前瞻性架构方案属于"还没落地、可能还会变"的事前规划，放进 architecture 会污染那份系统地图。等子 feature 真正落地，对应接口由 k-feat-accept 提炼回 architecture/——roadmap 完成过渡使命后归档。
为什么单独一层：requirements 记"要什么"（愿景）、architecture 记"怎么搭"（结构）、roadmap 记"怎么分步实现"（执行）。把执行规划塞进愿景或结构文档会把"要什么"和"打算怎么实现"混起来——查不到系统真实能力，计划改一下又得改两份文档。
为什么文件夹不是单文件：拆解过程会产生草稿 / 调研 / 方案对比 / 白板转述，塞一份 md 会乱又舍不得删。每个 roadmap 一个子目录，主文档对外口径，旁边 drafts/ 随便堆。
共享路径与命名约定看
.kflow/reference/shared-paths.md。读取材料遵守.kflow/reference/shared-token-budget.md：先看索引 / 摘要 / 相关节，准备整体改写时才读全文。主文档和 items 完整模板看同目录reference.md。
k-brainstorm 判为 case 3 移交过来（brainstorm 只做分诊，不做拆解）不适用：单 feature 能装下 → k-feat；描述能力"是什么、边界" → k-req；描述系统"结构怎么搭" → k-arch；拍板长期规约 / 选型 → k-decide。
| 用户说什么 | 模式 |
|---|---|
| "拆一下 X 需求"、"开一份 X 的 roadmap"、"我想要一个 X 系统" | new |
| "往 {已有 roadmap} 加子 feature"、"重排顺序"、"标 drop" | update |
判断不出问用户。
每次只动一份 roadmap。一次扔出"我想要 X 和 Y"先选一个，另一个下次。理由同 req / arch——一次吐多份用户 review 不过来。
.kflow/roadmap/{slug}/
├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分（概设）/ 接口契约（架构层详设）/ 子 feature 清单 / 排期
├── {slug}-items.yaml 机器可读清单（feature-design 读、feature-acceptance 回写）
└── drafts/ 可选，调研 / 讨论 / 草稿
{slug} 小写字母 / 数字 / 连字符，和大需求一致（permission-system、notification-center）。平铺不嵌套 epic / sub-epic。drafts/ 按需建，AI 不强制归档。
模式 + 目标 + 范围。new 模式先敲定一个英文 slug（参考现有 req / arch slug 习惯）。
共同必读：.kflow/attention.md + 用户素材。roadmap/ 其他 roadmap 先看目录名 / frontmatter / summary 防重复；requirements/ 和 architecture/ 只打开相关 req / doc 的相关节。
按情况读：
python .kflow/tools/search-yaml.py --dir .kflow/compound --query "{大需求关键词}"update 额外：当前主文档先读目录、frontmatter、要改章节 + items.yaml 当前状态；已启动 / 完成的子 feature 先读 frontmatter、summary、状态和相关设计 / 验收节。改接口契约或发现状态不一致时再读对应全文。
按 reference.md "主文档结构"和"items.yaml 格式"写完整初稿不分批。
拆解纪律：
review 前自跑一遍汇报处理：
.kflow/features/ 确认不冲突）主文档 + items.yaml 完整贴给用户。改到用户明确"可以了"。
new：建 .kflow/roadmap/{slug}/；写主文档（status: active / created / last_reviewed 当天）；写 items.yaml（每条 status: planned、feature: null）；validate-yaml.py 校验。
update：改主文档（last_reviewed 当天，结构性改动文末加变更日志）；改 items.yaml 对应条目（drop 不删，status: dropped 留存理由）；重新校验 yaml。
不改 requirements / architecture——roadmap 是规划层，那两层只描述现状。拆解过程发现 req / 架构过时，在主文档"观察项"记一句给用户，不顺手改。
用户说"开始做 roadmap 里的 {子 feature}"时：
k-feat-design（或 ff / brainstorm）起 feature 目录roadmap: {slug} + roadmap_item: {子 slug}status: in-progress、feature: YYYY-MM-DD-{slug}职责在 k-feat-design 不在本技能。
roadmap 主文档第 4 节"接口契约"是 feature 的硬约束输入——不是参考，是不能违反、要改先回 roadmap update。这就是为什么 roadmap 要在拆 feature 前先把架构方案定下来：让多条 feature 并行 / 串行实现时对外接口对齐。
feature-design 发现接口契约不合理 / 漏了 / 描述不准 → 回 k-roadmap update 改了再继续，不要在 feature 里偷偷绕开（绕开会让下一条同模块 feature 接到老契约导致二次冲突）。
k-feat-accept 收尾时如果 design frontmatter 有 roadmap 字段就改对应 roadmap_item 的 status: done，同时同步主文档子 feature 清单勾选状态。职责在 k-feat-accept 不在本技能。
done / dropped 后主文档 status: completed，目录留作历史档案status: paused，主文档加理由doc_type: roadmap / slug / status / created / last_reviewed / tags）slug / description / depends_on / status / featurevalidate-yaml.py 校验| 方向 | 关系 |
|---|---|
k-req 配合 | req 记"为什么有这个能力"、roadmap 记"打算怎么分步做出来"。大需求下可能多份 req；缺 req 提示用户先 k-req |
k-arch 配合 | architecture 记现状、roadmap 记若干步。读 arch 理解现状但不改它 |
k-feat 下游 | 每条子 feature 是未来一次 feature 流程的种子；起头时 design frontmatter 带 roadmap / roadmap_item |
k-feat-accept 回写方 | acceptance 自动改 items.yaml 为 done，本技能只定义格式不负责回写 |
k-onboard 创建者 | 建 roadmap/ 空目录 |
k-brainstorm 上游 | case 3 移交本技能，带"真问题 / 大致范围 / 可能子模块"一句话汇总。本技能不重复分诊直接拆 |