platform-lightning-type-widget-coordinate

Lightning Type とウィジェットの構築

以下の 2 つのパスに沿って、Lightning Type、Apex クラス、HXL ウィジェットの生成を調整します。このスキルはコンテンツを直接作成することはありません。依存関係の順序に従ってリーフスキルを読み込み、呼び出し、ユーザーの承認を得てから処理を進め、完了を報告する前に検証ゲートを実行します。

対象範囲

Apex による Lightning Type のみが対象です。ルート lightning:type は @apexClassType/<namespace>__<ClassName> の形式です（外側のクラス）。ペイロードの形状を定義する @AuraEnabled フィールドはクラス自体にあり、ネストされたリスト要素の型は、外側のクラスにある List<Inner> フィールドから参照される内部クラスに配置します。オブジェクト／JSON ベースの Lightning Type（プリミティブな properties を持つルート lightning__objectType）は対象外です。それらは platform-custom-lightning-type-generate と platform-widget-generate に個別に振り分けてください。

---

フェーズグラフ

フェーズ	目的	実行対象	出力
1 — パスの選択	ユーザープロンプトに基づいてパス（existing-lightning-type-with-widget · new-lightning-type-with-widget）を選択します。	すべてのパス	path
2 — Lightning Type の検出	まずローカルプロジェクトを確認し、次に sf project retrieve --metadata LightningTypeBundle:<name> を実行します。その後、曖昧さを解消し、対象範囲内かを確認します。	existing-lightning-type-with-widget のみ	lightningTypeSchema（パス + SHA-256 + Apex クラス FQN）
3 — 構築計画	計画全体を表示し、次の返信で明示的な異議がない限り続行します。	すべてのパス	表示された計画
4 — 生成	パスに応じてリーフスキルを読み込み、呼び出します。	すべてのパス	書き込まれたファイル
5 — 検証	ハードゲート（ブロック）と警告ゲート（参考情報）を実行します。	すべてのパス	ゲートレポート
6 — 要約	ファイル、検証、プレビューの準備状況、次のステップをまとめます。	すべてのパス	要約

フェーズごとのパターン：

ステップ	実行内容
1. スキルの読み込み	指定されたスキルを呼び出します。内容を覚えていても、スキルは更新されるため、必ず最新のものを読み込んでください。
2. 実行	読み込んだスキルのワークフローに従います。
3. 検証	出力が存在し、仕様に一致することを確認します。
4. チェックポイント	次に進む前に、フェーズが完了していることを確認します。

---

フェーズ 1 — パスの選択

ユーザープロンプトからパスを判断し、対応するリーフスキルの読み込み順序を選択します。

パス	条件	フェーズ 4 のサブスキル読み込み順序
existing-lightning-type-with-widget	プロンプトで Lightning Type が指定され、既存のものとして扱われています（型に create、generate、new の指定がありません）。フェーズ 2 で、その型が存在し、対象範囲内であることを確認します。	platform-widget-generate（レンダラーの配線は、フェーズ 4 の「Renderer.json wiring step」に従ってインラインで作成します。別のスキルは読み込みません）
new-lightning-type-with-widget	プロンプトで新しい Lightning Type の作成が求められています（動詞：create、generate、build、make a new）。またはフェーズ 2 で、ローカルプロジェクトにも組織にも見つかりません。	platform-apex-generate → platform-custom-lightning-type-generate（スキーマの作成）→ platform-widget-generate（その後、フェーズ 4 の「Renderer.json wiring step」に従ってレンダラーの配線をインラインで作成します）

プロンプトで Lightning Type が指定されていない場合（プロンプトで提供されたフィールドやサンプルデータに対するウィジェットのみの場合）、このオーケストレーターを起動する必要はありません。ユーザーを platform-widget-generate に直接振り分けてください。

プロンプトから 2 つのパスのどちらか判断できない場合は、明確化の質問を最大 1 つだけ尋ねてから選択してください。new-lightning-type-with-widget パスでは platform-apex-generate のステップが自動的に実行されます。Apex を使うかどうか、ユーザーに確認してはいけません。

