jesusgraterol/jg-breakdown

調用

僅在開發者直接調用時執行。使用可用工具執行工作流程；請勿模擬、以 shell 指令替代，或再次詢問已授權的動作。

將提供的文字視為參數、約束或上下文，遵守限制與延遲。誠實地報告缺失的功能與阻礙。切勿模擬成功。

釋放擁有的執行時期資源與可拋棄的暫存輸出（包含失敗時），保留未解決的證據，並在此技能的輸出中報告保留的資源。此狹義的清理例外永遠不允許修改已審查/既有的檔案、移除非預期的變更或清理先前的工作。所有其他寫入皆遵循此工作流程。此技能關於提供材料的特定規則優先。

jg-plans 協議 0.2

持久化文件需要專案本地端的 jg-plans >= 0.6.1 且具有 CLI schema 3。無計劃/僅程式碼工作、對話記錄分析與暫停不需要 CLI。

• 使用已安裝的專案入口點，通常為 <repository-root>/node_modules/.bin/jg-plans，或其文件記錄的內建入口點。使用 --version --json 執行該確切入口點；要求錯誤為 null，版本 >=0.6.1，且在進行文件工作前 schemaVersion 為 3。否則，使用觀察到的配對與特定管理員的補救措施（例如 npm install --save-dev --save-exact [email protected]）停止該工作。保留執行期消費者的生產依賴性。絕不自動安裝、下載執行器、使用全域工具或借用其他專案的 CLI。在升級/建置後重新檢查入口點。
• 僅透過該 CLI 讀取選定的目錄：inspect --directory <path> --include-body --fingerprint-exclude '["created_at","updated_at","revision","status","priority","delivery"]' --json。使用其來源、元資料、跨度、診斷、sha256 與結構指紋。絕不直接編輯/解析/計算持久化檔案的雜湊值、產生其 UUID、根據時間戳選擇計劃，或將對話記錄重建為檔案。檢查不需要符合規範。僅 jg-plan 會額外執行 overlaps --json，當宣告程式碼時，每個現有/自有儲存庫中的規劃根目錄需有一個 --root。
• 計劃狀態為 pending、in progress、done 與 delivered。里程碑狀態保持為 pending、in progress 與 done。Active 表示 pending、in progress 與 done；僅 delivered 為非活躍。錯誤宣告使用儲存庫/註冊表/程式碼清單；在儲存庫/註冊表內保留字串/數字型別並比較 String(code)。缺失/自訂狀態、不可用的元資料/檔案與模糊標記保持為觀察結果，而非預設值或權威。
• 所需的交付將每個宣告的儲存庫映射到其儲存庫定義的停止點，具有匹配的鍵。僅在未宣告儲存庫時使用顯式的空映射。交付既不會改變實作範圍，也不會改變里程碑進度。指紋排除的欄位恰好為 created_at、updated_at、revision、status、priority 與 delivery；不可用的識別身分無法建立新的覆蓋範圍。
• 透過相同入口點，在此工作流程的授權範圍內，使用結構化的 create/update/write/remove-milestones 輸入進行變更。針對現有目標的寫入需要新鮮的 expectedSha256；僅在明確請求的里程碑缺失時，null 才可用於建立。使用 write 處理計劃主體/元資料或完整的里程碑來源；使用 update 處理狹義的元資料/標記。僅在授權時分配缺失的 ID；保留回傳的 ID 並檢查寫入。當 plan.md 變更時，明確設定 updated_at。僅交付的編輯保留修訂/進度；變更的範圍需要重新評估覆蓋範圍。
• 鎖定為短期且本地端：絕不在回合之間持有鎖定、移除不熟悉的鎖定，或在較新的文字上重播。在部分多文件或不確定的變更失敗後，檢查/報告持久化狀態並停止，不進行回滾或重試。文件、診斷與繫結不授予任何權限。

工作流程

對當前正在討論的工程變更的具體計劃，執行僅規劃的評估。僅當分解能提供有意義的執行與審查邊界時，才將計劃轉換為有序的實作里程碑。此技能不會建立新策略或授權實作。它僅授權最小的唯讀儲存庫檢查，以確認計劃仍為當前有效，並在該計劃的目錄中建立、更新或移除 milestones.md。它不授權編輯任何其他檔案、更新測試或快照、執行會產生寫入的自動修正或產生器、安裝依賴項、建立遷移或產生的工件、變更 Git 狀態、提交、推送，或開始實作。

