fr-goal
一個操作者觸點,從目標到審查完成的 PR:腦力激盪情境 → 一次批次問答 → 規格 → 審查 → fr-plan → 審查 → TDD 實作 → 審查 → 單一 PR。每次審查都會修復所有發現的問題;操作者的自主性指示將每個 superpowers 核准暫停替換為審查與修正回合。遇到阻礙時:停止,說明阻礙為何以及你嘗試過的方法,然後提問——在 PR 中送出錯誤猜測的成本遠高於暫停執行。
開始時宣告:「我正在使用 fr-goal 自主執行此目標。」
保持互動的部分
| 時刻 | 原因 |
|---|---|
| 批次問答(一次,在腦力激盪時) | 設計決策由操作者擁有——未回答 = 停止,絕不使用預設值 |
| 多專案儲存庫位置 | 存取問題——僅當檔案系統無法回答時 |
| 手動階段 | 金鑰、UI 操作、部署僅限人類操作——請參閱放置政策 |
| PR 合併 | 代理程式從不自行合併 |
| 合併後測試計劃 | 證明實際部署;需要操作者的環境 |
1. 腦力激盪與批次問答——在隔離環境中
呼叫 fr-brainstorming(先執行 fr isolation up;若無開發容器設定檔 → 暫停以進行 fr-init 訪談)。隔離優先於一切——包括探索、測量、叢集操作;操作者「從 X 開始」只會變更第一個工作項目,絕非第一個動作。探索、收集所有操作者擁有的決策,並在一次 AskUserQuestion 呼叫中提出所有問題(最多 4 個問題,建議為第一個)。僅當交付內容會部署(服務/機器人/基礎設施)時,才包含合併後測試計劃問題,純程式碼則不需要。批次處理落後問題。**嚴格關卡:**未回答的呼叫是停止訊號——結束回合時重申未回答的問題並等待;絕不要用預設值替代真實答案。
2. 規格——然後審查它
撰寫 docs/superpowers/specs/<YYYY-MM-DD-slug>-design.md,然後根據問答答案和程式碼庫現狀(它所命名的檔案/輔助工具/服務是否存在?)進行審查。修正所有發現。測試計劃選擇後 → 規格中會包含 ## Test Plan 區段,列出合併後的步驟。
3. 多專案檢查
對於跨儲存庫規格(owner/repo:path 形式),此工作階段只擁有單一儲存庫的計劃和 PR。對於其他每個儲存庫:自行定位其工作副本(兄弟目錄、常用根目錄);只有在找不到時才要求路徑/複製——將其批次納入問答中。為每個儲存庫分派一個代理程式(isolation: "worktree"),附上規格參考和此管線(從步驟 4 開始)。每個儲存庫一份計劃、一個 PR。
4. 計劃——fr-plan,然後審查它
呼叫 fr-plan,跳過逐節核准(規格已編碼設計)。保持 v2 計劃即資料夾、TDD 形狀的步驟。審查:fr plan self-review 必須通過,且階段必須與規格對照(全部涵蓋)。修正,實作。
5. 手動階段——預設延後
fr-plan 的 agentic-purity 關卡會將手動工作收集到專用的 [manual] 階段中。fr-goal 添加了放置政策(計劃中間的手動階段會阻礙執行):
- **預設延後:**所有手動工作放在最後一個階段,沒有代理程式階段依賴它。PR 刻意以未實作狀態送出,標記為操作者處理,操作者實作後推送到同一個 PR(
fr plan edit --complete-phase N --note)。 - 僅當代理程式工作確實依賴它時才提前。 完成計劃 + 審查,開啟一個包含規格 + 計劃的 PR(手動指示本身就是交付內容),暫停;等到操作者發出行動信號後才繼續。
- **多儲存庫:**建模跨儲存庫依賴——
depends_on僅在計劃內有效,因此排序存在於規格和 PR 順序中(一個儲存庫的金鑰可能阻礙另一個儲存庫的階段)。
6. 實作——fr-execute 本機模式、TDD、無子代理程式
步驟 1 的隔離工作空間就是工作副本——所有命令都透過 fr isolation exec 執行。透過 fr-execute 以 LOCAL 模式(計劃目錄 + 階段)執行階段,不可分派(規格/計劃不在 main 分支上,fr apply --yes 會拒絕)。內聯實作,而非透過子代理程式(情境需要問答 + 規格歷史)。每個步驟遵循 TDD;透過 fr plan edit 勾選步驟 / 完成階段。絕不觸及手動階段。
實作層只推送分支——絕不開啟 PR(內聯,或委託的多儲存庫建置器)。在此處開啟 PR 會將交付(步驟 8)提前到審查(步驟 7)之前,讓操作者在修正存在之前就合併——它們會孤立到已合併的分支上(#320,3 次)。協調器會開啟一個草稿 PR 以便可見——在步驟 8 之前不可合併,其「草稿」徽章表示「請勿合併」。
7. 在里程碑處審查——修正所有發現的問題
在每個里程碑(完成的階段,或小型計劃的完整實作)之後,對規格 + 計劃 + 程式碼呼叫 superpowers:requesting-code-review。立即修正所有發現的問題,並附上測試;對於事實錯誤的發現,提供反駁理由(superpowers:receiving-code-review),絕不無聲丟棄。保留一份發現清單。
8. 交付——每個儲存庫一個 PR,所有成品一併提交
先驗證(superpowers:verification-before-completion):完整的測試套件輸出、自我審查通過、步驟已勾選。PR 現在才可以設為可合併(在步驟 7 的修正之後):gh pr ready 將草稿轉為正式——在此之前絕不說「準備好合併」。PR 主體:摘要 + 規格/計劃路徑;審查發現及其修正(加上任何被反駁的發現);延後的手動階段標記為「未實作——操作者推送到此 PR」;測試計劃原文,標記為「合併後——操作者驅動」。停止;由操作者合併。
9. 合併後結案
當操作者回報合併完成時:首先驗證修正已到達 main——執行 fr isolation verify-merge --branch <b>(適用於 squash/rebase/merge,回傳 1 表示未驗證)。未驗證 → 停止並復原(cherry-pick / 新的 PR)。然後,如果測試計劃存在則執行(代理程式執行檢查,操作者確認無法觸及的部分),確認階段完成(fr status),fr archive <plan-dir>,透過維護 PR 提交,fr isolation down。