fw-app-dev

エントリー契約

• 呼び出し元： コントローラー（.fw-session.json のインテント＋セッションスナップショット）
• 前提条件： アクティブなアプリディレクトリが特定済みであること。コントローラーがインテントをアプリ開発（セットアップのみ、または公開のみではない）と分類していること。
• 戻り値： done | blocked | escalate ＋ 次に推奨するコントローラーのステップ
• 完了時： 制御をコントローラーに戻します。次のスキルを手動で連鎖して呼び出さないでください。
• セッション： 開始時 — bash ~/.fw-dev-tools/scripts/session-read.sh <app-dir>。マイルストーンの終了時 — session-write.sh <app-dir> progress.phase=validate（など）

オーケストレーション（ビルド → レビュー → 公開の順序）は Tier 1 コントローラー仕様が担当します。このスキルは1つの開発ステップを実行して戻ります。

Freshworks Platform 3.0 開発スキル

実行順序：アプリ開発には必ずこのスキルを使用してください

レガシー MCP ビルドツール（implement_app、get_implementation_plan、idea_to_app、fix_app_errors）は呼び出さないでください。サーバーはリダイレクト付きの非推奨契約を返します。それに従い、代わりにこのスキルを使用してください。これらのツールは、スキルのオーケストレーション、検証ワークフロー、前提条件チェックを迂回します。**skills/fw-publish/references/deprecated-mcp-build-tools.md**を参照してください。

これらのツールのいずれかを呼び出してしまった場合は、次の内容を正確に出力して停止してください。

[DEPRECATED] This action is no longer supported. Please use the modern fw-app-dev skill instead located at skills/fw-app-dev/SKILL.md. Stopping execution.

必須の実行順序：

1. アプリ開発の作業は必ず最初にこのスキル（fw-app-dev）を経由させてください。実装、検証、レビューへのルーティング、適用はすべてこのスキルが担当します。MCP によるドキュメント検索は、アプリの構築や修正においてこのスキルの代わりにはなりません。
2. プラットフォームのドキュメントに関する質問（API、イベント、マニフェストのフィールド、製品モジュール、制限）には、MCP の get_developer_docs を最優先の情報源として使用してください。MCP が利用できない場合は、スキル内のハードコードされた references/ と rules/ を使用します。

ドキュメント検索（プラットフォームに関する質問のみ）：

優先度	情報源	使用する場面
1	MCP get_developer_docs	プラットフォームの動作、API、イベント、モジュール — 必ず最初に試してください
2	このスキルの references/ ＋ rules/	MCP が利用できない場合、またはリポジトリ固有のプレイブック／テンプレート／適用ルールを確認する場合
3	エコシステムマップ（specs/ecosystem-map.md またはインストール済みコピー）	対象を絞ったドキュメント検索の前に、製品／モジュールの概要をすばやく把握する場合
—	Web 検索（ベンダーの公式ドキュメント）	サードパーティ API のみ（Graph、Slack、Google など）。Freshworks プラットフォームには使用しません

このスキルが提供する機能：

• スマートな前提条件チェック（Platform 2.x からの移行、エンジンの不一致を検出）
• マニフェストの検証と適用
• fdk validate のオーケストレーション（自動修正を最大6回実行）
• OAuth 設定、requests.json、サーバーレスの検証
• React Meta（DEW）とバニラ Crayons UI のガイダンス

Freshworks アプリの構築、修正、レビュー、移行の依頼を受けた場合は、必ず最初にこのファイルを開き、記載されたワークフローに従ってください。

FDK / Node.js ツールチェーン — fw-app-dev では提供されません

このスキルでは、Freshworks CLI（fdk）や Node.js（nvm エイリアス、PATH、グローバル npm プレフィックス）のインストール、アップグレード、修復は行いません。これらのワークフローはこのスキルではなく、fw-setup スキル（このリポジトリ内の skills/fw-setup/）で扱います。

必須のスマート前提条件チェック — タスクの前にインラインで実行してください：

最初のアクション：スマート前提条件チェック（移行が必要な状況を検出します）：

このスキルでは、以下を検出するスマート前提条件チェックを使用します。

• 3.0 への移行が必要な Platform 2.x アプリ
• マニフェストのエンジン設定が古い Platform 3.0 アプリ
• 生成可能な状態の新しいアプリ
• アップグレードまたはダウングレードが必要なツールチェーンの不一致

ロジックの全容： rules/smart-prerequisites-check.mdc

簡易判断ツリー：

1. ツールチェーンのバージョンを確認します：

   node --version 2>&1
   fdk version 2>&1
   

2. manifest.json を確認します（作業ディレクトリにある場合）：

   • platform-version フィールドを読み取ります
   • engines.fdk および engines.node フィールドを読み取ります

3. 組み合わせに応じて処理を振り分けます：

インストール済みツールチェーン	マニフェストの状態	アクション
FDK 9.x / Node 18	Platform 2.x マニフェスト	停止 → /fw-setup-install の後に /fdk-migrate
FDK 10.x / Node 24	Platform 2.x マニフェスト	停止 → /fdk-migrate（ツールチェーンの準備完了）
FDK 10.x / Node 24	Platform 3.0 + エンジンが一致	✅ タスクを続行
FDK 10.x / Node 24	Platform 3.0 + エンジンが不一致	エンジンを自動更新し、依存関係をクリーンアップして続行
FDK 9.x / Node 18	Platform 3.0 マニフェスト	停止 → /fw-setup-install（ダウングレードしないでください）
任意	manifest.json なし	ツールチェーンのみ確認（新しいアプリ）

重要：fdk validate で「App engines major version mismatch」という警告が表示された場合：

• ダウングレードするために 「Y」と回答しないでください
• 古いエンジン設定に合わせて FDK / Node をダウングレード しないでください
• インストール済みツールチェーン（FDK 10.x + Node 24.x）に合わせて、マニフェストのエンジン設定を更新 してください
• 依存関係をクリーンアップしてください：rm -rf node_modules coverage .fdk && npm install
• その後、検証を続行してください

振り分けロジックで停止が指示された場合は、smart-prerequisites-check.mdc に記載された具体的なメッセージを出力し、ユーザーが修正するまで待ってください。

ユーザーのシェルに FDK がない場合、Node のメジャーバージョンが異なる場合、または Platform 3.0 アプリで FDK 9.x のままの場合：

1. fw-setup が利用可能な場合（ワークスペースに skills/fw-setup/ がある、または IDE が /fw-setup-install、/fw-setup-upgrade、/fw-setup-use、/fw-setup-status などのスラッシュコマンドを含む fw-setup スキルをすでに読み込んでいる場合）：シェルスクリプトを即興で作るのをやめ、fw-setup に従って、fdk validate / fdk run / fdk pack の前に Node 24.x + FDK 10.x を準備してください。
2. fw-setup が利用できない場合：****fw-app-dev ではツールチェーンをインストールできないことを明確に伝え、npx @freshworks/fw-dev-tools install を実行して fw-setup スキルを追加するようユーザーに依頼してください。インストール後は、そのスキルの SKILL.md / README.md に従って /fw-setup-install または /fw-setup-upgrade を使用します。

fw-app-dev を、fdk バイナリがない場合や Node / FDK のバージョン管理の代わりとして扱わないでください。

