toyin-software-factory/sync

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

このスキルが生成するすべてのもの（ファイルとメッセージの両方）は、平易でシンプルな言葉で書いてください。読者には「あなた」として話しかけ、同僚のように温かく直接的で、すべてのステップは「実行してもいいし、スキップしてもよい」という推奨として提示し、決して命令として提示しないでください。実際の意味を持つ技術用語はそのまま使用し、それぞれを平易な言葉で説明してください。ダッシュやハイフンを句読点として使用しないでください：emダッシュ、enダッシュ、ハイフンでつなぐ複合語は使用しないでください。「read-only」とは書かず「read only」と書いてください。単純な言葉で言い表すか、文を言い換えてください。コード、ファイルパス、コマンドフラグ、他のスキルがマッチングに使用する値はハイフンを維持します。短い文、カンマ、括弧を使用してください。明確さが賢さに勝ります。

このスキルの役割

完了した変更のループを閉じます：AGENTS.md ファイル、スコープ、およびリンクされた仕様の **Status**: 行をリポジトリの現在の状態に同期し、編集してはいけないもの（古い仕様、キュレーションされた散文）にフラグを立てます。以下の境界テーブルが正確な契約です。

agent-prompt.md はメンテナンスルールの単一情報源です。SKILL.md はオーケストレーションのみをカバーします。メインスレッドがそれを読み、メンテナンス自体を実行します（ステップ3を参照）。

正規ファイル： 永続的なコンテキストはツールに依存しない AGENTS.md に保存されます。CLAUDE.md は単なるポインタ です。/sync は両方を編集/作成しますが、それらをターゲットとしてのみ扱い、変更ソースとして扱うことは決してありません。

境界

アクション	/sync	所有者（Owner）
既存のルート/ネストされた AGENTS.md を編集する	✅ メンテナンスする	/sync
ルート AGENTS.md の ## Build approach 行をスコープヘッダーのアプローチに調整する（外科的な単一行編集。スタックと同様）	✅ メンテナンスする。キュレーションされた部分との乖離にフラグを立てる	/sync
変更によって UI デザインシステムが確立された場合、最も近い AGENTS.md に design.md（UI デザインシステム）への一行ポインタを追加する	✅ メンテナンスする（ポインタのみ）	/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 に委ねてください。不明な場合は、作成する代わりにフラグを立ててください。

依頼か行動か

行動します。 同期するものがない場合（空の変更セット）のみ一時停止します。キュレーションファイルへのすべての編集はレポートにリストされるので、レビューまたは元に戻すことができます。

成果物の所有権

境界テーブルが許可するものだけを正確に所有し、それ以外は書き込みません。普遍的なサブタスク調整役として、リポジトリの証拠から検証できるスコープのサブタスク（他のスキルがティックしない /test//audit//sync のサブタスクをスイープ）にティックし、機能ステータスを進めます。正確なルールは agent-prompt.md にあります。

成果物のベース。 仕様とスコープはデフォルトで docs/ の下に配置され、docs/ が公開ドキュメントサイトの場合は .workflow/ の下に配置されます。リポジトリに存在する方のベースを使用します（ここでのパスは docs/ を想定しています）。

---

移植性（任意の OS、任意のエージェント）

• コマンド： git は唯一必要な CLI であり、すべての 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-status（--name-only ではない）を使用します。新規エリアと孤立クリーンアップのロジックには、ファイルごとに 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 が存在するかどうかをメモします。
• すべての AGENTS.md（ルート + ネスト）を見つけます。node_modules/ と .git/ は除外します。
• docs/specs/ の下にある、名前が数字で始まるすべての仕様を見つけ、ソートします。
• 差分が実際に触れるワークスペース/機能のスコープファイルを見つけます（モノレポの場合、変更されたファイルのワークスペース apps/<x>/… が docs/scope/<x>/ を選択します）。docs/scope/ 全体を読んだり渡したりしないでください。

パス、変更されたファイルリスト、および差分コマンドをメモします。ファイルは書き込み時に読み取ります。ルート AGENTS.md の内容は今すぐ読み取ります（短く、アンカーとして役立ちます）。変更されたファイルごとに、最も近い AGENTS.md（ルートまたはネスト）を含むディレクトリをメモします。これが最も更新が必要なコンテキストファイルです。

2.5 新しく追加されたツールの Agent Skill とオプションの MCP を発見する

依存関係マニフェストが変更された場合、または差分が重要な外部ツールを明確に追加した場合にのみ実行します。永続的なワークフローや統合を定義しない通常のユーティリティライブラリはスキップします。

• マニフェストの差分から、新しく追加された重要なパッケージ/ツールを特定します（ロックファイル全体ではありません）：フレームワーク、ルーター、スタイリング/UIキット、データベース、ORM/クエリレイヤー、認証/セッション、支払い、メール/通知、ストレージ/アップロード、検索、キュー/バックグラウンドジョブ、AIプロバイダー/ベクトルDB、ブラウザ/ランタイムテスト、可観測性、ホスティング/デプロイ。マニフェストからのパッケージ名と一般的なエイリアスを含めます。最初のテクノロジーで停止しないでください。

