visual-plan

エージェントネイティブなプラン

Agent-Native Plans は、コーディングエージェント向けの構造化されたビジュアルプランニングモードです。通常 Markdown で作成するプランを、スキャンしやすいドキュメントとして作成できます。編集可能なブロックとして、インライン図、コードスニペット、未解決の質問を組み合わせられます。また、最上部にビジュアルレビュー領域（ワイヤーフレームキャンバス、ライブプロトタイプ、またはタブで切り替える両方）を任意で設けられます。アーキテクチャやバックエンドのプランはドキュメントのみで構成されます。UIやプロダクトのプランは最上部のキャンバス／プロトタイプから始めます（このルールは Visual Surface Choice セクションで定めています）。

/visual-plan はパッケージ化されたコマンドであり、主なエントリーポイントです。タスクに応じてレビュー方式を選択します。作業の中心がプロダクト UI で、画面からレビューを始める場合は UI-first、機能するライブプロトタイプからレビューを始める場合は prototype-first、ブランドを反映した高忠実度の画面でレビューする必要がある場合は design-first、計画の前にユーザーが明示的に質問票を希望する場合は visual-intake を選びます。Codex、Claude Code、Markdown、または貼り付けたプランがすでにある場合、/visual-plan はそのプランを出発点として、最初からやり直すのではなく、それをもとにレビュー用の画面を作成します。

使用するタイミング

チャットの段落よりもレビュー可能な成果物にするほうがよい場合は、いつでもビジュアルプランを作成または調整します。これには、状態を含む単一の UI 画面、小規模なワークフロー、プロダクトの変更前後の比較、認識合わせが必要なコンポーネント／API／データ構造の決定といった比較的小さな作業に加え、複数ファイルにまたがる作業、曖昧な作業、長期にわたる作業、リスクの高い作業、UI の比重が大きい作業も含まれます。アーキテクチャ／データフロー／UI の方向性／選択肢／未解決の質問をインライン図や構造化ブロックで示すと有益な場合、実装の前にユーザーが方向性を確認する必要がある場合、または既存のテキストプランにより充実したレビュー用の画面が必要な場合に使用します。

プランの作成方針

• 慎重にゲートを設けます。 ビジュアルプランは、巨大なプロジェクトだけに使うツールではなく、より充実したレビューの場です。コードを書く前に、ユーザーが方針を確認、比較、コメント、承認する必要がある場合は、小規模な UI、状態、ワークフローの変更であっても使います。明白で本当に些細な作業――誤字、1 行の修正、仕様が明確な単一の関数、差分を 1 文で説明できるもの――では省略し、そのまま変更します。プランを水増ししてはならず、1 ステップだけのプランを作成してはなりません。
• 下書きの前に調査します。 実際のファイル、アクション、スキーマ、パターンを先に確認し、架空のものではなく、実在するファイル、シンボル、データ形状を挙げます。エンドポイントを提案する前に既存の actions/ を確認し、生の fetch より名前付きのクライアントヘルパーを優先します。広範な調査はサブエージェントに委任します。まず再利用を検討します。各ステップでは、追加する内容より先に、再利用するもの（既存のアクション、スキーマ、コンポーネント、ヘルパー）を挙げ、既存の内容を言い換えるのではなく、本当に新たに加わる部分をプランで説明します。
• 後戻りしにくい判断を先に決めます。 重要度の高いバックエンド、データ、API の作業では、機能の目指す方向を概説したうえで、データや呼び出し元に依存されるようになると変更にコストがかかる判断（ワイヤ形式、公開 ID、データモデルの形状、認証と所有権の境界）を挙げ、機能の大部分が後回しになる場合でも、プランの段階で正しく決めます。そのうえで、方向性を損なわずにアプローチを検証できる最小限の初回実装に範囲を絞り、含める内容と、明確に先送りする内容の両方を示します。
• 例は適切な抽象度で扱います。 ユーザーのアイデアが、広範なフレームワーク、製品、運用モデルの変更である場合、最初に挙げられた具体例、プロバイダー、同期経路だけに縮小してはなりません。中核となる抽象概念と、動機となる例やアプリ／プロバイダー向けアダプターを分けます。例を使ってプランを分かりやすくしつつ、依頼の範囲全体を例が占めるのでない限り、例であることを明記します。
• 単独で理解できるプランを公開します。 ユーザーが Codex、Claude Code、Markdown のプランを貼り付けた、参照した、またはすでに用意している場合は、資料として扱います。ただし、公開するプランは独立した提案として書き直します。元のプランの有用な意図とコードベースに関する事実を保ち、推測したビジュアルには推測であることを明記し、「以前のプランを維持する」「古いアイデアを削除しない」「前のバージョンとは異なり」「今回の改訂で変更する」といった改訂を前提とする表現は避けます。チャットや以前の草案を見たことがない読者にも、プランが理解できるようにします。
• 最初に読んだときから具体的にします。 プランをチャット外の人と共有する場合、または構想が抽象的な場合は、モード表、アーキテクチャ、ロードマップより前の上部に、具体的な製品例を置きます。UI に対応する構想なら、通常は製品用語で実際のユーザーワークフローを示す、キャンバス上部のアプリ状態を使います。会話の中でしか通じない表現に頼らず、「以前のアイデアではない」という形でプランを説明せず、目指すモデルをそのまま述べます。
• プランニングは読み取り専用です。 プランの作成やレビュー中にソースコードを編集してはなりません。編集は、ユーザーが方針を承認してから開始します。
• 確認するか、前提を置くかを判断します。 作り方を尋ねてはなりません。アプローチや選択肢を調査し、プランで提示します。設計に影響する曖昧さがあり、コードから解決できない場合に限り、確認の質問をします。ホストエージェントの通常のユーザーへの質問フローを使い、最終化する前に影響の大きい質問を 2～4 個まとめて提示します。通常の確認や事前確認で create-visual-questions を呼び出してはなりません。ユーザーがビジュアルインテーク用の質問票を明示的に求めた場合に限り、ビジュアルインテークモードで使用します。それ以外の場合は、前提を明示して作業を進め、未解決事項はプラン下部にある単一の question-form「未解決の質問」ブロックにまとめます。複雑なプランでは、引き継ぎの前に未解決の質問を最終確認します。アーキテクチャ、範囲、UX、データ形状、ロールアウトに影響する判断は、根拠とともにプラン内で決定するか、推奨するデフォルトを添えてその下部のフォームに記載します。
• プランが承認の関門です。 プランを提示したら、コードを書く前にユーザーにレビューと承認を求め、作業が影響するファイルや領域を明示します。プランの提示と承認依頼が承認のステップです。「これでよさそうですか？」と別途尋ねてはなりません。
• 正本はチャットではなく文書です。 範囲が変わった場合は、チャット上だけで方針を変えるのではなく、update-visual-plan でプランを更新し、更新後の文書だけで内容が理解できるようにします。プラン内で、更新を以前の草案の修正として説明してはなりません。大きなステップに進む前に、承認済みのプランを読み直します。

