القائمة
把"大到塞不进单个 feature"的需求做成完整事前规划：概设 + 接口契约 + 子 feature 拆解清单，放在 `.kflow/roadmap/{slug}/`。两种模式 new / update。触发：用户说"我想要一个 X 系统"、"帮我把这块需求拆一下"、"开一份 roadmap"，或 feature-design 阶段发现需求太大。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
维护 `.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 移交本技能，带"真问题 / 大致范围 / 可能子模块"一句话汇总。本技能不重复分诊直接拆 |