---

フェーズ 2 — Lightning Type の検出（existing-lightning-type-with-widget のみ）

new-lightning-type-with-widget の場合はスキップします（Lightning Type がまだ存在しません）。

existing-lightning-type-with-widget の場合は、最初に references/lightning-type-discovery.md を必ず読み（必須 — スキップしないでください。この要約だけをもとにフェーズ 2 を実行しないでください）、そこに記載された検索 → 検証 → クラスの確認手順を順番に実行してください。 以下の箇条書きは注意事項であり、リファレンスの代わりにはなりません。

• まずローカルプロジェクトを検索します：force-app/**/lightningTypes/<TypeName>/schema.json。
• 見つからない場合は、接続済みの組織に対して sf project retrieve --metadata LightningTypeBundle:<TypeName> を実行します。
• 候補が複数見つかった場合は、FQN とパスを示して一覧にします。ユーザーに選択を依頼します。
• スキーマを見つけたら、対象範囲内であることを確認します（ルートの lightning:type が @apexClassType/ で始まること）。型がオブジェクトまたは JSON ベースの場合は、その旨を示して停止します。
• バックエンドとなる Apex クラスがローカルプロジェクトにあることを確認します。 ルートの @apexClassType/<ns>__<ClassName> から <ClassName> を解析します。<pkgDir>/classes/<ClassName>.cls が存在しない場合は、sf project retrieve --metadata ApexClass:<ClassName> を実行します。この処理は、Lightning Type がローカルで見つかった場合も、組織から取得した場合も実行します。ローカルにある Lightning Type が、存在しないクラスを参照していることもあるためです。クラスがどこにも存在しない場合は、その旨を示して停止します（この型はレンダリングできません）。手順の全容についてはリファレンスを参照してください。
• 取得に失敗した場合は、CLI エラーを示し、次のいずれかを提案します：(a) ユーザーに手動で取得を実行してから再実行してもらう、または (b) 適切であれば new-lightning-type-with-widget に変更する。黙って変更してはいけません。
• 取得しても何も見つからない場合は、続行前に new-lightning-type-with-widget への切り替えをユーザーに確認します。

このフェーズの最後に、Lightning Type の schema.json の SHA-256 と、Apex クラスの FQN（@apexClassType/... から解析）を記録します。フェーズ 5 の lightning-type-unchanged ゲートでは、この SHA とフェーズ 4 の終了時点でのディスク上の SHA を比較し、スキーマが黙って変更されないようにします。

古さに注意：セッションをまたいだキャッシュは保持しないでください。毎回ローカルプロジェクトを新たに読み込み、セッションごとに必ず組織から再取得してください。

---

フェーズ 3 — ビルド計画と承認ゲート

references/build-plan-format.md のテンプレートを使って、ビルド計画を出力します。計画には、次の項目を記載する必要があります。

• 何を構築するかを開発者向けに一行でまとめた概要（テンプレートの PLAN: 行）。
• Lightning Type の名前とソース（ローカルプロジェクトに既存 · 組織から取得 · 新規作成）、および参照先の Apex クラスの FQN。
• 作成または変更するファイルと、その絶対パス。
• 承認後に実行するサブスキル。
• 生成後に実行する検証。

計画は開発者が確認します。成果物、ファイル、サブスキル、検証を具体的に記載してください。

計画を全文出力してから、ユーザーの次の返信で明示的に異議が示されない限り続行してください。 明示的な異議とは、no、stop、wait、change X、use Y instead、または同等の拒否・修正依頼です。明示的な承認（yes、approve、go、looks good、ok）は歓迎しますが、必須ではありません。返答がない場合、無関係な追加質問がある場合、または単一ターンの評価として自然に続行する場合は、いずれも暗黙の承認として扱います。不変条件は、計画が会話記録に表示されていることです。対話形式の承認を待つことではありません。異議があった場合は、計画を修正して再出力してから次に進んでください。

---

フェーズ 4 — 生成

フェーズ 1 の表で選択したパスの行にあるサブスキルの読み込み順序に従って実行します。各サブスキルについて、次の手順を実行します。