構造化されたエージェントネイティブプランを作成する — インラインで提示しない

成果物は常に、チャット内だけのプランではなく、構造化されたエージェントネイティブプランです。 ホスト型 Plan MCP コネクター（plan サーバー、または旧称 agent-native-plans）は、コラボレーションとコメントのためのデフォルトの場です。外部依存やレンタルレイヤーであることを理由に、プランニングのパターンを拒否する必要はありません。プランは移植可能なソース成果物（plan.mdx、任意の canvas.mdx ／ prototype.mdx、JSON、HTML エクスポート）であり、所有権に配慮が必要なワークフローでは、スキルのレビュー規律を損なうことなく、ローカルファイルモードやセルフホスト／カスタムの Plan アプリ URL を利用できます。デフォルトの場がホスト型だからといって、ユーザーに /visual-plan を省略するよう勧めないでください。ユーザーの所有権、プライバシー、共有、ブランディングのニーズに応じて、適切な Plan モードを選択してください。

デフォルトでは、Plan MCP コネクターを使ってプランを作成し、インラインのチャットコンテンツとして提示してはなりません。Markdown の文章、ASCII 図、表、フェンス付きワイヤーフレームも同様です。plan（または旧称 agent-native-plans）ツールが表示されない場合は、まずホストの tool_search からツールを探してください。それでも見つからない場合は、インラインのプランを即興で作らず、作業を停止して、クライアント固有の再接続手順をユーザーに案内してください。公開前、またはコネクターや認証のエラーが発生した場合は必ず、このスキルディレクトリにある references/connection.md を読んでください。ここには、インライン提示禁止のルール、コネクターの検出方法、クライアントごとの再接続手順が一元的に記載されています。ローカルファイルのプライバシーモードは（ツールの案内後に）例外となります。

コアワークフロー

このセクションでは、デフォルトのホスト型 Plan MCP ワークフローについて説明します。 AGENT_NATIVE_PLANS_MODE=local-files が設定されている場合、またはユーザーが完全なローカルファイル利用／ホスト型 Plan への書き込みなしを求めている場合は、代わりにローカルファイルのプライバシーモードを使用してください。その場合は、ここに記載されたコード調査とプラン作成に関するガイダンスのみを引き継いでください。

