SuperAPI AI 工具集

roadmap

编程与开发

查看项目

更新于 10-22 16:17

技能介绍

用途:Roadmap 技能用于将超大的功能想法转换为持久、可检查点分解的计划。路线图本身不是更大的规格说明,而是一组有序变更序列及变更之间状态的文档,每个步骤足够小,可独立交付且不破坏应用。

主要能力:该技能统一处理所有路线图相关事务,包括存储/命名/状态文件约定,并根据情境路由到对应参考文件:撰写新路线图读 references/writing.md;含义不清的“继续路线图”读 references/resuming-work.md;用户指定检查点要求开始工作时读 references/executing-checkpoints.md;批量起草与验证多个步骤的 PRD/规格/计划读 references/batch-plan-validate.md。

工作流程:分为三阶段。阶段一撰写路线图,分析功能并分解为检查点,核心原则是每步之后应用仍可构建,同时写路线图和功能级 PRD。阶段二针对路线图中的每个步骤生成步骤级 PRD 与设计/规格并验证,按任务起草模式设为 brainstorming、design-only,此时不产出实施计划;每步结果经过 EnterPlanMode → ExitPlanMode → Plannotator 循环评审。阶段三在步骤真正被拾取工作时,才即时编写该步骤的实施计划(superpowers:writing-plans),以便计划反映开始工作时的仓库状态。禁止在阶段二提前为所有步骤写实施计划。

存储与命名:所有内容存放在仓库根目录 docs/<feature-slug>/ 下,受 Git 跟踪并永久保留作为迁移/推出历史,不得放在 tmp/ 或检查点完成后立即删除。写入此位置需先进入原生 Plan Mode。路线图文件为 docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-roadmap.md,每个检查点是顶层复选框,格式为 - [ ] <TICKET> <简称>,使用项目真实问题追踪前缀,无工单时用占位符 TBD。每个路线图有且仅有一个功能级 PRD,存储于 docs/<feature-slug>/YYYY-MM-DD-<feature-slug>-prd.md,路线图需从上下文/简介部分链接到它;先写路线图再写 PRD。步骤级文档放在 docs/<feature-slug>/steps/<step-slug>/ 下,包括 PRD、设计(如有架构决策)和实施计划;无架构决策的步骤仍有 PRD 和计划,仅缺 -design.md;用户明确选择时可跳过 PRD。

状态文件:docs/<feature-slug>/roadmap-state.json 记录整个路线图的进度,包含 feature、roadmapPath、featurePrdPath、updatedAt 和 steps 数组。每个步骤有 id、title、ticket、dependsOn、stepFolder、status、prdPath、specPath、planPath。status 依次为 not-started → prd-drafted → spec-drafted → spec-validated → plan-drafted → implemented → closed;若阶段二直接使用 writing-plans,则跳过 spec-* 阶段;若跳过 PRD,则从 not-started 直接到 plan-drafted 且 prdPath 为 null。不同参考文件在不同时机更新该文件:writing.md 创建时写入初始条目;batch-plan-validate.md 在阶段转换后更新;executing-checkpoints.md 在拾取、实施验证通过及关闭时更新。

依赖管理:检查点行可附加机器可读依赖标签 (depends: <id>[, <id>...]),裸 id 指同一路线图,<feature-slug>:<id> 指相邻路线图。无依赖时省略标签。检查点就绪条件为未勾选且所有依赖满足。裸 id 满足条件是该步骤在本路线图状态文件中 status 为 closed;跨路线图引用只读单向,若目标文件夹不存在视为已完成,若无状态文件则回退到该路线图 Markdown 复选框,若状态文件无对应 id 则引用损坏,应阻止该检查点并提示用户修复标签。多个检查点可同时就绪,从而可并行处理。

提交策略:绝不自动提交路线图/规格/计划文件,仅在用户明确要求时提交。

完全完成时:当路线图中所有复选框均为 - [x],路线图文件及已空的 docs/<feature-slug>/ 文件夹应删除而非保留,具体触发时机见 references/executing-checkpoints.md。

限制:该技能为独立技能,所有产出文档(路线图、功能级与步骤级 PRD、设计/规格、实施计划)强制完全用俄语撰写,无论请求使用何种语言;代码块、标识符、文件路径和工单 id 保持原样;实施计划保留 superpowers 英文标记,如 ### Task N: <русское название> 标题、复选框及 Step/Files/Interfaces/Global Constraints 标签。项目自身的 rules/skills/writing-plans.md 或 rules/skills/brainstorming.md 若存在且表述相同规则,可覆盖;该规则不以这些文件存在为条件。