plankit

plankit

大まかなアイデア（機能、プロジェクト、仕様、PRD）を、実行に移せる構成済みの計画ドキュメントに変換します。plankit は生成型で、アプローチをブレインストーミングし、一貫性のあるドラフトに必要な決定を固め、実際のコードベースに基づいた（推測ではない）NNNN-plan-<slug>-YYYY-MM-DD.md を作成します。GitHub Issues で作業を追跡するプロジェクトでは、plankit drafts → grillkit hardens → issuekit files というフローの出発点となり、そうでないプロジェクトでは、plankit drafts → grillkit hardens → implementkit builds となります。どちらの場合も、作成する計画は次のステップがそのまま入力として使える形式です。plankit は計画のみを行い、アプリケーションコードを書いたり、イシューを作成したりすることはありません。

このスキルが起動する場面

ユーザーが、作業に着手する前に内容を十分に検討したいときです。「この機能を計画して」「計画／PRD／仕様をブレインストーミングして」「計画ドキュメントを書いて」「まず X を一緒に考えて」「/plankit」などです。重要な違いが一つあります。

• 対立的に問い詰めるスキルではありません。 それは grillkit の役割です。plankit は一貫性のある計画を作るために必要なことを質問し、情報が不足している点は未解決の質問として記録します。一つずつ決定事項を検証するのは grillkit の役割です。

手順

1. アイデアを把握する

コンセプト、解決する問題、対象ユーザー、成功を示す結果を把握します。成功を示す結果とは、依頼の背後にある目標です。つまり、何を作るかだけでなく、その作業の目的を指します（「このクラッシュを修正する」ではなく「アプリがクラッシュしない状態を保つ」）。さらに、成功を示す目標値、つまり成果を示す数値も必要です。入力が一言だけの場合は、範囲を定める質問をいくつかします（利用できる場合は AskUserQuestion を使います）。質問は「何を、なぜ作るのか」という生成的なものであり、「何を見落としたか」という対立的なものではありません。質問は最大で一度だけ、入力から不明な四つの項目についてのみ行います。

目標値はユーザーに尋ね、ベースラインがある場合に限って提案します。 まず、ユーザーに数値を尋ねます。ユーザーが数値を持っていない場合は、ユーザーが示したベースライン、または読み取れるファイル（CI レポート、ベンチマーク出力、ダッシュボードのエクスポートなど）に基づく場合に限って提案し、次のように両方を明記します。Target: p95 load under 200 ms (proposed; baseline 4.8 s from ci/bench.json) このスキルにはシェルがないため、ベースラインを自ら測定することはありません。ベースラインがない場合は、Target: open, no baseline と記述し、その行を未解決の質問にも引き継ぎます。これにより、数値を作り上げるのではなく grillkit が決定できます。作業に数値が適さない場合は、その理由と、成功を示す指標を記録します（「ドキュメントのみの変更なので、チェックは lint のパスです」）。「該当なし」だけでは指標が示されず、この手順を満たしません。

完了条件： コンセプト、問題、ユーザー、成功を示す結果のそれぞれについて、入力またはユーザーから得た一行の回答があり、成功を示す結果には目標値、Target: open, no baseline の行、または数値が適さない理由と成功を示す指標が含まれていること。

2. 実情に基づいて計画する

提案する前に調査し、既存のものを再利用できるようにします。車輪の再発明は避けてください。

• 既存のリポジトリがある場合： 関連するコード、ドキュメント、設定を読み、計画の土台となるパターン、ユーティリティ、規約を見つけます。事実は自分で調べ（Read、Grep、Glob）、質問は本当に決定が必要な点に限ります。適切な実装がすでに存在する場合、新しいコードを提案してはいけません。代わりに、計画の中で既存のものを名前を挙げて記載します。
• グリーンフィールド（まだリポジトリがない場合）： コード調査は省略し、ユーザーが示した目標と制約を計画の根拠にします。

完了条件： 作業が触れるシステムの各部分について、既存のモジュール、ユーティリティ、規約がパスとともに記載されているか、存在しないことが記録されていること。また、UI の変更では、プロジェクトの規則と視覚的な参照が見つかっているか、見つからないことが記録されていること（UI plans）。グリーンフィールドの作業では、示された目標と制約がすべて書き留められていること。

3. 方向を広げ、アプローチを探る