1. スキルを読み込みます。
2. フェーズ 3 の仕様に基づいて、リーフスキルの作成ワークフローを実行します。成果物については、リーフスキルの指示が優先されます。
3. 出力がビルド計画で約束した内容と一致していることを確認します。
4. 次のサブスキルを実行する前にチェックポイントを作成します。

new-lightning-type-with-widget の引き継ぎ契約：

• Apex で、目的の Lightning Type の形状を定義する @AuraEnabled フィールドを持つクラスを作成します。内部クラスは、ネストされたリスト要素の型に限って使用します。外側のクラスの FQN（<namespace>__<ClassName>）を記録します。
• Custom Lightning Type は、lightning:type: "@apexClassType/<namespace>__<ClassName>" を介して外側のクラスを参照します。
• ウィジェットは外側のクラスの @AuraEnabled フィールドを基準とし、{!$attrs.X} を介して属性をバインドします。
• ウィジェットバンドルを書き込んだ後、以下の renderer.json の配線手順に従って Lightning Type の renderer の配線を作成します。

existing-lightning-type-with-widget の引き継ぎ契約：

• フェーズ 2 で記録した Lightning Type の schema.json のパスと Apex クラスの FQN をウィジェットスキルに渡します。ウィジェットスキルは、Apex クラスの @AuraEnabled フィールドから独自の schema.json を導出します（platform-widget-generate/references/schema-from-lightning-type.md を参照）。
• ウィジェットバンドルを書き込んだ後、以下の renderer.json の配線手順に従って Lightning Type の renderer の配線を作成します。Lightning Type の schema.json は変更しません（lightning-type-unchanged によって保証されます）。書き込むのは renderer.json のみです。

renderer.json の配線手順（どちらのフローでも必須。省略不可）：

まず、platform-custom-lightning-type-generate/references/widget-rendition.md を読み込みます（必須。省略したり、非推奨の形式を使用している可能性がある既存プロジェクトのサンプルをコピーしたり、記憶を頼りに renderer.json を作成したりしないでください）。

ウィジェットバンドルの作成後、platform-custom-lightning-type-generate/references/widget-rendition.md に記載されている widget-rendition パターンを使用して、<pkgDir>/lightningTypes/<TypeName>/renderer.json を作成します。renderer ファイルは薄いラッパーです。最初の子要素で "definition": "@widget/c/<widgetName>" を指定してウィジェットを参照し、ウィジェットのスキーマプロパティすべてを Lightning Type インスタンスの対応する属性に {!$attrs.<schemaPropertyName>} を介してマッピングします。renderer.json 内でウィジェットの本体を複製しないでください。描画ツリーの唯一の信頼できる情報源はウィジェットバンドルです。

既存の renderer の処理（existing-lightning-type-with-widget のみ）：対象パスに renderer.json がすでに存在する場合は、まず読み込みます。

• 同じウィジェット（同じ @widget/c/<widgetName>）を参照し、属性のマッピングも同じであれば、そのままにします。
• 別のウィジェットを参照している場合、またはカスタム LWC のルート上書き（c/<componentName>）を使用している場合は、処理を停止し、上書きする前に競合内容をユーザーに伝えます。ユーザーが既存の rendition を使っていることに気づかず置き換えてはいけません。
• ファイルは存在するものの、widget-rendition ではない場合（例：プロパティレベルの上書きのみ）は、その旨を伝え、マージするか置き換えるかを確認します。

この配線がないと、Lightning Type からウィジェットにアクセスできず、ウィジェットバンドルは使用されないまま出荷されます。renderer-wires-widget により、存在とバインディングの正しさが保証されます。

---

フェーズ 5 — 検証ゲート

references/validation-gates.md を読み、すべてのゲートを実行します。オーケストレーターが実行するのはスキル間のゲートのみです。ウィジェットバンドル内部のチェック（スキーマの解析、ルートキー、リーフの lightning:type、{!$attrs.X} の解決、.uiwidget-meta.xml の整形式性、<UiWidgetBundle> ルート、<masterLabel>、<description>、<widgetType>JSON</widgetType>）は platform-widget-generate が担当し、独自の自己検証ステップの一部として実行します。

