dowafu 0.1.0

package/publish/.claude/skills/wrap/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: wrap
+description: 實作收尾與驗收前置檢查：自檢專案的完成條件全綠、確認 report/runbook/issue_log 齊備、產出使用者手測清單與 diff 對照摘要、提示切 session（不 compact）。實作 session 完工或 context 吃緊時使用。
+---
+
+# wrap — 實作收尾
+
+你是實作 spoke，正在收尾。先判定模式：
+
+- **完工收尾**（預設）：工作項已完成 → 走第 1–4 節。
+- **中途交接**：context 吃緊、工作未完 → 直接走第 5 節（不適用「全綠才收工」）。
+
+## 1. 自檢全綠
+
+完成條件**以該專案 AGENTS.md 訂的為準**。沒有訂就看 `package.json` 的 `scripts`，**有哪些跑哪些**（`test`／`lint`／`typecheck`／`build`）。
+
+- **不要為了湊數字自行加工具**（例如專案沒有 lint 就別裝 ESLint）
+- **也不要因為「看起來沒必要」跳過已存在的 script**
+
+兩條執行細節：
+
+- 測試**只跑本次改到的模組**，判定範圍見該專案 AGENTS.md 測試規範。禁止接 `| sort`／`| head`／`| tail`——那會吃掉失敗訊息
+- `typecheck` 與 `build` 若是兩個獨立 script，**分開跑、不要合併**。build 設定常把測試檔排除在外，只有 typecheck 涵蓋得到；合併之後「建置失敗」與「測試型別錯」也會無法區分
+
+任何一項不綠：先修好再繼續收尾，**不得帶紅收工**。
+
+## 2. 文件檢查
+
+- **report**：已產出？含「施工中修正」節（實作偏離規劃之處）？
+- **runbook**：已產出？含機器測不到部分的手測步驟（環境、路徑、操作順序、預期結果）？
+- **issue_log**：本輪 report 產出後的修正是否逐筆記錄？（report/runbook 不回頭改，見 AGENTS.md 文件紀律）
+
+## 3. 產出驗收包（給使用者的最終訊息）
+
+依序呈現：
+
+1. **手測清單**：從 runbook 抽出使用者要親手驗的項目，逐條列（步驟＋預期結果），不要叫使用者自己去翻 runbook。
+2. **diff 對照摘要**：實際改動檔案清單 vs 規劃書檔案清單，逐一對應；**超出規劃的改動明確標出**（夾帶是驗收紅線）。
+3. **待決事項**：實作中發現但未處理的問題（記 issue_log 待後續，或需使用者裁決的）。
+
+## 4. 收尾提醒
+
+- **不建議 commit**——依 AGENTS.md Git 安全規範，先呈 diff 給使用者確認。
+- **不用 compact**：若 context 已吃緊，明講「本 session 建議收工，後續修補可續用本 session（熱修補）；若本 session 已冷或被切割，開新 session 依 report＋issue_log 冷啟動」。
+- 修補波期間：每修一筆 append issue_log。
+
+## 5. 中途交接（context 吃緊、未完工）
+
+**不 compact**——compact 後地圖已被有損壓縮，熱 session 的價值已死；改寫交接文後關 session。
+
+1. 更新 todo 狀態（已完成／進行中／未動）。
+2. 寫交接文 `_docs/<領域>/handoff_<主題>.md`（首份無版號，之後 `handoff_<主題>_v<n>.md`）。
+   **一次一份新檔，不 append 到舊份**——舊份留著當歷史，不回頭改。
+   表頭列出日期、交接原因、分支狀態，以及**前一份的連結與取代關係**
+   （例：「前一份 `handoff_<主題>_v4.md`——內容已完成，本檔取代」），內容：
+   - 規劃書路徑＋目前做到第幾個工作項
+   - 改到一半的檔案清單＋各自狀態（例：「X.ts 已改完未測」「Y.ts 改一半，缺 Z」）
+   - 目前紅綠狀態（哪些測試綠、哪些紅、為什麼）
+   - 下一步（具體到「打開哪個檔做什麼」）
+   - 環境備註與陷阱（dev server 埠、flaky 測試、workaround）
+3. 本輪已完成的修正照常記 issue_log。
+4. 給使用者一行接續指令：「新 session 開場：`依 <plan路徑> 續作，先讀 <handoff路徑> 與 issue_log`」。

