Back to Details

plankit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

plankit

plankit

Turn a rough idea (a feature, a project, a spec, a PRD) into a structured plan document you can act on. plankit is generative: it brainstorms the approach, settles the decisions needed for a coherent draft, and writes a 
plan-<slug>-YYYY-MM-DD.md
grounded in the real codebase (not a guess). It is the front of a flow, plankit drafts → grillkit hardens → issuekit files where a project tracks work in GitHub Issues, and plankit drafts → grillkit hardens → implementkit builds where it doesn't. Either way the plan it writes is the exact input the next step expects. plankit plans only: it never writes application code and never creates issues.
将粗略的想法（功能、项目、规格说明书、PRD）转化为可落地执行的结构化计划文档。plankit具备生成式能力：它会构思实现方案、确定连贯草稿所需的决策，并基于真实代码库（而非猜测）撰写
plan-<slug>-YYYY-MM-DD.md
文档。它是一套工作流的起始环节，plankit 起草 → grillkit 优化 → issuekit 创建工单适用于在GitHub Issues中跟踪工作的项目，而plankit 起草 → grillkit 优化 → implementkit 开发适用于不使用该方式的项目。无论哪种情况，它撰写的计划都是下一环节所需的精准输入。plankit 仅负责规划：它从不编写应用代码，也从不创建工单。

When this fires

触发场景

The user wants to think a piece of work through before building it: "plan this feature", "brainstorm a plan / PRD / spec", "write a plan doc", "help me think through X first", "/plankit". One distinction matters:
  • It is not the adversarial interrogator. That's grillkit. plankit asks enough to draft a coherent plan and records the thin spots as open questions; grillkit is what pressure-tests them one decision at a time.
用户希望在开发前梳理清楚工作内容：“规划这个功能”“构思一份计划/PRD/规格说明书”“撰写计划文档”“先帮我梳理X的思路”“/plankit”。需要明确一个区别：
  • 它不是对抗性质询工具。那是grillkit的职责。plankit会提出足够的问题来起草连贯的计划，并将薄弱点记录为待解决问题；grillkit则会逐个决策进行压力测试。

Procedure

执行流程

1. Capture the idea

1. 捕捉需求

Get the concept, the problem it solves, who it's for, and the outcome that means success. If the input is a one-liner, ask a few scoping questions (use 
AskUserQuestion
when available). Those are generative "what are we building and why", not adversarial "what did you miss". Enough to draft, no more.
获取概念、要解决的问题、目标用户以及衡量成功的结果。如果输入只是一句话，提出几个范围界定问题（若可用则使用
AskUserQuestion
）。这些是生成式的“我们要构建什么以及为什么”，而非对抗性的“你遗漏了什么”。只需足够支撑起草计划即可，无需过多追问。

2. Ground it in reality

2. 贴合实际情况

Research before proposing, so the plan reuses what exists instead of reinventing it.
  • In an existing repo: read the relevant code, docs, and config to find the patterns, utilities, and conventions the plan should build on. Look up facts yourself (
    Read
    , 
    Grep
    , 
    Glob
    ); reserve questions for genuine decisions. Never propose new code where a suitable implementation already exists; name the existing thing in the plan instead.
  • Greenfield (no repo yet): skip the code research; ground the plan in the user's stated goals and constraints.
在提出方案前先开展调研，确保计划复用现有内容而非重新发明。
  • 现有代码仓库中：阅读相关代码、文档和配置，找到计划应基于的模式、工具和约定。自行查找事实（使用
    Read
    、
    Grep
    、
    Glob
    ）；仅对真正需要决策的内容提问。绝不在已有合适实现的地方提议新代码；而是在计划中直接引用现有内容。
  • 全新项目（无代码仓库）：跳过代码调研；基于用户陈述的目标和约束制定计划。

3. Diverge, explore approaches

3. 发散探索，多方案构思