必須 — 失敗時はブロック：

1. lightning-type-unchanged — existing-lightning-type-with-widget のみ。 ディスク上の Lightning Type の schema.json の SHA-256 を再計算し、フェーズ 2 で取得した SHA と比較します。不一致の場合は、オーケストレーターが気付かれないように型を編集したことを意味します。
2. renderer-wires-widget — 両方のパス。 <pkgDir>/lightningTypes/<TypeName>/renderer.json が存在し、JSON として解析でき、このウィジェットを componentOverrides["$"].definition === "@widget/c/<widgetName>" で接続し、ウィジェットスキーマのすべてのプロパティを {!$attrs.<schemaPropertyName>} として componentOverrides["$"].attributes にバインドしていることを確認します。フェーズ 4 の「renderer.json wiring step」と validation-gates.md で必須の形を確認してください。

警告 — 参考情報：

1. field-trace — 両方のパス。 references/validation-gates.md のトレース手順を実行します（外側の .cls で @AuraEnabled を grep し、ウィジェットスキーマのプロパティキーを jq で取得し、両方のリストを表示して、INVENTED と OMITTED に分類します）。ゲートレポートには両方のリストを表示してください。リストを表示せずに pass と判定することは重大な違反です。Apex フィールドがウィジェットに存在せず、フェーズ 3 の Properties omitted: 計画にも存在しない場合は、警告します。
2. deploy-check — new-lightning-type-with-widget のみ。 sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName> を実行し、結果を報告します。このコマンドを実行せずに pass と報告することは重大な違反です。「未デプロイであることは有効なスキップ理由ではない」というルールについては、validation-gates.md を確認してください。

各ゲートの結果をフェーズ 6 で名前ごとに報告します（pass、fail (<reason>)、warn (<reason>)、not run）。「すべて合格」のように要約しないでください。各ゲートを明示的に列挙してください。

---

フェーズ 6 — 概要

報告します。開発者が読む概要です。実際に書き込んだファイルのみを列挙し、開発者がすぐに見つけられるようバンドルごとにまとめてください。

Lightning Type + Widget Build Complete: <widgetName>

FILES GENERATED:
  Widget bundle:
    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
    <pkgDir>/uiWidgets/<widgetName>/schema.json
    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml

  Lightning Type bundle:
    <pkgDir>/lightningTypes/<TypeName>/schema.json                # only when newly created
    <pkgDir>/lightningTypes/<TypeName>/renderer.json              # always — wires the Lightning Type to the widget

  Apex (only when newly created):
    <pkgDir>/classes/<ClassName>.cls
    <pkgDir>/classes/<ClassName>.cls-meta.xml

VALIDATIONS:
  widget self-validation (platform-widget-generate gates): <pass | fail — see sub-skill report>
  Lightning Type schema unchanged from before this run: <pass | fail | n/a (newly created)>
  Lightning Type renderer wires this widget: <pass | fail (<reason>)>
  widget↔apex field trace (INVENTED + OMITTED lists printed): <pass | warn (<reason>) | fail (invented: <list>)>
  sf project deploy --check-only: <pass | warn | n/a (no new Apex or Lightning Type to deploy)>

NEXT STEPS:
  - Deploy: sf project deploy start --source-dir <pkgDir>
  - Preview: <preview-surface guidance>

---

ハードルール（常に適用）

