sync

出力スタイル（平易な言葉、ダッシュなし、ハイフンなし）

このスキルが生成するファイルもメッセージも、すべて平易で簡潔な言葉で書いてください。読者には「あなた」と呼びかけ、同僚に話すように、温かく率直に伝えてください。各手順は命令ではなく、実行しても省略してもよい提案として示してください。意味のある技術用語はそのまま使い、それぞれを平易な言葉で説明してください。句読点としてダッシュやハイフンは使わないでください。em dash、en dash、ハイフンでつないだ複合語は使わないでください。read-only ではなく read only と書いてください。平易な言葉で説明するか、文を書き換えてください。コード、ファイルパス、コマンドフラグ、ほかのスキルが照合する値では、ハイフンをそのまま使ってください。短い文を書き、読点や括弧を使ってください。気の利いた表現より、明快さを優先してください。

このスキルの役割

変更が完了した後の仕上げとして、リポジトリの現状に合わせて AGENTS.md ファイル、スコープ、関連する仕様書の **Status**: 行を同期し、編集してはいけないもの（古くなった仕様書、内容を練り上げた文章）に注意を促します。以下の境界テーブルが厳密な契約です。

agent-prompt.md はメンテナンスルールの唯一の信頼できる情報源です。SKILL.md は調整のみを扱います。メインスレッドがこれを読み、メンテナンスを自ら行います（ステップ 3 を参照）。

正式なファイル： 永続的なコンテキストは、ツールに依存しない AGENTS.md にあります。CLAUDE.md はそのファイルへのポインターにすぎません。 /sync は両方を編集または作成しますが、どちらも変更元ではなく、変更対象としてのみ扱います。

境界

アクション	/sync	担当
既存のルートまたはネストされた AGENTS.md を編集する	✅ メンテナンスします	/sync
ルート AGENTS.md の ## Build approach の行をスコープのヘッダーにあるアプローチに合わせる（スタックと同様、必要な一行だけを編集）	✅ メンテナンスします。内容を練り上げた記述との相違があれば注意を促します	/sync
変更によって UI デザインシステムが定まった場合、最も近い AGENTS.md に design.md への一行のポインターを追加する	✅ メンテナンスします（ポインターのみ）	/sync
この変更で新たに追加された領域のために、ネストされた <area>/AGENTS.md を作成する	✅ 作成します（差分 = 領域全体のコンテキスト）。ルートにポインターも追加します	/sync
すでに存在するがドキュメント化されていない領域のために、ネストされたドキュメントを作成する（差分で確認できる範囲のみ）	❌「/audit を実行」と注意を促します	/audit
ルート AGENTS.md を新規作成または再構成する	❌「/audit を実行」と注意を促します	/audit
仕様書の **Status**: 行を機能のスコープ上のステータスに合わせる（planned→Proposed、in-progress→In Progress、done→Accepted。ただし Assumed の仕様書は例外です。Assumed のままにして、その旨を伝えます。Accepted には決して合わせません）	✅ ステータス行のみ	/sync
Assumed の仕様書を解消する（Assumed 以外に変更する）	❌ 判断待ちとして「承認のために /architect を実行」と注意を促します（機能のステータスには決して合わせません。承認された場合にのみ解消されます）	/architect
仕様書の内容を編集または置き換える	❌ 古くなったものとして注意を促します	/architect
スコープを調整する。対象は該当するワークスペースのスコープファイルのみで、docs/scope/ 全体ではありません。リポジトリ内の根拠（コード、テスト、AGENTS.md）に基づいて、完了したサブタスクにチェックを入れ、ステータスを進めます	✅ 修正します	/sync
スコープに機能やサブタスクを追加または並べ替える	❌ 変更しません	/scope
内容を練り上げた AGENTS.md の文章を上書きまたは書き換える	❌ その代わりに競合を指摘します	人間

作成するかどうかの分かれ目は方針ではなく、コンテキストです。この変更から領域全体が確認できる場合に限り、作成してください。領域がこの変更より前から存在し、一部しか確認できない場合は、/audit に委ねてください。判断に迷ったら、作成せずに注意を促してください。

提案と実行

実行します。 同期するものがない場合（変更セットが空の場合）に限り、一時停止します。内容を練り上げたファイルへの編集はすべて報告書に記載するため、確認や差し戻しができます。

成果物の所有範囲

