planetscale-safe-orchestrator

PlanetScale セーフオーケストレーター（マスタースキル）

目的

PlanetScale の安全なベストプラクティスに関するスキルパック全体を、最初から最後まで実行します。各サブスキルを順番に読み込んで実行し、証拠を蓄積して、統一された推奨事項レポートを作成します。最初のパスは評価のみです。

必須の安全契約

デフォルトでは読み取り専用とします。

設定、ブランチ、クエリテレメトリー、推奨事項、Webhook、ロール、バックアップ、トラフィック予算、リポジトリのコードを調査できます。明示的に承認された変更セットがない限り、PlanetScale、データベース、リポジトリ、ネットワークのセキュリティ態勢、認証情報、スキーマ、本番トラフィック制御、自動化エンドポイントを変更してはなりません。

クラス C／D／E の変更には、../planetscale-change-gates-and-approval-contract/SKILL.md に従った承認が必要です。判断に迷った場合は、実行せずに停止し、提案する変更セットに追加してください。

例外が 1 つあります。オペレーターが ../planetscale-autonomous-execution-mode/SKILL.md に従ってリスクを明示的に了承し、スコープを指定した場合は、変更ごとの承認を求めて停止するのではなく、そのスキルに定められた状況報告と停止の規律に従って、自律的に実行を進めます。いずれの場合も、以下の評価フェーズは同じです。

サブスキルはこのスキルと同階層のフォルダーにあり、相対パスで参照されています。参照先のパスが存在しない場合は、frontmatter の name が一致する同階層のスキルを探して使用してください。

CLI と API の使い方は、推測せず、必ず公式ドキュメントに基づいてください。ドキュメントのインデックスは https://planetscale.com/docs/llms.txt にあります（ドキュメントの URL に .md を追加すると Markdown 版を参照できます）。API リファレンスは https://planetscale.com/docs/openapi.yaml です。コマンドまたはエンドポイントが失敗した場合は、証拠の不足を記録する前に、ドキュメントで正しい形式を確認してください。ツールやアクセスに関する失敗は内部実行ログに記録し、顧客向けレポートには記載しないでください。

開始前に

1. このファイルを最後まで読んでください。

2. 以下の進捗チェックリストを作業メモにコピーし、作業に合わせて更新してください。

3. 入力情報を収集してください（質問するか、AGENTS.md、MCP コンテキスト、環境、リポジトリから推測してください）。

   • 組織のスラッグ
   • データベース名
   • ブランチ名
   • エンジン：PlanetScale Vitess または PlanetScale Postgres
   • 本番ブランチ（複数可）
   • 接続されているアプリケーションリポジトリのパス（利用可能な場合）
   • アプリケーションの言語、フレームワーク、ORM、クエリビルダー、コネクションプーリング
   • オペレーターの許容範囲：レポートのみ、PR 作成、ブランチのみでのマイグレーション、または監督下での本番環境への適用

入力情報が不足している場合も、調査を続けてください。すべて揃うまで作業を止めないでください。

進捗チェックリスト

コピーして進捗を記録してください。

Master assessment progress:
- [ ] Phase 0: Safety contract loaded
- [ ] Phase 1: Read-only inventory
- [ ] Phase 2: Engine safety review (Vitess OR Postgres)
- [ ] Phase 3: Query Insights and tags
- [ ] Phase 4: Traffic Control (Postgres only — skip for Vitess)
- [ ] Phase 5: Webhook automation
- [ ] Phase 6: Schema recommendations agent loop
- [ ] Phase 7: Codebase SQLCommenter instrumentation
- [ ] Phase 8: MCP agent operating model
- [ ] Phase 9: Best-practices matrix coverage check
- [ ] Phase 10: Unified customer report
- [ ] Phase 11: Change gates verified — stop, no mutations

インターフェースの優先順位

1. PlanetScale MCP インサイト専用サーバー — クエリを実行せずに自律分析
2. 読み取り専用スコープの完全な PlanetScale MCP — スキーマまたは限定的な読み取りクエリ
3. pscale CLI と pscale api — 構造化されたインベントリと正確な API の状態
4. リポジトリの調査 — コードベースの分析と計測に関する推奨事項
5. 直接 SQL — オペレーターからデータベースの読み取りアクセスが許可された場合に限り、読み取り専用のイントロスペクションを実施

