agentic-sop-to-work plugin

---
name: agentic-sop
description: Use when turning a human SOP or manual process into an agentic workflow, building or adding an agent tool, or starting a new agent-workflow project — even if the user never says 'SOP' or 'methodology'. ｜ 要把人工流程／SOP 自動化、建立或新增 agent 工具、或開一個新的 agent 工作流專案時使用；只要意圖是把流程工程化成自動代理就觸發。不適用：稽核既有工作流是否退化成 mega agent（改用 agentic-workflow-audit）。
---

# 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。

## 拆解完，先畫拓撲（動手接線之前）
拆出節點之後、寫 `flow.json` 之前，**先把圖講清楚**——這一步只花幾分鐘，卻是後面所有閘門的地基：

1. **節點**：列出每個節點（＝一個工具的一步）。
   *節點不是 agent*：把工具換成模型的節點常被叫做 agent，但**一 skill 一工具**不變；
   一個節點裡塞了整條流程就是 mega agent，名字叫什麼都一樣。
2. **邊**：每條邊**取一個名字**——「誰把**什麼**交給誰」。交接的是具名產物，不是「整包 context 丟過去」。
   接著給它型別（`schema_ref` 指向 `workflow/schemas/<tag>.json`）：邊沒有型別，交接協定就是假的。
3. **狀態欄位與 owner**：列出流程要共用的欄位，**每個欄位指定唯一一個 writer 節點**；
   讀取方宣告 `reads`。值不另外存——留在該節點的 artifact 裡（`written_by` 就是 `produced_by`）。
4. **退回邊**：哪一步的判定會把工作**退回**上游？那條邊宣告 `back:true` ＋ `max_revisits:<N>`。
   沒有上界的環不准存在；退回的判定必須由**確定性的欄位**決定，不是由模型當場決定。
5. **驗證**：`python3 workflow/run.py --plan` 會把整張圖靜態判過（不可達節點、read-before-write、
   寫入衝突、無界環、孤邊），不合法在跑之前就 exit 2；`--graph` 畫出來給人看。

> 五題有任一題答不出來，就是還沒拆完——**別急著寫 flow.json**。
> 若流程本來就是一條直線、也沒有退回，那就照直線做：以上宣告全是選擇性的，不宣告即維持線性行為。

## 落地：導入 agentic-sop-kit（不要重造）
方法論已封裝成可攜套件，**直接導入、別重寫**：
1. 一鍵導入：`python3 "${CLAUDE_PLUGIN_ROOT}/kit/bootstrap.py" --project /path/to/project`（複製 kit＋裝 `/sop-flow`）。canonical kit 在本 plugin 的 `${CLAUDE_PLUGIN_ROOT}/kit/`；Stop 回歸閘門由 plugin hook 負責（沒裝 plugin 才加 `--with-hooks`）。
2. `python3 agentic-sop-kit/check_deps.py` 驗依賴；`workflow/run.py` 跑通範例。