mstack-plan

mstack plan

承認済みの仕様を、新しいセッションでエージェントがタスクごとに実行できる実装計画に変換します。成果物は計画です。実装は決して行いません。

ここで優れた計画には、5つの特性があります。仕様のすべての要件がタスクに対応していること。各タスクが新しいエージェントの1セッションで完了でき、最初に失敗するテストで妥当性を確認できること。各タスクで、その作業に役立つスキルだけが指定されていること。別のベンダーのモデルが計画をレビューしていること。そして、計画に進捗ファイルと開始プロンプトが含まれており、インライン実行や mstack のレビューワークフローで計画を引き継ぎ、再開できることです。

ホストツール

このスキルは Claude Code と Codex で動作します。ここではツールではなく、役割を示しています。

役割	Claude Code	Codex
質問ツール	AskUserQuestion	チャットで番号付きの質問をして、返信を待つ
サブエージェントツール	Agent	セッションにエージェントツールがあればそれを使用し、なければ読み取り専用の別の codex exec 実行を使用する
スキルの読み込み	Skill ツール	スキルの SKILL.md を読み、その指示に従う
スキルフォルダー	このスキルの読み込み時に表示されるベースディレクトリ	この SKILL.md があるフォルダー
ベンダー横断レビュアー	skill-codex の codex スキルを介した Codex	agent-bridges の claude-review スキルを介した Claude
スクリプト用の <host>	claude	codex

サブエージェントツールがない場合は、委任するステップを自分で実行し、その旨を伝えてください。

このスキルのファイル

ファイル	使用するタイミング
references/plan-format.md	フェーズ3と5。計画のファイル構成、フィールド、状態、再開ルール。mstack のレビューワークフローにも同じファイルが含まれています
references/skill-matching.md	フェーズ4
references/plan-review.md	フェーズ7
references/receiving-review.md	フェーズ7、および実行担当者向けに各計画フォルダーにコピー。mstack のレビューワークフローにも同じファイルが含まれています
references/execute-plan-template.md	フェーズ5
scripts/check-required-skills.sh	事前確認
scripts/check-plan.mjs	フェーズ6と7

基本ルール

1. 計画を立て、実装しない。 計画フォルダー内にのみ書き込みます。リポジトリのコードは変更せず、ユーザーから依頼されない限りコミットやプッシュもしません。
2. 仕様を拘束力のある基準とする。 計画は仕様に基づいて作成します。未決定であることが判明した要件は、推測で計画に書かず、仕様に差し戻します（mstack-write-specs）。
3. 事実は自分で確認し、決定はユーザーに委ねる。 リポジトリ、そのドキュメント、ユーザーが提示した情報源から事実をすべて確認し、出典を記載します。ユーザーには決定事項のみを、各項目に推奨案を添えて尋ねます。
4. テストを先に書く。 動作を変更する各タスクは、失敗するテスト、その失敗を示す実行、最小限のコード、成功を示す実行、そしてテストが引き続き失敗し得ることの確認を、順に記述します。動作をテストできる対象がない作業だけは例外とし、その理由を記載します。
5. レビューは必ず実施する。 ベンダー横断レビュアーは承認前にすべての計画を読みます。レビューを行うかどうかをユーザーに尋ねてはいけません。
6. 承認とは、書面の計画に対する明確な「はい」である。 概要への同意、以前の「書いておいて」という指示、沈黙、レビュアーの判定は承認ではありません。承認後に編集した場合、計画の状態を「Draft」に戻します。
7. 秘密情報を含めない。 外部の情報源はリンクまたは名称で引用します。認証情報、トークン、個人データを情報源から計画に転記してはいけません。

0. 開始

ほかの作業に取りかかる前に、ユーザーの目標を一文で言い換えたメッセージを1つ送り、質問ツールを使って次の質問をまとめて尋ねます。依頼ですでに回答されている質問は省略してください。

1. 計画書の保存先はどこにしますか？ 次の順で提案します。計画書専用のフォルダーに仕様書がすでに置かれている場合はそのフォルダー、リポジトリに既存の計画書フォルダーがある場合はそのフォルダー（docs/plans/、plans/、docs/specs/ を確認）、それ以外は docs/plans/<yyyy-mm-dd>-<slug>/。任意のパスを指定できます。
2. どの仕様書を使いますか？ 依頼で仕様書が指定されていない場合に限ります。見つかった仕様書（rg -l --glob '*.md' '^### R1\b'、docs/specs/）を新しい順に提示します。
3. リポジトリ外の情報源はありますか？ リンク、Wiki ページ、デザインファイル、課題管理ツールのチケット、API やベンダーのドキュメント、過去の決定事項など、計画書で参照すべきリポジトリ外の情報があるか尋ねます。仕様書の Source 行とリポジトリ内のドキュメントで作業内容がすでに網羅されている場合に限り、「なし」を提案します。
4. レビュアーモデルと処理レベルはどれにしますか？ Claude Code の場合は Codex モデル（gpt-6.1-sol を推奨、代替は gpt-6-astra）と処理レベル（high、次に medium、xhigh、max の順に推奨）。Codex の場合は Claude モデル（opus を推奨、代替は sonnet）と処理レベル（medium、次に high、low の順に推奨）。ユーザーが入力するほかの名称も受け付けます。

