agentflowctl 0.19.2 → 0.20.0

package/README.md

@@ -33,6 +33,11 @@ npx agentflowctl run --req-file ./requirement.md
 ## 執行時會發生什麼
 
 1. agent 整理需求與驗收條件，接著寫計畫，交給其他 agent 審查。
+   驗收條件的原則（規格、計畫審查與修訂都依同一套標準）：
+   - 行為變更：把需要新寫或修改程式才成立的獨立行為列為驗收條件；不同輸入或情境需要不同結果時，以及新行為所需的邊界情況與錯誤處理，都分開列。
+   - 不另立條件：相同結果的不同說法、修正後自然成立的推論，以及沒有具體誤傷風險的既有行為，不會各自變成驗收條件和實作任務；審查者與修訂者會保留必要條件，並合併或刪除重複的。
+   - 不回歸條件：需求明寫要維持不變的行為各列一條，其餘限於最關鍵的一兩條。
+   - 非行為變更：需求本身若是文件、設定、純重構或特徵化測試，仍以所需產物與自動檢查結果列出驗收條件。
 2. 依計畫逐個任務寫出會失敗的測試，再由另一位 agent 實作到測試通過；每個任務都會經過審查與驗證。計畫 agent 會依改動內容在任務標記 `tdd`：建置流程、設定、文件、型別、純重構，以及實作前就會通過的特徵化測試，會略過紅綠燈直接實作，改由任務審查與驗證把關。描述寫明不要求紅燈卻沒標 `tdd: false` 的計畫不會通過。已定案的計畫若仍帶著這個衝突，執行到該任務時仍會寫測試，但測試一開始就通過也算完成，不會再要求紅燈、也不會因此讓 run 失敗。專案沒有測試框架時，所有任務都略過紅綠燈，也不跑 `test` 檢查。只跑檢查、不改檔案的工作不要拆成實作任務；這種任務若沒有檔案變更會直接略過，不再要求 commit。需要人眼確認的任務標成 `kind: confirm`，計畫定案後寫進 `.flow/confirmations.json`，不進入實作，也不會把 run 停下來。`status` 在任務清單之外另列「待你確認（不進實作）」；`confirmations <id>` 只印這個區塊。計畫還沒通過首次驗證前查詢，清單會從尚未經檢查的草稿蒐集，標題會多帶「（計畫尚未定案，以下為草稿）」，項目最終可能不會定案。
 3. 全部任務完成後，再執行專案檢查與整體程式碼審查。未通過的項目會交回修正。
 4. 有 `origin` 時會推送分支；若 `gh` 可用，會嘗試建立 PR。沒有 `origin` 時，完成的分支留在本機。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "讓 Claude Code、Codex、Gemini CLI 等 agent 分工整理需求、規劃、寫測試與程式並交叉審查，最後建立 PR；由程式推進流程，以測試與檢查結果把關",
   "keywords": [
     "ai",

package/prompts/plan-arbiter.md

@@ -32,6 +32,7 @@
 
 - 意見如果只是偏好、風格或「也可以這樣做」，而計畫本身能正確完成需求，就核准。
 - 如果有意見指出計畫會導致錯誤結果、遺漏需求，或無法用測試驗證，就不核准。
+- 驗收條件的爭議：意見只是要求把同一預期結果的換句話說、修正後不需另寫程式就必然成立的推論、沒有具體誤傷風險的既有行為併入其他條件或刪除，屬於偏好，計畫仍能滿足需求就核准；意見指出遺漏了新增或修改行為所需的邊界情況、錯誤處理，或需求明寫要維持不變的行為，才算實質問題。
 - 不要因為意見聽起來很有道理就預設它是對的，也不要因為作者有回應就預設問題已解決；請對照需求與程式碼實際判斷。
 </criteria>
 

package/prompts/plan-fix.md

@@ -23,14 +23,14 @@
 
 <steps>
 1. 先閱讀 .flow/feedback.md，依每則意見定位 .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json 中相關的段落或項目；技術細節需要確認時才讀相關程式碼。
-2. 逐條處理審查意見，只修改需要修訂的檔案。新增或調整驗收條件、任務時，檢查受影響的條件與任務對應。
+2. 逐條處理審查意見，只修改需要修訂的檔案。新增或調整驗收條件、任務時，檢查受影響的條件與任務對應。審查指出重複、換句話說或沒有具體誤傷風險的既有行為驗收條件時，併入相關條件或刪除，並同步調整任務對應。需求明寫要維持不變的行為，以及需求本身是文件、設定、純重構或特徵化測試等非行為變更時，保留必要的驗收條件；後者描述所需產物與自動檢查結果，不要因為產品行為不變而刪除。
 3. 覆寫 .flow/plan-replies.md，只寫這一輪的回應：每個相關任務一節，用「## T-1」這種標題逐條說明意見怎麼處理；不屬於單一任務的意見寫在「## 整體」一節。不同意要寫出具體理由。不要把回應寫進 .flow/plan.md。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
 </steps>
 
 <output_format>
 - acceptance.json 與 tasks.json 的格式必須維持不變（見檔案內現有內容）。
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
-- 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為。修改時若任務變大，請拆開，不要合併。
+- 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為（一個輸入或情境對應一個預期結果），或一項非行為變更的完成結果。修改時若任務變大，請拆開任務，不要把不同行為併成同一條驗收條件；只有審查指出重複或換句話說的條件，才依步驟 2 併入或刪除。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
 - 修改 task 時保留或補上 `complexity`（`low`、`medium`、`high`）。依影響範圍、技術不確定性與失敗後果重新判定，取最高等級；同步更新 .flow/plan.md 中該 task 的逐項證據與最終等級。若不同意審查者建議的等級，在 .flow/plan-replies.md 對應的 `## T-<數字>` 節引用具體程式碼或測試依據。同步更新 .flow/plan.md 中該 task 的證據時，放在該 task 的 `## T-<數字>` 標題下。
 - 只跑檢查、不改檔案的任務要併回會改檔的任務，不要留成獨立任務。需要人眼確認的任務設 `"kind": "confirm"`，它們會另存給使用者，不要留在實作佇列。

package/prompts/plan-review-index.md

@@ -46,7 +46,7 @@
 <review_focus>
 看五件事：
 1. **需求覆蓋**：規格、驗收條文與任務是否涵蓋需求？有沒有遺漏、誤解，或出現需求沒要求的範圍？
-2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
+2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為（一個輸入或情境對應一個預期結果）或一項非行為變更的完成結果？把多個輸入或預期結果寫在同一條的，要求拆開。新增或修改的行為若有重要的邊界情況或錯誤處理（含無效、空值輸入）沒被列入，要求補上；判斷方式：修正後必須新寫或修改程式才會有的結果（例如空字串改回傳預設值）算新增或修改的行為，優先要求列入；只描述既有行為、不需改程式的不算。需求本身若是文件、設定、純重構或特徵化測試等非行為變更，仍須保留描述所需產物與自動檢查結果的驗收條件；不要因為產品行為不變而要求刪除，也不要把每個既有行為另拆成一條。同一預期結果的不同說法、修正後必然成立的推論，或沒有具體誤傷風險的既有行為，要求併入相關條件的描述或刪除，不要求新增；需求明寫「維持不變」的行為視為有具體風險，各列一條不回歸條件，其餘不回歸條件限於最關鍵的一兩條。
 3. **順序**：depends 是否讓後續任務建立在它需要的前置任務之後？
 4. **技術方向**：整體做法是否合理？有沒有更簡單的做法，或明顯的風險？
 5. **跨任務一致性**：不同任務是否重複負責同一件事、對同一個介面或資料格式的假設互相矛盾，或實際有先後關係卻沒寫 depends？任務群審查者只看得到自己那一群與直接相依的任務，這類問題只有你看得到。

package/prompts/plan-review.md

@@ -29,7 +29,7 @@
 
 <review_focus>
 1. **需求覆蓋**：規格是否完整涵蓋原始需求？有沒有遺漏、誤解，或加入需求沒要求的範圍？
-2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
+2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為（一個輸入或情境對應一個預期結果）或一項非行為變更的完成結果？把多個輸入或預期結果寫在同一條的，要求拆開。新增或修改的行為若有重要的邊界情況或錯誤處理（含無效、空值輸入）沒被列入，要求補上；判斷方式：修正後必須新寫或修改程式才會有的結果（例如空字串改回傳預設值）算新增或修改的行為，優先要求列入；只描述既有行為、不需改程式的不算。需求本身若是文件、設定、純重構或特徵化測試等非行為變更，仍須保留描述所需產物與自動檢查結果的驗收條件；不要因為產品行為不變而要求刪除，也不要把每個既有行為另拆成一條。同一預期結果的不同說法、修正後必然成立的推論，或沒有具體誤傷風險的既有行為，要求併入相關條件的描述或刪除，不要求新增；需求明寫「維持不變」的行為視為有具體風險，各列一條不回歸條件，其餘不回歸條件限於最關鍵的一兩條。
 3. **任務拆解**：每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試（標 `tdd: false` 的任務除外：核對它的改動內容確實不適合先寫失敗測試，例如建置流程、設定、文件、型別、純重構，或實作前就會通過的特徵化測試，並有寫明驗收方式；會改變程式行為卻標成 `false` 的，要求改回 `true`。描述寫明不要求紅燈，`tdd` 卻不是 `false` 的，要求改成 `false`）？任務太大、一次要動很多檔案或驗證很多行為的，要求拆成更小的任務。相依順序是否合理？只跑既有檢查、不改檔案的工作不要獨立成任務，要求併回會改檔的任務。需要人眼確認、程式無法判定的，要求改成 `"kind": "confirm"`，讓它離開實作佇列、另存給使用者，不要留給 agent，也不要為此把流程停住。
    同時依 .flow/plan.md 的逐項理由及實際程式碼，獨立核對每個 task 的 `complexity`：分別看影響範圍、技術不確定性與失敗後果，取最高等級。`low` 須是沿用既有做法、侷限單一行為或模組且失敗可由局部測試發現；`medium` 包括多模組或介面協調、非典型邊界、相容性或狀態遷移風險；`high` 包括跨系統契約、架構或資料模型變更、未知的關鍵技術路徑，或資料遺失、權限、難以回復的風險。不要只憑檔案數、程式碼行數或驗收條件數判定。
    理由缺漏、與程式碼不符，或高低估會影響選模時，要求修正；在 `note` 指出 task ID、具體證據、建議等級及須修改的 .flow/plan.md／.flow/tasks.json 部分。不要為缺少高價值證據的細微措辭差異要求修改。

package/prompts/spec.md

@@ -29,10 +29,13 @@
 </steps>
 
 <guidelines>
-- 驗收條件要寫細：一條只描述一個可觀察的行為（一個輸入或情境，對應一個預期結果）。
-- 描述裡出現「並且」「同時」「以及」，或同時涵蓋成功與失敗路徑時，拆成多條。
-- 邊界情況與錯誤處理各自獨立成一條，不要附在正常路徑那一條裡。
-- 寧可多幾條小的，也不要少數幾條大的；後面每個任務最多只能對應兩條驗收條件。
+- 驗收條件要寫細：一條只描述一個可觀察的行為（一個輸入或情境，對應一個預期結果），或一項非行為變更的完成結果（見下方非行為變更那條）。
+- 描述裡出現「並且」「同時」「以及」，或同一描述涵蓋成功與失敗這類不同預期結果時，拆成多條。
+- 邊界情況與錯誤處理只要需要新寫或修改程式才會成立（含無效、空值輸入，以及正常與錯誤路徑各自不同的結果），各自獨立成一條，不要附在正常路徑那一條裡。
+- 行為變更的驗收條件，一條對應一個「需要新寫或修改程式才會成立」的行為。同一預期結果的換句話說、修正後不需另寫程式就必然成立的推論（例如修好排序後「輸出一定有序」），以及沒有具體誤傷風險的既有行為，不另立條件：把可驗證的細節併入相關條件的描述，背景寫進 spec.md。
+- 需求本身若是文件、設定、純重構或特徵化測試等非行為變更，仍要列出驗收條件：描述需求要求新增或修改的產物，以及能自動檢查的完成結果（例如文件包含指定內容、重構後檢查通過，或新增的測試在既有實作下通過）。不要因為產品行為不變而省略這類條件，也不要把每個既有行為另拆成一條。
+- 既有行為真的有被這次改動誤傷的風險才另立「不回歸」條件：需求明寫要維持不變的行為各列一條，其餘限於最關鍵的一兩條。
+- 在上述前提下仍要寫細：後面每個任務最多只能對應兩條驗收條件。
 </guidelines>
 
 <output_format>