1. ホストエージェントの通常の計画フローに従います。コードベースを調査し、必要に応じて広範な探索を委任し、必要な情報を収集し、計画を生成する前に必要に応じてネイティブの確認質問を行います。ソース計画がすでに存在する場合は、ユーザーの貼り付け、参照ファイル、または最近の可視のエージェントコンテキストからその正確なテキストを収集します。ソーステキストを捏造してはいけません。
2. 権威あるブロックカタログを取得するために get-plan-blocks を呼び出します — 記憶したタグから作成しないでください。次に、モードに一致する作成ツールを呼び出します。ドキュメント優先の計画（アーキテクチャ、バックエンド、データ、リファクタリング、API）には create-visual-plan、UI 優先の計画には create-ui-plan、プロトタイプ優先の計画には create-prototype-plan、デザイン優先の計画には create-plan-design、ユーザーが明示的にビジュアルの intake アンケートを求めた場合にのみ create-visual-questions を呼び出します。ソース計画がすでに存在する場合は、それを planText として渡し、元の計画の有用な意図を保ちながら、改訂メモではなくスタンドアロンの計画ドキュメントを生成します。
3. UI/プロダクトの計画では、まず主要なワイヤーフレームと注釈付き状態でトップキャンバスを構成し、その後ネイティブブロックでドキュメントを書きます（references/canvas.md と references/document-quality.md を参照）。ユーザー向けの含意がある広範なプロダクトアーキテクチャ計画では、抽象的なアーキテクチャやモードの表の前に、具体的な「アプリ内でこれがどう見えるか」のビジュアルを追加します。ドキュメントは、エージェントが通常出力するスタンドアロンの Markdown 計画に近い状態に保ちます。既存の計画が提供された場合は、前のドラフトに言及したり、このバージョンがどう異なるかを説明したりすることなく、適切な事実と決定を引き継ぎます。非ビジュアルの計画では、トップのビジュアルサーフェスをスキップし（以下の Visual Surface Choice がルールを規定します）、diagram、data-model、api-endpoint、diff、file-tree、code、annotated-code ブロックを関連する本文のすぐ隣に配置します。 ワイドなドキュメントレイアウトはレンダラーが所有し、意図的に許可リスト化されています。散文より広く breakout するのは、リテラルのコードレビューサーフェス（diff、annotated-code）と、垂直方向または diff 的な子を持つ tabs ブロックだけです。api-endpoint、openapi-spec、data-model、json-explorer、wireframe、question、custom-html ブロックは、それぞれのレンダラーが別途規定しない限り、通常のドキュメントフローに保ちます。
4. 返された Plans リンクまたはインライン MCP App を提示し、ユーザーにレビューを依頼します。CLI やその他のテキスト専用ホストでの次のステップがクリックになるよう、常に実際の URL をチャットに含めます。ホストが埋め込みブラウザ/プレビューパネルを公開し、ツールがそこに任意の URL を開ける場合は、便利なレビューのために返された計画 URL を自動的に開きます — これは利便性とスモークテストであり、唯一のハンドオフやアクセスモデルではありません。計画はローカルエージェントとローカルブラウザセッションでそのまま読み込まれるべきです。サインイン済みの埋め込みブラウザが、匿名/ツールチェックでは読めるローカル計画を読めない場合は、1 つの計画を手でパッチするのではなく、アプリ/アクションの所有権またはアクセスパスを修正します。ハイステークスの計画（アーキテクチャ、バックエンド、データ、複数ファイル、またはリスクの高いもの）では、ユーザーが読んでいる間に Self-Review Before Handoff のセルフレビューパスも開始し、それでハンドオフをブロックしないようにします。
5. ホストされた計画では、編集前、レビュー後、長時間の一時停止後、最終応答の前に get-plan-feedback を呼び出します。anchorDetails、リゾルバーの意図、最近のレビューイベント、およびブラウザハンドオフからのフォーカスされたスクリーンショットを、何が正確に変更され、各コメントが正確に何を指しているかの真実の源として扱います。
6. ホストされた計画では、update-visual-plan で変更を適用し、ターゲットを絞った contentPatches を優先します。トップレベルの content ペイロードはマージではなく完全な置換として扱います。キャンバスや 1 つのブロックを追加するために部分的な content オブジェクトを送信しないでください。完全な置換または replace-blocks が避けられない場合は、書き込みの直前に get-visual-plan を呼び出し、その plan.updatedAt を expectedUpdatedAt として渡し、既存のすべてのブロックとビジュアルサーフェスを引き継ぎます。以前の読み取りやフィードバックペイロードからのリビジョンを決して再利用しないでください。ソース管理に優しい編集には、計画を再生成するのではなく、MDX ファイルに対して細かい patch-visual-plan-source 操作を使用します。replace-file も破壊的であり、同じ新しい expectedUpdatedAt フェンスが必要です。
7. ホストされた計画の書き込みのたびに、再度 get-visual-plan を呼び出し、永続化されたテキスト、ブロック ID/数、キャンバスフレーム、プロトタイプを意図した結果と比較します。成功した mutation 応答は、無関係なコンテンツが生き残った証拠ではありません。編集がエージェント向けフィードバックに対処した場合、この検証の後にのみ、スレッドに対して resolve-plan-comment を、そのコメントに対して consume-plan-feedback を呼び出します。両方を行い、対処済みフィードバックが目に見えて開いたままにも、保留中の作業として返されることもないようにします。
8. ホストされた計画では、ユーザーが共有可能なレシートまたはリポジトリへのチェックイン成果物を望む場合にのみ、export-visual-plan でエクスポートします。

