計畫樹 (Plan Tree)
將此技能作為持久專案方向、執行就緒度、進度狀態和 Markdown 規劃樹的規劃工作流程權威。它能跨 session 和跨 agent 保留用戶意圖、現有文件風格、推理軌跡以及計畫落地證據。
必要操作模式
對於每個計畫樹任務，請在編輯或實作之前決定工作模式。
- 如果模式不明確，預設為
clarify或ready-check，而非execute-ready。 - 當有現有的計畫樹狀態可用時，請先檢查相關的進入點和當前計畫狀態，再改變方向。
- 在解決方案成熟到足以實作之前，請保持在規劃和釐清模式。將用戶意圖擴展為目標、非目標、限制條件、選項、權衡、風險、相依性、驗收標準、驗證路徑以及上線或回退說明。
- 當範疇、方法、受影響表面、預期行為、驗收標準、驗證路徑或風險的核心歧義仍存在時，請勿在主專案表面開始正式的實作。
- 僅在驗證方向且明確獨立於生產路徑時，才允許建立小型隔離原型或範例。
- 只有當實作不應依賴於「邊寫程式邊想辦法」來決定核心決策時，計畫才算已準備好實作。
- 實作落地後，更新計畫樹狀態、落地證據、決策、待解決問題和交接說明，以便將實作成果反映回持久的計畫狀態。
工作模式
在任務開始時選擇一種主要模式，然後僅在狀態變更時進行轉換。
clarify：意圖、範疇、限制條件、成功標準或權衡不明確。進行討論，必要時提出有針對性的問題，並在有用時將持久的釐清結果記錄在計畫樹檔案中。請勿編輯主要專案實作檔案。shape-plan：方向大致已知，但需要具體的解決方案地圖。建立或更新路線圖項目、主題、假設、決策、風險、驗收標準和待解決問題。ready-check：用戶想要實作或繼續，但就緒狀態不明確。評估範疇、方法、受影響表面、驗收標準、驗證和風險是否足夠明確。如果不是，返回clarify或shape-plan。resume：從先前的工作繼續。讀取根進入點、相關基準、目標計畫 README、實作狀態、路線圖，以及僅限活躍的連結檔案。在編輯之前，總結當前階段、活躍待辦事項、阻礙、下一個目標和最後驗證。execute-ready：計畫已足夠準備好實作。僅在約定的範疇內修改專案檔案，然後更新計畫樹狀態和證據。status-update：在工作或審查後更新路線圖狀態、實作狀態、最後落地、下一個目標、阻礙、交接或計畫註冊。archive：將已取代的細節、舊狀態快照、已接受的證據或僅供參考的資料移出活躍檔案，同時保留檢索連結。normalize：重新組織現有計畫樹或過大的混合角色原始檔案，使其成為較小的檢索單元。首先建立或更新indexes/migration-map.md或最接近的有用索引，然後按檢索角色分類原始資料，建立簡短膠囊和讀者任務細節片段，將已接受的驗證移至evidence/，並將舊狀態或推理敘述移至history/，除非明確批准，否則不刪除原始資料。audit或migrate：檢查一致性、檢索、漂移、舊根節點或遷移映射。預設為唯讀，除非用戶要求修復、正規化或遷移。
文件動作如 idea、promote、question 和 decision 在這些模式內部發生：
idea：將低承諾的想法新增到ideas/inbox.md或本地等效檔案。promote：將想法提升為路線圖項目、主題、待解決問題或決策，並連結原始想法。question：新增、縮小或解決未解決的問題。decision：建立或更新穩定的決策記錄。
核心工作流程
對於每個計畫樹任務：
- 選擇工作模式和允許的寫入表面：無、僅計畫樹、隔離原型，或專案檔案加上計畫樹更新。
- 識別計畫樹根節點、目標計畫根節點和用戶意圖。
- 讀取根索引以及僅限相關的路線圖、狀態、主題、決策、問題、想法、歷史或基準檔案。
- 保留現有的進入點、已註冊根節點、資料夾名稱、文件樣式和權威順序，除非任務明確要求重新組織它們。
- 保持活躍的路線圖、交接和主題膠囊檔案較小；將細節、證據和歷史移出活躍狀態。
- 在新增、移動、提升、歸檔或拆分持久檔案時，更新索引、檢索標頭和連結。
- 在回覆前執行最終檢查。
- 報告已變更的檔案、未解決的問題、活躍模式和相關的下一個有用維護動作。
預設檔案系統
使用 docs/plantree/ 作為計畫樹管理資料的預設跨專案檔案系統。它是計畫樹系統根節點和註冊中心，而非單一計畫根節點；此名稱可避免與提供者原生或框架原生的 plans/ 資料夾衝突。
預設結構：
docs/plantree/README.md：註冊中心、權威順序、基準連結、活躍計畫表格以及如何閱讀樹。docs/plantree/baseline/：專案範圍的上下文，如模組映射、執行時流程、狀態/儲存邊界、測試/發布閘道和風險熱點。docs/plantree/plans/<NNN>-<plan-name>/：具有穩定數字排序、路線圖/狀態、主題、決策、待解決問題、證據、索引和可選歷史的特定計畫根節點（當專案沒有既定命名慣例時）。docs/plantree/ideas/inbox.md：低承諾的想法收件匣。
發現順序：
- 當提供明確的用戶路徑時，使用該路徑。
- 否則，當
docs/plantree/README.md存在時，使用docs/plantree/。 - 否則，為當前任務保留另一個明顯活躍且已建立的樹；僅在用戶要求採用、正規化或遷移時評估遷移。
- 否則，在建立或更新計畫之前，先引導建立
docs/plantree/。
當沒有本地慣例時，新的具體計畫預設放在 docs/plantree/plans/<NNN>-<plan-name>/，必須在 docs/plantree/README.md 中註冊，並且應連結到相關的基準檔案，而不是複製全域上下文。除非用戶明確批准遷移，否則保留已建立的未編號或不同組織的樹。
首次使用
當在沒有 docs/plantree/ 的專案中呼叫計畫樹任務時，建立一個最小的根節點，除非用戶明確要求不要建立檔案。
引導建立：
- 根節點：
docs/plantree/README.md - 基準：
baseline/README.md、module-map.md、runtime-flows.md、storage-and-state.md、test-and-release-gates.md、risk-hotspots.md - 容器：
plans/、ideas/inbox.md
保持引導內容輕量且基於證據。如果尚未檢查足夠的程式碼，請寫 未知 / 需要盤點，而不是編造專案事實。對於老舊或不熟悉的專案，在建立詳細計畫之前，先建立或刷新基準。
計畫模型
建立或維護計畫根節點時，使用以下角色，並按本地慣例調整名稱：
README.md：範疇、權威、檔案映射、閱讀路徑，以及當它是計畫樹根節點時的活躍註冊中心。對於活躍的計畫表格，建議使用ID | 計畫 | 受影響模組 | 狀態 | 當前階段 | 最後落地 | 下一個目標（當使用輕量 ID 時）。roadmap.md：持久狀態，分組為已完成、進行中、下一個和已延遲，除非該樹已使用其他模型。implementation-status.md：僅針對進行中的計畫的簡短操作交接。處於規劃或延遲狀態的計畫通常不需要此檔案。open-questions.md：僅限未解決的問題。topics/：持久的上下文、解決方案映射、選項、限制條件、驗收標準、實作說明、儲存庫衛生計畫和風險分析。保持頂層主題檔案為簡短膠囊；將大型主題拆分為主題資料夾和細節片段。decisions/：穩定的決策，當集合增長時建立索引。evidence/：當前或已接受的驗證記錄、審查結果、工件說明和證據索引（當這些需要獨立於歷史檢索時）。history/：已接受的檢查點記錄、舊審查、已淘汰的快照、僅歸檔的原始說明和已取代的細節。indexes/：可選的檢索映射，如階段映射、主題映射、權威映射、遷移映射和證據映射（當本地索引解決導航問題時）。ideas/：可選的低承諾想法池（當根級別的想法不夠具體時）。
在建立模板、處理大型樹、維護決策/狀態/交接/歷史/索引檔案、新增儲存庫衛生計畫，或需要詳細的最終檢查清單時，請閱讀 references/maintenance-patterns.md。
輕量 ID 和模組分類
當專案沒有既定的計畫命名慣例時，使用輕量 ID 來改善檔案系統掃描和持久參照，而無需建立任務資料庫：
- 為整個專案分配計畫 ID，如
P001、P002等。將P001映射到一個平面根節點，例如docs/plantree/plans/001-authentication/。 - 使用固定寬度的三位數十進位數字。分配最大保留計畫編號加一；切勿重用 ID，不要透過重新編號來填補空缺，也不要對優先級、狀態、模組、擁有者、工作者、階段或日期進行編碼。
- 保持語義 slug 穩定且為小寫 kebab-case。標題或受影響模組可能更改，而無需更改計畫 ID 或目錄。
- 當計畫註冊中心很小時，將身分和生命週期註冊保留在
docs/plantree/README.md中。僅在該註冊中心能改善檢索時才將其拆分為索引；預設不維護並行分配帳本。 - 路線圖任務 ID（如
T001）是可選的，且僅限於計畫本地。僅在穩定的跨檔案參照有幫助時才使用它們。當使用時，roadmap.md是任務身分、狀態和順序的唯一活躍權威；預設不要建立單獨的任務註冊中心或任務資料夾。 - 決策檔案名稱可以保留
001-<decision>.md慣例。當持久參照有幫助時，待解決問題可以使用Q001。想法在提升之前保持無編號。 - 將程式碼或產品模組視為計畫元數據，例如
受影響模組，使用baseline/module-map.md中定義的穩定鍵。預設保持計畫根節點扁平；僅在證明有導航需求並記錄決策後，才新增模組索引或實際的模組目錄。 - 應用相同變更一致性：在一次維護變更中更新權威檔案和任何所需的進入點摘要，然後在完成前檢查 ID、路徑、模組鍵、路線圖唯一性、狀態聲明和相對連結。
- 偏好唯讀的漂移檢測，而非自動修復。在觀察到的協調失敗證明其成本合理之前，不要新增監視器、自動重新編號、分配鎖定或復原日誌。
這些預設值是漸進式的。保留成熟樹的本地 ID、問題、工單或資料夾慣例，而不是在其上疊加一個競爭的名稱空間。
動態狀態和證據
- 僅
進行中的計畫需要implementation-status.md；規劃中的計畫應在roadmap.md、主題、待解決問題或決策中表達就緒狀態。 - 保持
implementation-status.md具有操作性且簡短。偏好少於 100 行；如果增長，則歸檔或索引舊的細節。 - 將
活躍待辦事項保持在最多五個當前項目。更多項目通常意味著工作需要一個路線圖階段、主題或拆分。 - 當使用路線圖任務 ID 時，在
活躍待辦事項中重用這些 ID，而不是在第二個註冊中心中重述任務身分。 - 包含具體的
當前階段、下一個目標、最後落地、活躍待辦事項、受阻於和最後驗證或交接說明（如適用）。 最後落地應指向一個提交、工件、測試結果、已接受的檢查點或其他證據，並附上日期（如有）。- 對於階段/套件/關卡級別的證據，使用
evidence/README.md、indexes/evidence-map.md或本地等效檔案。僅對已取代的證據檔案使用history/evidence-index.md。不要記錄每個小步驟。 - 活躍的路線圖/狀態檔案應連結到舊證據，而不是吸收重複的記錄、舊的自動化輸出、審查工作細節或歷史敘述。
檢索模型
計畫樹是一個檢索單元系統，而不是一個用來增長大型綜合文件的地方。每個持久檔案應有一個主要角色：
- 進入點或索引：路由、權威順序、閱讀路徑和一行摘要。
- 當前狀態：活躍路線圖、當前階段、阻礙、下一個目標和交接。
- 主題膠囊：一個領域、功能、限制條件集或工作流的簡短摘要，並附有指向細節片段的連結。
- 細節片段：合約、替代方案、邊緣情況、實作說明、上線、操作、就緒狀態或一個讀者任務的儲存庫衛生細節。
- 決策：一個穩定的選擇，附帶上下文和後果。
- 證據：驗證記錄、審查結果、工件連結、已接受的測試摘要或證據索引。
- 歷史/存檔：已取代的狀態、舊的執行記錄、已遷移的原始資料和已淘汰的細節。
不要讓一個檔案同時承載摘要、活躍狀態、決策、長篇推理、記錄、證據和歷史。如果一次更新會使檔案跨越其角色邊界，請先建立或更新一個連結的檢索單元，然後只在活躍檔案中留下簡潔的摘要和連結。
使用以下行數作為拆分觸發器，而非硬性正確性測試：
- 根 README、計畫 README、路線圖和實作狀態：保持在大約 150 行或更少。
- 主題膠囊：保持在大約 250 行或更少。
- 普通細節片段：在大約 400 行時拆分或索引。
- 歷史或證據檔案：在大約 500 行時索引或拆分。
當拆分...
[為翻譯而截斷]