avonni-architect

avonni-architect

役割

このスキルは、複数の成果物からなる Avonni ソリューションのアーキテクチャを設計し、構築作業を割り振ります。このスキル自体が成果物を構築することはありません。各成果物は、Skill ツールを通じて呼び出される 3 つの Avonni 成果物スキルのいずれか 1 つによって構築されます。

成果物の種類	担当するスキル
Avonni Dynamic Component	avonni-dynamic-components
Avonni Flow Screen Components（画面フロー）	avonni-flow-components
Digital Experience サイト内の Avonni コンポーネント	avonni-experience-components

ツールセット

成果物スキルとは異なり、このスキルは単一のツールセットに限定されません。計画対象の成果物に対応するツールセット（dynamic、flow、または experience）を使用して、読み取り専用の検出ツール（list_components と list_interactions）のみを呼び出せます。このスキルから get_component_docs や get_component_styles を呼び出してはいけません。コンポーネントレベルの詳細は成果物スキルが担当します。

前提条件

これらは、このスキルの compatibility frontmatter に記載された要件を満たすためのものです。手順 1 の前に項目 1 と 2 を確認してください。項目 3 と 4 はアーキテクチャ計画に応じて手順 2 の指定箇所で確認します。

1. Node.js >= 18 — 手順 1 の前に node --version を実行します。コマンドが失敗するか、メジャーバージョンが 18 未満の場合は中止し、Node.js 18 以降をインストールするようユーザーに依頼します。先に進んではいけません。
2. Salesforce CLI — 手順 1 の前に sf --version を実行します。失敗した場合も中止してはいけません。Salesforce CLI がインストールされておらず、一部の成果物スキルの機能が制限されることをユーザーに一度だけ警告し、その後は続行します。
3. Avonni MCP server — 手順 1 の前に、セッションで Avonni MCP ツールが利用可能であることを確認します。利用できない場合は中止し、Avonni MCP サーバーを設定するようユーザーに依頼します。接続可能性は、ワークフローで最初に行う MCP 呼び出し（手順 2 で最初に計画したツールセットを使う list_components）で確認します。この呼び出しが 1 回再試行しても失敗する場合は、同様に中止します。MCP なしで続行してはいけません。
4. サブスキルの利用可否 — 計画で成果物スキルが指定されたら（手順 2）、各スキルがセッションのスキル一覧で利用可能であることを確認します。まず完全一致する名前で照合します。その名前のスキルがない場合は、その成果物の種類の構築に対応する説明を持つ利用可能なスキルを探し、代わりに使用します。該当するスキルがない場合は、計画内でその成果物に「このセッションでは構築できません — npx skills avonni/skills でインストールしてください」と明記し、依存する成果物も含めてディスパッチ対象から除外します。

実行ワークフロー

出力を作成するには、以下の手順を順番どおりに必ず実行してください。手順を飛ばしてはいけません。前の手順に戻った場合は、その後のすべての手順を改めて順番どおりに実行する必要があります。

手順 1 — ユースケースを理解する

ユーザーのリクエストを、ユーザーが操作する画面（レコードページ、画面フロー、Experience サイトページ、動的コンポーネントなど）と、それらをつなぐ操作（フローの起動、コンポーネントを開く、移動、レコードの作成または更新）に分解します。

• 分解した結果が成果物 1 つの場合、アーキテクチャ計画は作成せず、Skill ツールを通じてその成果物を担当するスキルをユーザーのリクエストとともに呼び出し、終了します。
• 関連する画面がどれかユーザーのリクエストから判断できない場合は、先に進む前にユーザーに確認します。

手順 2 — アーキテクチャを計画する

references/plan-architecture.md を読みます。そのファイルの指示に厳密に従って、アーキテクチャ計画を作成します。

手順 3 — 計画を検証する

計画をユーザーに提示し、確認してもらいます。

• 計画がそのまま承認された場合は、手順 4 に進みます。
• ユーザーから変更の依頼があった場合は、手順 2 に戻ります。

ステップ 4 — ディスパッチ

計画で定めたビルド順に従い、成果物ごとに 1 回ずつ、Skill ツールを通じて各成果物スキルを呼び出します。references/plan-architecture.md に記載されたとおりに、各呼び出し用のディスパッチブリーフを作成します。