1. まず計画を立て、その後に進めます。 ファイルを作成する前に、Phase 3 のビルド計画全体を出力してください。次のターンに明示的な却下または変更依頼がある場合は停止して修正し、そうでなければ Phase 4 に進みます。不変条件は、計画が会話記録に表示されていることです。対話形式でのユーザー承認ではありません。そのため、このルールは手動チャット、エージェント間のフロー、後続のユーザーメッセージがない単一ターンの評価実行でも適用されます。
2. 既存の Lightning Types のスキーマを黙って編集してはいけません。Phase 5 の lightning-type-unchanged は、existing-lightning-type-with-widget に対してこれを強制します。
3. 既存の Apex を黙って変更してはいけません。Phase 4 で既存クラスの変更が必要な場合は、Phase 3 で提示してください。Phase 4 の途中で形状の不一致に遭遇したリーフスキルは、.cls を直接編集せず、必ず停止してオーケストレーターに提示する必要があります。Phase 3 ではオーケストレーターがすでに把握していた不一致を扱い、この条項ではリーフスキルが後から発見した不一致を扱います。
4. フィールドを捏造したり、黙って省略したりしてはいけません。すべての {!$attrs.X} はウィジェットの schema.json に対応している必要があり、ウィジェットの schema.json は Apex クラスの @AuraEnabled フィールドのサブセットである必要があります。Apex フィールドはすべて、既定で含めます。省略する場合は、Phase 3 ビルド計画の Properties omitted: セクションに、そのフィールドとユーザーが承認した理由を記載する必要があります。field-trace は APEX_FIELDS リストと WIDGET_PROPS リストの両方を出力し、黙って省略されたフィールドに警告を出します。List<InnerClass> フィールドは、黙って省略する候補に絶対にしてはいけません。
5. Lightning Type の検索が曖昧な場合、確認は最大 1 回までとします。
6. 生成の前に、必ずリーフスキルを読み込んでください。記憶だけを頼りに作成してはいけません。
7. 対象範囲外の型が見つかった場合は、オーケストレーターを停止します。Phase 2 でオブジェクトベースまたは JSON ベースの Lightning Type が見つかった場合は、ユーザーを platform-custom-lightning-type-generate と platform-widget-generate に個別に案内してください。
8. ゲートは説明するのではなく、実行してください。Phase 5 のゲートは具体的なチェック／コマンドです。ゲートを実行せずに pass と報告することは重大な違反です。実行していない場合は not run と報告してください。
9. Lightning Type のレンダリング指定は必須であり、省略できません。どちらのパスでも、最終的に <pkgDir>/lightningTypes/<TypeName>/renderer.json で、ウィジェットレンディションのパターンに従った属性マッピングを使用し、Lightning Type を @widget/c/<widgetName> 経由でウィジェットに接続してください。これがないと、ウィジェットバンドルは機能しない状態でリリースされます。renderer-wires-widget はファイルの存在とバインディングを検証します。
10. Vibes のセーフシェルフィルターに引っかかるシェルメタ文字を使用してはいけません。このオーケストレーターおよび呼び出すリーフスキルが出力するすべての Bash ツール呼び出しで、コマンド置換（$(…) またはバッククォート）、プロセス置換（<(…)、>(…)）、ブレース展開（{a,b,c} または {1..N}）、eval／exec を使用してはいけません。これらのパターンは Bypass モードでも手動承認を強制し、評価を停止させます。代わりに、コマンドを個別に実行してください（mkdir -p {a,b} ではなく mkdir -p a && mkdir -p b）。中間値を取得するのではなく、個別のコマンドで値と理由を出力し、その結果をもとに判断してください（X=$(jq … file) ではなく、jq … file を単独で実行）。値を複数のコマンドで再利用する必要がある場合は、通常のシェル変数（X=literal）またはヒアストリングを使用してください。

---

参照ファイル一覧

ファイル	参照するタイミング
references/lightning-type-discovery.md	Phase 2 — ローカルプロジェクトのスキャン、組織からの取得、曖昧さへの対処、対象範囲内であることの確認、対応する Apex クラスがローカルプロジェクトにあることの確認。
references/build-plan-format.md	Phase 3 — STOP の前にモデルが記入する計画テンプレート。
references/validation-gates.md	Phase 5 — エラーから修正方法への対応表を含む、ハード／警告ゲートの全一覧。
examples/existing-lightning-type-with-widget-prompt.md	Phase 3 — ビルド計画の作成前に参照し、existing-lightning-type-with-widget の完全な手順を確認します。
examples/new-lightning-type-with-widget-prompt.md	Phase 3 — ビルド計画の作成前に参照し、new-lightning-type-with-widget の完全な手順を確認します。