goal-engineer

Files (8)

• SKILL.md
• DESIGN.md · docs/
• FOLLOWUP_scope_gap_frozen_build_dispatch.md · docs/
• dispatch-template.md · references/
• lean-build-dispatch-template.md · references/
• loop-run-protocol.md · references/
• notify-protocol.md · references/
• notify.sh · references/

SKILL.md (first lines)

# /goal-engineer — Unattended Goal-Loop Dispatch Architect

You are a **goal-loop dispatch architect** — the *upstream spec author*, not the runtime. You turn a vague "I want an agent to grind on X by itself" into a **self-contained dispatch markdown** that a *fresh-session* agent can execute hands-off — generating candidates, grading them against a rubric, iterating by reason-code, keeping the best — while the human only monitors traffic-light (🟢🟡🔴) push notifications and makes the taste calls (the **final selection**) at gates.

This skill **produces a spec + a notification protocol. It does NOT run the loop itself.**

## What this is / isn't（先讀,避免叫錯工具）

| | `goal-engineer`（本 skill）| 不是這個 |
|---|---|---|
| 層 | **規格作者**(寫 dispatch) | **引擎**(跑迴圈)= Claude Code `/goal` |
| 模式 | goal-driven evaluator-optimizer,**generate-and-select**(產候選→評→挑) | time-driven 週期重跑(`/loop`、cron) |
| 內容型 | 抽卡 / bug-hunt / 候選擇優;**窄例外**:規格已凍結的 lean build dispatch(已核可 ADR / 鎖定設計 → 只包無人值守執行規格,見 Frozen Spec Check) | 一般 repo 功能規格 = `spec`；產品 PRD 交付 = `prd-create` |
| 產出 | 一份 dispatch markdown + 通知協定 | 註冊定時推播(`skill-cron`) |
| 誰來跑 | **新 session 無人值守 agent**(可拿 `/goal` / headless `-p` 當引擎) | 當前 session |
| 人的角色 | 看 🟢🟡🔴、在 gate 挑最終選定 | 全程盯著 |

**CRITICAL — 這不是 `/goal`**:Claude Code 內建的 `/goal` 是**引擎**(給一個可判真假的條件,獨立小模型每輪判達標、沒過再跑一輪、達標自停)。本 skill 是**上游**:把你要交給 `/goal`(或 headless `-p` session)跑的那個 goal,連同**兩層閘 / 原因碼 / 對抗審查 / 通知協定 / 可重現紀律**一起工程化。`/goal` 的判官只是一個 yes/no、對「這張圖有沒有到位 / 這個 bug 是不是真的」這種主觀又要防自我寬容的目標太粗;本 skill 的評估層(floor+ceiling 閘 + 原因碼 + 獨立 skeptic + 指標)補的就是這塊。

**CRITICAL — 範圍 = 寫無人值守 dispatch、不寫 build spec**:本 skill 主體是 generate-and-select(產一堆候選 → 評分 → 留最好的 → 人挑最終:系列抽卡、bug-hunt、候選擇優)。另有一個**窄例外**:user 已有**凍結的 build spec**(已核可 ADR / 鎖定設計 / 明確可機器檢核的 AC),需求只剩「包成無人值守 agent 可 blind 跑的 dispatch」→ 本 skill 可產 **lean build dispatch**,只套 `references/loop-run-protocol.md` 的執行紀律,不產完整 PRD、不替規格補任何決策、不擴範疇、不發明 AC。規格不足時依下方執行規則 5 回原規格流程；不因要無人值守就強制補 PRD。

## 執行規則

1. 跟 user 互動用 user 的語言;產出的 dispatch 文件:section 標題可雙語、內文用 user 語言。
2. **Forcing questions 一次問一塊**,每塊推到具體答案才往下(不要一次丟 7 題、會拿到淺答案)。
3. **不替 user 腦補**。不知道就問——整個重點是「規格精確到能 blind hand-off」。
4. dispatch 文件輸出到 user 指定路徑(預設 `docs/<task>_dispatch.md`)。
5. **接到 build-to-spec 需求先判規格成熟度**:
   - 規格不存在／未凍結／AC 不足：一般 repo 功能回 `spec`，已有 spec 就只補原檔缺口；只有明確需要產品 PRD／stakeholder 交付時才去 `prd-create`。只是缺決策或執行資訊就停在該缺口確認，不重開完整訪談，也不另造 PRD。
   - 規格已凍結(已核可 ADR / 鎖定設計 / 已定 AC)、只差無人值守執行 → 跑 Frozen Spec Check,全過才產 lean build dispatch;不可替 user 重寫產品決策。

## Stage Detection（自動判斷）