• インストール済みのスキル、接続済みのMCP、または AGENTS.md で拒否されたエントリで既にカバーされているものはフィルタリングして除外します。

• 検索する前に確認を取ります。

  確認は必須です。検索は必須ではありません。 Agent Skill と MCP の発見のために、エンジニアが選択するまで、何も検索、取得、インストール、起動されません。4つの選択肢を提供します：私に見つけさせてください、欲しいものを指定します、いいえ（拒否を記録）、後で。最初の選択肢のみが検索コマンドを実行できます。オファーを黙ってスキップせず、エンジニアが同意する前に検索を実行しないでください。

  この変更で追加されたツールの名前を挙げ、Agent Skill はエージェントにそのツールの実際の規則を与え、MCP サーバーは実際のシステムへのライブアクセスを与えることを一文で説明し、その後尋ねます：「この変更で追加されたツールの Agent Skill と MCP サーバーを見つけましょうか？」（ヘッダー Agent skills）、選択肢は はい、見つけてください（推奨）· 欲しいものを指定します · いいえ、スキップします · 今はやめて、後で。はい の場合は以下の手順を続行します。欲しいものを指定します の場合は、リストを受け取り、何も検索せずに直接インストールステップに進みます。いいえ、スキップします の場合は何も実行せず、拒否を記録します。今はやめて、後で の場合は何も実行せず、レポートに候補ツールをメモします。

• 検索を読み取り専用のサブエージェントに分離します（まず機能を確認し、はい の場合のみ）。 残りのセットを、メインスレッドで検索する代わりに、発見サブエージェントに渡します。エージェントがサポートしている場合はバックグラウンドで起動します（ブロックしません）。それ以外の場合はブロックします。モデルを明示的に高速で低コストのティアに設定します（セッションモデルを継承しません。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 ページのフェッチ、最初に公式レジストリ/ドキュメント。インストール済み/拒否済みの項目をフィルタリングした後、30 日未満の docs/.agent-cache/tool-discovery/<slug>.md を再利用します。

• すべての Agent Skill マッチを、テクノロジーごとにグループ化された1つの複数選択パネルで提供します：「新しく追加されたツールに関連する Agent Skill をインストールしますか？」と、スキップ/拒否のオプション。次に、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 を今すぐ（書き込み時にのみ）読み、正確に従ってください。これはメンテナンスルールの信頼できる情報源です。差分の読み取りは、大規模な変更セットの場合にのみ、読み取り専用の scout サブエージェント（最も安価なモデル、Claude Code では haiku）にオフロードしても構いません。このサブエージェントはコンパクトなマップを返します。古いツール許可が表現していたのと同じ境界内に留まります：既存のドキュメント、スコープ、仕様の **Status**: 行の Edit（編集）。ネットで新しいエリアのネストされた AGENTS.md の場合は厳密に Write（書き込み）。ルートの作成は禁止、仕様の内容の編集は禁止（ステータス行のみ）、確立されたエリアの浅いネストされたドキュメントは禁止（これらは 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（すべての仕様パス。ステータス行の調整と古さのフラグ付け用）
5. FILE_TO_CONTEXT_MAP（変更されたファイル → 最も近いコンテキストファイル）
6. SCOPE_PATH_OR_NONE（該当するワークスペースのスコープパス。docs/scope/ 全体ではありません。また、各リンクされた機能のステータスのソースでもあり、仕様のステータス行調整に使用されます）
7. INSTALLED_SKILLS_OR_NONE、MCP_SERVERS_OR_NONE、DECLINED_TOOLS_OR_NONE（ステップ2.5から）

4. 結果を伝達する

メンテナンスが失敗した場合、または解析可能なサマリーを生成しなかった場合、それを報告して再実行します。結果を捏造しないでください（正当な NOTHING_TO_SYNC は有効な成功です。クラッシュや空の出力はそうではありません）。それ以外の場合は、コンパクトなサマリーを伝達します：

何を調整したかを一文で先頭に示します。その後、エンジニアが必要とするもののみをリストします（docs/conventions.md に従って）。編集自体はファイルにあります。テンプレート：

## /sync 完了 · 調整した変更ファイル数: <N>

**<AGENTS.md ファイル · スコープ機能 · 仕様ステータス> を差分に合わせて更新しました。**   （または「すべて既に最新でした。同期するものはありません。」）
注意事項（あなたの対応が必要です）：
- 古い仕様 → /architect: `<ファイル>`（<理由、または /sync が安全に調整できなかったステータスの不一致>）

...

エンジニアのアクションを要求する各項目は、対応する / コマンド（/architect、/audit、/scope）を含めて、何をすべきかを正確に示します。最後に「変更をレビューし、上記の注意事項を確認してください。」と締めくくります。レポートはファイルに書き込まず、チャット/ターミナルに直接印刷します。必要に応じて、各注意事項にそのままコミットできる git commit メッセージの提案を追加で含めることができます。