需求編排器

需求編排器 是做什麼的？

將軟體需求轉換為可獨立驗證的工作，同時保持單一控制代理負責範圍、相依性、證據與整合。本技能是編排器，而非提示產生器。

選擇語意模式

• analyze：調查需求與程式碼庫、維護帳冊，並產出執行藍圖，但不修改程式碼。當未要求實作時為預設模式。
• diagnose：重現並說明回報的失敗，區分已確認的根本原因、證據、未知事項與建議的修復路徑。診斷即為交付物；請勿修改程式碼。
• execute：分派有邊界的工作、審查回傳結果，並完成整合。僅在使用者授權實作或執行時進入此模式。
• challenge：測試現有需求、分解或設計是否存在遺漏與風險，但不改變其已確認的產品目標。請參閱 references/challenge.md。

這些是技能層級的語意模式。它們不會叫用或要求平台原生的計畫模式（Plan Mode）、EnterPlanMode 或強制的探索/計畫代理。僅在獨立有用且與使用者限制相容時使用原生模式。

對於單一根本原因且無需委派的工作，直接使用控制循環。請閱讀 references/spec-driven.md 以塑造規格（需求、驗收情境、合約）。在現有程式碼庫中進行分解前，請閱讀 references/context-grounding.md。當存在一個以上的候選任務、服務/領域邊界、排程決策，或建構/部署失敗而儲存庫狀態可能為原因時，請閱讀 references/decomposition.md。請閱讀 references/verification.md 了解驗收證據標準。當工作涉及多個任務、代理、工作階段或平台時，請閱讀 references/ledger.md。當執行會改寫、刪除或將變更擴及一個以上的現有成品，或寫入外部系統時，請閱讀 references/mutation.md。實際執行範例：references/examples/feature-example.md 與 references/examples/bug-example.md。

在 diagnose 模式中，回報觀察到或已重現的失敗、已確認的根本原因與證據、未驗證的項目、影響範圍與建議的修復路徑。除非使用者另行授權 execute，否則應在此停止。

控制循環

1. 確立目標、範圍、驗收標準、限制條件與已驗證的程式碼事實。先確認未知事項（references/context-grounding.md），然後將結果表達為規格——需求、驗收情境與合約（references/spec-driven.md）。調查可發現的事實；僅就實際影響範圍、驗收或方向的決策詢問使用者。在分解之前，查閱能力知識庫（請參閱 references/knowledge-base.md）以提取與目標相關的現有技能及同領域比較；優先考慮重用或匯入已知能力，而非從頭研究，並將所選能力記錄在帳冊中。
   • 若存在先前專案的經驗教訓（references/experience.md），將其視為待驗證的候選事實，而非絕對真理。
   • 對於非平凡的建構，在規格之後產出技術設計（references/tech-design.md）——架構、詳細設計、替代方案、跨領域關注點——並將成品持久化至 docs/ 目錄佈局下（references/deliverables.md）。
2. 對於回報的錯誤或失敗，在宣稱根本原因之前嘗試進行比例合理的本機重現。將觀察到的失敗與報告進行比較。在重現或獲得等效的直接證據支援之前，將根本原因陳述標記為假設，並說明哪些部分仍未驗證。
3. 選擇一個主要分解軸並建立有邊界的任務。推導出共享合約，並在依賴性或平行工作之前凍結這些合約（references/spec-driven.md）。明確記錄依賴性與跨任務合約。將產生的任務組映射至分階段的待辦事項（請參閱進度表面）。
4. 僅保留一個控制代理。控制者擁有帳冊、分派決策、審查狀態、重新規劃與最終整合的所有權。
5. 僅分派具有完整合約的任務。在首次分派前閱讀 references/agent-contract.md。在分派寫入任何非本機工作樹的系統之前，執行下方的目標系統預檢。
6. 將工作者結果接受至 review，根據驗收證據標準（references/verification.md）驗證其證據與邊界，然後將其標記為 completed 或附帶具體發現退回。對於大量或外部變更，透過獨立的回讀與結構差異來驗證，而非工具回報的成功計數。
7. 在發現、失敗或範圍變更後重新計算受影響的依賴性。重新處理受影響的最小分支。
8. 僅在任務層級檢查、跨任務合約與每個驗收情境全部通過時，才宣告需求完成；端到端閘門定義於 references/verification.md。完成後，將任何符合條件的專案特定經驗教訓附加至經驗日誌（references/experience.md）。從執行中改進技能本身是單獨的選擇性動作——僅在教訓具有普遍性且重複發生時提供，僅在使用者選擇時套用，永不自動執行（請參閱 references/experience.md）。

進度表面

保持可見的分階段待辦事項與帳冊同步，以便使用者查看階段與步驟層級的進度，而不僅僅是文字敘述。帳冊仍是詳細的真實來源（依賴性、範圍、合約、證據）；分階段待辦事項是其進度檢視。