オペレーターが指定したインターフェース上の制約は、この優先順位に優先します。特定のインターフェースに実行を制限する場合（たとえば CLI のみ）、そのインターフェースを使用してください。これは競合ではなく、顧客向けレポートの「スコープ」セクションにインターフェースを記載する以外に、回避策や注記は不要です。

実行計画

各フェーズでは、スキルファイルを読み、その指示に従い、必要な出力を記録して、調査結果を次のフェーズに引き継いでください。チェックリストにスキップの指示がない限り、フェーズを省略しないでください。

フェーズ 0 — 安全契約

参照先：../planetscale-change-gates-and-approval-contract/SKILL.md

操作のクラス A～E を把握してください。オペレーターが変更を明示的に承認しない限り、以降のすべてのフェーズはクラス A のもとで実行します。

フェーズ 1 — 読み取り専用のインベントリ

../planetscale-readonly-inventory/SKILL.md を読み、実行します。

引き継ぐ成果物：

• 根拠を含むインベントリ表（情報源、パス／コマンド、タイムスタンプ、確度）
• 不足している根拠の表
• リスクフラグ
• 確認済みのエンジン（Vitess または Postgres）
• ブランチ構成と本番ブランチ

インベントリの後もエンジンが不明な場合は、フェーズ 2 の前に特定します。

フェーズ 2 — エンジンの安全性レビュー

次のいずれか 1 つを正確に実行します。

エンジン	スキルファイル
Vitess	../planetscale-vitess-safety-review/SKILL.md
Postgres	../planetscale-postgres-safety-review/SKILL.md

成果物：エンジン固有の安全性のギャップ、ワークフローのギャップ、承認が必要な変更案。

フェーズ 3 — Query Insights とタグ

../planetscale-query-insights-and-tags/SKILL.md を読み、実行します。

成果物：クエリリスク表、タグのカバレッジ表、不適切なタグ／カーディナリティの高いタグ、推奨するタグスキーマ、Traffic Control の候補スライス、候補となるスキーマおよびコードの変更。

フェーズ 4 — Traffic Control（Postgres のみ）

Vitess の場合、このフェーズはスキップします。 チェックリスト項目を完了としてマークし、注記に「N/A — Vitess」と記載します。

Postgres の場合は、../planetscale-traffic-control-recommendations/SKILL.md を読み、実行します。

成果物：提案する予算（名前、モード、トラフィックスライス、ルールタイプ、上限の根拠、テスト／ロールバック計画）。

クエリタグが不十分な場合は、そのスキルに従って「まずタグ付け」と記録し、強制モードの推奨は保留します。

フェーズ 5 — Webhook の自動化

../planetscale-webhook-automation-recommendations/SKILL.md を読み、実行します。

成果物：Webhook のインベントリ、不足しているサブスクリプション、配信先の品質レビュー、自動化の機会、安全でない自動化のリスク。

フェーズ 6 — スキーマ推奨エージェントループ

../planetscale-schema-recommendations-agent-loop/SKILL.md を読み、実行します。

成果物：推奨事項ごとのトリアージ（タイプ、重大度、根拠、安全な実装方法、検証／ロールバック計画）。

フェーズ 7 — コードベースへの SQLCommenter の計測導入

../planetscale-codebase-sqlcommenter-instrumentation/SKILL.md を読み、実行します。

リポジトリを利用できない場合に限りスキップします。最終レポートに「リポジトリをレビューしていません」と記載します。

成果物：検出されたスタック、現在のタグ付け状況、推奨パッケージ／パス、提案するタグスキーマ、変更される可能性が高いファイル。

フェーズ 8 — MCP エージェントの運用モデル

../planetscale-mcp-agent-operating-model/SKILL.md を読み、実行します。

成果物：推奨する MCP サーバーの選択、AGENTS.md への追記、自律的に許可／禁止する作業、提案するエージェントループ。

フェーズ 9 — ベストプラクティス・マトリックスの網羅性チェック

../planetscale-best-practices-matrix/SKILL.md を読み、実行します。

各マトリックス項目をフェーズ 1〜8 の調査結果と照合します。各項目について、次の内容を記録します。

• 該当するか：はい／いいえ／不明
• 現状
• ギャップ
• 推奨 ID（以下の ID 方式を参照）
• 承認要件

ギャップを埋めます。マトリックス項目が前のフェーズで扱われていない場合は、ここで不足している根拠を集めます（読み取り専用のみ）。

フェーズ 10 — 顧客向け統合レポート

