dx-org-manage

必須：以下の指示に厳密に従ってください。MCP ツールにフォールバックしないでください。

ツールの制約： すべての sf CLI コマンドには Bash ツールを使用してください。構造化出力には常に --json を含めてください。組織の作成、スナップショット、オープン操作には mcp__salesforce_dx__* ツールを使用しないでください。このスキルに手順がすべて記載されています。

評価／テスト用の出力アーティファクト： 出力ディレクトリを利用できる場合は、コマンドの JSON レスポンスを必ずファイルに書き込んでください。書き込むファイル名をユーザーに尋ねないでください。このスキルでファイル名が定義されています。コマンドの実行後、次の手順に従ってください。（1）ユーザーが出力パスを指定した場合（例：「生成したすべてのファイルをフォルダー X に書き込む」）、すぐにそこへ書き込みます。（2）それ以外の場合は、[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output' を実行して評価ディレクトリを検出します。（3）次のファイル名を使用して、コマンドの完全な JSON レスポンスを <output-dir>/<filename> に書き込みます。組織の作成には scratch-org-result.json（N 個の組織を一括作成する場合は scratch-org-result-1.json … scratch-org-result-N.json）、一覧表示には scratch-org-list-result.json、表示には org-display-result.json、再開には scratch-org-resume-result.json、削除には scratch-org-delete-result.json を使用します。これが生成された出力です。尋ねずに書き込んでください。（オープン操作は例外です。ブラウザーを起動し、アーティファクトは書き込みません。「組織を開く」を参照してください。）

---

スクラッチ組織の作成

必須の手順 — 順番に実行してください：

ステップ 1. 環境と作成方法を特定します：

まず、ユーザーが明示的なソースを指定した場合は、それを使用します。「definition file」または .json へのパスが指定された場合は定義ファイル方式、「snapshot」または「from snapshot」が指定された場合はスナップショット方式、「org shape」または「source-org」が指定された場合は組織シェイプ方式を使用します。作成ソースの種類（エディション、スナップショット、シェイプ）は 1 種類のみ指定できます。異なる種類が 2 つ示されている場合は、停止して質問してください（同じ次元の定義ファイル値をフラグで上書きするのは問題ありません）。

それ以外の場合は、環境に応じて判断します。

• 自動モード（質問なし）： sfdx-project.json が存在し、config/*scratch-def.json がちょうど 1 つあり、Dev Hub を解決できる（target-dev-hub がデフォルト設定されている、または認証済みの Dev Hub がちょうど 1 つある）場合は、そのファイル、解決した Dev Hub、導出したエイリアス、CLI のデフォルト設定を使用して、すぐに作成します。質問は不要です。 このモードでも一括作成数に従います（下記参照）。
• 状態 A（プロジェクト内）、自動モードではない場合： config/*scratch-def.json を列挙します。ファイルが 0 個の場合は、デフォルトで --edition developer を使用します（機能や設定が必要な場合は、後述のとおりファイルを作成します）。ファイルが 1 個の場合は、それを使用します。複数ある場合は、どれを使うか尋ねてください（黙って選ばないでください）。
• 状態 B（sfdx-project.json がない場合）： 処理を止めたり、使い捨ての組織を黙って作成したりしないでください。ガイド付きの 3 つの選択肢を提示します（プロジェクトを指定する／sf template generate project --name <name> でプロジェクトを作成する／ここで使い捨ての組織を作成し、ソースを案内する）。references/scratch-org-create.md を参照してください。

一括作成 — 「スクラッチ組織を N 個作成」： ネイティブの個数指定フラグはありません。作成コマンドを N 回繰り返し、それぞれ異なるエイリアス（<base>-1 … <base>-N）を使用します。既存の組織を誤って参照し直さないよう、各エイリアスの衝突を確認してください。各組織を報告し、組織ごとにアーティファクトを 1 つ書き込みます。途中で Dev Hub の上限エラーが発生した場合は、CLI のエラーを変更せずに提示し、すでに作成に成功した組織を報告してください。

定義ファイルの作成： 機能や設定が要求されていて、適切なファイルが存在しない場合は、目的に合った新しい定義ファイルを作成します（既存ファイルをベースにして変更し、文書化されたフィールドのみを使用し、既存ファイルを上書きしない）。内容を表示してから、そのファイルを使って作成します。非対話型／評価環境では、編集の確認を待たずにファイルを作成し、そのまま作成処理を進めてください。 詳細は references/scratch-org-create.md と references/definition_file_options.md を参照してください。

ステップ 2. Dev Hub を具体的な値に解決し、その値を明示的に渡します。 Dev Hub を実際のユーザー名またはエイリアスに一度だけ解決し、ステップ 3 の各コマンドで、その値を --target-dev-hub に指定してください。解決の優先順位：

1. ユーザーが明示的に名前を指定した Dev Hub → 指定された名前をそのまま使用します。
2. それ以外の場合のデフォルト： sf config get target-dev-hub --json の result[0].value が空でない場合、その値を使用します。

   sf config get target-dev-hub --json
   

3. それ以外の場合は、認証済みの Dev Hub が1つだけ存在する場合です。 次のコマンドをそのまま実行してください。独自のフィルターを手書きしてはいけません。Dev Hub は sf org list のどのバケット（devHubs、nonScratchOrgs、other、sandboxes、scratchOrgs）にも表示される可能性があります。1つのバケットのみを確認するフィルター（例：.other[] のみ）では見落とし、ハブが存在しないと思い込むことになります。

   sf org list --json | jq -r '[.result.devHubs[]?, .result.nonScratchOrgs[]?, .result.other[]?, .result.sandboxes[]?, .result.scratchOrgs[]?] | map(select(.isDevHub == true).username) | unique | .[]'
   

   • ユーザー名がちょうど1つ表示された場合 → それを使用します。
   • 何も表示されなかった場合 → 認証済みのハブはありません。sf org create は絶対に実行しないでください — --target-dev-hub に渡す値がなく、作成を試みても失敗します。代わりに、ここで停止します。sf org login web --set-default-dev-hub を案内し、出力ディレクトリが利用できる場合は、その案内を成果物として書き出します。Step 3 に進まないでください。
   • 2つ以上表示された場合 → どれを使用するかユーザーに確認します（任意に選ばないでください）。

• Dev Hub 名を決して作り出したり、推測したりしないでください。 プレースホルダーのエイリアス（例：eval-target、my-dev-hub、DevHub）を捏造することが、評価で最もよくある失敗です。CLI は NotADevHubError を返して正しく拒否します。上記のコマンドで何も表示されない場合、この環境にはDev Hub が存在しないという意味であり、代わりの名前を指定すべきという意味ではありません。推測で作れる有効な代替名はありません。ハブを特定できない場合は値を推測するのではなく、処理を停止してください。作り上げた --target-dev-hub を指定して sf org create scratch を実行してはいけません。また、--target-dev-hub フラグなしで実行してもいけません（NoDefaultDevHubError が発生します）。停止して、sf org login web --set-default-dev-hub を案内してください。
• 一部の CLI 設定では、デフォルトの target-dev-hub がディレクトリ単位の場合があります（cd 後に sf config get が空を返すことがあります）。そのため、Step 3 で全バケットを確認する sf org list が信頼できる代替手段となります。この確認はディレクトリ単位ではありません。
• 具体的な Dev Hub の値が確定するまで、先に進まないでください。

Step 3. コマンドを組み立てて実行します（方法に応じて選択）：

定義ファイル：

sf org create scratch --definition-file <path> --target-dev-hub <alias> --alias <name> --json

エディションのみ：

sf org create scratch --edition developer --target-dev-hub <alias> --alias <name> --json

スナップショットから：

sf org create scratch --snapshot <snapshot-name> --target-dev-hub <alias> --alias <name> --json

組織の形状から：

sf org create scratch --source-org <source-org-id> --target-dev-hub <alias> --alias <name> --json

--source-org には15文字のソース組織 ID、つまり形状を取得した組織の ID（00D… の組織 ID）を指定します。sf org list shape に表示される 3SR… の形状レコード ID ではありません。ユーザーから渡された ID は変更せずに渡してください。CLI がその ID を拒否した場合（例：InvalidIdLengthError、InvalidPrefixError）、エラーをそのまま提示して停止してください。切り詰めたり、形式を変えたり、推測したり、別の ID で再試行したりしてはいけません。

要求された場合は、次のフラグを適用します：

• --duration-days <days> — デフォルトは7、最大30
• --set-default — この組織をデフォルトに設定します
• --no-track-source — ソース追跡を無効にします（CI/CD 用）

Step 4. 必須 — org list を実行して出力を書き出します（成功時のみ）： この手順は、Step 3 で組織の作成に成功した場合のみ実行します。Step 3 でエラーが返された場合は、この手順をスキップして、代わりに以下のエラー処理に従ってください。組織の作成後、必ず次のコマンドを実行してください：

sf org list --json

次に：

1. JSON の結果を解析し、scratchOrgs 配列を見つけます
2. Step 3 の作成結果から得たユーザー名と username が一致するエントリを見つけます
3. その組織オブジェクト全体を抽出します（alias、username、orgId、instanceUrl、loginUrl、isDefaultUsername、orgEdition、status、expirationDate、devHubUsername、および CLI が返すその他のフィールドが含まれます）。
4. ユーザーに次の情報を報告します：
   • スクラッチ組織を作成しました。
   • エイリアス：[組織リストのエントリから取得したエイリアス]
   • ユーザー名：[ユーザー名]
   • 組織 ID：[orgId]
5. 出力ディレクトリが利用可能な場合（上記の出力アーティファクトのルールに従います）、抽出した組織オブジェクトを <output-dir>/scratch-org-result.json にそのまま書き込みます。このスキルはパススルーラッパーです。CLI がその組織について返すすべてのフィールドを書き込みます。非シークレットフィールドを選別、許可リスト化、削除してはいけません（例：instanceName、createdOrgInstance、signupUsername、orgName、edition は、CLI がそのまま返す非シークレットのメタデータです。保持してください）。出力してはならないのは、実際に有効なシークレットだけです。accessToken と sfdxAuthUrl は CLI が --json 出力で既にマスキングしており（"[REDACTED] …" として返されます）、そのマスキングをそのまま保持し、マスキングを解除したり実際の値を再導出したりしないでください。

例：sf org list --json が {"result": {"scratchOrgs": [{"alias": "feature-dev", "username": "[email protected]", "orgId": "00D...", ...}]}} を返す場合、内側の組織オブジェクト {"alias": "feature-dev", "username": "[email protected]", "orgId": "00D...", ...} を、その組織の完全なオブジェクトとしてファイルに書き込みます。

生の作成コマンドのレスポンスではなく、抽出した組織リストのエントリー（解決済みの組織レコード）を書き込みます。ユーザーに確認手順を提案してはいけません。

エラー処理（Step 3 の作成に失敗し、組織が作成されなかった場合）： CLI のエラー出力を一字一句そのままユーザーに提示します（書き換え、再試行、定義ファイルの編集はしません）。Step 4 は実行しません（リスト表示または抽出する組織がありません）。出力ディレクトリが利用可能な場合は、作成コマンドの生のエラー JSON をそのまま <output-dir>/scratch-org-result.json に書き込みます。これはコマンドのレスポンスであり、失敗した実行の出力アーティファクトです。（バッチの場合は、失敗した組織のアーティファクトにエラーを書き込み、失敗前に既に成功していた組織の成功エントリーも引き続き書き込みます。）次に、CLI のエラーが以下のいずれかに該当する場合は、対応する案内を追加します。

• "Snapshot not found" → sf org list snapshot --target-dev-hub <alias> を提案します
• "No default Dev Hub" → sf org login web --set-default-dev-hub を案内します

詳細が必要な場合：

• 作成ワークフロー全体（AUTO MODE、STATE A/B、バッチ、定義ファイルの作成）については references/scratch-org-create.md を読み込みます。リスト表示／詳細表示／再開／削除については references/scratch-org-operations.md を読み込みます
• 利用可能な機能、設定、定義ファイルの構造については references/definition_file_options.md を読み込みます
• エディションの選択に関するガイダンスと比較については references/edition_types.md を読み込みます
• ここで参照する前にスナップショット自体を作成／確認／一覧表示／削除するには、dx-org-snapshot-manage スキルを使用します

---

Scratch Org の一覧表示

Step 1. 実行：

sf org list --json

Step 2. 結果の報告と出力の書き込み： デフォルト表示は result.scratchOrgs[] にあるアクティブな Scratch Org です。各組織について alias／username／orgId／有効期限を報告します。--all（期限切れ／削除済みを含む）と --clean はオプションとして説明し、デフォルトにはしません。result.scratchOrgs[] の配列を <output-dir>/scratch-org-list-result.json に書き込みます（出力アーティファクトのルールに従います）。

詳細： references/scratch-org-operations.md。

---

組織の詳細表示

Step 1. 実行：

sf org display --target-org <alias> --json

Step 2. 結果の報告と出力の書き込み： alias／username／orgId／instanceUrl／status／有効期限を報告します。ラップされた {status, result} JSON を <output-dir>/org-display-result.json に書き込みます。ラップを解除してはいけません。コミットされるサンプル／gold では、accessToken と sfdxAuthUrl をマスキングする必要があります（値は [REDACTED] で始まります）。

--verbose： 決して追加せず、このスキルから実行してはいけません。エージェントのコンテキストに sfdxAuthUrl（リフレッシュトークン）が返されます。認証 URL が必要な場合は、ユーザー自身のターミナルで sf org display --verbose を実行するよう伝えてください。

詳細： references/scratch-org-operations.md。

スクラッチ組織の作成を再開する

--async を指定して実行した場合、またはタイムアウトした場合（終了コード 69）。

ステップ 1. 実行します：

sf org resume scratch --job-id <id> --json

ユーザーが明示的に --job-id を指定した場合はそれを使用し、指定していない場合は --use-most-recent を既定値として使用します。最近のジョブがない場合は、CLI の not-found 結果をそのまま提示し、sf org list を案内してください。ジョブ ID を捏造してはいけません。

ステップ 2. 出力を書き込みます： コマンドの JSON をそのまま <output-dir>/scratch-org-resume-result.json に書き込みます。

詳細： references/scratch-org-operations.md。

---

スクラッチ組織を削除する

破壊的な操作です。元に戻せません。

ステップ 1. 実行前に確認します。 明示的に削除する意図をユーザーがすでに示していない限り、「スクラッチ組織 X を削除しますか？」と尋ね、確認を待ちます。対象が現在のデフォルト組織の場合は、確認時にその旨も伝えます（追加の安全措置）。

ステップ 2. 実行します（確認後のみ）：

sf org delete scratch --target-org <alias> --no-prompt --json

--no-prompt は、スキル側で確認した後に渡すため、エージェントが CLI の対話型プロンプトで待ち続けることはありません。

ステップ 3. 出力を書き込みます： コマンドの JSON をそのまま <output-dir>/scratch-org-delete-result.json に書き込みます。

詳細： references/scratch-org-operations.md。

---

組織を開く

必須の手順です。順番どおりに実行してください：

ブラウザーの起動のみ — --json と --url-only は絶対に使用しないでください。 このスキルで成果物を書き込まない操作は、Open のみです。通常の sf org open は、ログイン URL を出力せずにブラウザーを起動してユーザーをログインさせるため、認証情報がエージェントのコンテキストやファイルに入ることはありません。--json を追加してはいけません。sf org open --json は result.url に有効なログイン URL（/secur/frontdoor.jsp?otp=／sid=<token>）を返します。これは認証情報と同等のものです。これをコンテキストに取り込むこと（書き込む前に秘匿化する場合も含む）は、通常のコマンドなら防げる S1 の漏えいそのものです。同じ理由で --url-only も禁止です。ユーザーがブラウザーではなく URL を明示的に求めた場合（例：「URL のみ」「リンクだけ教えて」「ヘッドレス／リモート」）は、実行してはいけません。ユーザー自身のターミナルで sf org open --url-only を実行するよう伝えてください（sf org display --verbose と同じ対応です）。「自分の組織を開いて」という曖昧な依頼の場合は、ブラウザーを開くだけです。

ステップ 1. ユーザーの依頼に対応するコマンドを選びます：

ユーザーの希望	コマンド
デフォルト組織を開く	sf org open
特定の組織を開く	sf org open --target-org <alias>
特定のブラウザーを使う	sf org open --browser chrome
シークレットモード	sf org open --private
パスに移動する	sf org open --path '<path>'
メタデータファイルを開く	sf org open --source-file <file-path>
URL のみ	実行してはいけません。 スキルから出力してはいけない有効なログイントークンが返されるため、ローカルで sf org open --url-only を実行するようユーザーに伝えてください。

ステップ 2. Bash ツールを使って、該当するコマンドを実行します。 通常の sf org open は成功時に何も出力しません。これは想定どおりです。

ステップ 3. 結果を報告します： 組織（またはパス／メタデータファイル）がブラウザーで開かれたことをユーザーに伝えます。Open 操作では書き込む成果物はありません。org-url-result.json やその他のファイルを書き込んではいけません。また、成果物を作成するために --json を追加してはいけません。コマンドでエラーが発生した場合は、以下のエラー処理に従ってその内容を提示してください。

エラー処理：

• 「no target org」→ sf config set target-org <alias> を案内します
• 「auth error」→ sf org login web --alias <alias> を案内します

詳細が必要な場合：

• 組織を開くワークフローの全体と使用可能なすべてのフラグについては、references/opening-org.md を読み込みます

---

リファレンスファイル一覧

詳細なガイダンスについては、以下のリファレンスファイルを読み込んでください。

ファイル	読むタイミング
references/scratch-org-create.md	スクラッチ組織の作成（エディション、定義ファイル、スナップショット、組織の形状）、AUTO MODE、STATE A/B プロジェクトの処理、一括作成、定義ファイルの作成
references/scratch-org-operations.md	既存の組織の操作：一覧表示、詳細表示、再開、削除 — および共通のライフサイクルルールとトラブルシューティング
references/definition_file_options.md	基本的な組織作成以外に、組織の機能、設定、または高度な定義ファイルオプションを構成する必要がある場合
references/edition_types.md	選択するエディションについて尋ねられた場合、またはエディションの違いを把握する必要がある場合
references/opening-org.md	特定の設定パスへの移動、メタデータファイルを開く操作、高度なオープンフラグの使用が必要な場合

スナップショット自体を作成、確認、一覧表示、削除する場合（単に使用するのではなく）は、dx-org-snapshot-manage スキルを使用してください。

サンプルファイル

テストとトラブルシューティングに使用するコマンド出力の例：

ファイル	用途
examples/scratch-orgs/success_definition_file.json	--definition-file を使用したスクラッチ組織の作成成功例
examples/scratch-orgs/success_edition.json	--edition developer を使用したスクラッチ組織の作成成功例
examples/scratch-orgs/success_snapshot.json	--snapshot を使用したスクラッチ組織の作成成功例
examples/scratch-orgs/success_shape.json	--source-org（組織の形状）を使用したスクラッチ組織の作成成功例
examples/scratch-orgs/error_no_devhub.json	Dev Hub が認証されていない場合のエラー
examples/scratch-orgs/error_timeout.json	組織の作成中に発生するタイムアウトエラー（終了コード 69）
examples/scratch-orgs/list_output.json	sf org list --json の出力（アクティブなスクラッチ組織の配列）
examples/scratch-orgs/display_output.json	sf org display --json の出力（ラップ済み、トークンはマスキング）
examples/scratch-orgs/resume_output.json	sf org resume scratch --json の出力（作成完了済みの組織）
examples/scratch-orgs/delete_output.json	sf org delete scratch --json の出力