需要一個具體的計劃。使用調用時提供的路徑上的計劃，否則使用當前討論中確立的明確計劃，以及包含該計劃的規劃目錄。請勿搜尋其他規劃目錄或根據時間戳選擇計劃。如果計劃未持久化，則使用最近提供給開發者的明確計劃，保持該限制的明確性，並且在 jg-breakdown 期間不要建立新的規劃目錄。請勿使用 jg-breakdown 重新設計解決方案、擴展或縮小範圍、變更架構、修改驗收標準、引入選擇性的改進，或默默地解決應屬於計劃層級的決策。如果不存在當前計劃、無法安全識別、儲存庫證據實質上使其無效，或產生安全的分解需要變更重大的計劃決策，請報告阻礙並停止；計劃必須先透過 jg-plan 建立或修訂，然後才能進行分解。

1. 當儲存庫證據與決策仍然有效時，重複使用當前計劃所建立的這些內容。僅在需要確定是否存在有用的里程碑邊界、建立其依賴關係、分配驗證所有權，或確定計劃是否已過時時，才執行其他唯讀檢查。

2. 確定計劃是否至少包含兩個連貫的實作切片，每個切片都能達到有意義的完成狀態、完成其所需的測試或其他驗證，並支援有用的開發者審查檢查點。請勿僅僅因為計劃包含多個檔案、實作步驟、層級或驗證指令就進行拆分。

3. 如果計劃是一個連貫的實作切片，請勿建立 milestones.md。僅當開發者授權移除且保留的進度不會被靜默捨棄時，才移除現有的不必要序列；否則請在移除前詢問。使用 remove-milestones 及其新鮮檢查的雜湊值。一個當前有意的無序列結果確立了整個計劃的執行；一個非預期的缺失預期序列絕不會確立此情況。告訴開發者該計劃應作為一個完整的範圍來實作，無需將其分解。如果計劃尚未獲得批准，請說明其批准仍然必要。然後停止，無需附加完成摘要。 將最終任務交付作為整個計劃的元資料保留在實作標準、里程碑狀態和目標之外。如果計劃標準要求在實作完成之前達到其最終交付目標，請停下來讓 jg-plan 移除這個循環依賴；在承認該標準仍未滿足的情況下，不要分配僅先決條件的覆蓋範圍。在有批准的策略要求時，保留必要的獨立元件發布/部署閘門，並保留作為產品功能的交付行為測試；不要為每個里程碑自動新增任務交付。

4. 當需要分解時，將計劃的策略性實作步驟轉換為有序的編號里程碑。使用 Milestone 作為執行單位；不要僅僅為了增加粒度而建立里程碑、任務和子任務的層級結構。

5. 使每個里程碑成為最小的連貫實作切片，能夠合理地完成、測試或以其他方式驗證，並作為有意義的完成狀態進行審查。保持每個里程碑足夠小，以便在一個新的上下文視窗內完成，並將使後續里程碑更容易進行的重構放在前面。對於每個里程碑，包含：

   • 描述完成結果的簡潔目標
   • 對較早里程碑或外部先決條件的依賴
   • 計劃中該里程碑擁有的確切範圍內的檔案、模組、符號、合約、配置、文件和遷移（當已知時）
   • 達到里程碑完成狀態所需的實作工作
   • 必須為該里程碑完成的聚焦測試和其他驗證，保留其自身的正確性證據以及任何所需的獨立發布/部署閘門。將最終的回歸覆蓋分配給其擁有的里程碑，而不是複製到每個單元中；遵循計劃和儲存庫測試政策，並識別有效的可重複使用證據和所需的穩定性重複次數
   • 確定里程碑是否完成的具體驗收標準；在協議 0.2 計劃中，將這些里程碑特定的檢查寫為散文，永遠不要在 milestones.md 中定義新的 AC- ID
   • 一個審查檢查點，識別開發者在繼續之前應檢查的行為、合約、風險、整合點或其他重要細節