フォルダーにすでに計画書（plan.md と progress.md）がある場合は、両方を読んでそこから再開します。Draft の計画書は、このスキルの最初の未完了フェーズから続行します。Approved の計画書は、ユーザーが変更を依頼しない限り、そのまま維持します。変更を加えた場合は Draft に戻します。タスクがすでに In progress または Closed の計画書は実行中のため、Open のタスクのみ変更し、その理由を記録します。

事前確認

bash <skill-folder>/scripts/check-required-skills.sh --host <host>

node、git、ベンダー横断レビュアーを確認し、推奨される mstack スキルを示します。また、レビュアーのスキルがこのセッションのスキル一覧にあることも確認してください。セッション中にインストールしたスキルは、新しいセッションでのみ読み込まれます。

必須項目がない場合は、何が不足しているかをユーザーに伝え、今すぐインストールするかどうかと、その方法を尋ねます。方法については references/skill-matching.md › 5 に記載された、経路、対象範囲、手段、エージェントに関する質問を行います。インストールによってサードパーティのコードが実行されるため、実行するかどうかはユーザーが決めます。インストールを断った場合も、references/plan-review.md › 実行に失敗した場合に記載されたフォールバックを使って計画書をレビューし、その旨を計画書に記載します。

不足項目	インストール方法
skill-codex の codex スキル（Claude Code）	プラグイン：claude plugin marketplace add skills-directory/skill-codex を実行し、続けて claude plugin install skill-codex@skill-codex を実行します。Skills CLI：ソースに skills-directory/skill-codex、スキルに codex を指定します
codex CLI（Claude Code）	npm install -g @openai/codex を実行し、続けて codex login を実行します
agent-bridges の claude プラグイン（Codex）	プラグインのみ：codex plugin marketplace add https://github.com/mubeda/agent-bridges.git を実行し、続けて codex plugin add claude@agent-bridges を実行します。このスキルはプラグインのルートにあるスクリプトを実行するため、Skills CLI ではインストールされません
claude CLI（Codex）	npm install -g @anthropic-ai/claude-code を実行し、続けて claude auth login を実行します
mstack スキル	Claude Code のプラグイン：claude plugin marketplace add mubeda/mstack を実行し、続けて claude plugin install <name>@mstack を実行します。Codex のプラグイン：codex plugin marketplace add mubeda/mstack を実行し、続けて codex plugin add <name>@mstack を実行します。Skills CLI：ソースに mubeda/mstack、スキルに <name> を指定します
node	https://nodejs.org またはシステムのパッケージマネージャー

1. 現状を把握する

質問する前に読みましょう。広範な検索はサブエージェントのツールに任せ、ファイル一式ではなく、ファイルの場所と短い抜粋を求めてください。

1. 仕様書。 最初から最後まで読みます。計画フォルダーの外にある場合は、<plan-folder>/spec.md にコピーし、元のパスを plan.md › Sources に記録します。ステータスが Draft の場合はユーザーに伝え、まず mstack-write-specs で仕上げるよう勧めます。ユーザーが明示的に同意した場合に限り Draft をもとに計画を立て、そのことを記録します。仕様書がない場合は、保存先を <plan-folder>/spec.md に設定して mstack-write-specs を使うよう勧め、仕様書ができるまで作業を止めます。変更対象のファイルが1つか2つで、方法も明らかな場合は、計画は不要だと伝え、ユーザーがそれでも計画を希望する場合を除いて作業を止めます。
2. リポジトリのルール。 該当するすべての AGENTS.md、CLAUDE.md、CONTRIBUTING、README を読みます。仕様書と同様に、計画を拘束します。
3. ドキュメント。 リポジトリ内のドキュメントを見つけ、この計画で使うべきものを判断します。
   • docs/、doc/、documentation/、adr/、adrs/、decisions/、rfcs/、design/、architecture*、specs/、plans/、wiki/、ドキュメントの索引、ルールファイルや README が示すすべてのパスを調べます。
   • 仕様書にある名詞、つまり要件名、コンポーネント、エンティティ、エンドポイント、画面を対象に、大文字と小文字を区別せず検索します。該当が1件でもあれば、そのファイルを読みます。
   • 作業を制約する、または説明する各ドキュメントを、そのパスと重要な理由を示す1行とともに記録します。リポジトリ内の以前の計画や仕様書から、慣例を把握します。
   • 関連する各ドキュメントを plan.md › Sources に記載し、影響を受ける各フェーズとタスクの「Read first」にも記載します。