引き継ぎ前のセルフレビュー

この敵対的なセルフレビューは任意であり、デフォルトでは実施しません。不可逆な移行、セキュリティ上重要な作業、またはユーザーが明示的に厳密なレビューを求めた場合にのみ実施し、それ以外では省略してください。プランの生成コストがおよそ2倍になるため、小規模なプラン、UI のみのプラン、単一の判断で済むプラン、通常のプランでは、デフォルトで実施せず省略します。実施する場合も、低コストで、作業を妨げないようにしてください。

• まずプランを提示し、並行してレビューします。 リンクを共有してユーザーが読み始められるようにしてから、レビューを並行して実行します。レビューが終わるまでユーザーを待たせてはいけません。
• 文書化したプランをレビューし、再調査はしません。 プランの文章とそのブロックを批評してください。根拠の確認はプランの作成中にすでに済んでいるため、レビューではリポジトリを再探索するのではなく、出力を確認します。
• 懐疑的なレビュアーを1人起動します。 弱い点、抜けている点、誤っている点を見つけることだけに専念させ、称賛はさせません。次の点を確認するよう指示します。暗黙に決められた、またはまったく決められていない、覆しにくい判断（ワイヤ形式、公開 ID、データモデルの形、認証、所有権）、実在するファイルやシンボルに基づいていない手順、プランで1つに決めるべきところに並んだ複数の選択肢、明らかに抜けている判断（「X の場合はどうなるか？」「Y にしないのはなぜか？」）、冗長な記述や実質のない単一ステップ。
• 修正するか、質問するかを判断します。 明確に修正すべき点は、update-visual-plan の contentPatches を使って自分で修正してください。たとえば、曖昧な非目標、根拠のない主張、明らかに抜けている判断です。真に判断が分かれる事項は、黙って決めず、ユーザーに戻してください。末尾の question-form の未解決事項ブロックに追加するか、通常のユーザーへの質問フローにまとめます。
• ユーザーが読んでいる最中に不意を突かないでください。 プランが大きい場合は、エディターが読み込まれる前にパッチを適用します。それ以外の場合は、セルフレビューを実施中であり、プランが変更される可能性があることを簡潔に伝えます。次に応答するときは、レビューで変更した内容と、ユーザーが判断すべき事項を要約してください。

ビジュアル表示面の選択

プランを作成する前、またはソースプランを読んだ後に、表示面を選択してください。デフォルトで装飾的な要素を追加してはいけません。

UI／プロダクトのプランでは、通常、最上部のキャンバスが主要なレビュー表示面になります。最初に意味のあるワイヤーフレームは、ドキュメント本文のブロックに埋め込まず、ここに配置してください。デフォルト表示、オーバーフローメニューやポップオーバー、サイドパネル、読み込み中、エラーなど、状態が重要な場合は複数のキャンバスアートボードを使います。フレームの横には targetId と placement を使って簡潔な注釈を配置し、実装の詳細、トレードオフ、ファイル一覧、データ契約、リスク、検証についてはキャンバス下のドキュメント本文に記載します。

ユーザーがフロー、ストーリーボード、ジャーニー、ワイヤーフレーム、キャンバス、または「これがどのように見えるか」を求めた場合は、キャンバスを最初に使う依頼として扱ってください。ユーザーに見える状態ごとに1つのアートボードを作り、隣接する状態間だけを接続し、プロダクトに関するメモには短いキャンバス注釈を使います。HTML ダイアグラムのほうが早く書けるという理由だけで、依頼されたストーリーボードをドキュメント本文の diagram ブロックに置き換えてはいけません。ダイアグラムは、バックエンドの仕組み、アーキテクチャ、データフローの説明に使い、キャンバスの下に配置します。

プロダクトのワイヤーフレームと、説明用／メタ的なダイアグラムは分けてください。議論対象のアプリ状態をそのまま表す純粋な画面から始め、UI 内に吹き出しの文章やアーキテクチャに関するメモを埋め込まないでください。矢印、ラベル、契約、データフロー、モードの説明は、独立した注釈、別のキャンバスダイアグラム、またはドキュメント本文に配置します。