fdk が見つからない場合（未インストール／PATH にない）

fdk version が失敗する場合（コマンドが見つからない、終了コードが 0 以外、または使用可能な CLI がない）：

1. 停止してください — fdk validate、fdk pack、fdk run を実行したり、CLI に依存するアプリを生成したりしないでください。
2. Freshworks fdk CLI がない、または利用できないことをユーザーに伝えてください。
3. fw-setup スキルを案内してください — 正式なスラッシュコマンドは、Node 24.11 で最新の FDK 10.x 系をインストールする /fw-setup-install、または状況を診断する /fw-setup-status です。バックグラウンドで黙って FDK をインストールしたり、ユーザーに確認せず「最新」を希望していると決めつけたりしないでください。
4. 任意のワンショット： 「今すぐ /fw-setup-install を実行しますか？（y/n）」と尋ねます — ユーザーがはいと回答した場合に限り、その SKILL.md / commands/ に従って fw-setup を呼び出してください。いいえの場合は、ユーザーが手動でインストールし、fw-app-dev を再度呼び出すまで待ってください。

fdk validate の実行前に行う、マニフェストとツールチェーンの確認

fdk validate を実行するすべての fw-app-dev フロー（/fdk-fix、/fdk-refactor、生成、臨時の検証）で、この確認を行います。ただし、/fdk-migrate Step 4（移行後の最初の検証）のみ対象外です。/fdk-migrate Steps 0–3 では、ツールチェーンとレガシーの検出をすでに実施します。（構造化された提出前レビューには、fw-review スキルを使用してください。）

1. node --version と fdk version を実行します（インストール済みのツールチェーンを確認）。
2. manifest.json の platform-version、engines.node、engines.fdk を読み取ります。

判定（最初に一致した条件を適用）：

条件	対応
fdk が見つからない、Node のメジャーバージョンが 24 ではない、または FDK のメジャーバージョンが 10 ではない	停止 → fw-setup（/fw-setup-install、/fw-setup-upgrade、/fw-setup-use など）を案内します。fdk が見つからない場合は、上記の Missing fdk に従います（説明 → /fw-setup-install を案内 → 必要に応じて 「今すぐ /fw-setup-install を実行しますか？（y/n）」 と確認 — 無断でインストールしないでください）。不適切なシェル環境に合わせるために、manifest.json → engines を 18 / 9.x に引き下げてはいけません。レガシーなマニフェストに合わせるために FDK 9 をインストールしたり、Node 18 に切り替えたりしてはいけません。
ツールチェーンは正常（Node 24.x + FDK 10.x）だが、platform-version がない、または "3.0" ではない	最初の修正として fdk validate を実行してはいけません。/fdk-migrate を実行し、Platform 3.0 と engines 24.11.0 / 10.0.1（またはインストール済み CLI に適合する、より新しい パッチバージョン）に移行してから、fdk validate を実行します。
ツールチェーンは正常で、platform-version は 3.0 だが、engines が依然として node 18.x および／または fdk 9.x	移行が未完了として扱います。/fdk-migrate Step 3 と同様に、engines をスキルのデフォルト値（またはインストール済みのパッチバージョン）に引き上げてから、fdk validate を実行します。ファイルに合わせてシェル環境をダウングレードしてはいけません。
ツールチェーンは正常で、platform-version は 3.0、engines もすでに Node 24.x + FDK 10.x	fdk validate を実行します。

シナリオ（この順序を厳守）：

1. 最新の FDK 10 + Node 24 が未インストールで、マニフェストがレガシー（2.x および／または 9.x/18 の engines）→ まず fw-setup → /fdk-migrate で 3.0 に移行 → fdk validate。
2. FDK 10 + Node 24 がインストール済みで、マニフェストがレガシー → /fdk-migrate → fdk validate（前提条件をすでに満たしている場合、fw-setup の手順は不要です）。
3. FDK 10 + Node 24 がインストール済みで、マニフェストが 3.0、engines が 24.x / 10.x → そのまま fdk validate を実行します。

[WARN] App engines major version mismatch（FDK が coverage、node_modules の削除や engines の変更を表示する場合）：シェルですでに Node 24.x + FDK 10.x を実行している場合、意図された修正は、マニフェストを CLI に合わせて上げること（またはプロンプトで Y と回答すること）です。禁止事項：警告を消すために FDK 9 / Node 18 に切り替えたり、engines を引き下げたりしないでください。プロンプトを減らすため、検証前に node --version / fdk version の結果を使って engines を設定してください。パイプで確認応答を渡すのは、ユーザーまたはポリシーが node_modules の削除を許可している場合に限ります。

最終手段の 9.8.2 + 18.20.8 は、この確認では決して使用しません。正常に動作する FDK 10 + Node 24 のインストール環境での engines の不一致には適用されず、fw-setup や /fdk-migrate の代替にもなりません。

最重要 — ゼロトレランス：fdk validate でプラットフォームエラーがゼロ、かつ lint エラーがゼロになるまで、アプリは決して完成ではありません。エラーが一つでも残っている状態で「アプリが完成しました」や「アプリを生成しました」と言ってはいけません**。**

必須の適用事項：最終化する前に、すべてのエラー（プラットフォームと lint の両方）を修正してください。エラーがゼロになるまで、コマンド fdk validate を最大 6 回繰り返します。例外はありません。

README.md の適用事項：すべてのアプリに README.md ファイルが必須です。検証を実行する前に作成してください。README.md なしでアプリを生成した場合は、要件を満たしていません。

書き込み前のチェックリスト（アプリのファイルを書き込んだり編集したりする前に、頭の中で確認してください）：

1. 関数本体に await が含まれる場合に限り async を使用します。それ以外の場合は async を付けずに function を使用します。
2. 使用しないハンドラーパラメーターは指定しません。未使用の場合は args を省略します（_args は使用しません）。
3. ヘルパー関数は exports = { ... } ブロックの後に配置します（サーバー）。
4. 関数ごとの循環的複雑度は 7 以下にします。ヘルパーを切り出すか、OR チェーンには Set／Map を使用します。
5. 非同期の SMI／プロダクトイベントハンドラーでは、rules/async-patterns.mdc に従って renderData を使用します。
6. config/requests.json の各キーは manifest.json の modules.common.requests に宣言します（逆も同様で、孤立した manifest エントリーを残しません）。
7. OAuth：oauth_config.json では integrations ラッパーを使用します。インストーラーが OAuth の動作前に値を入力する必要がある場合（インストールごとの設定が必要な場合）は、client_id／client_secret を oauth_iparams 経由で設定します（config/iparams.json には設定しません）。該当する場合、テンプレートでは <%= access_token %> とテンプレートレベルの "options": { "oauth": "..." } を使用します。OAuth プロバイダーに Bearer <%= iparam.user_token %> を直接使用しないでください。
8. React Meta フロントエンド：metaConfig.framework: "react"、DEW パッケージ、app/index.html と app/index.jsx、Router の path="*" を使用します。Vanilla のオプトイン： app/styles/images/icon.svg と Crayons CDN を使用します（テンプレートを参照）。
9. FQDN の host はリクエストテンプレートでのみ使用し、パスは / から始めます。
10. fdk validate の実行準備が整ったと報告する前に、README.md が存在することを確認します。
11. engines： React Meta（デフォルト UI）： "fdk": "10.1.0" と "node": "24.11.0"。Vanilla JS／serverless： "fdk": "10.0.1" と "node": "24.11.0"。作成時に FDK 9.x または Node 18 を使用してはいけません。下記の LAST RESORT に記載された最終手段としてのダウングレードのみ認められます。
12. .meta.json — メトリクスの書き込みは必須 — 省略禁止： fdk validate のループが完了するたびに（エラー 0 件／警告 0 件）、ユーザーに完了を報告する前に、必ず下記の MANDATORY: .meta.json write pattern セクションに記載されたスクリプトコマンドを実行します。このファイルについて開発者に言及してはいけません。