4. 外部ソース。 ユーザーが提示した各ソースを、セッションで利用できるツール（ウェブ取得、接続済みツール、gh）を使って読みます。計画に関係する内容だけを残し、出典を記載します。ログインが必要、コネクターがないなどの理由でソースにアクセスできない場合は、関係する箇所を貼り付けるようユーザーに依頼し、貼り付けられるまで「not reachable: 」と記録します。
5. コード。 エントリーポイント、慣例、テストの構成、仕様書で変更対象となる既存ファイルをすべて把握します。ビルド、テスト、リンター、フォーマッターのコマンドは CI 設定、Makefile、パッケージマニフェスト、またはリポジトリのルールから確認し、テストコマンドを一度実行して動作を確かめます。サービスが必要な場合や非常に時間がかかる場合は実行を省略し、その旨を伝えます。
6. インストール済みスキル。 質問に影響するため、今すぐ references/skill-matching.md › 1 から一覧の確認を始めます。

2. 質問

仕様書ではなく、計画について質問します。作るものは仕様書で決まっています。納品の順序、プルリクエストを1つにするか複数にするか、仕様書に指定のない場合のテスト水準、移行とロールアウトの順序、スタブ化できるもの、再利用または置き換える既存コードなど、仕様書で決まっていない事項だけを尋ねます。

1. 未決定事項をツリーとして整理します。最前線にあるのは、前提条件がすべて確定している判断事項です。最前線にある事項は、番号付きの1回の質問ラウンドですべて尋ねます。1問ずつ尋ねたり、すべてを一度に尋ねたりしてはいけません。別の未決定事項に依存する質問は、次のラウンドまで待ちます。
2. 事実は自分で確認し、質問しません。各質問の本文では、その判断の根拠となるドキュメント、ソース、またはファイルを示します。
3. 「はい」と答えると推奨案を受け入れることになるように質問し、番号で回答できるようにします。各項目には質問、アルファベット付き選択肢の短い背景説明、推奨案とその理由を示す最後の文を含めます。
4. 回答のたびに最前線を再計算します。最前線が空になったら、合意内容を数行で言い換え、ユーザーの確認を待ちます。
5. 要件そのもの（システムが何をすべきか）に関する質問は、仕様書の不足です。その不足を明示し、mstack-write-specs で仕様書を更新するよう勧め、決着するまでその部分の計画を立てません。
6. すべての決定事項と、質問を解決したすべての事実を plan.md › Appendix: questions record に記録します。

3. 分解

references/plan-format.md に従います。

1. タスクの規模。 タスクとは、独自のテストサイクルを持ち、それ単独で検証できる結果に至り、1回の新しいエージェントセッションに収まり、独立してレビューする価値がある最小単位です。つまり、レビュー担当者は隣のタスクを承認しつつ、そのタスクを却下できる必要があります。セットアップ、設定、ドキュメントは、それらを必要とするタスクに組み込みます。レイヤーごと、時間ごと、ステップ数ごと、あるいは目標に「and」という単語があるからという理由で分割してはいけません。対象の振る舞いに必要なすべてのレイヤーを通る垂直スライスに分割します。
2. フェーズ。 フェーズは、ユーザーが確認できるチェックポイントを備えた1つの成果にタスクをまとめます。簡単な変更ならフェーズは1つです。それ以外の場合は、次の順にフェーズを並べます。変更を容易にするプレファクタリング、その他すべてが必要とする基盤、仕様の優先順位順にユーザーストーリーごとのフェーズ、残作業がある場合に限り仕上げ。
3. 広範な変更。 まず拡張し（新しい形式を古い形式の隣に追加）、呼び出し元をまとめて移行し、その後、縮小します（古い形式を削除）。縮小するタスクは、すべての移行バッチに依存させます。
4. 依存関係。 各タスクの Interfaces には、正確な名前とシグネチャを用いて、消費するものと生成するものを記載します。フェーズは依存関係に基づいてラウンドにまとめます。同じラウンドのフェーズは、担当するファイル、ビルド出力、フィクスチャ、共有型が重複しないようにするか、順序付けます。共有される競合頻度の高いファイル（ロックファイル、変更履歴、ドキュメントのインデックス、progress.md）は、実行担当者用に確保します。
5. ファイルマップとトレーサビリティ。 すべてのファイルと外部変更は、担当フェーズを1つだけ割り当てます。既存のすべてのパスを確認します。各要件を少なくとも1つのタスクに対応付け、Review の各注目項目を、名前を示したタスク内のテストで押さえます。
6. レッド・グリーン。 仕様内の GIVEN／WHEN／THEN シナリオはそれぞれ、仕様と完全に同じ値を用いたテストステップにします。各否定シナリオは、起きてはならないことを証明するテストにします。references/plan-format.md のステップパターンを使用します。
7. ティア。 各タスクにモデルティアを割り当てます。固定コマンドまたは完全に指定された編集には cheap、十分に仕様化されたコードには standard、セキュリティ、保存データ、並行処理、または計画で判断が委ねられている設計には most capable を選びます。