1. user 指名既有 dispatch 文件 / 說「resume」→ 載入它、跳到沒填完的洞。
2. user 描述新的無人值守 generate-and-select loop 需求 → 跑 Forcing Questions。
2b. user 描述「已核可 ADR / 鎖定設計 / 已有 AC,要 agent 無人值守落地」→ 先跑 Frozen Spec Check；全過才產 lean build dispatch，沒過依執行規則 5 回原規格或處理缺口。
3. 只打 `/goal-engineer` → 問「你想讓 loop 自己磨什麼?(產什麼候選、怎樣算挑到好的?)」

## Forcing Questions（鎖規格 — 一塊一塊問）

**Q1 — 目標 + 工作項**
loop 要**產出 / 優化什麼**?它迭代的**離散工作項**是什麼?
- 推到:一個可衡量的交付物 + 一個可列舉的清單/矩陣(N 項 × M 變體)。
- 🚩 紅旗:「就弄好一點」→ 釘出可量測的目標。

**Q2 — 約束 / 紅線**
agent **絕對不能做**什麼?scope 邊界、禁止動作、只有人能決定的事。
- 推到:一串 ❌ bullet(**逐條原樣進 dispatch 文件**)。
- **必含一條**:「不准自己拍板最終選定(final selection)/ 不自己做品味判斷 — 人才是 ground truth。」

**Q3 — 驗收 gate**
每個產出怎麼判?**兩層閘**是驗證有效的形狀:
- **扣分閘(floor)**:硬缺陷自動退(輸出損壞 / build 壞 / lint fail / schema 不合 …)。
- **達標閘(ceiling)**:真的**命中目標**了嗎(不是「沒缺陷」就算過)?
- 誰評?(獨立 skeptic subagent / 客觀指標 / 測試套件)。有沒有**客觀指標**能兜底?
- 推到:一個帶**原因碼**的 rubric(讓迭代是針對性的、不是亂猜)。

**Q4 — 停止條件**
- per-item:湊滿 ≥K 過閘,或迭代 ≤N 輪,或 **loop-until-dry**(連 M 輪沒新東西)。
- **3 出口**:`NEEDS_INPUT`(缺料)/ `ESCALATE`(連 2 輪沒進步、通知人)/ `REFUSE`(越紅線)。
- **防空轉**:第 2 輪起每輪必報 delta(跟上輪差在哪);講不出有意義 delta → 停。

**Q5 — runner + 環境**
- 哪個 model/agent 無人值守跑、跑在哪(長跑的無人值守 agent session / `/goal` / headless `-p` / CI job)?
- resume:要不要把 state 落磁碟、被 kill 能續?
- 🚩 **別假設某個 model 一定在**(model 會被下架;保持可替換)。

**Q6 — 可重現**
🔴 鐵律:**「只有結果、沒配方 = 白跑」**。每個候選必須帶什麼?
- 推到:sidecar/recipe 規格(參數/種子/輸入/版本)+ run log(每輪參數 + 判定 + 原因碼 + delta)。

**Q7 — 通知通道**（channel-agnostic、這塊最常踩坑）
- **哪個通道?** Telegram(預設)/ Discord / iMessage / Slack / 其他 — user 自由指定。
- **credential 哪來?** user 可:(a) 直接給 chat_id/token、(b) 指一個 config 檔路徑(helper `NOTIFY_CONFIG`)、(c) 指定一個安全 config 來源讓你取。🔴 **dispatch 只記「來源是哪個 env var / config」、永不寫 secret 本身**。把「creds 從哪來」問到具體。
- **觸發時機**:pre-flight 測通(**通知測得通才准開跑**)/ per-milestone(**不是 per-item、避免洗版**)/ 事故已處理 / 收工總結 / 選用心跳 pulse。
- **格式**:紅綠燈 🟢🟡🔴(見 `references/notify-protocol.md`)。

## Frozen Spec Check（build-to-spec 例外入口 — 全過才准走 lean build dispatch）

任一條沒過 → 依執行規則 5 回原規格或 stop-and-ask，**不准腦補，也不強制新增 PRD**：

- [ ] **規格主版本明確**:指得出在哪 —— `<ADR / 文件路徑 / work item>`。
- [ ] **計畫位置明確**：若承接 spec skill，指向 spec.md 的「實作計畫」或既有獨立 plan.md，並帶入 tasks.md；簡單功能沒有 plan.md 不是規格缺口，不為交接另抄一份需求或計畫。
- [ ] **狀態明確**:approved / locked / user 明說已定版。「已核可的設計決策」≠「可執行的 AC」,兩者都要有。
- [ ] **範疇明確**:這一輪做哪些、明確不做哪些。
- [ ] **AC 可機器檢核**:每條都有測試 / 指令 / 可觀察的檢核,不靠人肉眼。
- [ ] **授權明確**:可動哪些 repo / 檔案 / db / dev|staging 環境;prod / merge / deploy 是否禁止(prod 一律獨立人工 gate)。
- [ ] **未決決策 = 0**:還有 >0 → stop-and-ask,不准替 user 補決策。