現実的な選択肢をブレインストーミングし、1つを推奨してください。選択または軌道修正を具体的に行える案を示し、単なる選択肢の羅列にしないでください。ここが発想を広げる段階です。最初の案に飛びつかず、実現上の制約を考える前に、作業を制約なしで進めた場合の形も検討してください。

信頼できる進め方が複数ある場合は、同じ案のバリエーションではなく、本当に異なる案を幅広く提示するのが基本です。たとえば、最小限の実用案（リリースできて役立つ、最小限の差分）、理想案（十分な時間をかけて適切に実装するなら選ぶ形）、そして可能であれば、問題を解決するのではなく問題そのものを解消する別角度の案を示します。それぞれの案で、上記の調査内容から何を再利用するかを明記し、直前に読んだコードに計画を根ざしたものにしてください。作業内容に応じて、1つのアプローチに絞ってもかまいません。でっち上げた選択肢 B を出すより、「信頼できる代替案がない」とする方が適切です。

完了条件： 1つのアプローチを推奨し、各代替案は、明示された軸で推奨案と異なるか、信頼できる代替案がない理由を1行で示しています。

見かけだけ選択肢が複数ある場合は、失敗です。

バリエーション（避ける）： レスポンスをキャッシュする · TTL を短くしてキャッシュする · 後で調整できるようフラグの後ろでキャッシュする。帽子を3つかぶせた同じ案なので、実質的な選択肢がありません。

異なる案（目指す）： レスポンスをキャッシュする（最小限の差分で今週リリースできるが、書き込み後に古くなる）· 読み取りパスを非正規化して、キャッシュを不要にする（マイグレーションが必要だが、古さに関する問題を根本からなくせる）· ここでは修正しない。ループ内で呼び出す場合にしか遅くないため、上流でまとめて処理すればエンドポイントは問題にならない。

4. 収束させ、構成を固める

一貫性のあるドラフトに必要な構成上の決定（アーキテクチャ、フェーズ、スコープの境界、また新しい種類のテストが必要になるフェーズではテスト方法）を、1つずつ、推奨案とともに確定させてください。その後は止めます。より深い部分、薄い部分、または不確かな部分はすべて grillkit に委ね、ここであらゆる例外ケースを掘り下げないでください。これらは、次の強化ステップで検討できるよう、ドキュメントの未解決の質問に記録してください。

完了条件： アーキテクチャ、フェーズ一覧、スコープの境界について、ユーザーが承認または修正した確定案があり、人の関与が必要な各フェーズに attended の印が付いており、その他の未確定事項はすべて「未解決の質問」の一覧に記載されています。

5. 計画書を作成する