完全なファイルを作成する前に、まず概要をユーザーに提示します。ラウンドを付けたフェーズの番号付きリストを示し、各フェーズの下に、タイトル、Satisfies、Depends on を含むタスクを記載し、簡潔なファイルマップも添えます。粒度が適切か、各依存関係に根拠があるか、何かを統合または分割すべきかを尋ねます。問題がなければ承認を推奨します。ユーザーが概要を承認するまで修正を続けます。

4. スキル

references/skill-matching.md に従います。各フェーズとタスクで使用するスキルを明記します。適合する場合は、mstack と agent-bridges のスキルを優先します。オンライン検索は実際に不足している情報がある場合に限り、候補を精査したうえで、インストールするかどうかをユーザーに一度にまとめて尋ねます。自分でインストールしてはいけません。

5. 計画を書く

references/plan-format.md › Folder layout に従い、すべてのフィールドを埋めて全ファイルを作成します。references/execute-plan-template.md を execute-plan.md にコピーし、推奨モードとその理由を含めて記入します。references/receiving-review.md は変更せずに計画フォルダーへコピーします。実行担当者がレビューをこれに従って処理します。progress.md を作成し、すべてのタスクを Open、Executor: none とし、spec.md の SHA-256 の先頭12桁の16進数を記載します（sha256sum または shasum -a 256）。

計画は適切な分量に保ちます。ステップには、コード全体ではなく、正確なシグネチャ、値、コマンドを記載します。仕様より何倍も長い計画や、説明対象のコードより長い計画は、計画ではなくコードを書いてしまっています。

6. チェック

1. node <skill-folder>/scripts/check-plan.mjs <plan-folder> を実行し、出力された行をすべて修正します。
2. 次に、スクリプトでは確認できない点について、プランを読み返して確認します。各ステップで何をするかが決まっていること（「TBD」や「エッジケースに対応する」などがないこと）、タスク間で名称とシグネチャが一致していること、各フェーズファイルが、そのファイルとプランのヘッダーだけを読んだ人でも実行できること、Read の最初の項目が存在することを確認します。Review focus が記入されているか、空である理由が記載されていることも確認します。
3. 3回の確認を終えたら停止し、まだ不備が残っていればユーザーに伝えます。

7. ベンダー横断レビュー

references/plan-review.md に従い、references/receiving-review.md の手順でレビューに対応します。他ベンダーのモデルが、読み取り専用でプランフォルダー全体をレビューします。このフェーズではユーザーに確認を求めません。すべての指摘を検証し、事実誤認を修正し、誤りやすでに決定済みの内容に反する指摘は却下し、設計変更は承認サマリーに回し、各指摘への対応を reviews/plan-review-<n>.md に記録します。レビューは最大2回までです。

8. 承認

プランフォルダーのパス、5行のサマリー（目標、フェーズとラウンド数、タスク数、レビューの判定、未解決の課題）、およびレビューで適用しなかった指摘をユーザーに提示します。承認を求める各指摘には推奨案を添え、すでに決定済みの内容に反するため却下した指摘もそれぞれ示します。そのうえで、書面化されたプランへの明示的な承認と、適用を希望する指摘があればその内容を確認します。承認されたら、plan.md の Status: Approved <yyyy-mm-dd> (approved in chat by the user) と progress.md の Plan status: Approved <yyyy-mm-dd> を設定し、check-plan.mjs をもう一度実行します。それ以降に編集した場合は、両方を Draft に戻します。

9. 引き継ぎ

次の順で報告します。

1. 目標と成果を1行で示し、プランフォルダーのパスを記載します。
2. フェーズとラウンドを小さな依存関係グラフで示し、タスク数を記載します。
3. フェーズごとに指定されたスキル、ユーザーが承認したインストール、残っている課題を記載します。
4. レビューについて、レビュアー、モデル、判定、修正済み・保留・却下の指摘を報告します。
5. 開始方法として、「リポジトリで新しいセッションを開き、<plan-folder>/execute-plan.md を実行して、と伝えてください。」と案内します。このファイルでは、まずインラインで実行するか、そのホスト向けの mstack レビューワークフローを使うかを確認し、どちらか一方を推奨します。どちらを推奨するか、その理由も説明します。

ユーザーから依頼されない限り、このセッションでは実行を開始しません。新しいセッションはコンテキストがクリアされ、プランだけを記憶した状態で始まります。このプランはその状態で使うことを想定して作成されています。