toyin-software-factory/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）	✅ 僅 Status 行	/sync
清除 Assumed 規格（將其移出 Assumed）	❌ 標記為決策負債「執行 /architect 以批准」（絕不協調為功能狀態；僅批准才能清除它）	/architect
編輯規格的內容/取代它	❌ 標記為過時	/architect
協調範圍，僅針對相關工作區的範圍檔案（非所有 docs/scope/），根據儲存庫證據（程式碼、測試、AGENTS.md）勾選任何完成的子任務，推進狀態	✅ 修正	/sync
在範圍中新增/重新排序功能或子任務	❌ 保留不變	/scope
覆寫或重寫已編寫的 AGENTS.md 解釋性文字	❌ 改為標記衝突	人類

建立的界線是上下文，而非政策：僅在此變更向您展示完整領域時才建立；當領域早於此變更且您只看見一部分時，則交由 /audit 處理。若不確定，標記而非建立。

要求 vs 執行

執行。 僅在無任何可同步的內容（空的變更集）時暫停。對已編寫檔案所做的每次編輯都會列在報告中，以便您可以檢閱或還原。

成品所有權

僅擁有界限表授予的內容，不寫入其他任何東西。作為通用子任務協調器，它會勾選任何它能根據儲存庫證據驗證的範圍子任務（掃描其他技能未勾選的 /test//audit//sync 子任務）並推進功能狀態；確切規則在 agent-prompt.md 中。

成品基礎。 規格和範圍預設存放於 docs/ 下，或當 docs/ 是已發布的文件網站時存放於 .workflow/ 下；使用儲存庫中存在的任何基礎（此處的路徑假設為 docs/）。

---

可攜性（任何作業系統，任何代理）

• 命令：git 是唯一需要的 CLI，且在每個作業系統上行為相同，請按所示執行 git 行。其他 shell 片段是 POSIX 參考，而非字面腳本：不要假設存在 find、grep、sed、cat、test/[ ]、ls 或 xargs；請使用您的代理的跨平台檔案工具，並自行應用分支邏輯，而非使用 shell 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）；全新領域和孤立清理邏輯需要每個檔案的Added、Modified 或 Deleted。

• 目前分支就是基礎，模式 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. 定位上下文檔案和規格（僅路徑，此處不要讀取它們）

使用您的代理的檔案搜尋/萬用字元工具：

• 注意根目錄 AGENTS.md 是否存在。
• 尋找每個 AGENTS.md（根目錄 + 巢狀），排除 node_modules/ 和 .git/。
• 在 docs/specs/ 下尋找所有名稱以數字開頭的規格，排序。
• 尋找差異實際觸及的工作區/功能的範圍檔案（在單一儲存庫中，已變更檔案的 workspace apps/<x>/… 會選擇 docs/scope/<x>/）；永遠不要讀取或傳遞所有 docs/scope/。

記下路徑以及已變更檔案清單和差異命令；在寫入時讀取這些檔案。現在讀取根目錄 AGENTS.md 內容（簡短且有助於錨定）。對於每個已變更的檔案，記下其最接近的包含 AGENTS.md 的上層目錄（根目錄或巢狀）；這是可能需要更新的上下文檔案。

2.5 為新新增的工具發現代理技能和選擇性 MCP

僅在依賴項清單已變更或差異明確新增了重要的外部工具時執行。跳過普通的工具庫，除非它們定義了持久的工作流程或整合。

• 從清單差異中識別新新增的重要套件/工具，而非完整的鎖定檔案：框架、路由器、樣式/UI 套件、資料庫、ORM/查詢層、驗證/會話、付款、電子郵件/通知、儲存/上傳、搜尋、佇列/背景工作、AI 提供者/向量資料庫、瀏覽器/執行時期測試、可觀測性、託管/部署。包括來自清單的套件名稱和常見別名。不要在找到第一個技術後就停止。

• 過濾掉已安裝技能、已連接 MCP 或 AGENTS.md 中已拒絕條目已涵蓋的任何內容。

• 在搜尋前先詢問。

  詢問是強制性的。搜尋不是。 在工程師做出選擇之前，不會對代理技能和 MCP 發現進行任何搜尋、提取、安裝或觸發。提供四個選項：幫我找到它們、我會指定我想要的、不執行並記錄拒絕、或稍後再說。只有第一個選項可以執行搜尋命令。永遠不要默默跳過此選項，也永遠不要在工程師同意之前執行搜尋。

  提及此變更新增了哪些工具，用一句話說明代理技能能賦予代理該工具的真實慣例，而 MCP 伺服器則能賦予其對真實系統的即時存取權限，然後詢問：「是否要我為此變更新增的工具尋找代理技能和 MCP 伺服器？」（標題代理技能），選項為 是的，幫我找到它們（建議）· 我會指定我想要的 · 不，跳過它 · 現在不要，以後再說。選擇 是的 則繼續以下步驟。選擇 我會指定我想要的，取得清單後直接跳到安裝步驟，不搜尋任何內容。選擇 不，跳過它，則不執行任何操作並記錄拒絕。選擇 現在不要，以後再說，則不執行任何操作並在報告中記下候選工具。

• 將搜尋隔離在唯讀子代理中（僅在 是的 之後，以能力為優先）。 將剩餘的集合交給一個發現子代理，而不是在主執行緒上搜尋：如果您的代理支援，則在背景觸發它（它不會阻塞），否則阻塞；明確將其模型設定為快速、低成本的層級（不要繼承會話模型；在 Claude Code 上，將其作為 researcher 子代理類型觸發，這會固定模型）；它僅返回緊湊的候選清單。這將搜尋輸出排除在 /sync 的有限上下文之外。沒有子代理 → 內聯搜尋；沒有搜尋能力 → 跳過並記下它。選項面板保留在主執行緒上。

• 對於每個剩餘項目，執行 npx skills find <tool-or-package>；如果結果薄弱，則重試套件/組織名稱的別名。收集每個可信的代理技能候選項，並在實際可行時使用 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 天時重複使用，過濾掉已安裝/已拒絕的項目後。

• 在一個多選面板中提供所有代理技能匹配項，按技術分組：「為新新增的工具安裝相關的代理技能？」加上跳過/拒絕。然後單獨提供 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 子代理，它會返回一個緊湊的映射。保持在舊工具授予所表達的相同界限內：Edit 現有文件、範圍和規格 **Status**: 行；嚴格僅為全新領域的巢狀 AGENTS.md 執行 Write；不建立根目錄，不編輯規格內容（僅 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 是有效成功；崩潰或空輸出則不是）。否則，傳達簡潔摘要：

以一行話開頭說明它協調了什麼；然後僅列出需要工程師注意的項目（根據 docs/conventions.md）。編輯內容已存在於檔案中。範本：

## /sync 完成 · 已協調 <N> 個變更的檔案

**已更新 <AGENTS.md 檔案 · 範圍功能 · 規格狀態> 以符合差異。** （或「一切已是最新，無需同步」）

注意（需要您處理）：
- 過時規格 → /architect：`<檔案>`（<原因，或 /sync 無法安全重新⋯

⋯（為翻譯而截斷）

（原始內容已截斷，但大致遵循此結構）

4. 傳達結果（續）

⋯ 協調的狀態不符>）

• 手動審查新 AGENTS.md：<路徑>（全新領域，請確認其準確性）
• 衝突的已編寫文字 → 您的判斷：<檔案>（/sync 發現的可能需要更新的段落）
• 建議的工具：已安裝 <技能> 和 <MCP>（或無）

如果您決定不執行建議的操作，請說「跳過此步驟，它不會阻塞」。