docs/plans/NNNN-plan-<slug>-YYYY-MM-DD.md を作成します。NNNN は docs/plans/ にある次の4桁の通し番号、<slug> は機能を表す短い小文字のケバブケース名、末尾は計画書の ISO 作成日です（0007-plan-sso-login-2026-07-23.md）。通し番号を決めるには、このチェックアウトとリポジトリ内のほかのすべてのワークツリーで、docs/plans/ にある先頭の通し番号の最大値を調べて1を足します。番号がない場合は 0001 から始めます。このスキルではシェルを使えないため、Read と Glob でワークツリーを調べます。リンクされたワークツリーでは、.git は <main>/.git/worktrees/<name> を示すファイルです。<main> はメインのチェックアウトで、各 <main>/.git/worktrees/*/gitdir には別のワークツリーのパスが記載されています。並行するワークツリーで同じ番号が使われないよう、すべてを調べます。通し番号はディレクトリごとに割り当て、再利用しません。新規リポジトリも含め、あらゆるリポジトリに適用されます。後の編集でもファイル名全体を変えず、必要であれば文書内に更新日を記録します。以下の計画書の形式を使用します。この形式は grillkit と issuekit の両方が読み取る契約なので、本文はフェーズとタスクの構成にします。docs/plans/ がなければ作成します。この作業の計画書がすでにある場合は、2つ目のファイルを作成せず、既存のファイルを更新します。番号が付いていなくても、そのファイル名は変えません。計画書に Grilled: の行があり、更新内容が実質的な場合は、その行を削除し、引き継ぎで削除したことを伝えます。

完了条件： ファイルが指定のパスに存在し、形式の各セクションに内容が記入されているか、意図的に省略されており、すべてのフェーズに受け入れ確認の観察項目があること。

6. 引き継ぐ

このセクションは手順を示す文体で記述します。1文につき1つの指示とし、能動態、現在形を使い、比喩は使いません。

計画書の保存先と、Grilled: の行を削除したかどうかを報告します。次に行う手順を、順番に提示します。兄弟キットの名前を挙げるのは、それがインストールされている場合に限り、インストールされていない場合は作業内容を平易に説明します。

• grillkit. 草案を厳しく検証して完成度を高めます（同じファイルをその場で更新できます）。
• プロジェクトで GitHub Issues を使って作業を管理している場合は、issuekit を使います。完成度を高めた計画を Issue に変換します。
• 使っていない場合は、implementkit を使います。計画に沿って、フェーズを1つずつ実装します。

どちらに該当するか判断できる場合は、2つ目か3つ目のどちらか一方を挙げ、両方は挙げません。該当するキットは、プロンプトまたはリポジトリのエージェントガイドファイルで確認します。リポジトリの未解決 Issue は、判断材料としてはそれより弱いものです。何も判断できない場合に限り両方を挙げます。GitHub でホストされているという理由だけで、プロジェクトが GitHub Issues を使っていると決めつけてはいけません。

計画の作成を通じて明確化する価値のあるプロジェクト用語や、後戻りしにくいトレードオフの判断が明らかになった場合は、domainkit がインストールされていれば domainkit を提示します。インストールされていなければ、用語集の項目または ADR を直接記録することを提案します。

これらの作業は自分では開始しません。

計画書の形式

plankit が管理する標準的な構成です。簡潔に保ち、各セクションに役割を持たせ、本文はフェーズ／タスクとして整理して、issuekit が課題に分解できるようにします。

# Plan: <title>

## Context
The problem, why it matters now, and the outcome that means success: the goal behind the request and its target line.

## Design decisions (settled)
| Decision | Resolution |
|----------|-----------|
| <the choice> | <what we picked and, briefly, why> |

## 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.

### Phase 1: <name>
Attended: <only when the phase needs a person: the pick or approval it waits on>
<the tasks>
Done when: <an observable a reviewer can check: a command and its output, a behavior in the running app, a test that passes>

## Migration and rollback
Only when the plan changes stored data (a schema, a persisted file format, existing records). How existing data moves to the new shape, in which phase, and how to undo it if the phase fails. Omit the section otherwise.

## Open questions
Unresolved or thin spots, written as targets for grillkit to interrogate.

## Non-goals
Explicit scope boundaries, meaning what this plan deliberately does not cover.

強化された計画書には、タイトルの直下に Grilled: YYYY-MM-DD の行も記載します。計画書がグリルセッションを通過すると grillkit がこの行を書き込み、issuekit は課題を ready として登録するための条件として読み取ります。plankit がこのスタンプを書き込むことはありません。新しい草案は定義上、未グリルです。

すべてのフェーズは Done when: の行で終わります。これは受け入れ条件として確認できる内容です。フェーズの完了後に人やテストが確認できる事柄を記し、意図（「認証が動作する」など）は記しません。これにより、ビルドの完了ラインが定まり、それがなければフェーズに終わりはありません。

ビルドで測定できる場合は、最後のフェーズの Done when: に目標値を記します。そうすれば、ビルドでは記録するだけでなく、数値を確認できます。リリース後にしか確認できない指標は Context に measured after release と明記します。ビルドでは確認できないためです。

新しい種類のテストを求めるフェーズでは、Design decisions にランナーとアプローチを記します（たとえば、「vitest と Testing Library を使ったコンポーネントテストを、ソースの隣に配置する」）。この行がないと、ビルド時にどのランナーを使うか確認する必要が生じます。

人が関わるフェーズ

人の作業が必要なフェーズには Attended: の行を設け、待ち受ける内容を記します。たとえば、デザインの選択、モックアップの承認、課題の登録やデプロイなどの外部への操作です。人が関わるフェーズを、無人で実行できるフェーズより先に配置し、人による作業を先に終わらせてから、キーボードに誰もいない状態で残りを実行できるようにします。無人ランナーはこの行を読み取り、ビルドの途中ではなく、ビルドの前に停止します。

UI の計画書

画面を変更する計画書では、PR の後ではなく、ビルドの前に見た目を確定します。 プロジェクトの DESIGN.md とエージェント向けの指示を読み、UI に関するプロジェクトのルール（たとえば、外部リンクは新しいタブで開く、テーマ切り替えはライトとダークのみ、同じ行に並ぶカードの高さはそろえる）を確認します。そして、この計画書の画面が従うべきルールを、Design decisions の1行にまとめます。計画中にユーザーが示したルールがまだどのファイルにも記録されていない場合も、その行に new と明記して含め、DESIGN.md に反映できるようにします。視覚的な参考資料（モックアップのパス、課題への添付資料、参考サイトなど）を指定し、計画中にユーザーに承認を求めます。承認は日付を添えて Design decisions の行に記録します。参考資料がまだない場合は、視覚的な選択を人が関わるフェーズとして最初に配置します。

Grilled: スタンプが古くなった場合

このスタンプは、グリル時点での計画書を保証します。重要な編集とは、確定済みのデザイン上の決定の追加、削除、変更、フェーズの追加、削除、対象範囲の変更、Done when: の確認可能な内容の変更、または非目標や移行セクションの変更を指します。重要な編集を行う人は、同じ編集内で Grilled: の行を削除します。これにより、grillkit が再度実行されるまで、計画書は未グリルとして扱われます。文言の修正、以下のフェーズ見出しへの注記、更新日の行、新しい未解決の質問は重要な編集ではないため、スタンプはそのまま残します。

フェーズ見出しの注釈欄

フェーズ見出しには任意の注釈が末尾に付き、後続のスキルがその欄に書き込みます。 plankit はプレーンな見出し（### Phase 2: auth）を書き、自身では注釈を付けません。作成したばかりの計画は、まだ課題として登録も実装もされていないためです。この欄では、2 種類の表記が共存します。

• (#41)：issuekit がそのフェーズを課題として登録するときに記入します。フェーズの追跡先を示します。
• (built YYYY-MM-DD)：implementkit がそのフェーズの実装を終えたときに記入します。フェーズが完了したことを示します。

この 2 つは共存できるため、### Phase 2: auth (#41) (built 2026-08-20) は、追跡され、リリース済みのフェーズを表します。両方を同じ欄に保つことで、読者や調査ツールは、参照する課題管理ツールがなくても、計画だけを見て「この計画には何が残っているか？」に答えられます。課題を登録しないプロジェクトでこの質問に答えるには、これしかありません。

スタンプを付けるかどうかは、計画ごとに選べます。 どこにも注釈のない計画は、それ自体について何も主張していないため、フェーズが未実装だと読み取ってはいけません。これにより、移行なしでこの規約を導入できます。導入前に書かれた計画は、注釈なしのままで正しい状態を保ち、何かが初めてスタンプを付けたときに、計画が主張を始めます。

見出しは柔軟に判定してください。 フェーズ見出しは Phase <n> で始まりますが、その後に続く区切り文字は実際の計画セットによって異なるため、こうした見出しを読み取るものは、コロン、ダッシュ、または区切り文字なしを受け入れてください。

注意事項

• 計画のみ。 アプリケーションコードも課題も対象外です。これらは別の手順（implementkit、issuekit）です。plankit は引き継ぎを行いますが、その範囲には踏み込みません。
• 誠実に、セクションは最小限に。 内容を水増しするより、短く明快な計画を優先してください。埋め草を書くくらいなら、セクションを削除してください。実際の作業範囲に合わせて文書の規模を調整してください。
• 質問攻めは後回しに。 未解決の質問を残しても問題ありませんし、それが想定されています。まとまりのある計画を作成し、grillkit に補強してもらいましょう。両方を同時に行おうとしないでください。
• リポジトリの規約に従ってください。 コードベースに独自の計画／RFC／PRD の保存場所やテンプレートがある場合は、それに従い、docs/plans を無理に使うのではなく、その旨を伝えてください。
• ファイルシステムやシェルを使えない場合（例：ブラウザー上で動作するエージェント）は、ファイルを書き込めません。その場合は、完成した計画文書をコードブロックで出力し、ユーザーが計画を保存している場所に保存できるよう、正式なファイル名 NNNN-plan-<slug>-YYYY-MM-DD.md を伝えてください。ユーザーの計画一覧を確認できない場合は、0001 を使ってください。