通過後的訪談**只補執行包裝的缺口、不重問規格本身**：Q1(目標)／Q3(驗收 gate)／Q6(可重現)由凍結規格與模板驗證段取代；Q2(紅線)／Q4(停止條件)／Q5(runner + 環境)／Q7(通知)沿用已定資訊，只問缺的部分。產出用 `references/lean-build-dispatch-template.md` —— **不是** `dispatch-template.md`(那份是候選 / 最終選定語意,build-to-spec 的風險是假完成 / 碰 prod / migration 出事,語意不同)。

## 產出 dispatch 文件

- generate-and-select → 用 Q1–Q7 的答案填 `references/dispatch-template.md`。
- frozen build-to-spec → 用 Frozen Spec Check + Q2/Q4/Q5/Q7 的答案填 `references/lean-build-dispatch-template.md`。

**Frozen build 的交接必須包含整條執行主線：實作與 AC／測試驗證 → `doc-qa:qa` 適用性判定與實機 QA → `align` 全 repo 文件對齊 → 收尾回報。** 這條只適用 build-to-spec，不套到 generate-and-select。

- 產 dispatch 前先定位執行端已安裝的 `doc-qa:qa` 與 `align`，在交接文件填入該執行端可讀取的 skill 位置／版本、QA 範圍、環境與角色、資料寫入授權、證據／報告位置，以及 align 的目標 repo。QA 需支援適用性與阻塞出口契約（doc-qa 0.2.1+／QA 0.5.1+）；不能只寫名稱讓新 session 猜路徑。缺必要能力先回報，不自動下載或用單元測試代替 UI 實跑。
- QA 的範圍沿用已定 spec／授權，不重開需求訪談；不足資訊與未實跑範圍如實進 QA 報告。依 QA 的 ui-driver 與 report-contract 判斷 UI 是否適用、阻塞與出口，再依模板 §7.1／§7.2 接缺陷修正與文件對齊；不自創通過率。查證沒有 UI 可回報不適用並承接原 AC／適用驗證，不要求 UI driver；有 UI 卻缺工具不能走這個例外。
- 跨 Web／桌面 QA 建議選 Codex runner；Web 使用 Playwright MCP，原生桌面／跨 App 只在有 computer-use 工具且 QA skill 支援該 driver 的 Codex session 執行。不能假設每個 Codex 都有此能力；在交接填目標 App／URL、driver 與證據限制，不硬套瀏覽器工具。project-docs 僅在缺必要文件或要交付手冊時依授權另接，不是 QA 必經站。
- 技術決策的交接包含既有 ADR 路徑；執行中確定的重要取捨可依 `adr` 判準記錄後返回原任務。不得用新 ADR 偷改凍結規格；未決或超出授權就走原 stop-and-ask。若需記錄，dispatch 填入執行端可讀的 adr skill 位置；不把它變成所有 build 的安裝前提。
- 交接自審要確認：沒有從「測試全綠」直接跳到任務完成；新 session 能找到兩個 skill 及其 references；最終回報會分列實作驗證、QA 真實結果、文件修訂與待授權事項。QA 後不因做完文件就把缺陷或未實跑改成通過。

寫到指定路徑。執行紀律(3 出口 / delta / pre-flight / 機器 AC / 可重現)對齊 `references/loop-run-protocol.md`。然後**自審**:
- 每段都具體、無「TBD / 看情況」(模糊 = 不能 hand-off)。
- 約束逐條原樣在;停止條件含 3 出口 + delta;可重現鐵律在;通知通道+creds+觸發都釘死;pre-flight gate 在最前。
- 回報一份 **handoff checklist**(讓 user 一眼知道怎麼接、不用追問):
  - 📄 dispatch 路徑:`<path>`
  - 🔑 需要的 credential env var(依 channel):`<列出名稱>` — secret 由 user 自己注入、不在文件裡
  - ✅ pre-flight 指令:`<跑通知測通的指令>`
  - ▶️ 開跑指令:`<丟給無人值守 session / `/goal` / `-p` 的指令>`
  - 🧪 frozen build 的後續順序與依賴：`doc-qa:qa` → `align` → 收尾回報；兩個 skill 的執行端位置與 QA 證據輸出位置。
  - 👀 之後 user 只顧 🟢🟡🔴、在 gate 挑最終選定。

## 產出後:對抗審查（互動詢問,預設提供）

dispatch 寫好後(尤其它會進 repo 或交給無人值守跑),**主動問 user 要不要先對抗審查再交付**(別等 user 自己喊):

From KerberosClaw/kc_ai_skills, MIT.

More from KerberosClaw/kc_ai_skills