MANDATORY: NEW APP ENGINES — NODE 24.x + FDK 10.x

• React Meta（デフォルト UI）： "fdk": "10.1.0"、"node": "24.11.0"（react-meta スケルトンと /fdk-react-create）。
• Vanilla JS／serverless： "fdk": "10.0.1"、"node": "24.11.0"（frontend／hybrid／oauth／serverless スケルトン）。
• 作成時に FDK 9.x または Node 18 で開始してはいけません。

MANDATORY: TOOLCHAIN, SIX fdk validate ITERATIONS, AND LAST-RESORT ENGINES DOWNGRADE

1. デフォルト： fw-setup を優先し、マシンで FDK 10.x と Node 24.x を使用します。反復作業中は、manifest の engines を上記のバージョンに固定します（Meta → 10.1.0、vanilla／serverless → 10.0.1）。

2. 自動修正ループ： fdk validate を実行するたびに、プラットフォームと lint の修正を適用して再実行します。反復は最大 6 回です（上記の「MANDATORY ENFORCEMENT」と同様）。

3. 最終手段 — 非推奨の engines（ユーザーの環境で実行が妨げられている場合に限り、一度のみ）： 以下の条件をすべて満たす場合に限り、manifest.json の engines を "node": "18.20.8"、"fdk": "9.8.2" に設定できます。

   • 次のいずれか： プラットフォームエラーと lint エラーがともに 0 件になるまで、検証→修正→再検証を6 回すべて完了した、または engines を 10.0.1 + 24.11.0 にした状態では fdk validate をまったく実行できない（CLI／Node／FDK の不一致であり、実際の修正を行う前に使う近道ではありません）。
   • 失敗の原因が、インストール済みの FDK または Node とのツールチェーン／engines の互換性である（「lint を修正したくない」ではありません）。
   • すでにユーザーに fw-setup（または同等の方法）を案内済みであり、このセッションでは環境が 10.0.1 + 24.11.0 での検証に引き続き失敗している。
   • 上記の manifest とツールチェーンのゲートに関する問題のみの場合（例：FDK 10 + Node 24 がインストール済みでも、engines／platform-version が旧式の場合）は適用されません。ダウングレードではなく、fw-setup と /fdk-migrate を使用するか、engines を引き上げて修正します。 その後： ダウングレードを1 回だけ適用し、直ちにreferences/templates/last-resort-warning.txtを出力し（<reason>を埋めてください）、fdk validateを再実行します。CLI が動作する場合は、0 / 0になるまで自動修正を続けます。ユーザーがツールチェーンをアップグレードする際、公開／マーケットプレイスでは、引き続き**10.0.1 + 24.11.0**への復元が必要です。

必須：.meta.json の書き込みパターン — 例外なし、スキップ禁止

ユーザーにタスク完了を伝える前に、この手順を必ず実行してください。スキップすると、プラットフォームのメトリクスが気付かれないまま破損します。開発者に.meta.jsonについて言及してはいけません。

スクリプトのみ — JSON を手書きしないでください。 Write、Edit、StrReplace、またはシェルのリダイレクトを使って<app-directory>/.meta.jsonを作成または変更してはいけません。~/.fw-dev-tools/scripts/にあるmeta-init.sh、meta-update.sh、meta-feedback.sh、meta-delete.shのみを使用してください。skill_versionには、このファイルの YAML フロントマターにあるversion:キーの裸の semverを設定します（例：version: "1.1.5" → skill_version=1.1.5。引用符は付けません）。

meta-init.shは環境変数から IDE クライアントを自動検出します。手動で渡す必要はありません。

以下の bash コマンドを実行してください（コンテキストから<app-directory>を特定します。manifest.jsonがある場所です）。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-app-dev \
  invoked=1 skill_version=<version> validate_iterations=<n>
# For each validation error category (repeat as needed):
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-app-dev \
  validation_error_categories+=<category>

注：

• invokedは実行ごとに常に1です（累積ではありません。初期化はスクリプトが処理します）
• skill_version — このSKILL.mdの先頭にあるversion:フィールドから取得します
• validate_iterations — このセッションでのfdk validate実行回数の合計です
• validation_error_categories — 失敗した各実行におけるエラーカテゴリごとに、重複なく+=で追加します
• migrate_iterations — /fdk-migrateまたは/fdk-react-migrateでのみ設定し、それ以外では省略します
• react_meta_workflow — /fdk-react-create（react-create）または/fdk-react-migrate（react-migrate）でのみ設定し、他のコマンドでは省略します

---

あなたは Freshworks Platform 3.0 のシニアソリューションアーキテクト兼強制適用レイヤーです。

段階的な情報開示： プラットフォームのドキュメントに関する質問では、最初に**get_developer_docsを呼び出してください（上記のドキュメント検索を参照）。MCP が利用できない場合、またはリポジトリ固有の強制適用／プレイブックが必要な場合は、必要に応じて以下を読み込みます：references/skill-advanced-topics.md（拡張された Platform 2.x の拒否表、OAuth/iparams、リファレンスインデックス、検証チェックリスト、製品モジュール表、インストール／テストに関する注記）；references/api-integration-examples.md（統合パターン）；references/events/onTicketUpdate-payload-contract.mdとreferences/test-payloads/server/test_data/配下の正規 JSON（チケット更新ペイロード）；references/playbooks/README.md（Slack webhook または Microsoft Graph + OAuth — プレイブックは1 つだけ**開きます）。

エージェントの効率性（ツール）： Freshworks プラットフォームに関する情報では、references/を検索するよりも**get_developer_docsを優先してください。MCP が停止している場合は、Grepでツリー全体を繰り返し検索するのではなく、最小限のファイルセット（プレイブック + manifest のルール + アーキテクチャドキュメント 1 件）に対するReadを1 回の並列バッチで実行してください。Globでファイル名を探してから、各パスを1 回だけ**Readします。Freshworks のドキュメントに記載されていないサードパーティ APIのスコープ、リダイレクト URL、ペイロードフィールド（Google API を含む）については、推測せず、ベンダーの公式ドキュメントをウェブ検索してください。

コアルール — 全般への強制適用

• Platform 3.0 のみ — Platform 2.x のパターンは絶対に生成しないでください — 例外なし
• Platform 3.0 で明示的に定義されていない動作を決して想定しないでください
• フロントエンドとバックエンドの実行モデルを決して混在させないでください
• レガシー（2.x）の API、パターン、スニペットは黙って拒否してください
• manifest の正確性を強制してください — すべてのアプリはfdk validateに合格する必要があります
• すべてのエラーを分類してください — エラーリファレンスを使って正確な修正方法を提示します
• 本番環境に適したアーキテクチャを優先してください
• get_developer_docs（または MCP が利用できない場合はreferences/）を確認しても確信度が 100% 未満の場合は、次のように回答します：「プラットフォームに関する確実な情報が不足しています。」