Boundaries テーブルで許可された内容だけを所有し、それ以外は一切書き込みません。汎用のサブタスク調整役として、リポジトリの証拠から検証できる範囲サブタスクをすべてチェックします（ほかのスキルがチェックしない /test／/audit／/sync のサブタスクも確認します）。また、機能のステータスを進めます。詳細なルールは agent-prompt.md を参照してください。

成果物のベース。 仕様と範囲は、デフォルトでは docs/ の下に置きます。docs/ が公開ドキュメントサイトの場合は、.workflow/ の下に置きます。リポジトリに存在する方のベースを使用してください（ここに記載するパスは docs/ を前提としています）。

---

ポータビリティ（任意の OS、任意のエージェント）

• コマンド：必須の CLI は git のみで、どの OS でも同じように動作します。記載どおりに git の行を実行してください。ほかのシェルスニペットは POSIX の参考例であり、そのまま実行できるスクリプトではありません。find、grep、sed、cat、test／[ ]、ls、xargs が使えると想定せず、エージェントのクロスプラットフォーム対応のファイルツールを使い、シェルの if／変数／リダイレクトではなく、自分で分岐ロジックを適用してください。
• 同梱ファイル：参照先は、このスキルのフォルダーを基準とした相対パスです。フォルダーを絶対パスに解決し（相対パスはすでに解決済みです）、前の手順ではなく、書き込み時（ステップ 3）に agent-prompt.md を自分で読み取ってください。
• メンテナンス全体は、agent-prompt.md（規則の正式な定義）に厳密に従い、メインスレッド内で実行します。

実行手順

1. 変更対象を絞り込む（低コスト、ファイルごとのステータス付き）

まず最新状態を確認する（チーム向け）： git fetch --quiet を実行します。git rev-list --count HEAD..origin/$BASE が 0 より大きい場合は、origin/$BASE に遅れています。チームメイトがすでにこれらのドキュメントを同期している可能性があるため、先にプルするようエンジニアに警告してください。

ベース：git rev-parse --verify main が成功する場合は main、それ以外は master。現在のブランチ：git rev-parse --abbrev-ref HEAD。--name-only ではなく --name-status を使います。新たに対象となる領域の特定と孤立ファイルのクリーンアップには、ファイルごとの A（追加）／M（変更）／D（削除）の区別が必要です。

• 現在のブランチがベースと同一の場合、モードは uncommitted：git diff --name-status HEAD。
• それ以外の場合、モードは branch：git merge-base "$BASE" HEAD を実行し、その後 git diff --name-status <merge-base> を実行します。

いずれの場合も、git ls-files --others --exclude-standard で未追跡ファイルを追加し、それぞれの先頭に A ステータスを付けます（--name-status 形式に合わせます）。書き込み手順で使うため、モード、ベース、マージベースを記録してください。

重複を削除してから、同期元となるソースファイルに絞り込みます。