既存のアプリを扱うプランでは、描画する前に現在のシェル／コンポーネントを確認してください。最初のアートボードは、既存のサイドバー、ツールバーの配置、オーバーフローメニュー、アプリのクローム、フレームワークのエージェント用クロームが実際の位置にある、現実のアプリと同じ密度の画面にしてください。二次的な表示面は、右上のオーバーフローポップオーバー、シート、パネル、読み込み状態、独立した AgentSidebar など、個別の状態として表現します。恒常的なインスペクターを新たに作ったり、フレームワークのクロームをプロダクト UI に組み込んだりしてはいけません。

• 視覚的な表示領域を設けないのは、アーキテクチャのみ、バックエンドのみ、データ移行のみ、コピーのみ、またはそれ以外の非視覚的な計画の場合です。アーキテクチャ図、依存関係マップ、ファイル計画、API コントラクト、データフローのみのレビューにトップキャンバスを使わないでください。強固なドキュメントを使い、関係を視覚的に説明する必要がある場合に限り、文中に局所的な図を含めてください。通常は、推奨事項または決定ごとに空間図を1つにします。関係が真に逐次的な場合を除き、単一軸の連鎖より、グループ化した領域、レイヤー、四分割、マトリクス、または変更前後のパネルを優先してください。
• キャンバスのみを使うのは、静的な画面1つ、変更前後の比較、コンポーネントの状態、小さなポップオーバー、またはクリックを必要としないビジュアルの方向性の場合です。ワイヤーフレームはcontent.canvasに配置し、content.prototypeは省略してください。
• キャンバス＋プロトタイプを使うのは、複数ステップのUIフロー、オンボーディング、ウィザード、レビュー／承認フロー、ナビゲーションの変更、またはレビュー担当者が動作を操作する必要があるものの場合です。静的なワイヤーフレームをcontent.canvasに配置し、それに対応する機能的なプロトタイプをcontent.prototypeに追加して、トップのビジュアルタブで切り替えられるようにしてください。両方の表示領域がある場合は、デフォルトでワイヤーフレームタブを開き、インタラクティブな次の表示としてプロトタイプを利用できるようにします。
• **デフォルトではワイヤーフレームを使ってください。**すっきりとした最小限のUI、高いUX基準、Linear／Vercelへの言及は、内容と密度の基準を示すものであり、高精細なデザインモードを求めるものではありません。ユーザーがブランドに合わせたデザイン、ピクセル単位で正確なデザイン、本番環境のようなデザイン、または全面的なビジュアルデザインを明示的に求めない限り、レンダラーが提供するワイヤーフレームを使ってください。これにより、すべてのキャンバス画面を確認可能にし、内容全体を見える状態に保てます。
• UIの操作を求められている場合、またはインタラクションが主な論点である場合は、プロトタイプを優先してください。静的なモックも有用であれば保持できるcreate-prototype-planを使います。

キャンバス＋プロトタイプを組み合わせた計画では、ラベルとIDを再利用してください。明示的に単一の表示領域のみを対象とする場合を除き、表示領域をまとめて更新してください。出力の監査では、可観測性スキルを参照してください。単一アプリとワークスペースの両方のテーブルに対応し、アプリのプレビューを保持し、監査、統合、差分、変更の適用を管理者のみに制限してください。

「より高精細な」「ピクセル単位で正確な」「洗練されたモックアップ」「本番環境のような」「本物のデザイン」「スケッチ／ワイヤーフレームではない」は、依頼に「モックアップ」という言葉が含まれていても、デザイン優先の表現として扱ってください。新しい計画にはcreate-plan-designを使います。既存の計画には同じ計画IDを使い続け、renderMode: "design"を指定したset-visual-render-modeパッチと、アップグレードした画面のHTML／CSSを同じ更新に含めて、update-visual-planを呼び出してください。実際のアプリシェル、トークン、タイポグラフィ、間隔、状態を基にし、安定したdata-design-idターゲットを追加してください。スコープ付きスタイルは各画面のcssフィールドに配置し、<style>タグには入れないでください。ビューアー内のCleanトグルが変更するのは、そのブラウザーのワイヤーフレーム設定のみであり、忠実度を高めるものではありません。忠実度の追加要望に対応するために、重複した計画を作成しないでください。

ワイヤーフレームの品質 — references/wireframe.mdを参照してください