• 為每個分解組初始化一個階段，然後是最終驗收階段（對於錯誤流程為 對照 / 修復 / 驗證；對於功能流程為功能組後接 全量驗收）。每個項目是一個有邊界的任務或驗證步驟，以 5–10 個字詞的結果來表述。
• 使用平台原生的任務列表來驅動，而非手動格式化的樹狀結構。在 Claude/omp 上使用 todo 工具：以 init 搭配 list: [{phase, items}]，然後對每個項目執行 start/done。在 Codex 上使用其 plan/update-plan 機制。
• 根據實際進度推進狀態：當任務被分派時將項目標記為進行中，僅在控制者在帳冊中記錄 completed 後才標記為完成。階段計數（N/M）因此追蹤已驗證的驗收，而非分派。
• 保持兩者一致：一個待辦事項對應帳冊中的一個任務或驗證步驟。在重新規劃時同時重新計算兩者。
• 在 analyze 與 diagnose 模式中，階段為調查或診斷步驟，完成這些步驟不會修改任何程式碼。

交付成品

將可發布的文件與內部編排狀態分開：面向讀者的文件置於 docs/ 下（docs/prd/ 規格、docs/tech-design/ 設計）；帳冊、計畫與經驗教訓為內部工作狀態，置於 .ai-work/ 下——絕不置於 docs/ 下，且對於可發布的專案應加入 gitignore。請參閱 references/deliverables.md。

對於任何非平凡的建構，在規格之後、execute 之前產出技術設計：架構、詳細設計、考量過的替代方案與跨領域關注點（references/tech-design.md）。對於單一根本原因的修復，若規格加上任務列表已足夠，則可跳過。

在交接前自行審查每個產生的 Markdown 交付物：重新閱讀並確認其呈現方式與讀者所見一致——結構完整，圍欄/Mermaid 區塊實際可解析（渲染它們，而非僅用目測），連結可解析。解析/渲染失敗是現在應修復的缺陷。請參閱 references/deliverables.md 與 references/verification.md 中的「文件/圖表成品」行。

當交付物為獨立專案時，「完成」包括可供發布：README（什麼/為什麼、先決條件、安裝、使用範例、設定、架構、測試、限制、授權、免責聲明）、LICENSE 以及排除建構輸出、機密與 .ai-work/ 的 .gitignore。驗證 README 中的指令確實可執行。請參閱 references/deliverables.md。

目標系統預檢

在分派寫入任何非本機工作樹的系統——例如 Wiki、問題追蹤系統、資料庫或遠端 API——之前，請事先驗證：

• 寫入權限以及計劃操作所需的确切範圍，包括計畫中要求的刪除或移動；
• 速率限制以及失敗是否為靜默；選擇安全的並發度與重試或退避策略；
• 結果是否可以回讀以進行驗證。

請在此處發現缺失的能力，而非在批次處理中途。若所需的權限或範圍不可用，則將其視為阻礙：確切說明缺失的內容與能夠解除阻礙的最小授權，然後在進行任何部分套用之前停止。

平台路由

• 對於 Codex，請閱讀 references/codex-adapter.md。
• 對於 Claude，請閱讀 references/claude-adapter.md。
• 在兩者之間轉移控制權時，請在舊控制者停止分派之前撰寫並確認交接快照。
• Trellis 為可選。僅在其升級信號適用或使用者要求時，才閱讀 references/trellis-adapter.md。

不可逾越的邊界

這些是無論措辭為何的 MUST NOT 級別不變量；請保持其數量稀少且明確。在本技能的其他部分，使用 RFC 2119 關鍵詞來評定規則強度——MUST / SHOULD / MAY，僅在大寫時有意義——並保持節制：保留 MUST / MUST NOT 給正確性或危害，將偏好作為 SHOULD / MAY。每個禁止事項都應搭配「改為這樣做」的正面指引：對於代理來說，僅有負面規則不可靠（它們會提示它們原本要禁止的行為），因此一組少量的硬邊界加上正面預設值才是穩健的形式，而非不斷增長的強制檢查清單。

• 請勿將任務樹的位置視為執行依賴性。
• 請勿讓工作者靜默地擴展其寫入範圍。
• 除非依賴性已解決、寫入範圍不重疊、共享合約已凍結且驗證是獨立的，否則請勿並行執行寫入代理。
• 工作者可提交工作以供審查；只有控制者才能將其標記為完成。
• 在變更現有成品時，請勿清除並重寫任何非任務所建立且無法重新產生的內容；應在原位插入或修補，使用可安全重新執行的標記進行標註，並透過獨立的回讀進行驗證。
• 請勿斷言任何超出其已驗證來源的推導值——分類、標籤、摘要、風險評級或建議；將未經驗證的推導標記為如此，而非編造數值。
• 請勿僅因為 .trellis/ 存在就啟動 Trellis。
• analyze 與 diagnose 為唯讀模式。平台的權限或原生計畫批准並不等於授權編輯。僅在收到使用者單獨指示授權實作後，才進入 execute 模式。
• 請勿在未以其讀者將使用的方式消費交付物之前進行交接——渲染文件，並從儲存庫根目錄原樣執行 README/使用指令。（改為這樣做：渲染圖表、執行指令、在交接前修復中斷。）
• 若無可運作的 README、LICENSE 與 .gitignore，或已提交內部的 .ai-work/ 成品，請勿將獨立專案宣告為完成。（改為這樣做：發布可發布的支架；將編排狀態保留在儲存庫之外。）