migrate-design-system

デザインシステムへの移行

1. モードを選択します。フルモードは、依頼で移行が明示されている場合、または利用者が提案を受け入れた場合にのみ実行します（build-design-system/references/run-record.md、用語集）。それ以外はすべて監査モードです。
2. 枠組みを定めます。すべてのデフォルトを適用して frame.md と standing-orders.md を作成します（references/run-folder.md）。
3. インベントリ、マッピング、パリティの確認を読み取り専用で行います（references/inventory.md）。監査モードはここで終了し、plan.md、その「発見したが未修正」の表、および提案を作成します。
4. 編集の前にベースラインを取得します（references/verification.md、ベースライン）。
5. 共有レイヤーは、1 人のエージェントだけで作業します（references/inventory.md、共有レイヤー）。
6. パイロットをエンドツーエンドで完了してから、そのレシピに基づいてコードモッドを行います（references/worker-brief.md）。
7. ローリングウィンドウで並行展開します。各ワーカーは 1 つのサーフェスを担当し、別のエージェントがそれぞれを検証します（references/orchestration.md、references/verification.md）。
8. 検証済みの各サーフェスを個別のコミットとして取り込み、その後 close.md と 1 つの「発見したが未修正」の表で締めくくります（references/run-folder.md、close.md）。

リリースしてはならないもの：

• 監査モードでの編集、または「アプリをきれいにして」のような曖昧な依頼で開始したフルモード。
• 作成者とは別の検証者による確認なしに取り込まれたサーフェス。
• 不足を埋めるために新たに考案したトークン、コンポーネント、プロパティ、またはバリアント。
• 移行の一部として取り繕われた動作変更。
• 最後の呼び出し元が移行した後も残されたレガシーモジュール。ただし、ゲートで担当者と削除日が指定されている場合を除きます。
• 引き継ぎ時に失敗しているチェック、または緩和された判定条件。

このスキルが別のコーディネーターの配下でサブエージェントとして動作する場合、ワーカーはフォアグラウンド呼び出しで起動します。1 回のメッセージで複数のワーカーを起動し、各ウェーブが並行して進むようにします。また、バックグラウンドワーカーが実行中のまま処理を終えることはありません。ステップエージェントが制御を戻したときに、ホストがそのワーカーを孤立させるか終了させるためです。ウェーブ全体の処理が戻ってから、ワーカーの終了を待ちます。

システムは確定済みです。1 人のコーディネーターがアプリをサーフェスに分割し、動作を変更せずに、ワーカーエージェントを使って 1 サーフェスずつ処理します。同階層のスキルパスは <skills> から始まります。サーフェス、実行ブランチ、同一値の差し替え、決定、ゲート、クリアランス、フットプリント、ステータス用語、および <skills> の意味は、build-design-system/references/run-record.md（用語集）の定義に従います。このスキルがシステムを設計することはありません。トークンまたはコンポーネントが不足している場合は、システムのオーナーに依頼します。常設指示で許可されていない限り、デプロイは行いません。frame.md に予算が記載されるまで、編集を行うワーカーを開始しません。

書き込みを行う実行では、すべてのサーフェスと、決定済みのゲートのデフォルトをすべて、実行ブランチ（ブランチ名が指定されていない場合は ds/<yyyy-mm-dd>-migrate）に取り込みます。これにより、次の作業は通常のマージで済みます。表示される変更にはそれぞれ、ゲートまたは決定、変更前後のキャプチャ、およびモンタージュの行が必要です（references/verification.md）。

コーディネーターから呼び出された場合

コーディネーターからは、モード、システムの場所、スコープ、パイロット、予算、または実行フォルダーが渡されます。渡された情報を使い、残りは「入力」に基づいてデフォルトを設定し、質問は gates.md に記録します。未回答のゲートは default (unanswered) をデフォルトとして適用し、その回答を待って実行を止めることはありません。サブエージェントのないホストで上司がこの役割を担う場合、そのことを決定の行として 1 件記録します。応答はステータス行から始め、続けて Commit: <run branch head> を記載し、その後に最終レポート、監査モードの場合は plan.md、または以下の停止形式を記載します。監査モードはビルドと並行して実行できます（references/inventory.md、監査モードと plan.md）。

完了条件