• ドキュメントと設定ファイルを除外します（任意の階層にある AGENTS.md、docs/**、*.md、test-preferences.json、ロックファイル、生成物）。/sync はこれらを同期先／コンテキストとして読み取り、変更元としては扱いません。
• テストファイルを除外します（*.test.*、*.spec.*、__tests__/ など）。テストは永続的な領域の規約ではありません。
• D（削除）の項目は別のリストに残します。同期元としては使いませんが、孤立ファイルのクリーンアップ（ステップ 3）に使用します。
• 依存関係マニフェストの変更は、設定ファイルであっても、ツールの検出に使うため別のリストに残します。対象は package.json、pyproject.toml、requirements*.txt、go.mod、Cargo.toml、composer.json、Gemfile、pubspec.yaml、mix.exs、*.csproj および同等のパッケージマニフェストです。ロックファイルはシグナルとしてのみ使用し、内容を渡さないでください。

ソースファイルも依存関係マニフェストの変更も残らない場合（変更されたのがドキュメント／テスト／ロックファイル／生成ファイルのみの場合）は、ここで終了します。同期するものはありません。起動しないでください。

2. コンテキストファイルと仕様書を特定する（パスのみ。ここでは読み込まない）

エージェントのファイル検索／glob ツールを使って、次の項目を確認します。

• ルートに AGENTS.md があるかどうかを確認します。
• node_modules/ と .git/ を除外して、すべての AGENTS.md（ルートとネストされたもの）を検索します。
• 名前が数字で始まる docs/specs/ 配下の仕様書をすべて検索し、並べ替えます。
• 差分が実際に影響するワークスペース／機能のスコープファイルを検索します（モノレポでは、変更されたファイルが apps/<x>/… にある場合、docs/scope/<x>/ を選択します）。docs/scope/ 全体を読み込んだり渡したりしないでください。

パス、変更ファイルの一覧、diff コマンドを記録し、ファイルは書き込み時に読み込みます。ルートの AGENTS.md の内容は、作業の参考として、簡潔で役立つ範囲で今すぐ読み込みます。変更ファイルごとに、それを囲む最も近いディレクトリの AGENTS.md（ルートまたはネストされたもの）を記録します。これは、更新が必要になる可能性が最も高いコンテキストファイルです。

2.5 新たに追加されたツール向けの Agent Skills と任意の MCP を見つける

依存関係マニフェストが変更された場合、または差分から重要な外部ツールが追加されたことが明らかな場合にのみ実行します。通常のユーティリティライブラリは、継続的に使われるワークフローや統合を定義していない限り、対象外にします。

• マニフェストの差分から新たに追加された重要なパッケージ／ツールを特定します。ロックファイル全体は調べません。対象は、フレームワーク、ルーター、スタイリング／UI キット、データベース、ORM／クエリレイヤー、認証／セッション、決済、メール／通知、ストレージ／アップロード、検索、キュー／バックグラウンドジョブ、AI プロバイダー／ベクトル DB、ブラウザー／ランタイムテスト、オブザーバビリティ、ホスティング／デプロイです。マニフェストにあるパッケージ名と一般的な別名を含めます。最初のテクノロジーだけで調査を終えないでください。

• インストール済みのスキル、接続済みの MCP、または AGENTS.md の辞退済み項目ですでにカバーされているものを除外します。

• 検索する前に確認してください。

  確認は必須です。検索は必須ではありません。 エンジニアが選択するまでは、Agent Skill と MCP の探索で検索、取得、インストール、サブエージェントの起動を行いません。選択肢を4つ提示します。「こちらで探す」「必要なものを指定する」「いいえ、辞退を記録する」「今はしない」。検索コマンドを実行できるのは最初の選択肢だけです。確認なしに提案を省略したり、エンジニアの同意前に検索を実行したりしてはいけません。

  変更で追加されたツール名を挙げ、「Agent Skill はそのツール固有の実際の規約をエージェントに提供し、MCP サーバーは実システムへのライブアクセスを提供します」と1行で伝えてから、「この変更で追加されたツール向けの Agent Skills と MCP サーバーを探しますか？」と尋ねます（見出しは Agent skills）。選択肢は Yes, find them for me（推奨） · I'll name the ones I want · No, skip it · Not now, later とします。Yes の場合は以下に進みます。I'll name the ones I want の場合はリストを受け取り、検索せずにインストール手順へ進みます。No, skip it の場合は何も実行せず、辞退を記録します。Not now, later の場合は何も実行せず、候補ツールをレポートに記載します。

• 検索は読み取り専用のサブエージェントに隔離します（機能を確認してから、Yes の場合にのみ実行）。 残りの項目はメインスレッドで検索せず、探索用サブエージェントに渡します。エージェントが対応している場合はバックグラウンドで起動し（ブロックしません）、対応していない場合はブロッキングで起動します。モデルは高速で低コストのティアに明示的に設定します（セッションのモデルを引き継がないでください。Claude Code では、モデルが固定される researcher サブエージェントタイプで起動します）。返すのは簡潔な候補リストのみとします。これにより、検索結果が /sync の制限付きコンテキストに入り込むのを防ぎます。サブエージェントがなければインラインで検索し、検索機能がなければスキップしてその旨を記録します。提案パネルはメインスレッドに表示したままにします。

• 残りの各項目について npx skills find <tool-or-package> を実行します。結果が不十分な場合は、パッケージ名／組織名の別名で再試行します。信頼できる Agent Skill の候補をすべて集め、可能であれば npx skills add <owner>/<repo> --list で確認します。CLI が対話式である、または利用できない場合は、"<tool>" "agent skill" を検索し、提示前に確認します。

• MCP の検索は任意です。まずコネクター一覧を確認し、利用できない場合は項目ごとに "<tool>" "MCP server" を検索します。MCP は推奨できる追加要素ですが、必須ではありません。

• 探索の範囲を制限し、キャッシュ可能にします。ウェブ検索は最大5回、取得するページは合計8ページまでとし、公式レジストリ／ドキュメントを優先します。docs/.agent-cache/tool-discovery/<slug>.md が30日以内のものであれば、インストール済み／辞退済み項目を除外したうえで再利用します。

• Agent Skill の候補は、テクノロジーごとにまとめて1つの複数選択パネルで提示します。「新たに追加されたツールに関連する Agent Skills をインストールしますか？」と、スキップ／辞退の選択肢を表示します。その後、MCP を別に提示します。「これらのツールに役立つ可能性がある任意の MCP サーバー」と、スキップ／辞退の選択肢を表示します。自動でインストールまたは接続してはいけません。

• 選択されたスキルは npx skills add <owner>/<repo> -y でインストールします。MCP については、ユーザーのコネクター／MCP 設定を案内します。接続後、ツールは自動的に使用されます。

• 結果を INSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE、DECLINED_TOOLS_OR_NONE として引き継ぎ、書き込み時に適切な AGENTS.md ファイルへ永続的な記録を残します。何も見つからなかった場合や機能がない場合は、none として扱います。

3. メンテナンスを実施します（メインスレッド）

メインスレッドがメンテナンスを直接実施します。AGENTS.md／スコープ／仕様のステータス編集をサブエージェントに任せることはありません。今（書き込み時のみ）agent-prompt.mdを読み、記載された指示に厳密に従ってください。メンテナンスルールとして、これが最優先です。差分の確認だけは、大規模な変更セットの場合に限り、最も低コストのモデル（Claude Code：haiku）を使う読み取り専用のscoutサブエージェントに任せて、簡潔なマップを返させることができます。以前のツール権限で示された境界を守ってください。既存のドキュメント、スコープ、仕様の**Status**:行はEditで編集します。Writeは、新しい領域にネストされたAGENTS.mdを新規作成する場合に限ります。ルートには作成しません。仕様の内容は編集せず（Status行のみ）、確立済みの領域に浅い階層のネストされたドキュメントを作成しません（これらのルールはagent-prompt.mdに記載されています）。

適用する入力：

1. MODE、BASE、MERGE_BASE、CHANGED_FILES（名前、ステータス、変更されたソースの一覧）、DIFF_COMMAND（正確なgit diffコマンド）
2. DELETED_PATHS（削除されたパス。孤立項目のクリーンアップ用）
3. ROOT_AGENTS_MD（ルートのAGENTS.mdの内容）、NESTED_PATHS（ネストされたAGENTS.mdのパス）
4. SPEC_PATHS（Status行の整合と古さのフラグ付けに使う、すべての仕様パス）
5. FILE_TO_CONTEXT_MAP（変更されたファイル → 最も近いコンテキストファイル）
6. SCOPE_PATH_OR_NONE（関連するワークスペースのスコープパス。docs/scope/全体ではありません。また、仕様のStatus行を整合する際に使う、リンクされた各機能のステータスの情報源です）
7. 手順2.5のINSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE、DECLINED_TOOLS_OR_NONE

4. 結果を伝えます

メンテナンスに失敗した場合、または解析可能な要約が生成されなかった場合は、その旨を報告して、もう一度実行してください。結果を捏造してはいけません（実際にNOTHING_TO_SYNCとなった場合は、正常な成功です。クラッシュや空の出力は成功ではありません）。それ以外の場合は、簡潔な要約を伝えてください。

最初の1行で整合した内容を述べ、その後、エンジニアの対応が必要な項目だけを列挙します（docs/conventions.mdに従ってください）。テンプレート：

## /sync complete · reconciled <N> changed files

**Updated <AGENTS.md files · scope features · spec statuses> to match the diff.**   (or "everything already current, nothing to sync")
Heads up (need you):
- Stale spec → /architect: `<file>` (<why, or a status mismatch /sync couldn't safely resolve>)
- Assumed, not ratified → /architect: `<file>` (<feature>; owes ratification, doesn't block `done`)
- Context gap → /audit: `<area>` (established area /sync can't document from the diff alone)
- Conflict, decide manually: `<path>` (<curated content that would need rewriting>)

項目のない「注意」箇条書きは削除し、項目がなければ「注意」ブロック全体を削除してください。/syncが実施した内容（AGENTS.mdの行、スコープのチェック、孤立項目のクリーンアップ、ステータスの整合）はファイルに反映されています。列挙しないでください。/syncは/architectや/auditを実行しません。指摘するだけなので、対応するかどうかは自分で判断してください。

---

サブエージェント向けプロンプトのテンプレート

agent-prompt.mdを参照してください。