Brainstorm the real options and recommend one, something concrete to accept or redirect, not a naked menu. This is the generative half: don't settle for the first idea, and consider the unconstrained version of the work before narrowing to the practical one.
When more than one credible path exists, default to a spread that is genuinely different rather than variants of one idea: a minimal viable (the smallest diff that ships and is useful), an ideal (the shape you'd choose with time to do it properly), and where one exists a lateral (a reframe that dissolves the problem instead of solving it). Name what each option reuses from the research above, so the plan stays anchored to the code you just read. Collapsing to a single approach is fine when the work warrants it, since "no credible alternative" beats an invented Option B.
The failure mode is options that only look plural:
Variants (avoid): cache the response · cache it with a shorter TTL · cache it behind a flag we can tune later. One idea in three hats, so there's no real choice to make.
Distinct (aim for): cache the response (smallest diff, ships this week, goes stale on writes) · denormalize the read path so there's nothing to cache (a migration, but the whole staleness class disappears) · don't fix it here at all, because it's only slow when called in a loop, so batch upstream and the endpoint stops mattering.
构思切实可行的方案并推荐其中一个，提供具体的可接受或调整方向，而非单纯罗列选项。这是生成式环节的核心：不要满足于第一个想法，在缩小到实用方案前先考虑无约束版本的工作内容。
当存在多个可信路径时，默认选择真正不同的方案组合，而非同一想法的变体：最小可行版（能交付且有用的最小代码变更）、理想版（有充足时间时会选择的最佳形态），以及若存在的话横向方案（重构问题而非直接解决问题的思路）。标注每个选项复用了上述调研中的哪些内容，确保计划始终贴合你刚阅读的代码。当工作内容无需多方案时，仅保留单一方案即可，因为“无可信替代方案”强于强行编造选项B。
需避免的错误模式：看起来是多个选项但本质相同：
变体（需避免）：缓存响应 · 用更短的TTL缓存 · 在可调整的标志后缓存。同一想法换三种表述，没有真正的选择空间。
差异化方案（目标）：缓存响应（最小代码变更，本周交付，写入时失效） · 反规范化读取路径，无需缓存（需迁移，但完全消除过期问题） · 此处不修复，因为仅在循环调用时变慢，所以在上游批量处理，端点性能不再是问题。

4. Converge, settle the structure

4. 收敛思路，确定结构

Resolve the structural decisions a coherent draft needs (the architecture, the phases, the scope boundary) one at a time, each with a recommended answer. Then stop: deliberately leave the deeper, thin, or still-uncertain spots for grillkit rather than grinding every edge case here. Record those under Open questions in the doc so the hardening step has a target.
逐个解决连贯草稿所需的结构性决策（架构、阶段、范围边界），每个决策给出推荐答案。然后停止：有意将更深层、薄弱或仍不确定的内容留给grillkit处理，而非在此纠结所有边缘情况。在文档的待解决问题部分记录这些内容，以便优化环节有明确目标。

5. Write the plan document

5. 撰写计划文档

Write 
docs/plans/plan-<slug>-YYYY-MM-DD.md
, where 
<slug>
is a short lowercase kebab-case name for the feature and the suffix is the plan's ISO creation date (
plan-sso-login-2026-07-23.md
). Keep that date stable on later edits; record an updated date inside the document when useful. Use the plan-doc format below, which is the contract grillkit and issuekit both read, so keep the body phase/task-shaped. Create 
docs/plans/
if it doesn't exist. If a plan for this work already exists, update it in place rather than writing a second file. For a genuine same-day collision between distinct plans, make the slug more specific; only as a last resort insert a sequence immediately before the date (
plan-sso-login-02-2026-07-23.md
).
编写
docs/plans/plan-<slug>-YYYY-MM-DD.md
，其中
<slug>
是功能的简短小写短横线命名，后缀是计划的ISO创建日期（例如
plan-sso-login-2026-07-23.md
）。后续编辑时保持该日期稳定；必要时在文档内记录更新日期。使用下方的计划文档格式，这是grillkit和issuekit都能读取的约定，因此主体需按阶段/任务组织。若
docs/plans/
目录不存在则创建。如果针对该工作已有计划文档，直接更新原文件而非撰写新文件。若同一天内有针对不同内容的同名计划冲突，将slug修改得更具体；万不得已时在日期前添加序号（例如
plan-sso-login-02-2026-07-23.md
）。