frame.md の述語が最終インテグレーションコミットで成立し、実行フォルダーから証明できる状態を「完了」とします。

• インベントリスクリプトの --check がそのコミットで 0 を返します。レガシーインポート、allowlist.tsv にない生の値、frame.md が数えるパレット使用箇所、レガシーファイルがすべて 0 件です。
• queue.tsv のすべての行が done であり、そのコミットに verified または self-verified の台帳行があります。サーフェスのブランチコミット時点での判定や、再オープンした行は対象になりません。
• 新たなレガシー使用をブロックするルールが、意図的に仕込んだ違反で CI を失敗させ、各引き継ぎ時には、残っている検出事項がコミット済みの除外リスト（references/inventory.md）に記載された状態で 0 を返します。引き継ぎ時にチェックが赤であれば、実行は失敗です。
• baselines/MANIFEST.sha256 が引き続き一致し、取り込まれた差分ごとに禁止パスのチェックに合格しています。
• 起動したすべてのエージェントに agents.tsv の終端行があり、すべての decisions.tsv 行が解決可能な証拠を示しています。
• 再発した修正はすべてチェックに反映されているか、反映できなかった理由がレポートに記載されています。
• todo を読み取るゲートはありません。各項目は done、default (unanswered)、既定値が記載された gate、または skipped (<reason>) のいずれかです。

サーフェスを変更する最初のコミットで、frame.md に引用された指摘を解消し、すべての主張にコマンドを明記します。最終メッセージは run-record の引き継ぎ（Handoff report）であり、close.md の migrate の件数と Next を含めます。未回答の既定値を最初に記載し、Found, not fixed の表を最後に記載します。停止する場合は、停止したルール、これまでに検証した件数、実行フォルダーのパス、再開時の最初のアクション、ブロック解除に必要な最小限の返信を返します。

入力

入力	必須	未指定の場合
対象システム：トークンのソース、コンポーネント、ドキュメント、およびバージョンまたはコミット	はい	references/inventory.md（Finding the target system）に従って特定します。まずインストール済みシステムの SKILL.md を確認し、コミットを frame.md に固定します
基準	いいえ	インストール済みシステムの SKILL.md のルールを使用し、なければシステムの仕様とドキュメントを使用します。すべての検証担当者と ui-review に同じファイルを渡します
ビルドおよび実行可能なアプリのリポジトリ	はい	監査モード以外では、ビルドできない場合は停止します。実行できない場合は、何も検証できないため、監査モードのみを提案します
モード	いいえ	依頼に移行が明記されていない限り、監査
スコープ	いいえ	インベントリで検出されたすべての項目を frame.md に列挙し、担当者が絞り込めるようにします
パイロット対象のサーフェス	いいえ	担当者が指摘したサーフェスを使用し、該当するものがなければ、システムコンポーネントと障害状態が最も多いものを使用します
予算	いいえ	frame.md に記載されたセッション
画面幅とテーマ	いいえ	アプリの最小幅と最大幅を使用します。既定は 390 と 1280 で、提供されるすべてのテーマを対象とします
パリティモード（exact または mapped）	いいえ	システムの値がレガシーの値と異なる場合は mapped（references/verification.md）
ワークツリー分離を使用する並列エージェント	いいえ	references/platforms.md
ビジュアルテストハーネス	いいえ	capture.mjs を CI 環境で実行します

プロジェクトの指示（AGENTS.md、CLAUDE.md）を常設の指示に反映します。サーフェスが 8 個以下の場合は、build-design-system/references/coordinator-path.md（Small app）の小規模アプリ向けの手順に従い、1 人のワーカーが各フェーズを順番に実行します。ウィンドウのコストが節約分を上回るため、インベントリ、ベースライン、台帳、述語は引き続き使用します。

手順

Frame の前に references/orchestration.md と references/run-folder.md を読んでください。Inventory は読み取り専用で、Frame の作成中に開始します。各ステップは、参照先で指定された run-folder ファイルによって完了が証明された時点で終了します。