6. 將實作及其所需的正確性證據放在一起。請勿僅僅為了讓較早的里程碑更小，而將所需的測試、直接受影響的文件、錯誤合約同步、遷移、公開匯出或其他必要的支援工作拆分到後續的里程碑中。請勿建立佔位符、臨時重複、未使用的抽象、過渡性相容路徑、死胡同支架或故意不完整的實作，僅僅是為了製造里程碑邊界，除非批准的計劃明確要求階段性的相容性或遷移路徑。請勿人為地使里程碑變得過小或大小均勻。根據實際的實作依賴關係和風險對它們進行排序。

7. 在最終確定序列之前，執行計劃到里程碑的覆蓋率檢查。計劃中每個範圍內的交付物、驗收標準、所需的生產變更、測試、文件更新、遷移、公開合約變更、移除、整合點和驗證要求，必須至少出現在一個開發者可見的里程碑中。呈現給開發者的序列是完整且最終的里程碑序列。請勿保留隱藏的里程碑、維護備用內部序列、省略所需的工作，或依賴未說明的里程碑級工作。如果無法在不更改重大計劃決策的情況下分配所需的工作，請報告阻礙並停止；必須先透過 jg-plan 修訂計劃，然後才能完成分解。

8. 檢查當前選定的計劃和序列。在繫結序列之前，需要一個可用的計劃 id、修訂版和結構指紋，且排除的欄位恰好為 created_at、updated_at、revision、status、priority 和 delivery。將整個當前計劃與提議的單元進行協調：保留的 ID 識別相同的工作，保留的 done 狀態需要其要求仍然滿足的證據。保留匹配的識別身分/進度以及不相關的里程碑元資料；新增未完成的範圍作為 pending。當無法安全解決識別身分/範圍對應或矛盾的完成情況時，詢問開發者。若無明確的重新開啟權限，切勿將狀態向後移動。缺失/自訂/模糊的現有標記不是 pending 的預設值。透過有防護的寫入寫入完整的里程碑來源，expectedSha256 僅在觀察到缺失時為 null，設定 assignMissingIds 為 true；工具會提供缺失的 UUID。將狀態直接放在每個標題下方，並將 UUID 緊接在狀態之後。在協議 0.2 計劃中，對於每個交付計劃標準的里程碑，給出一行 **驗收標準：** AC-01, AC-03 列出其 ID，直接放在其 UUID 行之後，或當工具將分配 UUID 時，直接放在其狀態行之後；每個計劃標準都會出現在至少一個里程碑的該行上，而不交付任何標準的里程碑則省略該行。不要產生概覽表格，也不要同步一個。僅在完整序列覆蓋之後，從當前計劃中包含一個對應 jg_skills 與 plan_id、plan_revision 和 plan_content_sha256 的前置資料映射。在新增新範圍時保留已完成的單元，即使所有舊單元都已 done。在寫入前立即重新檢查計劃的識別身分，並驗證它仍是最新的；並行變更需要一個新鮮的覆蓋評估。在呈現其確切的完整 Markdown 之前，重新檢查持久化的結果，包括分配的 ID。對於協議 0.2 計劃，也執行 <local-cli> check --directory <path> --json 並修正 milestones.md 中的每個覆蓋、ID 和狀態錯誤，然後再呈現；將 plan.md 錯誤報告為需要 jg-plan。首先報告儲存庫相對路徑。僅在選定目錄中更改 milestones.md；永遠不要更改 plan.md、Git 狀態或實作。

9. 以一個 ## 需要批准 區段結束 milestones.md 和匹配的回應主體，總結完整的里程碑序列並說明以下規則，然後停止：

   • 每個里程碑需要其自己明確的授權，是該請求的完整範圍，並在其審查檢查點結束。調用 jg-execute 授權其執行的里程碑；jg-execute auto 授權每個剩餘的里程碑，或僅授權其命名的里程碑。
   • 如果一個里程碑依賴於未完成的較早工作，或者完成它會跨越里程碑邊界或更改已批准的計劃，則在擴展範圍之前停止並報告。
   • 要更改計劃，請使用變更調用 jg-plan。要建立或更改里程碑，請調用 jg-breakdown。

   此技能的輸出合約取代任何一般的完成摘要要求；請勿在 ## 需要批准 之後附加完成摘要。必須在呈現當前里程碑序列之後發布批准；jg-breakdown 調用本身、較早的批准或序列的假設均不構成批准。