6. Hand off

6. 交接

Write this section in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.
Report where the plan landed and offer the next step, in order, naming a sibling kit only when it is installed and otherwise describing the action in plain language:
  • grillkit. Pressure-test and harden the draft (it can update this same file in place).
  • issuekit, when the project tracks work in GitHub Issues. Turn the hardened plan into issues.
  • implementkit, when it does not. Build straight from the plan, one phase at a time.
Name the second or the third, not both, when you can tell which applies. The prompt or the repo's agent-guide file says which; open issues on the repo are the weaker signal. Name both when nothing settles it, and never assume a project files GitHub issues just because it is hosted on GitHub.
If the planning surfaced project vocabulary worth pinning down or a hard-to-reverse trade-off decision, offer domainkit when installed; otherwise offer to record a glossary entry or ADR directly.
Do not start either yourself.
此部分采用流程式表述：每句一个指令，主动语态，现在时，无比喻。
告知计划完成情况并按顺序提供下一步选项，仅在同级工具已安装时提及对应kit，否则用平实语言描述操作：
  • grillkit：对草稿进行压力测试和优化（可直接更新同一文件）。
  • issuekit，适用于在GitHub Issues中跟踪工作的项目：将优化后的计划转化为工单。
  • implementkit，适用于不使用上述方式的项目：直接按计划分阶段开发。
在能判断适用情况时，只提及第二个或第三个选项，而非两者都提。提示信息或仓库的agent-guide文件会说明适用情况；仓库中的公开工单是较弱的信号。当无法确定时可同时提及两者，绝不要假设项目托管在GitHub就一定使用GitHub Issues跟踪工作。
如果规划过程中发现值得明确的项目术语或难以逆转的权衡决策，若已安装domainkit则推荐使用；否则提议直接记录术语表条目或ADR（架构决策记录）。
不要自行启动任何后续环节。

Plan-doc format

计划文档格式

The canonical structure plankit owns. Keep it lean, so every section earns its place, and keep the body organized as phases/tasks so issuekit can decompose it into issues:
markdown
undefined
plankit遵循的标准结构。保持简洁，确保每个章节都有存在的必要，主体按阶段/任务组织，以便issuekit能将其分解为工单：
markdown
undefined

Plan: <title>

Plan: <title>

Context

Context

The problem, why it matters now, and the outcome that means success.
问题是什么、当前为何重要，以及衡量成功的结果。

Design decisions (settled)

Design decisions (settled)

DecisionResolution
<the choice><what we picked and, briefly, why>
DecisionResolution
<决策内容><选择方案及简要原因>

Approach

Approach

The chosen approach and what it reuses from the existing codebase, then the plan body as phases/milestones/tasks, each a concrete, verifiable unit of work. This is the structure issuekit reads to propose an issue breakdown. When the alternatives were close, keep the rejected ones to a line each so the choice stays legible later.
选定的方案以及它复用了现有代码库中的哪些内容，然后是按阶段/里程碑/任务划分的计划主体，每个部分都是具体可验证的工作单元。这是issuekit读取并生成工单分解的结构。当备选方案差异不大时，用一句话记录被否决的方案，以便后续清晰了解选择依据。

Open questions

Open questions

Unresolved or thin spots, written as targets for grillkit to interrogate.
未解决或薄弱的内容，作为grillkit质询的目标。

Non-goals

Non-goals

Explicit scope boundaries, meaning what this plan deliberately does not cover.

A hardened plan additionally carries a **`Grilled: YYYY-MM-DD` line directly under the title**. grillkit writes it when the plan survives a grill session, and issuekit reads it as the gate for filing issues `ready`. plankit never writes the stamp itself; a fresh draft is ungrilled by definition.
明确的范围边界，即本计划刻意不覆盖的内容。

优化后的计划还会在标题下方直接添加一行**`Grilled: YYYY-MM-DD`**。grillkit会在计划通过打磨环节后添加该标记，issuekit将其视为创建“就绪”工单的准入条件。plankit绝不会自行添加该标记；新起草的计划默认未经过打磨。

The phase-heading annotation slot

阶段标题注释位