1. Frame。 すべてのフィールドに値が入力されるか、明示的なデフォルトが設定された時点で終了します。spawn の前に完了してください。
2. Inventory。 1 人のエージェントが inventory スクリプトと、新たなレガシー使用を阻止する lint ルールを作成または再利用し、マッパーは各サーフェスで token-mapping を実行します。曖昧な行はゲートになります。inventory/counts.txt に件数が記載され、すべての検出項目にサーフェスが割り当てられ、仕込んだ違反でルールが失敗することを確認した時点で終了します。監査モードではルールを追加しません。
3. Parity。 読み取り専用のエージェント 1 人が、すべてのレガシー呼び出し箇所に parity.tsv で判定を付けます。ブロッキングギャップが解消されるまで、ファンアウト全体を停止します。監査モードではここに plan.md を書き、停止します。
4. Baselines。 すべてのサーフェスにベースラインがあるか、明示的な not captured の理由があり、マニフェストが書き込まれた時点で終了します。
5. Shared layer。 レイヤーが取り込まれ、ランタイムチェックが通り、すべてのベースラインが引き続き一致するか、差分の説明が済んだ時点で終了します。
6. Pilot。 Worker、verifier、台帳の行、取り込み。明らかになった問題をテンプレートで修正します。パイロットが verified になり、取り込まれた時点で終了します。
7. Codemod の作成。 パイロットの開始時のコミットに対して実行し、結果を手動移行と比較して差分を取ります。その差分が記録され、2 回目の実行で変更がない時点で終了します。
8. ファンアウト。 frame.md に定めた上限内でローリングウィンドウを使い、各 Worker に 1 つのサーフェスを割り当てます。それぞれに専用のブランチと worktree を用意します（または references/platforms.md のフォールバックを使います）。予算の約 70％に達したら spawn を停止します。
9. 各サーフェスの検証。 コードを書いていない verifier が、ビジュアル差分、レンダリング済みチェックリスト、アクセシビリティスナップショット、動作とその差分を確認し、ui-review を実行します。現在のコミットに対する判定が台帳に記録された時点で、サーフェスごとに終了します。
10. 継続的な統合。 検証済みの各サーフェスを、そのキャプチャとともに個別のコミットとして取り込み、その後に統合チェックを実行します。統合ビルドが赤になった場合、緑になるまで取り込みを停止します。
11. レガシーの削除。 レガシーモジュールの呼び出し元がゼロになったら、1 つのユニットが 1 回の変更でモジュール、そのアダプター、許可リストの該当行を削除し、lint ルールでそのパスを禁止します。
12. 完了。 最後に残作業を処理し、最終統合コミットですべてのサーフェスを再キャプチャして、close.md を作成し、decisions.tsv を監査し、繰り返し発生する修正をそれぞれチェックにし、スクラッチファイルを削除します。

境界

サブエージェントを起動できる場合、コーディネーターはプロダクトコードを書きません。サブエージェントを使えないホストでは、フェーズを順番に自分で実行し、references/verification.md に従って自分で検証します。

尋ねずに判断し、記録する内容：サーフェスの分割と順序、上限内のウィンドウサイズ、再試行と分割（build-design-system/references/coordinator-path.md、開発サーバーと再試行）、どの verifier を実行するか、問題のない取り込み、証拠に裏付けられた簡潔な修正または codemod、あらゆるサーフェスでの同一値の置換、決定済みのゲートのデフォルト、および追加のみのアクセシビリティ変更（build-design-system/references/traps.md、追加のみのアクセシビリティ変更）。

gates.md にデフォルトとともに保留事項を記録し、作業を続けます。マッピング済みのピクセル変更、色の変更、コンポーネントの置き換え、パイロット以外のサーフェスに対する codemod は、キャプチャとともに run ブランチへ取り込むデフォルトを設定したゲートです。これらのゲートでは、コードを現状のままにすることをデフォルトとします。システムに存在しないトークンやコンポーネント、説明できないビジュアル差分、セマンティクスを削除、改名、再構成する変更、ベースラインにすでに存在する blocking の ui-review 指摘（そのサーフェス自体は引き続き検証します）、規模を問わない動作変更、コードに反する恒常的な指示、再計画を 1 回行っても解決しない行き詰まり、リポジトリ外で使用されているデータやエクスポートの削除が該当します。

2 人の Worker に同じファイルを編集させてはいけません。また、共有レイヤーのフェーズが終わった後に Worker が共有レイヤーを変更することも禁止します。checks-only、blocked、自己申告を検証済みとして扱ってはいけません。また、判定の行で verifier を代替してはいけません。