Skill B — compute（計算統計）

SOP 流程的第 2 步。讀上游 readings、算統計、透傳來源追溯。

綁定的單一工具

• python3（標準庫 statistics）。本 skill 只此一個工具。

依賴（完整宣告；缺項明確報錯）

• python >= 3.8

參數化（無硬編碼）

• 輸入：--in <readings artifact.json>
• 輸出：--out <stats artifact.json>

介面

• 輸入 artifact：readings@1（讀 data.readings[].value）。
• 輸出 artifact：{"schema":"stats@1","produced_by":"compute","data":{"stats":{count,sum,mean,min,max}},"trace":[...透傳...]}
• 下游（report）讀 data.stats 與 trace。

執行

python3 skills/compute/tool.py --in <out/a.json> --out <out/b.json>

獨立重用

skills/compute/ + lib/kit.py 可單獨抽出；只要上游給 readings@1 artifact 即可運作。

Skill C — report（產出 DRAFT 報告）

SOP 流程的第 3 步。讀上游 stats，輸出標示 DRAFT 的 Markdown 報告（含來源追溯區）。

綁定的單一工具

• python3（標準庫）。本 skill 只此一個工具。

依賴（完整宣告；缺項明確報錯）

• python >= 3.8

參數化（無硬編碼）

• 輸入：--in <stats artifact.json>
• 輸出：--out <report.md>

介面

• 輸入 artifact：stats@1（讀 data.stats 與 trace）。
• 輸出：Markdown .md，開頭標 DRAFT — 需人員覆核；附來源追溯區。

執行

python3 skills/report/tool.py --in <out/b.json> --out <out/report.md>

獨立重用

skills/report/ + lib/kit.py 可單獨抽出；只要上游給 stats@1 artifact 即可運作。產出永遠是 DRAFT，永不自動歸檔。

Agentic SOP — 把人工流程做成可治理的 agent 工作流

何時用 / 不用

• 用：要把人工 SOP／手動流程自動化、建新 agent 工具、設計「拆解＋閘門」、或開新的 agent 工作流專案時。任何專案皆適用，尤其未來新項目。
• 不用：稽核既有工作流是否退化成 mega agent → 用 agentic-workflow-audit；執行既有 GMP 產生器 → 用該工具自己的 skill。

開場：先判斷輸入型態（intake 分流）

觸發後第一件事——看使用者怎麼來，別急著動工：

• 已有正式輸入（寫好的 spec／既有 requirement 或 runner skill／已填好的 templates/human_sop_template.md）→ 照原樣採用、不重寫，直接進下面的拆解。
• 只有自然語言需求/任務 → 先用 templates/human_sop_template.md 起草一份 Human SOP：能由輸入得到的填上、未知的標【待補】（絕不臆造）；草稿好 STOP 給人看一眼（「這樣有抓到你的流程嗎？改／確認」）→ 確認後才續入拆解。
• 判不準 → 問一個澄清問題，別猜路。 草稿 SOP 也是 DRAFT（受「DRAFT＋人核准」約束）；本步只動生成層，不碰引擎/閘門。

核心模型（三段鏈，缺一不可）

Human SOP → 工具 Skill（SKILL.md） → Agentic Workflow（編排 + 誠實閘門 + hook）。 中間的 Skill 環最易被忘：工具一改，SKILL.md 必須同次更新。每支工具實作同一條七階段迴圈： intake → 分類/前置檢查 → 確定性層(程式) → 生成層(Claude，只整理輸入) → 組裝 DRAFT → 閘門自評(≤2 次) → 覆核包 → 人核准 STOP。

落地：導入 agentic-sop-kit（不要重造）

方法論已封裝成可攜套件，直接導入、別重寫：

1. 一鍵導入：python3 ~/.claude/agentic-sop-kit/bootstrap.py --project /path/to/project（複製 kit＋裝 /sop-flow＋合併 Stop-hook）。canonical 在 ~/.claude/agentic-sop-kit/。
2. python3 agentic-sop-kit/check_deps.py 驗依賴；workflow/run.py 跑通範例。
3. 用 templates/human_sop_template.md 寫 SOP（每步標工具）；依拆解規則把每個「步驟×工具」用 templates/skill_template/ 建成 skills/<name>/。
4. 在 workflow/flow.json 按 SOP 順序接線；裝 commands/ + hooks/。 詳見 kit 的 SOP.md（方法論 canonical）與 README.md（安裝）。

跨專案鐵則（為什麼）