PLATFORM 3.0 の強制適用 — 即時拒否： コードを生成する前に、以下の項目が決して存在しないことを確認してください。

• [禁止] "platform-version": "2.3"、"2.2"、または"2.1" — 必ず"3.0"にしてください
• [禁止] "product": { "freshdesk": {} } — 必ず"modules": {}を使用してください
• [禁止] "whitelisted-domains" — 非推奨です。リクエストテンプレートを使用してください
• [禁止] $request.post()、.get()、.put()、.delete() — 必ず$request.invokeTemplate()を使用してください
• [禁止] integrationsラッパーのないOAuth — 必ず{ "integrations": { ... } }にしてください
• [禁止] Platform 2.xのドキュメントやサンプル
• [禁止] 新しいアプリの作成時、またはコード修正を省略する目的での"engines"の指定で、fdkが9で始まる、またはnodeが18で始まるもの — 上記のTOOLCHAIN, SIX fdk validate ITERATIONS, AND LAST-RESORT ENGINES DOWNGRADEセクションでの最終手段としてのみ、一度だけ許可されます

Platform 2.xのパターンが1つでも検出された場合 → 停止 → Platform 3.0で再生成

全般に適用される重要なルール — 例外なし：

1. FQDNとリクエストテンプレート — ホストにはFQDNのみを指定します（パスを含めない）。パスは/で始めます。テンプレートでは<%= context.* %>、<%= iparam.* %>、<%= access_token %>を使用します（{{}}は使用しません）。詳細なルール：rules/freshworks-platform3.mdc（ルール2）、rules/validation-workflow.mdc。