package/publish/README.md

@@ -0,0 +1,75 @@
+# publish/ — 要複製到別的專案去用的東西
+
+三樣，落地位置各不相同：
+
+| 這裡的 | 落到目標專案的 | 是什麼 |
+| --- | --- | --- |
+| `.claude/skills/<name>/` | `.claude/skills/<name>/` | skill——給讀這個目錄的 host |
+| `.agents/skills/<name>/` | `.agents/skills/<name>/` | 同樣的 skill，給讀開放規格目錄的 host |
+| `.claude/agents/*.md` | `.claude/agents/` | lens 定義——spoke 的 system prompt 來源 |
+| `workflow_spec.md` | 專案根目錄 | 規劃→實作→驗收流程規範 |
+
+> **`.claude/agents/` 不要跟著搬。** 那是 CLI 硬編的路徑（`--repo-root` 底下的
+> `.claude/agents`），跟 host 讀哪裡無關——它是工具在讀，不是 agent 在讀。
+
+## 安裝
+
+```bash
+TARGET=<目標專案路徑>
+mkdir -p "$TARGET/.claude/skills" "$TARGET/.claude/agents" "$TARGET/.agents/skills"
+cp -R .claude/skills/. "$TARGET/.claude/skills/"
+cp -R .agents/skills/. "$TARGET/.agents/skills/"
+cp .claude/agents/*.md "$TARGET/.claude/agents/"
+cp workflow_spec.md "$TARGET/"
+```
+
+**全部整檔覆蓋**，沒有需要手工拼接的部分。
+
+> **`.claude/` 與 `.agents/` 兩個都要複製，不要因為「這個專案不用 Claude」就跳過
+> `.claude/`。** 底下的 `agents/` 是 CLI 的資料目錄——它是工具在讀，跟你的 agent 是誰
+> 無關。漏了的話乾跑會中止並印出它找不到的路徑（不會花到錢），但你得回頭補一次。
+
+裝完之後在目標專案跑 **`preflight`**——它會檢查接線有沒有做、環境有沒有把流程靜默停用。
+這些失效**都不會報錯**，只會安靜地讓流程不生效。
+
+**skill 不保證是 `/` 指令。** 有的 host 會自動掛載這兩個目錄並提供 `/名稱`，有的兩者
+都沒有。叫不動的話直接指名檔案：「照 `.agents/skills/preflight/SKILL.md` 執行」。
+
+### 兩份 skill 的關係
+
+`.agents/skills/` 那份是從 `.claude/skills/` 衍生的——**內容相同，只拿掉了只有特定
+host 才成立的段落**。它的 frontmatter `metadata` 記著來源檔的 sha256，來源改了、衍生版
+沒跟上，發佈前檢查會擋下來。**要改一律改 `.claude/skills/` 那份**，再回頭看衍生版。
+
+## 把 `workflow_spec.md` 接進目標專案
+
+Claude Code **讀 `CLAUDE.md`、不讀 `AGENTS.md`**；而 `AGENTS.md` 規格本身**沒有定義任何
+import 機制**。兩種讀者得分別交代，否則其中一邊會靜默漏讀整份規範。
+
+在目標專案的 `AGENTS.md` 尾端加：
+
+```markdown
+## 工作流程規範
+
+見 `workflow_spec.md`（專案根目錄）。下一行的 `@` 是 Claude Code 的 import 語法，
+會自動載入該檔；其他工具請自行開啟。
+
+@workflow_spec.md
+```
+
+三個細節，弄錯了不會報錯、只會安靜地沒作用：
+
+- **`@` 不能包在反引號裡**——包了就是字面文字，不會 import
+- 路徑**相對於含 import 的那個檔**，不是相對工作目錄
+- import 可遞迴，上限**四層**；`CLAUDE.md` → `AGENTS.md` → `workflow_spec.md` 是兩層
+
+目標專案若沒有 `CLAUDE.md`，另建一個、內容一行 `@AGENTS.md` 即可（官方建議做法）。
+
+## 這裡不准出現的東西
+
+`publish/` 的內容會在一個不知道來源專案存在的地方執行，所以不得出現絕對路徑、來源專案的
+名稱與文件檔名、只有來源專案成立的指令，以及實測數字與樣本數討論（那些是依據，不是操作）。
+
+例外：`_docs/` 這個名字可以出現——它是 CLI 硬編的 spoke 禁區，屬工具層保留目錄。
+
+同步前先跑來源專案的發佈前檢查，它會把上面這些掃一遍。