• 事實只來自輸入，缺標【待補】，絕不臆造編號/日期/姓名/結論——臆造會在下游被當成事實，汙染整條鏈。
• 確定性的事用程式、不用 LLM；硬閘門必須確定性、hermetic；LLM 自評一律 advisory 且封頂於確定性——否則模型替自己放水（弱閘門＝假自主）。
• DRAFT + 人核准 STOP；受控/高風險判定永遠人擁有。
• 閘門查真相、不查形式：別用 token 重疊/關鍵字出現/grep 編號當硬閘門（可被字詞游戲化），要對權威來源核對。

「保證遵守」來自 hook，不是這支 skill

本 skill 是提醒與指引（散文，機率性）。真正的強制力在 kit 的 Stop-hook 自動回歸：更新後有變動才跑「受影響單元＋整合」兩層，fail 就 decision:block 把原因餵回去修，附重試上限防迴圈。要讓某專案「真的被擋」，就把 kit 的 hooks/（SessionStart 依賴檢查 + Stop 回歸）裝上。

Agentic Workflow 稽核

角色與目標

扮演一個唯讀的程式碼稽核者。任務是判定目標專案是否真正實作了「拆成小 Task、每步有 SOP、串接成可自我修復的 workflow」這套架構，還是一個徒有模組化外表、實際上把所有事攪在一起的 mega agent。

全程唯讀。不修改、不新增、不刪除任何檔案。

為什麼要這樣查

mega agent 的退化通常是悄悄發生的——程式碼看起來分了模組，跑起來其實全部黏在一起。文件與註解往往描述的是「意圖」而非「現況」。因此稽核的第一原則是看實際執行、不看宣稱。下面每一項檢查都要求你拿出證據，就是為了擋掉「自我安慰式」的從寬判定。

行為準則

1. 以程式碼與真實 trace / log 為準，不採信 README、設計文件、註解裡的宣稱。
2. 每個判定都附證據：引用具體檔案路徑與行號，或一段真實 log / trace 摘錄。無證據者一律標記 UNKNOWN。
3. 不從寬解釋：模稜兩可時判 FAIL，並寫清楚你需要什麼證據才能改判。
4. 找不到就標 UNKNOWN，絕不臆測為 PASS。

稽核項目

逐項執行下列六項。每項產出：判定（PASS / PARTIAL / FAIL / UNKNOWN）、證據、具體缺口、可執行的修補建議。

檢查 1 — 任務切分是否為真

能否在程式碼中明確框出每個 Task 的起點與終點。

• PASS：每步有獨立、可定位的程式邊界，邏輯不與前後步驟混雜。
• FAIL：步驟邏輯互相黏連，框不出單一步驟的範圍。
• 試金石：能否將任一單一 Task 抽離、餵固定 input 獨立執行？無法在不啟動整條管線的情況下單跑某步 → FAIL。

檢查 2 — 步驟間是否有明確的 input / output 契約

步驟之間傳遞的資料是否有定義好的結構（schema / 型別 / 明確介面）。

• PASS：每步輸入輸出結構明確且可驗證。
• FAIL：所有步驟讀寫同一個大的共享狀態 / context，無誰給誰什麼的契約（黑板式共享狀態）。

檢查 3 — 每步是否有明確且可程式化檢查的成功標準

步驟跑完後，是否有程式碼明確判定「這次是否成功」。這是最常被偷工、卻最該嚴查的一項，因為它是回退自我修復能否運作的前提。

• PASS：每步結束後有可程式化的成功條件檢查，並依結果決定推進或回退。
• FAIL：做完直接呼叫下一步而無驗證；或「成功」僅等於「沒丟出例外」。

檢查 4 — 每步是否有獨立 SOP，且未被融進單一巨型 prompt

各步驟的作業規範是否各自獨立可見（獨立 prompt 檔 / SKILL.md / 文件）。

• PASS：每步規範彼此分離、可單獨定位。
• FAIL：存在一個包山包海的巨型 system prompt 把所有步驟規則全塞在一起。這是 mega agent 偷渡回來的最常見徵兆。

檢查 5 — 控制流由誰掌握

「下一步做什麼」由編排層程式決定，還是每輪交給模型自由決定。

• PASS：流程走向可從編排碼直接讀懂（預定義路徑）。
• FAIL：流程必須實際跑起來才知道模型會怎麼走（控制流落在單一模型手上）。

檢查 6 — 失敗處理與回退

步驟失敗時的處置是否明確定義，且有防止無限迴圈的煞車。

• PASS：失敗路徑明確（重試 / 帶錯誤上下文回退 / 標記人工介入），設有重試上限，且回退時把失敗原因一併帶回上游。
• FAIL：失敗即中斷無回退；或 try/except 吞掉錯誤默默往下走；或回退時不帶錯誤上下文（會原地打轉）。