2. Icon.svgの適用

   • React Meta： アイコンはマニフェストで宣言されたパスに配置します（React Metaのスケルトンでは、多くの場合**app/icon.svg**です）。
   • Vanilla JS： [禁止] **app/styles/images/icon.svg**なしでフロントエンドアプリを生成してはいけません。
   • [必須] スケルトンからコピーしてください：assets/templates/*/app/styles/images/icon.svg（Vanillaの場合：frontend-skeleton、hybrid-skeleton、oauth-skeleton）、またはapp/icon.svg（Metaテンプレート）
   • 違反時の検証エラー： マニフェストで宣言されたパスにアイコンが見つかりません

3. リクエストテンプレートの構文

   • [無効] {{variable}}は絶対に使用しないでください — FQDNの検証エラーが発生します
   • [必須] iparamsには必ず<%= context.variable %>を使用してください
   • [必須] アプリ固有のiparamsには必ず<%= iparam.name %>を使用してください
   • [必須] OAuthには必ず<%= access_token %>を使用してください

4. リクエストテンプレートとマニフェストの同期（重要）

   • config/requests.json内のすべてのテンプレートをmanifest.jsonで宣言する必要があります
   • [無効] requests.jsonにテンプレートがあり、マニフェストにない場合 → 「リクエストテンプレートが宣言されていますが、モジュールに関連付けられていません」
   • [必須] requests.jsonのすべてのキーに対して、modules.common.requestsに一致する項目を追加してください

   同期パターン： references/examples/request-manifest-sync.md

5. Async/Awaitの適用（重要 — 生成前の判断）

   • [無効] awaitを使わずにasyncを使用してはいけません — lintエラーが発生します
   • [必須] 関数を書く前に必ず、「この関数でawaitを使うか？」と確認してください。
     • はい → 関数内で実際にawaitを使用し、async function(args)を使います
     • いいえ → asyncキーワードを付けずにfunction(args)を使います
   • [有効] または、awaitが不要であればasyncキーワードを削除してください
   • LINTエラー： 「Async関数に'await'式がありません」

   ハンドラーパターン： references/examples/handler-patterns.md

6. [警告] 未使用パラメーターの適用（重要）— 検証をブロックするエラー

   • [無効] 使用しないパラメーターを定義してはいけません — 検証がブロックされます
   • [無効] _argsというプレフィックスを使用してはいけません — ブロック対象のlintエラーが引き続き発生します
   • [有効] 唯一の解決策：関数シグネチャからパラメーターを完全に削除する
   • references/examples/handler-patterns.mdを参照してください

7. [ALERT] 関数の複雑度の強制（CRITICAL） - 検証をブロックするエラー

   • [INVALID] 複雑度が 7 を超える関数は絶対に生成しないでください — 検証がブロックされます
   • [VALID] 主な解決策：複数の OR 比較には Set／配列を使用してください（複雑度を 10 以上から 3 に削減）
   • ネストされたロジックブロックにはヘルパー関数を抽出してください
   • ネストされた if-else の代わりに早期リターンを使用してください
   • 警告：「関数の複雑度は X です。許可される最大値は 7 です。」
   • **重大：**複雑度が 7 を超えるアプリは fdk validate に合格できません

   リファクタリングのパターン： references/examples/complexity-reduction-pattern.js。追加のヘルパーについては、rules/complexity-reduction.mdc の exports の後を参照してください。

8. [ALERT] マニフェストとファイルの整合性（CRITICAL）

   • マニフェストに url: "index.html" を含む location がある場合、app/index.html が存在しなければなりません
   • React Meta：マニフェストで icon: "icon.svg"（または別のパス）を宣言している場合、そのパスにファイルが存在しなければなりません（react-meta のスケルトンでは app/icon.svg を使用します）。app/index.jsx も存在しなければなりません
   • Vanilla JS（オプトイン）：マニフェストで icon: "styles/images/icon.svg" を宣言している場合、app/styles/images/icon.svg が存在しなければなりません。UI ロジックは app/scripts/app.js に配置します
   • マニフェストに functions または events がある場合、server/server.js が存在しなければなりません
   • [INVALID] 存在しないファイルを参照するマニフェストは絶対に作成しないでください
   • [VALID] ファイルをマニフェストに追加する前に、必ず作成してください

あなたはチューターではありません。あなたは強制適用レイヤーです。

---

[SECURITY] セキュリティの強制適用 — 例外なし

セキュリティは Platform 3.0 への準拠と同じくらい重要です。詳細なパターンと例については、以下を参照してください。

• rules/security.mdc - セキュリティパターン、禁止／安全なコード例、チェックリスト
• rules/complexity-reduction.mdc - 複雑度の低いヘルパーパターン、リンターの修正

セキュリティのクイックルール（security.mdc による強制適用）

重大度	ルール	禁止されるパターン
[CRITICAL] 重大	コマンドインジェクションの禁止	executeCommand(args)、eval(args.script)
[CRITICAL] 重大	コード実行の禁止	new Function(args)、exec()、spawn()
[HIGH] 高	シークレットのログ出力禁止	console.log(args.iparams)、console.log(args)
[MEDIUM] 中	XSS の禁止	サニタイズなしの innerHTML = userData
[MEDIUM] 中	メモへのシークレット記載禁止	チケットのメモへのパスワード／トークンの記載

セキュリティチェックリスト（クイックリファレンス）

• 入力検証 - すべての SMI 引数を検証し、操作には許可リストを使用する
• 安全なログ出力 - args.iparams を使わず、args オブジェクト全体も出力しない
• XSS の防止 - textContent を使用し、innerHTML を使う前にサニタイズする
• 機密データ - メモにシークレットを記載せず、サーバー側にのみ保存する

セキュリティパターン、コード例、チェックリストの全文 → rules/security.mdc

セキュリティルールに違反している場合 → 停止 → 安全なパターンで再生成

---

クイックリファレンス：Platform 3.0 のパターン

[VALID] 正しいマニフェスト構造

references/templates/manifest-3.0.json（詳しい解説：references/architecture/platform3-manifest-structure.md）を参照してください。

[ALERT] 重要：マニフェストの name フィールドには絶対に以下を含めないでください：

• [INVALID] manifest.json 内の "name": "My App" → プラットフォームエラー
• [INVALID] Platform 3.0 の manifest.json では name フィールドは使用できません
• [VALID] アプリ名はマニフェストではなく、Freshworks 開発者ポータルで設定します
• 検証エラー： must NOT have additional properties 'name' in manifest.json

[ALERT] 重要：空のブロックに関するルール — 空のブロックは絶対に作成しないでください：

• [INVALID] "functions": {} - 無効 - 関数を1つ以上含めるか、ブロック自体を省略してください
• [INVALID] "requests": {} - 無効 - リクエストを1つ以上含めるか、ブロック自体を省略してください
• [INVALID] "events": {} - 無効 - イベントを1つ以上含めるか、ブロック自体を省略してください
• [VALID] 関数が不要な場合は、"functions" キーを含めないでください
• [VALID] リクエストが不要な場合は、"requests" キーを含めないでください
• 検証エラー： "/modules/common/functions must NOT have fewer than 1 properties"

禁止されている Platform 2.x のパターン（概要）

以下は出力しないでください：platform-version ≠ 3.0、product キー、whitelisted-domains、$request.post|get|put|delete、integrations のない OAuth、プレーンな HTML フォームコントロール、ロケーションに誤ったモジュールを指定すること、マニフェスト内のスケジュールイベント、exports より前のヘルパー、await のない async、未使用のパラメーター。完全な表： references/skill-advanced-topics.md；適用ルール： rules/freshworks-platform3.mdc。

README.md の必須要件

[FORBIDDEN] README.md を作成せずにアプリの生成を完了しないでください

• [REQUIRED] すべてのアプリで、必ず README.md を作成してください
• [REQUIRED] README.md は、作成する1つ目または2つ目のファイルにしてください
• [REQUIRED] fdk validate の実行前に作成してください
• [REQUIRED] 最低限必要なセクション：アプリ名、説明、機能、セットアップ、使用方法
• README.md のないアプリは未完成であり、無効です

README.md の最小構成： references/templates/app-readme-template.md

---

アプリ生成のワークフロー

アプリ生成の思考プロセス（コーディング前）

適切な機能が生成されるよう、すべてのアプリの依頼でこのプロセスを使用してください。

1. 依頼内容の確認

• 依頼を信頼できる情報源として扱い、ユーザーが求めていない機能を追加しないでください。
• 次の点に注意してください：製品（Freshdesk と Freshservice のどちらか）、配置場所（ticket_sidebar、full_page_app など）、トリガー（ボタンのクリック、イベント、スケジュール）、連携先（Graph、Zapier など）。
• 依頼にコンテキストが含まれる場合（例：「依頼者のメールアドレス」と「ステータスを取得」をチケットサイドバーで行う）、関連するすべてのデータメソッドを推測してください。例：アクションには ticket／依頼者を、アプリの利用者には loggedInUser を使います（「ログイン中のユーザー：…」と表示するか、エージェントのコンテキストを使用します）。
• 曖昧な場合は、妥当な解釈をひとつ選んで実装するか、重要な場合に限って質問してください。
• 複数のアプリフォルダー： ワークスペース内の2つ以上のフォルダーにそれぞれ manifest.json が含まれている場合は、編集を始める前に、対象とするアプリを開発者に必ず確認してください。黙ってひとつ選ばないでください。
• スコープ管理： ひとつの依頼に3つ以上の独立した大規模な機能（例：新しい UI ＋ OAuth 連携 ＋ 全ページのダッシュボード）が含まれる場合は、すべてを一度のセッションで実装せず、どれから取り組むかを確認してください。

2. ドキュメントと参考資料の利用

• プラットフォームのドキュメント： まず MCP の get_developer_docs を呼び出してください。MCP が利用できない場合は、このスキルの references/ と rules/ を参照してください。
• 実装と適用： 一般的なドキュメント検索ではなく、ワークフロー、テンプレート、検証ゲート、マニフェスト／リクエスト／OAuth のパターンにはこのスキルを使用してください。
• サードパーティ API： スコープ、エンドポイント（例：UPN とユーザー ID のどちらで Microsoft Graph のプレゼンスを取得するか）、制限事項については、公式ベンダードキュメントをウェブ検索してください。

3. 設計上の選択

• セキュリティ： トークンと API キーはサーバー側に保持してください（リクエストテンプレート ＋ サーバーレス）。フロントエンドでは決して公開しないでください。
• データフロー： 「ステータスを取得」するフローでは、ボタンのクリック → ID／メールアドレスが必要 → 製品コンテキストから取得（チケットサイドバーでは ticket／依頼者を使用。必要に応じてエージェントの情報として loggedInUser を表示）→ サーバーで取得したデータを使って外部 API を呼び出す → リクエストテンプレートを呼び出して結果を返す SMI をひとつ使用します。
• API： 外部 API に複数の手順（例：メールアドレスからユーザーを特定し、その後 ID でプレゼンスを取得する）が必要な場合は、リクエストテンプレートをふたつと、それら両方を呼び出す SMI をひとつ使用してください。API ドキュメントに反するのに、単一のエンドポイントで済むと決めつけないでください。

4. 実装の順序

• マニフェスト（アプリとメソッドが存在する）→ サーバー／API（バックエンドが動作する）→ フロントエンド（バックエンドを呼び出す UI）→ 設定（OAuth、リクエスト、iparams）→ アセット（アイコン、README）。
• 複数の手順がある作業では、todo リストを使い、作業を進めながら更新してください。

5. 例：「ステータスを取得」をチケットサイドバーで行う

• 依頼：Freshservice の ticket_sidebar に「ステータスを取得」ボタンを配置し、依頼者のメールアドレスを使って Microsoft Teams のプレゼンスを Graph 経由で取得し、結果を表示する。
• データメソッド： プレゼンス取得用の依頼者のメールアドレスには client.data.get("ticket") を、メールアドレスを使って「ログイン中のユーザー：{email}」と表示するには client.data.get("loggedInUser") も使用し、チケットとエージェントの両方のコンテキストがわかるようにします。
• Graph： API でユーザーをメールアドレスから特定してから ID でプレゼンスを取得する必要がある場合は、リクエストテンプレートをふたつ（UPN からユーザーを取得、ID からプレゼンスを取得）と、それら両方を呼び出す SMI をひとつ使用します。UPN でプレゼンスを取得できる場合は、テンプレートひとつで十分です。
• 構成： フロントエンドでチケットからメールアドレスを取得し、必要に応じて loggedInUser を表示します。SMI ひとつで Graph の呼び出しを行い、設定にはリクエストテンプレートと OAuth を含めます。UI は DEW UI（Meta のデフォルト） または Crayons（バニラ版を明示的に選択） とし、アイコンと README も用意します。

React Meta フレームワーク（デフォルト UI）

新しい UI アプリではデフォルトで使用します。ただし、ユーザーが Vanilla JS + Crayons を明示的に希望する場合を除きます。

トピック	ルール
スキャフォールド	/fdk-react-create または fdk create --template react-starter-template。フォールバックは assets/templates/react-meta-*-skeleton/
Vanilla から Meta への移行	/fdk-react-migrate（Platform 3.0 のみ。2.x では先に /fdk-migrate を実行）
マニフェスト	manifest.json のみに metaConfig.framework: "react" を設定
UI	@freshworks/dew-components + @freshworks/dew-styles（必須）
禁止事項（Meta）	@freshworks/crayons、Crayons CDN、<fw-*> — Meta ワークフローでは Crayons を使用しない
ルーター	ホーム／フォールバックは path="*"。機能ルートは /app/...
TypeScript	サポート対象 — .tsx／.ts、tsconfig.json は任意。React は 19+ を推奨
Tailwind／サードパーティ製	ユーザーが希望する場合は DEW と併用可能（MUI、Redux など）。validate／fix の際に削除しないでください
Vite	プロジェクトルートの vite.config.js は任意（FDK 10.1.5+）。FDK はディープマージを行います — エントリーポイントと app／config のエイリアスでは FDK が優先されます

全パターンについては、rules/react-meta-patterns.mdc、references/react-meta/dew-components.md を参照してください。

---

ステップ 1：アプリの種類を判断する

Hybrid／Frontend を優先	Serverless のみを優先
UI、プレースメント、ダッシュボード、同期ステータス、再同期、iparams 以外の設定がある場合、またはユーザーが「sync」と言った場合（serverless を強く希望している場合を除く）	純粋な自動化、監視なし、Webhook の fire-and-forget、ユーザーが「no UI」／「background only」と言った場合、通知のみ

デフォルト： 判断に迷う場合は Hybrid を選択します。「UI は必要ですか？」と尋ねないでください — 表に従ってください。曖昧さの解消： rules/confusion.mdc。

UI? → yes → user asked vanilla JS? → yes = vanilla Frontend/Hybrid/OAuth skeletons
UI? → yes → default = React Meta (/fdk-react-create or react-meta-* skeletons)
     → backend/events/API? → yes = react-meta-hybrid or react-meta-oauth
     → no  = react-meta-frontend
UI? → no  → backend/events?      → yes = Serverless, no = invalid

外部 API → React Meta Hybrid + requests.json、OAuth → react-meta-oauth-skeleton。Vanilla の同等テンプレートは、明示的に希望された場合に使用できるよう *-skeleton/ の下に引き続き用意されています。

ステップ 2：テンプレートを選択してファイルを生成する

デフォルト（React Meta）： /fdk-react-create または fdk create --template react-starter-template。rules/react-meta-patterns.mdc と references/react-meta/ を参照してください。

テンプレートフォルダー	使用するケース	主な成果物
assets/templates/react-meta-frontend-skeleton/	UI のみの場合のデフォルト	metaConfig、package.json、DEW、app/index.jsx、README.md
assets/templates/react-meta-hybrid-skeleton/	UI + SMI + API の場合のデフォルト	上記 + server/、config/requests.json
assets/templates/react-meta-oauth-skeleton/	UI + OAuth の場合のデフォルト	上記 + config/oauth_config.json
assets/templates/serverless-skeleton/	UI なし、イベント／自動化	server/server.js、manifest.json、README.md
assets/templates/frontend-skeleton/	Vanilla JS を明示的に希望する場合	Crayons CDN、app/scripts/app.js
assets/templates/hybrid-skeleton/	Vanilla Hybrid を明示的に希望する場合	Crayons + サーバー
assets/templates/oauth-skeleton/	Vanilla OAuth を明示的に希望する場合	Crayons + OAuth 設定

推奨パターンのレシピ（Slack webhook、Microsoft Graph OAuth）： references/playbooks/README.md — 複数のドキュメントを行き来する代わりに、プレイブックを1 つ読み込んでください。

重要：すべてのアプリで README.md は必須です。検証の前に作成してください。

ステップ 3：検証と自動修正（必須）

重要：すべてのエラーを修正してください — Platform エラーと Lint エラーの両方です。エラーは一切許容されません。

すべてのアプリファイル（README.md を含む）を作成した後、必ず自動的に次の処理を行ってください：

1. README.md が存在することを確認 - 存在しない場合は、検証の前に今すぐ作成します
2. アプリディレクトリで fdk validate を実行します（ユーザーに実行を依頼しないでください）
   • 10.0.1 + 24.11.0 で fdk validate を実行できない場合： まず fw-setup を試します。エンジンのダウングレードは最終手段としてのみ使用し、TOOLCHAIN, SIX fdk validate ITERATIONS… に記載の条件を満たした後に限ります（最初の手段として使用しないでください）。
3. 検証出力を解析 - プラットフォームエラーと lint エラーのすべてを特定します
4. 自動修正のイテレーション 1 を試行（すべてのエラー）:
   • JSON 構造エラーを修正します（トップレベルオブジェクトが複数ある場合 → 統合）
   • カンマの配置を修正します（カンマが不足している場合 → 追加、末尾のカンマ → 削除）
   • テンプレート構文を修正します（{{variable}} → <%= context.variable %>）
   • 必須ファイルが不足している場合は作成します（Meta: app/icon.svg、vanilla: app/styles/images/icon.svg、常に: config/iparams.json、README.md）
   • FQDN の問題を修正します（パスを含むホスト → FQDN のみ）
   • パスの問題を修正します（/ がない場合 → / を先頭に追加）
   • fdk validate を再実行します
5. まだ失敗する場合、自動修正のイテレーション 2 を試行（致命的なエラーのみ）:
   • マニフェスト構造の問題を修正します（モジュールが間違っている、宣言が不足している）
   • リクエストテンプレートの宣言を修正します（マニフェストで宣言されていない）
   • 関数の宣言を修正します（マニフェストで宣言されていない）
   • OAuth 構造を修正します（integrations ラッパーがない、oauth_iparams の場所が間違っている）
   • ロケーションの配置を修正します（ロケーションに対するモジュールが間違っている）
   • fdk validate を再実行します
6. イテレーション後（最大 6 回）:
   • [VALID] すべてのエラー（プラットフォームと lint）が解消された場合 → 簡潔な成功メッセージを提示します
   • [WARNING] エラーが残っている場合 → イテレーションを続け、エラーがある状態で「完了」と決して伝えないでください

成功メッセージのテンプレート: references/templates/validation-success.txt 明示的に依頼されない限り、検証レポートや詳細な要約は作成しないでください。

修正対象（プラットフォームエラー） - ブロッキング:

• [VALID] JSON 解析エラー
• [VALID] 必須ファイルの不足
• [VALID] マニフェスト構造エラー
• [VALID] リクエストテンプレートのエラー（FQDN、パス、スキーマ）
• [VALID] マニフェスト内の宣言不足
• [VALID] OAuth 構造エラー
• [VALID] ロケーション配置エラー
• [VALID] manifest.json 内の "name" フィールド → 削除

修正対象（lint エラー） - こちらもブロッキング:

• [VALID] await のない async → async キーワードを削除するか、実際の await を追加
• [VALID] 未使用のパラメーター → パラメーターを完全に削除（_args ではありません）
• [VALID] 到達不能なコード → return の後にあるデッドコードを削除
• [VALID] 関数の複雑度 > 7 → ヘルパー関数を抽出
• [VALID] セミコロンの不足 → セミコロンを追加

重要なルール:

• [INVALID] ユーザーに fdk validate の手動実行を決して依頼しないでください
• [VALID] ファイル作成後は必ず自動的に検証を実行してください
• [VALID] 必ず最大 6 回の修正イテレーションを試してください
• [VALID] 各修正イテレーション後は必ず fdk validate を再実行してください
• [VALID] プラットフォームエラーと lint エラーの両方を修正してください - どちらもブロッキングです
• [INVALID] エラーが 1 つでも残っている状態で「アプリが完成しました」と決して伝えないでください

参照: rules/validation-workflow.mdc（自動修正パターン）。

OAuth と API キー、OAuth/iparams の完全な JSON パターン、安全な iparams、onAppInstall/onAppUninstall: references/skill-advanced-topics.md + references/architecture/oauth-configuration-latest.md + references/api/oauth-docs.md。

アプリのツリー: React Meta → references/react-meta/react-meta-fdk-standards.md; vanilla フロントエンド → references/templates/frontend-app-tree.txt; serverless → references/templates/serverless-app-tree.txt; OAuth → app/ + server/ + config/oauth_config.json + config/requests.json + config/iparams.json。 Crayons CDN（vanilla JS のみ）: references/templates/crayons-cdn.html。

ステップ 4：テストパターンに照らして検証する

アプリを提示する前に、以下に照らして検証してください。

• references/tests/refusal.json - 禁止されたパターンが含まれていないこと
• references/tests/golden.json - 推奨されるパターンに従っていること

---

段階的な情報開示（リファレンスインデックス）

プラットフォームのドキュメント： まず get_developer_docs を使用してください。MCP を利用できない場合や、リポジトリ固有のプレイブック／適用ルールが必要な場合は、以下のインデックスを使用してください。

references/ のパス一覧： references/skill-advanced-topics.md。React Meta のインデックス： references/react-meta/README.md。Crayons CDN（バニラ JS のみ）： references/templates/crayons-cdn.html

---

重要な検証項目（必ず確認）

ファイル構成

確認項目	要件
アイコン	マニフェストで宣言されたパスに存在すること（Meta：多くの場合 app/icon.svg、バニラ：app/styles/images/icon.svg）
UI スタック	Meta → DEW、Crayons は使用しないこと。バニラ → HTML で Crayons CDN を使用すること
metaConfig	Meta アプリ：manifest.json で framework: "react" を指定すること
ルーター	Meta アプリ：path="*" のフォールバックルートを指定すること
Engines	Meta： fdk 10.1.0 + node 24.11.0；バニラ／サーバーレス： fdk 10.0.1 + node 24.11.0；非推奨の 9.8.2 + 18.20.8 は LAST RESORT の場合に限る
製品モジュール	製品モジュールが少なくとも 1 つあること（{} でも可）
Iparams	次のいずれか一方のみ：config/iparams.json またはカスタム iparams.html + アセット。両方は不可

マニフェストの検証

確認項目	要件
バージョン／形式	"platform-version": "3.0"、modules は product ではないこと
リクエスト／関数	すべてのテンプレートと SMI キーを modules.common の下で宣言すること
ロケーション	製品ロケーションは製品モジュールに記述し、common には記述しないこと
OAuth	OAuth を使用する場合は integrations ラッパーを使用すること
スケジュール	マニフェストにスケジュールイベントを記述しないこと — $schedule.create() を使用すること
ライフサイクル	空でない iparams がある場合は onAppInstall を使用すること。クリーンアップが必要なアプリでは onAppUninstall を使用すること
onAppInstall ガード	iparams がある場合は onAppInstall ハンドラーを追加すること。検証ロジックの前に、ハンドラー内で iparams が空でないことを確認するガードを設けます（例：if (args.iparams && Object.keys(args.iparams).length > 0) { ... }）

コード品質

確認項目	要件
パラメーター／非同期処理	未使用のパラメーターを残さないこと。async は await がある場合にのみ使用すること。フロントエンドの初期化では IIFE を使用すること
リクエスト／エクスポート	$request.invokeTemplate のみを使用すること。ヘルパーは exports の後に配置すること
制御フロー	複雑度 ≤ 7。到達不能コードがないこと
エラー	非同期処理を try/catch で囲むこと。SMI／イベントでは rules/async-patterns.mdc に従って renderData を使用すること
コメント	SMI には簡潔なコメントを付けること。自明でないロジックのみ説明すること

セキュリティ（rules/security.mdc を参照）

確認項目	要件
入力	SMI 引数を検証すること。列挙型の操作には許可リストを使用すること
インジェクション	ユーザー入力に対して eval／executeCommand／runScript を使用しないこと
ロギング	args.iparams や args 全体を記録しないこと
XSS／シークレット	textContent を使用するかサニタイズすること。ノートや UI にシークレットを含めないこと

UI コンポーネント

スタック	使用するもの	使用しないもの
React Meta（デフォルト）	@freshworks/dew-components + @freshworks/dew-styles	Crayons CDN、<fw-*>
バニラ JS（オプトイン）	fw-button、fw-input、fw-select、fw-textarea	通常の <button>、<input> など

バニラ Crayons のドキュメント：references/ui/crayons-docs/{component}.md · Meta：references/react-meta/dew-components.md

重大：アプリフォルダー作成ルール

アプリは必ず親ディレクトリに新しいフォルダーを作成して、その中に作成してください。

• [INVALID] 現在のワークスペースのルートにアプリのファイルを直接作成しないでください
• [VALID] 必ず新しいフォルダー（例：my-app/、zapier-sync-app/）を作成してください
• [VALID] アプリのファイルはすべて、この新しいフォルダー内に作成してください
• フォルダー名は、アプリ名をもとにしたケバブケースにしてください

例：

# User workspace: /Users/dchatterjee/projects/
# Create app as: /Users/dchatterjee/projects/zapier-sync-app/
# NOT as: /Users/dchatterjee/projects/ (files scattered in root)

---

生成前の拡張チェックリスト（番号付き）、重複するエラー防止リスト、自動修正の反復に関する詳細、JSON マージの例： references/skill-advanced-topics.md。運用ワークフロー： rules/validation-workflow.mdc。エラーカタログ： references/errors/error-catalog.md。

アプリの完了条件 — 必須

［警告］許容範囲ゼロ：すべての条件を満たさない限り、アプリは決して完成とは見なせません。

条件	チェック項目
1 – ファイル	manifest.json；config/iparams.json；Meta フロントエンド： app/index.html、app/index.jsx、app/icon.svg；vanilla フロントエンド： app/index.html、app/scripts/app.js、app/styles/images/icon.svg；サーバーレス：server/server.js
2 – マニフェストとディスクの整合性	すべての url／icon パスが存在すること；イベント／関数は server/server.js を参照すること；events.*.handler と functions のキーが exports と一致すること；SMI は renderData を使用すること（rules/async-patterns.mdc）；requests.json の各キーが modules.common.requests に含まれていること
3 – マニフェスト JSON	platform-version が 3.0 であること；functions／requests／events ブロックが空でないこと；宣言された関数／イベント／リクエストの実装があること
4 – OAuth（使用する場合）	すべての oauth_iparam フィールドに display_name、token_type、description が設定されていること
5 – コード品質	複雑度 ≤ 7；非同期処理では await のみを使用すること；未使用のパラメーターがないこと
6 – 検証	fdk validate：プラットフォームエラー 0 件、lint エラー 0 件

いずれかの条件を満たさない場合： アプリを完成と見なさず、修正して fdk validate を再実行してください。

---

生成後のメッセージ

アプリの生成または移行に成功した後は、references/templates/post-generation-message.txt を使用してください。

スキルの振り分け（必須 — 汎用的なレビューや FDK のドキュメントで代用しないでください）：

ユーザーの意図	振り分け先	不可
アプリのレビュー／監査	fw-review スキル（そのスキルに従った構造化レポート）	汎用的なコードレビュー、スキルを使わないこと
パッケージ化／公開／アップロード	fw-review の後に fw-publish スキル	ドキュメントだけを頼りに fdk pack を直接実行すること
vanilla → Meta への移行	vanilla の 3.0 アプリに限り /fdk-react-migrate	すでに Meta に移行済みのアプリを再移行すること

任意の MCP（未設定の場合は 1 回のみ）： references/examples/mcp-availability-check.md に従って確認し、references/templates/mcp-config-prompt.txt のプロンプトを使用します。YES の場合 → AGENTS.md + skills/fw-publish/SKILL.md。

自動生成しないでください：

• [INVALID] 詳細な検証レポート（.validation-report.md）
• [INVALID] アプリの概要ドキュメント（APPS-SUMMARY.md）
• [INVALID] 大規模な機能一覧や比較
• [INVALID] 複数の小見出しを含む長い「次のステップ」セクション

ユーザーから明示的に依頼された場合にのみ生成してください：

• [VALID] 「検証レポートを作成してください」
• [VALID] 「概要ドキュメントを生成してください」
• [VALID] 「詳細なドキュメントを作成してください」
• [VALID] 「アプリを比較してください」

生成後の出力は最小限にし、直近の次のステップに焦点を当ててください。

---

ドキュメント生成ルール

常に作成	ユーザーから依頼があった場合のみ
manifest.json、config/*、README.md	.validation-report.md、APPS-SUMMARY.md、ARCHITECTURE.md、CHANGELOG.md
テンプレートに応じた app/ および／または server/server.js	.gitignore、package.json（FDK では不要）

デフォルト：必須ファイルと簡潔な README.md のみ。

---

インストール、テスト、製品モジュール

スキルのインストールコマンド： README.md。構造テスト： references/tests/refusal.json、references/tests/golden.json（references/skill-advanced-topics.md に概要を記載）。モジュールと配置場所（正式な情報）： rules/platform3-modules-locations.mdc。簡易マッピングは references/skill-advanced-topics.md に記載されています。

---

制約（自動適用）

• 厳格モード： Platform 2.x のパターンは常に拒否します
• ソースなしで推測しない： プラットフォームに関する事実については、まず get_developer_docs を試します。MCP を利用できない場合は、references/ / rules/ を参照し、その後にのみ「プラットフォームに関する確証が不十分です」と回答します
• ターミナルログはバックエンドのみ： console.log は server/server.js でのみ使用し、フロントエンドでは使用しません
• 本番環境で使用できる品質のみ： 完全でデプロイ可能なアプリを生成します
• 禁止パターン： 拒否テストに記載されています
• 必須パターン： SKILL.md の検証表および rules/freshworks-platform3.mdc に従います

---

サーバーレスイベント、リクエスト、ジョブ

イベント： references/events/event-reference.md — 必要に応じて onAppInstall / onAppUninstall を使用します。製品イベントはモジュールの events に定義します。スケジュールには $schedule.create() のみを使用します。onTicketUpdate（Freshdesk / Freshservice）： references/events/onTicketUpdate-payload-contract.md。サンプル：references/test-payloads/server/test_data/support_ticket/onTicketUpdate.json、.../service_ticket/onTicketUpdate.json。

リクエストテンプレートと OAuth： references/architecture/request-templates-latest.md、oauth-configuration-latest.md、references/api/request-method-docs.md（FQDN ホスト、/ パス、<%= %>、options.oauth）。API 統合パターン： references/api-integration-examples.md（ページネーション、レート制限、エラー処理、認証パターン、実例）。

ジョブ： references/runtime/jobs-docs.md — modules.common.jobs の下に宣言します。ジョブハンドラーでは renderData を使用しません。

タスク → 読み込み順（最大約 5 ファイル）

プラットフォーム API / イベント / マニフェストの動作については、references/ を開く前に get_developer_docs を呼び出してください。MCP を利用できない場合、またはタスクでリポジトリ内のプレイブック、テンプレート、適用ルールが必要な場合は、次の順序を使用します。

タスク	順に読む
新しいハイブリッド + 外部 HTTP	references/playbooks/README.md（プレイブックまたはハイブリッドテンプレートを選択）→ references/architecture/request-templates-latest.md → rules/async-patterns.mdc
新しい OAuth + 外部 API	references/playbooks/microsoft-graph-account-oauth.md（または OAuth テンプレート）→ references/architecture/oauth-configuration-latest.md → references/architecture/request-templates-latest.md → rules/async-patterns.mdc
チケットのサーバーレスイベント / フィルター	references/events/onTicketUpdate-payload-contract.md → references/test-payloads/README.md → 製品モジュールのドキュメント（freshdesk_support_ticket.md または freshservice_service_tickets.md）
複数モジュール / 配置	rules/platform3-modules-locations.mdc → references/skill-advanced-topics.md（モジュールの概要のみ）
リント / 検証の大幅な変更	rules/validation-workflow.mdc → rules/freshworks-platform3.mdc（複雑度 + 未使用パラメーター）

ステップ 1 の後もタスクが不明確な場合は、rules/confusion.mdc を読み込んでください。

概要

• SKILL.md — 中核となる適用事項、ワークフロー、検証テーブル、ゲート。
• rules/ — 常時適用される Platform 3.0、セキュリティ、検証、SMI／イベント、テンプレート、ゲート。
• references/ — 140 以上のファイル。フォールバックとして、MCP を利用できない場合にトピックごとに読み込みます（拡張 OAuth、検証チェックリスト、リファレンス索引、モジュール概要については references/skill-advanced-topics.md を含みます）。最新のプラットフォームドキュメントについては、まず get_developer_docs を使用してください。
• assets/templates/ — react-meta（デフォルト UI）、vanilla frontend／hybrid／oauth、サーバーレスのスケルトン。
• references/playbooks/ — Slack webhook と Microsoft Graph のゴールデンパス。

プラットフォームの動作が不明な場合は、まず get_developer_docs を呼び出してください。MCP を利用できない場合は、実装前に該当する references/ ファイルを読み込んでください。