../planetscale-customer-report-template/SKILL.md を読み、実行します。

すべてのフェーズの成果物をすべて統合し、1 つのレポートにまとめます。フェーズごとの出力をそのまま並べず、統合して重複を除き、影響度順に整理します。

推奨 ID 方式

プレフィックス	分野
OBS-*	Insights とクエリタグ
VIT-*	Vitess の安全性とデプロイワークフロー
PG-*	Postgres のロール、pg_strict、Traffic Control、PITR、ネットワーク
WEB-*	Webhook と自動化
APP-*	リポジトリへの計測導入
AGENT-*	MCP とエージェントのワークフロー

レポート全体で安定した ID を割り当てます。提案する変更セットでも同じ ID を参照します。

優先順位付けの指針

推奨事項は次の順に並べます。

1. 本番環境の安全性と可用性のリスク（最も高いものを先頭）
2. 診断や Traffic Control を妨げる可観測性のギャップ
3. 検知／対応までの平均時間を短縮する自動化
4. 明確な根拠があるパフォーマンスとスキーマの改善

フェーズ 11 — 停止ゲート

../planetscale-change-gates-and-approval-contract/SKILL.md を再読してください。

以下を確認します。

• クラス C／D／E の操作が行われていない
• 提案されるすべての変更に、ID、対象、インターフェース、効果、リスク、ロールバック、テスト計画が記載されている
• レポートが必須の最終文で終わっている

停止してください。 変更は適用しないでください。ただし、リクエストに有効な自律モードの確認（../planetscale-autonomous-execution-mode/SKILL.md に従うもの）が添えられている場合は、レポートと実行計画を提示してから、そのスキルに従って直ちに実行に進んでください。

必須の最終レポート構成

../planetscale-customer-report-template/SKILL.md のテンプレートを使用してください。最低限、次のセクションを含めます。

1. スコープ — 組織、データベース、ブランチ、エンジン、リポジトリ、インターフェース、期間。適用した変更：なし

2. エグゼクティブサマリー — 最もリスクの高いギャップと、最も価値の高い改善点を 3～7 個の箇条書きで記載

3. 現状 — データベーストポロジー、安全ワークフロー、可観測性、自動化、リポジトリの計測（証拠を添付）

4. 推奨事項 — ID、対象、メリット、リスク、必要な承認、事前テスト、証拠を含む優先順位付き表

5. 承認が必要な変更案 — すべてのクラス C／D 項目について、具体的な変更、インターフェース、ロールバック、本番環境への影響を記載

6. 意図的に適用しなかった変更 — 変更しなかった内容を明示的に列挙

7. 証拠の付録 — 情報源、コマンド／パス、タイムスタンプ、値、注記

8. 必須の最終文（そのまま記載）：

   変更は適用されていません。変更を行う前に、具体的な変更 ID を承認してください。

部分的な実行への対応

MCP、CLI、API、またはリポジトリにアクセスできない場合：

• 利用可能なインターフェースを使って続行する
• 取得できない証拠をレポートに記録する
• 該当する推奨事項の確信度を下げる
• 状態を捏造せず、不明として記載する

レポートの後

実行に進む方法は 2 つあります。

変更ごとの承認。 オペレーターが具体的な変更 ID を承認した場合：

1. ../planetscale-change-gates-and-approval-contract/SKILL.md を再読する
2. 指定された ID のみを実行する
3. 同スキルで定義された実行後レポートを作成する

自律モード。 オペレーターが、対象範囲を明示したうえでリスクを明確に了承した場合（「リスクを受け入れます — storefront-demo にレポートの推奨事項をすべて適用してください。本番環境も含みます」）：

1. ../planetscale-autonomous-execution-mode/SKILL.md を読み、確認内容が同スキルの有効化契約を満たしていることを検証する
2. 依存関係の順序に沿った実行計画を提示してから、同スキルの停止ルールに従い、継続的な状況報告と各ステップの検証を行いながら最初から最後まで実行する
3. 実行概要と実行ログを作成する

「ベストプラクティスを適用して」「すべて修正して」「進めて」を、承認またはリスクの了承として解釈してはいけません。

クイック実行

ユーザーが「完全な評価を実行して」または「PlanetScale のベストプラクティススキルをすべて実行して」と言った場合：

1. このスキルを読み込む
2. フェーズ 0～11 を順に実行する
3. 統合レポートを返す
4. 停止する