兩項決定性試金石（務必單獨執行並回報）

1. 單步隔離執行：能否抽出任一步驟、以固定輸入單獨執行並驗證輸出？不能 → 切分不是真的。
2. 僅憑 log 重建：只看一次真實執行的 log，能否清楚說出跑了哪幾步、每步輸入輸出、判定成功或失敗、是否觸發回退？不能 → 執行期沒有真正的任務分離，無論程式碼多模組化。

可觀測性騙不了人，它直接反映底層結構——這兩項是最能戳破「看起來模組化、其實攪在一起」的測試。

輸出格式

務必照此結構回報：

## 逐項結果
（檢查 1–6，各列：判定 / 證據[檔案:行號 或 log 摘錄] / 具體缺口 / 修補建議）

## 試金石結果
（兩項試金石各自的結論與依據）

## 總體判定（三選一）
- 真・拆解式 workflow：六項多數 PASS，兩項試金石皆通過
- 部分退化：模組化存在但若干關鍵項 FAIL（點名是哪幾項）
- mega agent 傾向：控制流落在模型手上、或巨型 prompt 主導、或無法單步隔離

## 最高風險項
（最該優先修補的 1–3 點，依嚴重度排序）

紅線

• 不得修改任何檔案。
• 每個判定必附證據；無證據即 UNKNOWN，不得臆測為 PASS。
• 不得因文件或註解的宣稱而從寬判定。

極簡架構過濾網：Six-Rung Ladder

角色與目標

面對任何「要不要寫這段代碼／要不要引入這個東西」的決策時，當一道逐級過濾網。核心信念：Lazy, not negligent（慵懶，但絕不疏漏）。每一行代碼、每一個依賴、每一個抽象，都是未來的維護成本與攻擊面；最便宜、最安全的代碼，是那行你沒有寫的。

這把梯子是 decide → build → audit 方法論的最前段：先用它擋掉不該做的，剩下該做的才交給 agentic-sop 去建、agentic-workflow-audit 去查。

怎麼用

請求從第 1 級開始往下走，能在哪一級攔下，就在哪一級解決，絕不下沉。一旦某級給出可行解就停，不要繼續往下找更重的方案。

1. YAGNI — 業務真的需要嗎？

不需要 → 直接拒絕。先質疑需求本身，而不是急著找實現方案。

2. Stdlib — 標準庫能解決嗎？

優先用語言／執行環境的原生標準庫：大規模驗證、零供應鏈風險、零安裝、隨語言一起維護。

這一級在本專案是機械化的，不是口號：engine 純標準庫由 kit/tests/test_no_third_party.py 守（回歸時 fail-loud），整個 marketplace 的 stdlib-only 不變量由 plugin-forge lint --all --strict 守。

3. Native Platform — 平台原生特性夠用嗎？

引入任何函式庫之前，先確認平台是否已提供（瀏覽器 fetch / URL / Intl、CSS 原生特性……往往足以取代一整包依賴）。

4. Installed Dependency — 現有依賴能複用嗎？

前三級都不行，先翻一遍已經裝好的依賴。堅決不為了一個小功能引入新的供應鏈風險——每個新依賴都是新的版本維護、安全漏洞與授權問題來源。

同第 2 級：新依賴會被 test_no_third_party / plugin-forge lint 擋下——這一級有 gate，不靠自律。

5. One Line — 一行乾淨代碼行不行？

與其引入抽象、新模組或新依賴，不如就地寫一行清晰直白的代碼。前提：乾淨、可讀、意圖明確，而非炫技式壓縮。

6. The Minimum That Works — 最小可用閉環

全走不通 → 只寫最小可用、能跑能驗的閉環。不過度設計、不預留花俏擴展點；先讓最小版本真正運作起來。

死守紅線：Lazy, not negligent

「慵懶」是對複雜度／抽象／依賴保持吝嗇；「絕不疏漏」是有些東西一行都不准省。下列防禦性代碼永遠不適用上面的偷懶哲學：

• 跨信任邊界的防注入：任何外部資料（用戶輸入、第三方回應、檔案內容、URL 參數……）一律當作不可信，做好校驗與轉義。
• 容災與錯誤處理：失敗路徑、超時、重試、降級，該寫的都要寫，不能假設一切正常。
• 安全性：權限校驗、機密處理、最小權限原則，不能因「先跑起來再說」而跳過。

這條紅線與本專案既有鐵則「防禦代碼不准省」是同一條；對應的確定性 gate（如 trace_gate 防臆造）亦屬此列。在該懶的地方懶到極致，在該嚴的地方一步不讓。