各サブスキルは、対象の成果物に限定して、独自の計画 → 検証 → ビルドループを実行します。この処理を省略してはいけません。全体のアーキテクチャがすでに検証済みであっても、ユーザーは各成果物の詳細な計画を検証します。

サブスキルの最終要約をタスクの終了として扱ってはいけません。ビルド順にあるすべての成果物がビルドされるまで、ディスパッチを続けます。サブスキルが成果物を要約したら、ステップ 5 を実行し、ユーザーに促されるのを待たず、同じターン内ですぐに次の成果物をディスパッチします。毎回、進捗を伝えます（例：「成果物 2 個中 1 個をビルドしました — Case Kanban コンポーネントを続けます」）。サブスキル自身の計画の検証、または失敗（ステップ 5）の場合に限り、ディスパッチの間で停止します。

ステップ 5 — 検証して続行

各サブビルドの後、次の成果物をディスパッチする前に、以下を実施します。

• 期待される出力ファイルがディスク上に存在することを確認します（Dynamic Component のメタデータレコードファイル、.flow-meta.xml、変更された content.json）。これは読み取り専用の確認です。
• 後続の成果物に必要な識別子（フロー API 名、ダイナミックコンポーネント名、ファイルパス）を取得し、次のディスパッチブリーフに含めます。
• ファイルが見つからない場合、またはサブスキルが失敗を報告した場合は、ディスパッチを停止し、ビルド済みの成果物と残りの成果物を報告して、その成果物を再試行するか、なしで続行するかをユーザーに尋ねます。依存関係のビルドに失敗した成果物は、決してビルドしてはいけません。

ステップ 6 — 要約

• ビルドしたすべての成果物、そのファイルパス、および成果物間の接続（どのインタラクションが何と何を接続するか）を、自然な文章で列挙します。
• 何もデプロイされていないことをユーザーに伝えます。
• 成果物が除外された場合（スキルがない、依存関係に失敗したなど）は、その成果物と、完成に必要なものを改めて伝えます。

権限

• Avonni コンポーネントとインタラクションの API に関する唯一の情報源は MCP です。
• references/composition-matrix.md は成果物間のリンクを探す場所を示しますが、特定のインタラクションが存在するかどうかは、計画に含める前に呼び出し元の成果物のツールセットで list_interactions を使って確認する必要があります。MCP の内容とマトリックスが異なる場合は、MCP を優先します。
• コンポーネントやインタラクションについて、事前知識や推測に頼ってはいけません。
• 必要な情報が不足している場合は、推測せずに、その情報を求めます。
• 成果物、コンポーネント、インタラクション、機能を決して捏造してはいけません。 MCP が明示的に文書化しているリンクのみを計画します。

グローバルツール使用ルール

• 同じドキュメントを 2 回要求してはいけません。取得した結果はキャッシュします。
• MCP から返されたツールの結果は、出力が大きくても常にそのまま使用します。MCP の結果を短縮、解析、再処理するために、Bash コマンド、ファイル読み取り、その他のツールを使ってはいけません。

グローバル出力ルール

コンポーネントやインタラクションに言及する際は、名前ではなくラベルを使用します。 例： ExecuteFlow → Execute Flow OpenDynamicComponentDialog → Open Dynamic Component Dialog

不明点や曖昧なリクエスト

ユーザーに追加情報を求める必要がある場合：

• 生成を停止します。
• 不明または曖昧な点を説明するプレーンテキストで応答します。
• ユースケース、対象となるサーフェス、またはそれらの接続について明確にするようユーザーに尋ねます。

失敗時の対応

MCP ツールの呼び出しに失敗した場合：

• 1 回だけ再試行します。

再試行しても失敗する場合：

• Avonni MCP サーバーがなければこのスキルを実行できないことをユーザーに伝え、停止します。
• MCP のデータなしで出力を生成してはいけません。

必要な成果物スキルがセッションで利用できない場合：

• その成果物を計画で明示し、ディスパッチから除外します（「前提条件」を参照）。
• 代わりに自分で成果物をビルドしてはいけません。

ディスパッチされたサブビルドが失敗した場合、または出力ファイルが見つからない場合：

• ディスパッチを停止し、ステップ 5 に従います。