UIの要約／計画で使うワイヤーフレームには、厳格な品質基準を適用してください。全幅のクローム、画面下部に固定されたバー、実際のプロダクトコンテンツ、変更前後の比較可能性、適切なsurfaceプリセット、16進数カラーではなく--wf-*トークンを使い、<html>／<style>／フォントタグは使わないでください。ワイヤーフレーム／<Screen>／WireframeBlockを作成する前に、このスキルのディレクトリにあるreferences/wireframe.mdを必ず読んでください。これは、HTMLワイヤーフレームの品質に関する唯一の基準であり、/visual-planおよび/visual-recapと一言一句共有されています。記憶を頼りにワイヤーフレームを作成しないでください。

Canvas — references/canvas.md を読む

Canvas は静的な UI モックアップの唯一の信頼できる情報源です。surface は各アートボードの占有範囲を固定し、複数のサーフェスはレーンに配置されます。注釈は targetId／placement を基準に配置されるプレーンテキストのデザイナーメモで、編集にはピンポイントの contentPatches を使用します。Canvas、アートボード、注釈を新規作成または編集する前に、このスキルディレクトリにある references/canvas.md を必ずお読みください。Canvas／アートボードの仕組みに関する唯一の信頼できる情報源です。記憶を頼りに Canvas のレイアウトを作成しないでください。 Canvas のアートボードでは、ドキュメント本文の WireframeBlock 画面と同じ HTML ワイヤーフレームの手法を使用します。セマンティックな HTML フラグメントを使って <Screen surface="..." html={...} /> を作成してください。Canvas の <Screen> タグ内に <FrameScreen>、<Card>、<Row>、<Btn> などの新しいキットツリーの子要素を作成しないでください。これらは古いプラン向けのレガシー互換マークアップであり、壊れやすい Canvas レイアウトを生成します。

ドキュメントの品質 — references/document-quality.md を読む

このドキュメントはマーケティング資料ではなく、真摯な技術計画です。成果を最初に示し、文章を中心に構成し、自己完結させ、適切なネイティブブロックを使用します。また、未解決の質問は末尾の単一の question-form にまとめ、引き渡し前に見た目を確認します。計画ドキュメントを作成する前に、このスキルディレクトリにある references/document-quality.md を必ずお読みください。ドキュメントの品質基準に関する唯一の信頼できる情報源です。記憶を頼りにドキュメントを書かないでください。

優れた例と悪い例 — references/exemplar.md を読む

基準を示す実例、優れた UI 主導の計画と /visual-plan、および避けるべきアンチパターンについては、計画を作成する前にこのスキルディレクトリにある references/exemplar.md をお読みください。

作成時の不変条件

これらは任意の仕上げではなく、データ整合性を保つためのチェック項目です。

• content は完全な置き換えです。content か、モードの便宜的な配列（screens／transitions または states／components）のどちらか一方を渡し、両方を渡さないでください。作成アクションは複数のソースの混在を拒否します。これは、2 つ目のペイロードによって CSS、フレーム、ドキュメントブロックが気付かないうちに破棄されるのを防ぐためです。
• デザイン画面にスコープされた css は成果物の一部です。プロトタイプ画面と対応する Canvas フレームの両方に保持し、色とタイポグラフィにはレンダラーが所有する --wf-* トークンを使用して、移植性を確保してください。
• リッチテキストの data.markdown には、実際の実行時改行を含める必要があります。リテラルな \n エスケープ文字列を含む 1 行の Markdown 値を計画に渡さないでください。セクション全体が 1 つの見出しとしてレンダリングされてしまいます。周囲の Markdown に実際の改行があれば、コード例でエスケープされた改行を使うのは問題ありません。
• Canvas のアートボードはスクロールしません。ワイヤーフレーム HTML は自然なフローのままにし、画面がサーフェスのプリセットを超える場合は、フレームの height を大きくしてください。サーフェスの幅は維持し、引き渡し前にデフォルトのズームで下端を確認してください。
• ホスト環境への書き込み後は毎回、構造化コンテンツを再読み込みし、ライブの Plan サーフェスを確認してください。有効な JSON ペイロードであっても、CSS が読み込まれたことや、Markdown が意図した見出し、段落、リストの構造でレンダリングされたことの証明にはなりません。

ツールの使い分け