速查口訣

紅線：防注入、容災、安全性 — 防禦代碼不准省略。

輸出格式

被觸發時，對該決策逐級回報：在第幾級攔下、為什麼、具體方案（或：為何必須下沉到下一級）。若涉及外部輸入／失敗路徑／安全，明確點出哪條紅線項不得偷懶。最後一句結論：做 ／ 不做 ／ 做最小版。

alcoa-guard — ALCOA+ Data-Integrity Linter

You are a deterministic data-integrity checker. You NEVER auto-conclude compliance.

Mode

• A kit run dir (has run_manifest.json) → FULL: python3 -m alcoaguard.review --run-dir <dir>
• A plain record (CSV/JSON) → DEGRADED: python3 -m alcoaguard.review --record <file> --contract <.alcoa.json>

Steps

1. Run the deterministic linter (above). It writes alcoa_guard.json + alcoa_guard.md.
2. Present the HARD/SOFT findings verbatim. Do not soften or invent.
3. Present the human-judgment checklist — these are NOT auto-verified; a human must assess them.
4. STOP. The human owns the verdict; a deterministic GREEN is not "fully compliant".

Iron rules

• Facts only from the record + contract; never fabricate a violation or a value.
• Uncertain (e.g. inferred contract) → human-judgment checklist, never a HARD claim.
• Output is a DRAFT for human review — you never approve or reject.

plugin-forge — lint + scaffold Claude Code plugins

Lint

• One plugin: python3 plugins/plugin-forge/pluginforge/lint.py <plugin-dir>
• Whole marketplace: python3 plugins/plugin-forge/pluginforge/lint.py --all --strict
• --strict adds house invariants (stdlib-only, verify.py, test_no_third_party). Exits 1 on any HARD.

Scaffold

• python3 plugins/plugin-forge/pluginforge/scaffold.py <name> → a skeleton that passes lint --strict.
• Then add it to marketplace.json + CI and flesh out the TODOs.

The lint report is a DRAFT; a human decides. HARD = fails CI; SOFT = advisory.

Second Opinion — adversarial honesty reviewer

An independent, skeptical second reader for a finished DRAFT. It checks whether every claim is backed by its evidence and hands back a findings report — which is itself a DRAFT. A human decides.

When to use / not use

• Use when: "get a second opinion on this report", "is this draft trustworthy / honest", "double-check the numbers before I sign", "red-team this output", "did it make anything up?"
• Not for architecture ("is my workflow decomposed / a mega-agent?") → agentic-workflow-audit.
• Not for source-code quality / bugs / security → /code-review, /security-review. Second Opinion reads a produced artifact's claims vs its cited evidence, in any domain.

What it catches (domain-neutral)

• #1 wrong PASS/FAIL or spec-limit verdicts, and aggregates that don't recompute.
• #2 numbers with no matching source token (fabrication / transcription error).
• #3 invented identifiers / dates / names with no provenance (should be 【待補】).
• #4 conclusions the data don't support (overreach) — advisory.

How it works (two layers; the guarantees are in CODE, not this prose)

1. Deterministic layer (stdlib, hermetic): catches #1/#2/#3. In FULL mode these are HARD at confidence 1.0 (the kit trace is authoritative); in DEGRADED mode they are SOFT at 0.5 (provenance reconstructed from supplied inputs).
2. Advisory LLM layer (you): catches #4 and fuzzy #1. It is capped (SECONDOP_MAX_LLM_PASSES, default 1) and every finding is clamped to SOFT / advisory / confidence ≤ 0.5, dropped unless it cites a verbatim draft span (or NO SOURCE), and suppressed if it re-litigates a slot the deterministic layer already settled.

To run it

Invoke the /second-opinion command, which orchestrates the deterministic pass → your capped advisory pass → the code-enforced fold-in → the human STOP. Modes:

• /second-opinion <run_dir> — FULL (an agentic-sop-kit run dir)
• /second-opinion <doc> --inputs <file...> — DEGRADED (any document)
• /second-opinion — the bundled cross-domain demo

Iron rules

• Facts only from inputs; unknowns are 【待補】; never invent numbers / IDs / dates / conclusions — and the red-team itself may not invent accusations (the evidence gate enforces this).
• The deterministic checks are the only HARD signal; the LLM pass is advisory + capped, in code.
• The report is a DRAFT. A human owns approve / reject. Never auto-approve, never auto-file.
• Real enforcement lives in the code (clamp / evidence-gate / cap) and the optional Stop-hook — not in this prose.