Stats
Actions
Tags
From kflow
Creates structured roadmaps for large requirements: high-level design, interface contracts, and sub-feature breakdowns. Supports new and update modes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/kflow:k-roadmapThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
开始任何判断或动作前，先读取 `.kflow/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `k-onboard`。
开始任何判断或动作前，先读取 .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-conventions.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（防重复）+ requirements/ 相关 req + architecture/ 相关 doc。
按情况读：
python .kflow/tools/search-yaml.py --dir .kflow/compound --query "{大需求关键词}"update 额外：当前主文档全文 + items.yaml 当前状态 + 已启动 / 完成的子 feature 的 design / acceptance。
按 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 移交本技能，带"真问题 / 大致范围 / 可能子模块"一句话汇总。本技能不重复分诊直接拆 |
npx claudepluginhub kunbo928/kflowCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.