plankit

用途

plankit 用于在动手写代码之前，把粗略的想法（一个功能、一个项目、一份规格、一份 PRD）变成可执行的结构化计划文档。它是生成式的：会头脑风暴方案、敲定让草稿自洽所需的决策，并写出基于真实代码库（而非猜测）的 NNNN-plan-<slug>-YYYY-MM-DD.md。

它是流程的前端：在有 GitHub Issues 的项目中走 plankit 起草 → grillkit 加固 → issuekit 建单；在没有的项目中走 plankit 起草 → grillkit 加固 → implementkit 实现。无论哪条路径，它写出的计划都是下一步骤所期望的精确输入。plankit 只做计划：从不写应用代码，也从不创建 issue。

触发时机

当用户想在构建之前把一项工作想清楚时触发，例如“plan this feature”“brainstorm a plan / PRD / spec”“write a plan doc”“help me think through X first”“/plankit”。

一个关键区分：它不是对抗式审问者，那是 grillkit。plankit 只问足以起草一份自洽计划的问题，并把薄弱点记录为开放问题；grillkit 才是逐个决策施压检验的工具。

主要能力与流程

1. 捕获想法：获取概念、它解决的问题、面向谁、以及代表成功的成果。若输入只有一句话，会问少量范围界定问题（可用时使用 AskUserQuestion）。这些是生成式的“我们在构建什么、为什么”，而非对抗式的“你漏了什么”。最多问一轮，且只问输入未明确的四项。

2. 基于现实：先研究再提议，让计划复用已有内容而非重复造轮子。在已有仓库中，阅读相关代码、文档和配置，找出计划应沿用的模式、工具和约定；自行查证事实（Read、Grep、Glob），把提问留给真正的决策。已有合适实现时绝不提议新代码，而是在计划中指明现有实现。全新项目（尚无仓库）则跳过代码研究，基于用户陈述的目标与约束来写计划。

3. 发散、探索方案：头脑风暴真实选项并推荐一个，给出可接受或可改向的具体方案，而非裸菜单。这是生成式的一半：不要满足于第一个想法，在收窄到务实版本前先考虑不受约束的版本。当存在多条可信路径时，默认给出真正不同的分布：最小可行（能交付且有用的最小改动）、理想（有时间好好做时会选的形态），以及存在时的横向方案（重新框定问题使其消解而非被解决）。说明每个选项复用了上述研究中的什么。当工作本身只值得一种方案时，收敛为单一方案也可以，因为“没有可信替代”胜过编造的 Option B。

4. 收敛、敲定结构：逐个解决一份自洽草稿所需的结构性决策（架构、阶段、范围边界），每个都给出推荐答案。然后停下：刻意把更深、更薄或仍不确定的点留给 grillkit，而不是在这里磨完每个边界情况。把这些记录在文档的 Open questions 下，让加固步骤有靶子。

5. 写计划文档：写入 docs/plans/NNNN-plan-<slug>-YYYY-MM-DD.md，其中 NNNN 是 docs/plans/ 中的下一个四位序号，<slug> 是功能的简短小写 kebab-case 名称，后缀是计划的 ISO 创建日期（如 0007-plan-sso-login-2026-07-23.md）。取序号的方法是列出 docs/plans/，取最大前导序号加一；没有时从 0001 开始。序号按目录计且从不复用，适用于每个仓库，包括全新仓库。后续编辑保持整个文件名稳定；需要时在文档内记录更新日期。使用下方 plan-doc 格式，它是 grillkit 和 issuekit 都读取的契约，因此正文保持阶段/任务形态。若 docs/plans/ 不存在则创建。若该工作的计划已存在，就地更新而非写第二个文件，即使它没有序号也保留其名称。当该计划带有 Grilled: 行且你的更新是实质性时，删除该行并在交接中说明。

6. 交接：报告计划落在哪里，以及是否删除了 Grilled: 行。然后按顺序提供下一步，仅当同级 kit 已安装时点名，否则用平实语言描述动作：grillkit（施压检验并加固草稿，可就地更新同一文件）；issuekit（当项目在 GitHub Issues 中跟踪工作时，把加固后的计划转成 issue）；implementkit（当不跟踪时，直接从计划逐阶段构建）。能判断适用哪个时只点名第二个或第三个，不要都点。提示词或仓库的 agent-guide 文件会说明是哪个；仓库上的开放 issue 是较弱信号。无法确定时两个都点名，且绝不因为项目托管在 GitHub 上就假定它提交 GitHub issue。若规划中浮现出值得固定的项目词汇或难以逆转的取舍决策，已安装 domainkit 时提供它；否则直接提供记录术语表条目或 ADR。不要自己启动其中任何一个。