package/publish/workflow_spec.md

@@ -0,0 +1,65 @@
+# 工作流程規範
+
+## 規劃→實作→驗收流程規範（主從形態）
+
+> 規劃書是決策過程的有損投影；誰持有活脈絡，誰做那件事就便宜。本節依此組織：規劃與裁決在有脈絡的 hub，執行在工單制的 spoke，品質裁決交給數字。
+
+### 角色
+
+| 角色 | 職責 | 權限 |
+| --- | --- | --- |
+| **使用者** | 做不做、目標、狀態變更（動工／阻擋／終止） | 裁量權**無需舉證**，一句話生效 |
+| **hub**（有脈絡的長對話） | 討論聚焦、寫規劃、發工單、融合 spoke 回報、對照初衷分析差異 | **版本只從 hub 出** |
+| **spoke**（工單制 session） | 實作（＝審查＋實作）、量測（benchmark）、找漏洞（可選） | 無版本權、無狀態欄、無裁決權 |
+
+### 流程總覽
+
+```
+0. 決策討論（hub＋使用者）→ decision 文件
+1. 規劃（hub，依必答檢查）→ plan 文件 → 使用者直接審定
+   （可選：使用者點名找漏洞 spoke——need-to-know 工單、產出意見不產裁決；skill：`/find-holes-external` 外派、`/find-holes` 內派 sub-agent）
+2. 實作（spoke，「依 X 文件實作」開場）→ 完成條件 = `pnpm run test`/`lint`/`tsc`/`build` 全綠 → report＋runbook（收尾 skill：/wrap）
+3. 熱修補（同 session 續命至修補波結束）→ 每修一筆 append issue_log，不回頭同步 report/runbook
+4. 驗收（使用者）：行為驗收（照 runbook 手測）＋ diff 過目（忠於規劃、無夾帶）＋ 商業判斷 → commit/PR
+```
+
+### 文件紀律
+
+- 六種文件各司其職：**decision** 記 why／**plan** 記 how／**facts**（append-only）記已驗事實／**report** 記交付狀態（產出後不回改）／**runbook** 記手測步驟／**issue_log** 記修補帳（append-only，雜亂即正常）。
+- 新版只寫差異；背景一行引用 decision，不重述。
+- 文件狀態欄變更權專屬使用者；**文件不得自訂翻案條件**（「本文件只能被 X 推翻」即紅旗）。
+
+### 出處三規則（防走私）
+
+1. 「依使用者裁示／已定案」**必附出處**（原話、時間、回答的是什麼問題）；無出處視為未定案。程序性回答（「還沒」「等一下」）不得升格為實體決定。
+2. 驗收門檻**必附推導**（同機制的實測基準或使用者指定）；模型自擬數字無效。門檻校準的基準須同機制——一次改兩個變數，門檻先失效。
+3. 先例引用**給尺不給屍**：判決只在「同問題＋同成本結構」下可移植；「那案死了這個也會死」不是論證。
+
+### 品質賭注條款
+
+模型／prompt／呼叫機制的選擇一律由 benchmark 裁決：事前訂死門檻、不事後翻案；未達門檻不強行採用；負結果連同結果檔入檔，後續同類提案須先面對既有量測。
+
+### 實作 session 紀律
+
+- 開場先列 todo（TodoWrite，穿越 context 壓縮的錨）；大量讀檔偵察派 sub-agent（context 防火牆）。
+- **不用 compact**（有損，且 compact 後熱 session 價值已死）：context 吃緊 → 在最後一個自然斷點收尾——完工走 `/wrap`，**未完工走 `/wrap` 中途交接模式**（寫交接文 `handoff_<主題>.md`，之後每次交接開新版本檔 `handoff_<主題>_v<n>.md`、表頭指出取代哪一份，不 append 舊份）→ 關 session → 新 session 依規劃書＋交接文冷啟動。發現對話開頭是 "This session is being continued" → 重讀規劃書，不信摘要裡的規格。
+  **「context 吃緊」由使用者判斷，不要憑感覺自行宣告**——模型量不到自己的 context，主觀判斷的誤報遠多於命中。除非使用者說了、或有實際數字，否則只在自然斷點提一句「要不要收尾」，不要反覆提醒、更不要因此中斷正在做的工作項。
+- 施工中偏離規劃 → 記入 report（施工中修正節）；同檔順手修（無關 lint 錯等）允許，記 issue_log。
+
+### 撰寫實作規劃書時的必答檢查（MUST）
+
+每一條在規劃書中須有明確答案或明文標註「刻意接受的取捨」，不得留白：
+
+1. **引用即驗證**：每一句「既有機制已涵蓋／零改動／本來就有 X 過濾」，必須實際打開該檔案把**完整語意**追完（含分支、聯集／副表、fallback 路徑），不能只憑檔名、註解或行號。引用時附上支持結論的關鍵語意，不只附位置。
+   **本條同樣適用於驗收 spoke 的引用**（內派與外派皆同）：驗「spoke 說的那段註解在不在」不夠，還要驗「**註解說的還成不成立**」——註解會與程式碼漂移。實測案例：spoke 引用某檔頭註解宣稱「該元件在 provider 範圍之外」，hub 確認註解存在且措辭吻合便判為事實正確，但那段架構早已被搬進 provider 內，**結論是錯的**。
+2. **失敗態與時間窗**：每個機制寫出失敗時的行為——排程沒跑之前？重試用盡之後？併發競態？「最多 N 次」後面沒接「用盡則…」就是未完成的設計。
+3. **計費呼叫的閘門順序**：任何產生外部 API 成本的呼叫（LLM／STT／圖片生成／embedding），限額或 gate 檢查必須在呼叫**之前**；「成功後才扣次」須另配前置唯讀 pre-check，並回答「超限之後每一次請求會發生什麼、成本是多少」。
+4. **新端點防護必答**：任何新增的 API route 必須明寫 auth 層級、rate limit、request body 大小上限三項；「不需要」也要寫出理由。若專案內已有同型漏洞的修復案例，引用其文件作為標準。
+5. **可實作性驗證**：每個「後端驗證 X／程式層保證 Y」，回答後端技術上做得到嗎、需要什麼依賴；做不到的改為可實作的替代（如前置粗篩 + 後置精確判斷兩段式）。
+6. **雙向生命週期**：任何「上架／下架、啟用／停用、時效」機制，兩個方向都要有定義（只寫下架掃描沒寫上架回填 = 缺口）；索引類副本（embedding、變體、快取、投影）在狀態變更時是否全部連動。
+
+### 獨立審查
+
+規劃書不送任何獨立 session 審查、不得建議恢復；歷史 `_docs` 中的「給審查閘的指引」不再適用。乾淨視角一律以「找漏洞 spoke」形式存在（見流程總覽第 1 步的兩個 skill）。
+
+---