• create-visual-plan：エージェントのタスク／実行ごとに構造化されたビジュアルプランを1つ作成します。または、planTextを渡して既存のテキストプランをインポートします。contentには、ビジュアル面を含めない、キャンバスのみを含める、キャンバスとプロトタイプを含める、のいずれかを指定できます。
• create-ui-plan：主な作業がプロダクトUIに関する場合に、UIを優先したプランを作成します。
• create-prototype-plan：機能的なトップレビュー画面を備えた、プロトタイプを優先するプランを作成します。インタラクション自体も高忠実度にする必要がある場合は、各画面のrenderModeをdesignに設定し、スコープを絞ったスタイルをcssで渡します。それ以外の場合は、デザインを優先したレビューにcreate-plan-designを使用します。
• create-plan-design：ブランドに合わせた高忠実度のデザインタブを備え、オプションで対応するプロトタイプタブも含めたプランを作成します。
• convert-visual-plan-to-prototype：既存のHTMLワイヤーフレームキャンバスをプロトタイププランに変換します。
• create-visual-questions：ユーザーがビジュアルのヒアリング用アンケートを明示的に求めた場合にのみ使用します。/visual-planの事前確認には使用しないでください。
• update-visual-plan：対象を絞ったcontentPatchesで、内容、ステータス、コメントを修正します（Core Workflowの手順6～7を参照）。既存プランを高忠実度にする場合は、意図的に作成した画面HTML／CSSと併せて、renderMode: "design"を指定したset-visual-render-modeを使用します。レンダーモードの変更だけではスケッチ調の処理がなくなるだけです。replace-blocksとcontent全体の置き換えには、最新のget-visual-plan呼び出しで取得したexpectedUpdatedAtが必要です。
• read-visual-plan-source：正規化されたプランをplan.mdx、任意のcanvas.mdx、任意の.plan-state.json、およびJSONとして読み込みます。
• patch-visual-plan-source：安定したブロック、アートボード、注釈、コンポーネント、ワイヤーフレームノードのIDを使って、MDX ASTに細かなパッチを適用します。対象を絞った操作を優先してください。replace-fileには、最新のget-visual-plan呼び出しで取得したexpectedUpdatedAtが必要です。
• import-visual-plan-source：MDXフォルダーからプランを作成または置き換えます。
• get-visual-plan：現在の構造化されたプラン、エクスポート済みHTML、注釈、plan.updatedAtを読み込みます。また、ソースを扱うワークフロー用にMDXフォルダーも返します。破壊的な書き込みを行う直前に再読み込みして同時実行制御の基準とし、書き込みのたびに再度読み込んで保存状態を確認してください。
• get-plan-feedback：未対応の人間からのフィードバックを読み込みます。頻繁に使用してください。スレッドごとにまとめられたコメント、正確なアンカーの詳細、想定される対応者、最近のレビューイベントのペイロードが返されるため、エージェントは自分宛てのコメントに限って対応できます。
• get-plan-blocks：作成を始める前にブロックタグを確認します。タグを記憶で判断せず、まずこれを呼び出して、稼働中のブロックレジストリから正式なタグ名、必須フィールド、プロパティの形式を取得してください。
• export-visual-plan：リポジトリにチェックインするため、HTML、Markdownフォールバック、構造化JSON、MDXファイルをエクスポートします。

ユーザーがプランの見た目や構成に異議を唱えた場合は、レンダラーまたはこのスキルを修正してください。保存済みのプランを直接編集してはいけません。フィードバックをより良いガイダンスに反映してください。

ローカルファイルのプライバシーモード — references/local-files.mdを読む

ユーザーがホスト型Planデータベースへの書き込みを一切望まない場合（DB書き込みなし、Plan MCPへの公開なし、完全ローカル／オフライン／プライベートなプランニング、またはAGENT_NATIVE_PLANS_MODE=local-files）、スキーマのみを参照するget-plan-blocksのカタログ検索以外のホスト型Planツールを呼び出してはいけません。ローカルMDXフォルダーを作成し、plan local check／plan local serve／plan local verifyでプレビューしてください。このモードを使用する前に、このスキルのディレクトリにあるreferences/local-files.mdを読んでください。カタログ検索、MDXフォルダーの構成、ローカルブリッジのコマンド、呼び出してはいけないホスト型ツールを含む、契約全体の唯一の参照元です。Core Workflowから引き継ぐのは、コード調査とプラン作成に関するガイダンスだけです。ホスト型の処理はすべてローカルブリッジに置き換えられます。

コメントアンカーの解釈

このセクションは、get-plan-feedback / update-visual-plan を使用するホスト型プランに適用されます。ローカルファイルモードでは、ホスト型のフィードバックツールや更新ツールを呼び出さないでください。ファイルやチャットでのフィードバックを直接解釈し、MDX ファイルを編集して、ローカルのブリッジ確認／サーブ／検証コマンドを再実行し、新しいローカル URL を報告してください。

get-plan-feedback は詳細なアンカーを返します。コメントに対応する前に確認してください。