计划文档格式

plankit 拥有的规范结构。保持精简，让每个章节都物有所值，正文按阶段/任务组织，以便 issuekit 能拆解为 issue：

• # Plan: <title>
• ## Context：问题、为何现在重要、代表成功的成果。
• ## Design decisions (settled)：表格，列为 Decision / Resolution。
• ## Approach：所选方案及其从现有代码库复用的内容，然后是作为阶段/里程碑/任务的计划正文，每个都是具体、可验证的工作单元。这是 issuekit 读取以提出 issue 拆分的结构。当备选方案接近时，把被否决的每个保留一行，让选择日后仍可读。
• ### Phase 1: <name>：任务，并以 Done when: 结尾，给出评审者可检查的可观察项（命令及其输出、运行中应用的行为、通过的测试）。
• ## Migration and rollback：仅当计划改变存储数据（schema、持久化文件格式、现有记录）时。说明现有数据如何迁移到新形态、在哪个阶段、以及该阶段失败时如何撤销。否则省略此节。
• ## Open questions：未解决或薄弱的点，写成供 grillkit 审问的靶子。
• ## Non-goals：明确的范围边界，即本计划刻意不覆盖的内容。

加固后的计划在标题正下方额外带一行 Grilled: YYYY-MM-DD。grillkit 在计划通过一次 grill 会话时写入它，issuekit 将其读作提交 ready issue 的门槛。plankit 从不自己写这个戳记；新草稿按定义就是未 grill 的。

每个阶段都以 Done when: 行结尾，即验收可观察项。它命名人或测试在该阶段交付后可检查的东西，绝不是意图（如“auth works”）。它给构建一个可对照检查的终点，没有它的阶段就没有终点。

Grilled: 戳记何时失效

戳记为计划在 grill 时的状态背书。实质性编辑指：新增、删除或更改已敲定的设计决策；新增、删除或重新界定某阶段范围；更改 Done when: 可观察项；或更改 non-goals 或迁移章节。做实质性编辑的人在同一次编辑中删除 Grilled: 行，使计划在 grillkit 再次运行前读作未 grill。措辞修正、下方阶段标题注解、更新日期行、以及新增开放问题都不是实质性的，戳记保留。

阶段标题注解槽

阶段标题末尾有一个可选注解，下游技能写入其中。plankit 写裸标题（### Phase 2: auth），从不自己注解，因为新计划既未被建单也未被构建。两套词汇共用该槽：(#41) 由 issuekit 在该阶段被建为 issue 时写入，表示该阶段在哪里跟踪；(built YYYY-MM-DD) 由 implementkit 在完成该阶段构建时写入，表示该阶段已完成。二者共存，因此 ### Phase 2: auth (#41) (built 2026-08-20) 是一个已跟踪且已交付的阶段。把两者放在同一槽中，使读者和调查工具仅凭计划本身就能回答“这个计划还剩什么？”，无需查阅跟踪器——这是在不提交 issue 的项目上该问题唯一有答案的方式。

戳记按计划选择启用。任何地方都没有注解的计划不对自身作任何声明，因此不得把其阶段读作未构建。这使该约定无需迁移即可引入：约定之前写的计划保持沉默且正确，计划在第一次被盖章时才开始作声明。

宽松匹配标题。阶段标题以 Phase <n> 开头，其后的分隔符在真实计划集中各不相同，因此任何读取这些标题的工具都接受冒号、破折号或无分隔符。

注意事项

• 只做计划。不写应用代码、不建 issue；那些是独立步骤（implementkit、issuekit）。plankit 只交接，不越界。
• 最少的诚实章节。宁可要简短锐利的计划，不要注水的计划；宁可删掉一节，也不要用填充物填满它。按工作真实规模调整文档。
• 推迟 grill。留下开放问题是可以且被预期的。起草一份自洽计划，让 grillkit 加固它；不要试图两者兼任。
• 遵循仓库约定。若代码库有自己的计划/RFC/PRD 位置或模板，遵循它并说明你照做了，而不是强推 docs/plans。
• 没有文件系统或 shell（例如基于浏览器的 agent）？那就无法写文件。改为把完成的计划文档作为代码块打印出来，并给用户规范的 NNNN-plan-<slug>-YYYY-MM-DD.md 文件名（无法列出其计划时用 0001），让他们保存到存放计划的地方。