plan-build-verify

計画・実装・検証

実装作業は、仕様の信頼できる情報源をGitHub Issueとする順次のプロセスに沿って進めます。ロードマップは、補助モードのTriageとMigrateで管理します。

最初に規約を読む

どのモードを使う場合も、最初にreferences/conventions.mdを最後まで読んでください。このファイルでは、リポジトリの事前確認、ラベル分類、Issue本文のテンプレート、ステータスの遷移、サブIssueの仕組み、Issueの依存関係、一時的な本文ファイル、およびこのパックのpstackやその他のスキルとの共存について定義しています。その他のすべてのリファレンスファイルは、このファイルを前提としています。

pstackやこのパックの他のスキルとの共存

仕様、優先順位、およびPlan / Build / Verifyのライフサイクルの信頼できる情報源は、引き続きGitHub Issueです。GitHub Issueを使う製品リポジトリ（devbox、kata-code、kata-agents、kata-symphony）では、plan-build-verifyだけを製品OSとして使います。

スキル／レイヤー	役割	対象外
plan-build-verify	唯一の製品OS：仕様、優先順位、Plan / Build / Verify、ラベル	BuildまたはVerifyの実行中における実装手法
pstack（Cursorプラグイン）	BuildとVerifyでのエンジニアリング実行と証明、Planでの調査（architect / how / why）	計画、ラベル、承認、または別のIssueライフサイクル
ps（このパック内の/ps）	pstackの過去の移植版。扱いにくいため、製品のデリバリーにはインストールしないでください	pstackプラグインの代替、または別の製品OS
okf／finalizeのOKFステップ	**廃止済みです。**履歴のためだけにライブラリに残っています	現行のロードマップ、または仕様としてのドキュメントを扱うワークフロー
kata-linear	Linearを優先するリポジトリのみ	これら4つのGitHub Issueを使う製品リポジトリ

ルール：

• 「最良の仕様はコードだ」という理由で、未承認のIssueを飛ばさないでください。
• 製品開発に関わる作業では、Plan中のarchitectチェックポイントは調査のみを目的とします。pstackの「人間による承認で決して作業を止めない」という方針を、未承認の仕様を超えて実装を進める許可と見なさないでください。
• リポジトリごとのverify-*スキル（スラッシュ形式は/verify-<app>。通常は.cursor/skills/verify-*/内にあります）とその機能マップは、Issueの## Demonstration／## Verificationを補完するものです。受け入れ基準の代わりにはなりません。Verifyでは、同梱のUATプレイブックだけに頼る前に、/verify-*を探して従ってください。Verifyの途中でこれを生成しないでください。
• 2つ目のIssueトラッカーや、ファイルベースの仕様を独自に作らないでください。references/conventions.mdに記載されたPBV移行インデックス／アーカイブを除き、docs/specs/に製品仕様を作成または維持しないでください。
• okf init、okf update、またはfinalizeのOKFステップを実行しないでください。OKFは廃止済みであり、別のロードマップとして使うものではありません。
• これらの製品リポジトリにps、okf、またはkata-linearをインストールしないでください。scripts/install-skills.sh（またはreferences/conventions.mdに記載されたnpxコマンド）を使って、プロジェクトローカルのスキルをインストールしてください。npx skills add -gは実行せず、gannonh/skillsパック全体もインストールしないでください。

フェーズの契約