A phase heading ends in an optional annotation, and downstream skills write into it. plankit writes a bare heading (
### Phase 2: auth
) and never annotates one itself, because a fresh plan has neither been filed nor built. Two vocabularies share the slot:
  • (#41)
    , written by issuekit when it files that phase as an issue. It says where the phase is tracked.
  • (built YYYY-MM-DD)
    , written by implementkit when it finishes building that phase. It says the phase is done.
They coexist, so 
### Phase 2: auth (#41) (built 2026-08-20)
is a tracked phase that shipped. Keeping both in one slot is what lets a reader and a survey tool answer "what is left in this plan?" from the plan alone, with no tracker to consult, which is the only way that question has an answer on a project that files no issues.
The stamp is opt-in per plan. A plan with no annotation anywhere makes no claim about itself, so nothing may read its phases as unbuilt. That is what lets the convention arrive without a migration: plans written before it stay silent and correct, and a plan starts making claims the first time something stamps it.
Match the heading loosely. A phase heading begins 
Phase <n>
and the separator that follows varies across real plan sets, so anything reading these headings accepts a colon, a dash, or nothing.
阶段标题末尾可添加可选注释，下游工具会写入内容。 plankit仅写入纯标题（例如
### Phase 2: auth
），从不添加注释，因为新计划既未创建工单也未开发完成。两种词汇可共用该位置：
  • (#41)
    ，由issuekit在将该阶段创建为工单时添加。表示该阶段的跟踪位置。
  • (built YYYY-MM-DD)
    ，由implementkit在完成该阶段开发时添加。表示该阶段已完成。
两者可以共存，例如
### Phase 2: auth (#41) (built 2026-08-20)
表示该阶段已创建工单且已交付。将两者放在同一位置，读者和调研工具无需查阅跟踪系统，仅通过计划本身就能回答“本计划还有哪些未完成内容？”，这对于不创建工单的项目来说是唯一可行的方式。
标记为计划可选内容。 未添加任何注释的计划不做任何声明，因此不会被视为未完成。这一约定无需迁移即可推行：在此之前撰写的计划保持无注释状态且依然有效，只有当工具首次标记时，计划才开始做出相关声明。
宽松匹配标题。 阶段标题以
Phase <n>
开头，后续分隔符在实际计划中可能不同，因此读取这些标题时需接受冒号、短横线或无分隔符的情况。

Notes

注意事项

  • Plan only. No application code, no issues; those are separate steps (implementkit, issuekit). plankit hands off; it doesn't cross into them.
  • Fewest honest sections. Prefer a short, sharp plan over a padded one; drop a section rather than fill it with filler. Scale the doc to the work's real surface area.
  • Defer the grilling. Leaving open questions is fine and expected. Draft a coherent plan and let grillkit harden it; don't try to be both.
  • Follow the repo's conventions. If the codebase has its own plan/RFC/PRD location or template, follow that and say you did, rather than forcing 
    docs/plans
    .
  • No filesystem or shell (e.g. a browser-based agent)? Then you can't write the file. Instead print the finished plan document as a codeblock and give the user the canonical 
    plan-<slug>-YYYY-MM-DD.md
    filename to save wherever they keep plans.
  • 仅负责规划。不编写应用代码，不创建工单；这些是单独的环节（由implementkit、issuekit负责）。plankit仅负责交接，不介入后续环节。
  • 精简必要章节。优先选择简短清晰的计划，而非冗长填充的内容；若某章节无实质内容则直接省略。根据工作的实际规模调整文档篇幅。
  • 推迟打磨环节。遗留待解决问题是正常且预期的。起草连贯的计划后交由grillkit优化；不要试图同时承担两者的职责。
  • 遵循仓库约定。如果代码库有自己的计划/RFC/PRD存放位置或模板，请遵循该约定并说明，而非强制使用
    docs/plans
    目录。
  • 无文件系统或Shell权限（例如基于浏览器的Agent）？则无法写入文件。此时将最终计划文档以代码块形式输出，并告知用户标准文件名
    plan-<slug>-YYYY-MM-DD.md
    ，由用户自行保存到计划存放位置。