Community程式設計與開發github.com

hackycy/goal-loop

將已收斂的 map、ADR、spec 或 implementation plan 編譯為 Gate 計畫、狀態帳本和跨輪復用的固定執行提示詞。

goal-loop 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor 等)設計的技能,用於將開發者已收斂的決策文件(如架構決策記錄 ADR、規格說明 spec、實作計畫 implementation plan 或脈絡地圖 map)編譯成三個穩定的執行工件:`implementation-plan.md`(Gate 合約)、`goal-runbook.md`(狀態與證據帳本)和 `goal-prompt.md`(固定入口提示詞)。其核心價值在於建立一個明確的執行控制面,將「做什麼」、「做到哪裡」、「如何驗證」與「何時停止」等合約與執行狀態分離,避免 AI 代理在多次執行程式循環中偏離原始決策。此技能支援兩種輸入模式:僅有決策(Decision-only)與路徑尋找者(Wayfinder),並會自動驗證所有依賴的決策文件是否已收斂且無待辦事項(TBD、TODO 等)。當計畫或帳本已存在時,它會執行驗證而非覆寫,確保合約與狀態的一致性。此技能主要用於需要多輪反覆執行的軟體開發任務,例如逐步實作功能、驗收測試或架構重構,讓 AI 代理能在每次執行循環中重複使用相同的 Gate 合約,同時獨立追蹤每輪的執行進度與證據。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hackycy/skills/tree/main/skills/goal-loop

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Goal Loop

把決策文件編譯成三層工件:

  • implementation-plan.md:穩定的 Gate 合約,回答做什麼、邊界是什麼、如何驗證和何時停止。
  • goal-runbook.md:唯一的執行狀態與證據帳本,只回答目前執行到哪裡、已有何種證據。
  • goal-prompt.md:方便人工複製的固定入口,只指向前兩份文件;不綁定 Gate,也不重複合約。

本 skill 只建立或驗證執行控制面,不實施 Gate,不重做已批准決策。

定位輸入

使用者提供 effort 目錄、map.md、ADR/spec 或已有 implementation-plan.md。解析 Git 倉庫根目錄並定位 effort;無法唯一定位時停止,列出檢查過的路徑。

讀取適用的 CLAUDE.md、AGENTS.md、CONTEXT.md / CONTEXT-MAP.md,以及 effort 中的 map、spec、implementation plan 和它們連結的本機 ADR、decision、issue 與驗收依賴。CONTEXT.md 只提供術語和領域事實,不單獨產生 Gate。

支援兩種已收斂入口:

  • Decision-only:Gate、範圍、驗證和 Exit 能從已接受 ADR、spec 或已解決 issue 得到。
  • Wayfinder:map 的 Not yet specified 為空或明確為「無」,參與執行順序和驗收的 decision 全部已解決。

本機決策連結缺失、ADR 未接受、decision 未解決,或文件仍有 TBD、TODO、open question、pending decision 時停止,逐項報告缺口。不得用經驗補齊產品決定、驗收政策或回退邊界。

編譯計畫

若 implementation-plan.md 不存在,完整讀取 references/implementation-plan-schema.md,從已收斂決策生成計畫。若已存在,只讀取和驗證,不覆蓋。

計畫獨占所有穩定 Gate 合約:Objective、Inputs、Scope boundary、Constraints、Slice policy、Verification、Evidence rule、Stop conditions、Rollback 和 Exit conditions。專案命令與技術約束只寫入計畫,不進入固定 prompt。

若舊計畫包含 Current Execution State,初始化 runbook 時可以匯入一次;Gate 名稱、順序和狀態必須一致,passed / blocked 必須已有對應證據。匯入後不再更新計畫。

編譯或驗證帳本

完整讀取 references/runbook-schema.md。

goal-runbook.md 不存在時:

  1. 從計畫讀取 Gate 編號、名稱、依賴和合約位置。
  2. 寫入原始碼基線、唯一 Goal Ledger 和每個 Gate 的 Progress Log。
  3. 沒有可匯入狀態時只將 G0 標為 active,其餘標為 planned。
  4. 不複製計畫中的 Objective、Constraints、Verification 或其它 Gate 合約。

goal-runbook.md 已存在時:

  1. 比對原始碼路徑集合和 SHA-256;計畫或決策漂移時保持帳本原樣並停止。
  2. 驗證 Gate 順序、計畫引用、嚴格線性依賴、狀態機和 Progress Log 證據。
  3. 帳本只能呈現 passed* active planned*、passed* blocked planned* 或 passed+。

計畫是合約的唯一來源;帳本是狀態和證據的唯一來源。兩者不得相互複製欄位或雙寫狀態。

寫入固定 prompt

完整讀取 references/goal-prompt-template.md,只取代 {{EFFORT_PATH}},寫入或取代 goal-prompt.md。

固定 prompt 必須:

  • 在同一 effort 的所有 Gate 中保持完全相同;
  • 不出現 G0/G1 等具體 Gate、Gate 名稱或 Objective;
  • 不展開 Inputs、Constraints、Verification、Stop conditions、Rollback 或 Exit conditions;
  • 保留跨專案穩定的執行循環和行為約束:最小 slice、範圍控制、驗證失敗閉環、職責分片、保留無關實作、不弱化測試、人工驗收交接終止和禁止 push;
  • 要求在 Goal 啟動時鎖定目前唯一 active Gate,並只執行該 Gate;人工驗收時只請求一次確認,先記錄交接證據,再使用宿主 agent 提供的成功終態結束本次 Goal(不得標記為 blocked、paused 或繼續執行),最後輸出包含 Gate、自動化結果、驗收入口、最小清單、明確回覆格式和「Goal 已結束、Gate 仍 active」的交接結果並結束一般對話。此時 Gate 必須保持 active,後續只能由使用者帶著明確驗收結果手動重新觸發新的 Goal;沒有 Goal 狀態機制時直接結束目前任務,不建立等待迴圈。Gate 通過後將目前 Gate 標為 passed、直接後繼標為 active,彙總證據並明確結束整個 Goal,不得把後繼 Gate 納入同一 Goal。

goal-prompt.md 是可刪除、可重建的複製便利檔案。它不屬於原始碼基線,不被計畫或 runbook 引用,也不參與狀態驗證。

最終回覆說明是編譯還是驗證,給出計畫、runbook 和固定 prompt 的路徑,並輸出 prompt 內容。只最佳化工件時不得實施 Gate。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能