フェーズ	入力	出力	ステータスラベルの遷移
計画	アイデア、漠然とした依頼、または新規ビルドの依頼	コンテキストの調査 → 認識合わせの対話 → アプローチの承認 → 必須の ## Acceptance criteria を含む、垂直スライスされた仕様イシュー	なし → status:draft → status:approved
ビルド	承認済みの仕様イシュー番号、またはユーザーによる明示的な上書き	実装済みのタスク、コミット、レビュー結果、プッシュ済みブランチ、ビルド完了レポートのコメント	status:approved → status:implemented
検証	実装済みの仕様イシューと完了した作業、またはビルドレポート	受け入れの証拠、永続的な受け入れテスト、プルリクエスト、CI の成功、解決済みのレビューコメント、承認の推奨	status:implemented → status:verified
トリアージ	リポジトリのイシューバックログ	整理レポートと、適用したラベル付け、分解、クローズの対応	イシューごとの是正措置
移行	既存の docs/specs/*.md バンドル	評価レポート、仕様イシュー、アーカイブ済みのローカルファイル、書き換えられた相互リンク、更新済みの仕様インデックス	各ファイルに宣言されたステータスから決定

ワークフローを選択する

ユーザーが既存の課題の実行、完了した作業の検証、バックログの整理、または仕様の移行を明示的に指示していない限り、デフォルトで Plan を選択します。新しい構築依頼は、ユーザーが「構築して」と言った場合でも、Plan から開始します。

モード	参照	開始するタイミング
Plan	references/plan.md	作業の範囲設定、設計、仕様策定を行う場合、または依頼に該当する status:approved の課題がない場合。
Build	references/build.md	名前が指定された、承認済みの仕様課題を実行する場合。
Verify	references/verify.md	完了した作業が課題の受け入れ基準を満たしていることを証明する場合。
Triage	references/triage.md	バックログを整理する場合、または「次に何に取り組むべきか」に回答する場合。
Migrate	references/migration.md	docs/specs/*.md を課題に変換する場合。まず評価し、一方向に進めます。

references/conventions.md を読み、続けて選択した参照ファイルを最後まで読み、両方に従ってください。必要なワークフローだけを読み込んでください。

Build と Verify は連続した一連の実行です。 Build は、Verify を実行するかどうかを尋ねて停止しません。直接 Verify に進みます。Verify は、根拠の提示、受け入れテスト、PR の作成、CI の収束まで、人手を介さずに実行し、サインオフの段階でのみ停止します。自律性に関する契約については references/verify.md を参照してください。

必ず守るべきゲート：

• ユーザーが承認ゲートを明示的に上書きしない限り、Build は status:draft の課題から開始してはいけません。
• 根拠なしに Verify でサインオフを宣言してはいけません。
• Verify は PR を決してマージしてはいけません。サインオフとマージはユーザーが決定します。
• PR を作成するのは Build ではなく Verify です。PR の本文には受け入れ基準のマトリックスを記載します。
• Plan では、ユーザーが方向性に関する確認質問に回答するか、推奨する方針を承認するまでは、仕様課題の草案を作成してはいけません。作成しようとしている場合は、停止して質問してください。
• Migration は、まず評価を行います。書き込みを行う前に scripts/migrate_specs.sh --assess を実行し、分類されていないファイルや競合するファイルをすべてユーザーと確認してください。

コピーの変更や設定の単一項目の調整など、小さく明確に範囲が限定された編集では、Plan の全ワークフローを強制せず、課題も作成しないでください。前提を伝え、ユーザーに全プロセスを希望するか尋ねてください。モードが明確でない場合は、判断に必要な点を絞った質問を一つしてください。

同梱されているフェーズ別リファレンス

Build と Verify は、このスキルディレクトリに同梱されたワークフローを読み込みます。エントリーポイントを最後まで読み、同じサブツリー内のリンク先ファイルやスクリプトにも従ってください。

フェーズ	ワークフロー	エントリーポイント
Build	TDD	references/tdd/workflow.md
Verify	ユーザー受け入れ	プロジェクト内に verify-* があればそれを使用し、なければ references/user-acceptance/workflow.md を使用します。

Verify の収束ループ（ステップ 7）では、gh pr checks --watch と gh run を直接実行して CI を進めます。レビューのスレッドには、インストール済みスキルのディレクトリ内にある、次の関連スキルを使用します。

目的	スキル	エントリーポイント
レビュースレッドの一覧確認と修正	address-pr-comments	<path-to-skills-directory>/address-pr-comments/SKILL.md

インストールされていない場合、Verify は gh api graphql でスレッドを読み取ります。ループの実行にこのスキルは必要ありません。

ヘルパースクリプト

• scripts/ensure_labels.sh：このスキルのラベル分類を冪等に作成します。--dry-run を指定すると、変更内容を報告します。
• scripts/install-skills.sh：plan-build-verify と address-pr-comments のみを、プロジェクト内に非対話形式でインストールします。製品リポジトリではコピーして使用できます。-g は使用せず、ps、okf、kata-linear はインストールしません。
• scripts/migrate_specs.sh：docs/specs/*.md を一括で仕様イシューに変換し、元ファイルをアーカイブし、相互リンクを書き換え、仕様インデックスを更新します。--assess、次に --dry-run を実行してから、変更を適用してください。
• scripts/rewrite_spec_links.py：ファイルをアーカイブに移動した後、Markdown リンクの参照先を書き換えます。移行スクリプトから呼び出されます。python3 が必要です。

スクリプトのパスは、実行環境が実際に読み込んだスキルディレクトリを基準に解決してください。設定されたスキルパスが存在しない場合は、処理を中止し、どのインストール先を使用するか尋ねてください。パスを解決するために、スキルファイルをプロジェクトの作業ツリーにコピーしてはいけません。

要件

• gh CLI。対象リポジトリへのイシュー書き込み権限で認証済みであること。
• 分解した仕様には gh sub-issue 拡張機能（yahsan2/gh-sub-issue）が必要です。存在しない場合は、gh extension install yahsan2/gh-sub-issue でインストールするか、references/conventions.md のタスクリストによる代替手段を使用してください。この拡張機能の create サブコマンドには --body-file がないため、子イシューは gh issue create で作成し、その後 gh sub-issue add で親イシューに追加します。
• イシューの依存関係に対応したバージョンの gh（gh issue edit --add-blocked-by）。標準機能のため、拡張機能は不要です。
• ロードマップを所有する GitHub リポジトリを指す Git リモート。
• gh sub-issue list --json の出力を読み取るための jq。拡張機能自体には -q フラグがありません。
• 移行中のリンク書き換えにのみ使用する python3。

セッションで初めて gh に書き込む前に、references/conventions.md の事前確認を実行してください。gh が利用できない、または認証されていない場合は、処理を中止してユーザーに伝えてください。仕様ファイルをローカルに書き込む方法に切り替えてはいけません。

共通原則

• プロジェクトの構成、コマンド、既存の作業について述べる前に、リポジトリとイシューバックログを調査してください。
• 複数の手順がある作業では、ToDo リストを使用してください。
• Plan では、イシューを作成する前に、焦点を絞った確認質問を一度に1つずつ尋ねてください。事実関係の確認が不要な場合は、状況の捉え方、前提、受け入れ基準をユーザーに確認してください。
• Plan では、実行可能な方向性が複数ある場合、2～3つのアプローチを提示してください。明らかに最適なものが1つある場合は、推奨案を示し、承認または別案の提示を待ってください。
• 広範で未検証の変更よりも、ユーザーが確認、使用、評価できる、最小限のエンドツーエンドの単位を優先してください。ここでの「ユーザー」には、人間、オペレーター、API/SDK の利用者が含まれます。
• エピックは、アーキテクチャのレイヤー、コンポーネント、チームではなく、実証可能な動作に基づいて分解してください。1つの薄い垂直スライスで横断できる場合に、ストレージ、バックエンド、プロトコル、フロントエンド、テストを別々のロードマップフェーズにしてはいけません。
• 安全なエンドツーエンドのスライスを実現するために不可欠な場合に限り、技術的な基盤整備の子イシューを設けてください。内容は最小限にし、最初のスライスに統合できない理由と、それによって直ちに可能になるユーザー向けスライスを明記してください。
• ユーザー向けの各スライスには、パブリック境界での E2E テストの合格を必須とし、ビジュアルを対象とする場合は、開始時と終了時に必要なスクリーンショットを用意してください。
• 動画は理想的な時間的証拠として扱いますが、無制限のゲートにはしないでください。録画を1回だけ試み、引き続き利用できない場合はスキップし、環境またはツールの不足を明示してください。
• スコープは、選択したイシューとその受け入れ基準に沿わせてください。
• 仕様イシューには、Build が実装でき、Verify がテストできる、観測可能な合否基準を定めた、正確な ## Acceptance criteria セクションが必要です。これがない仕様イシューは不完全です。
• イシューが仕様書です。ローカルの Markdown は一時的な本文ファイルとしてのみ存在し、gh への書き込みが成功した後に削除します。
• フェーズが移行するたびに、イシューの status:* ラベルを更新してください。ラベルが実際の状態と一致しないイシューは、トリアージ上の不備です。
• 不確実な点は、推測で補わずに明示してください。