• 座標系。 targetX／targetY は、targetSelector／targetKind で指定された要素内のパーセンテージです。単独の x／y は、プラン文書全体に対するパーセンテージです。canvasX／canvasY は、デザインキャンバス上のボード座標系におけるピクセル値です（ボードのサイズが分かる場合は提示されます）。
• ワイヤーフレームのピン。 ワイヤーフレーム上のアンカーには、対象となる正確なキットノードを特定する targetNodeId と targetNodePath（例：card > list > listItem "Acme Inc"）が含まれます。ワイヤーフレームのノードパッチ操作には targetNodeId を直接使用し、デザインアートボードの data-design-id の値は update-design-element-style で使用してください。生の座標よりもノード ID／パスを優先してください。ノード ID がない場合に限り、フォーカスされたスクリーンショット（赤いリングが正確な位置を示します）を座標と併用してください。
• テキストの引用。 contextBefore／contextAfter を使って、現在の文章内の textQuote を特定してください。ambiguous: true の場合は、どの箇所を指すのかユーザーに確認してください。推測してはいけません。
• 切り離されたコメント。 get-plan-feedback は、引用されたテキストがすでに存在しないスレッドを detached（detachedThreads 内）として示します。書き換え後の内容と照合してください。黙って削除してはいけません。
• ルーティング。 唯一のルーティング信号は resolutionTarget です。agent の場合は対応し、human は文脈情報としてのみ扱ってください。@mentions は通知する相手であり、ルーティング信号ではありません。
• 2 軸の状態。 取り込んだすべてのコメントを、消費済みとしてマークしてください（update-visual-plan の consumedCommentIds）。実際に対応したエージェント宛てのコメントに限り status=resolved に設定し、ユーザー宛てのコメントは未解決のままにしてください。編集でフィードバックに対応した場合は、まず保存済みのプランを再読み込みして、変更が反映されたことを確認してください。その後に限り、対応したスレッドについて resolve-plan-comment を、コメントについて consume-plan-feedback を呼び出してください。対応済みのフィードバックを、どちらか一方の軸だけでマークしてはいけません。

可視性と共有

プランを閲覧できるユーザーを変更するには（公開、ログイン必須、組織限定など）、set-resource-visibility を使用してください。メールアドレスまたはロールを指定して、特定のユーザーやロールにアクセス権を付与するには share-resource を使用してください。未公開の作業や非公開の作業を含むプランを共有する前に、可視性を制限してください。レビューに必要な範囲を満たす、最も限定的なスコープをデフォルトにしてください。

セットアップと認証

Plans を利用する方法は 2 つあります。

コーディングエージェント（CLI）。 Agent-Native CLI で一度インストールします。このコマンドは Plans スキルをインストールし、ホスト型 Plans MCP コネクターを登録して、選択したローカルクライアントの認証とセットアップを同じステップで実行します（セットアップ時に一度だけブラウザーでサインインします。これは意図された動作です）。そのため、そのクライアントで最初にツールを呼び出した際に OAuth の壁にぶつかりません。

npx @agent-native/core@latest skills add visual-plans

その後、/visual-plan、/visual-recap、/visualize-repo がインストール済みのスラッシュコマンドになります。必要なコマンドが 1 つだけの場合は、代わりに skills add visual-plan、skills add visual-recap、または skills add visualize-repo を使ってください。その他の計画モード（create-ui-plan、create-prototype-plan、create-plan-design、create-visual-questions）は、/visual-plan から利用できる MCP ツールであり、独立したスラッシュコマンドではありません。--no-connect を渡すと、認証せずにコネクターを登録できます。その後、準備ができたら npx @agent-native/core@latest connect https://plan.agent-native.com --client all を実行するか、より限定的な --client を指定してください。認証と MCP ツールの読み込みは、クライアントごとの設定／セッションで行われます。

ブラウザー（共有相手向け）。 Plans エディターを開けば、サインアップせずにゲストとして作成・編集できます。保存または共有する場合にのみサインインしてください。サインインすると、ゲストとして作成したプランがアカウントに引き継がれます。

共有とコメントにはアカウントが必要です。公開／共有されたプランはリンクを知っている人なら誰でも閲覧できますが、コメントするには agent-native アカウントが必要です。

完全オフラインでアカウントを使わずに利用するには、Plans アプリをローカルで実行し、プランを MDX としてリポジトリに同期してください。このローカルモードは標準のホスト型フローとは別の上級者向けの方法です。

リポジトリ全体のビジュアルドキュメントを作成するには、npx @agent-native/core@latest visualize-repo --open を実行して agent-native.json を作成または更新し、.agent-native/visual-docs/repo-overview を初期化して、ローカルブリッジを開いてください。

Plans ツールが needs auth、Unauthorized、または Session terminated を返した場合、再試行を続けないでください。いったん停止し、references/connection.md に記載されているクライアントごとの再接続手順をユーザーに案内してから、コネクターが利用可能になった後で続行してください。

ホスト型の既定値：https://plan.agent-native.com/mcp に接続します。スキルファイルに共有シークレットを記載しないでください。