agentic-sop-to-work

agentic-sop-to-work

Loop Engineering — make an agent's loop produce verifiable progress, stay honest, and stay bounded, by deterministic mechanism rather than vibes. agentic-sop-kit is the reference toolkit: it turns a human SOP into a controlled loop, not a one-shot script — no fabrication, no "mega-agent" rot. Loop Engineering — 用確定性機制(不是 vibes)讓 agent 的迴圈每次迭代產生可驗證進度、不自我欺騙、不失控。agentic-sop-kit 是它的參考工具包:把人工 SOP 變成一條受控迴圈——不臆造、不退化成 mega agent。

⭘→◉ Graph Engineering — when one loop isn't enough. Loop Engineering makes one loop trustworthy; Graph Engineering composes trustworthy loops into a bounded graph: named nodes, typed handoff edges, field-level state ownership, and bounded back-edges. The loop invariants descend to nodes and edges — same determinism, one rung up. ⭘→◉ Graph Engineering — 一個迴圈不夠用時。 Loop Engineering 讓一個迴圈可信；Graph Engineering 把可信的迴圈接成一張有界的圖:具名節點、有型別的交接邊、欄位級的狀態所有權、有界退回邊。三個不變量下降到節點與邊的粒度——確定性不變,只是上了一階。

/plugin marketplace add s0912758806p/agentic-sop-to-work
/plugin install agentic-sop-kit@agentic-sop-to-work
/reload-plugins

🌐 English ・ 繁體中文

🗺️ At a glance · 運作一覽

Human SOP → single-tool skills → orchestrated flow (gated · branch · map) → DRAFT → human approval; a Stop-hook regression gate guards every change.Human SOP → 單一工具 skill → 編排流程（閘門・分支・map）→ DRAFT → 人核准；Stop-hook 回歸閘門守住每次變更。

flowchart LR
    SOP["📄 Human SOP"]
    SK["🔧 single-tool skills<br/>one tool · I/O contract"]
    RUN["⚙️ run.py<br/>steps · branch · back-edge · map · --plan"]
    G{{"🚦 per-step gate<br/>cmd · schema · trace · recompute · residual"}}
    DR["📝 DRAFT"]
    OK(["✋ human approval"])
    STOPN["✗ stop & fix"]
    REG[["🔁 Stop-hook regression<br/>change → tests → block & fix"]]

    SOP -- decompose --> SK
    SK -- orchestrate --> RUN
    RUN --> G
    G -- pass --> DR
    DR --> OK
    G -- fail --> STOPN
    G -. bounded back-edge .-> RUN
    REG -. guards every change .-> SK

    style OK fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    style G fill:#FFF8E1,stroke:#F9A825
    style REG fill:#FFEBEE,stroke:#C62828,color:#B71C1C

🔁 The loop, engineered · 受控迴圈的三不變量

agentic-sop-kit makes the loop a controlled one — three deterministic invariants, human-owned at the controlled/destructive edges:

• Bounded termination · 有界終止 — budget (count) + stall (progress): stop when iterations stop producing verifiable progress, not only when retries run out.
• Observable health · 可觀測健康 — a coverage drop hard-gates; slowdown / flaky surface as advisory.
• Bounded state · 有界狀態 — the regression log auto-rotates; run dirs prune on demand (human-authorized).

"Human SOP → workflow" is one application of this loop; the same loop-control applies to any agent loop.

◉ The graph, engineered · 把迴圈接成一張有界的圖

A linear pipeline cannot express "the reviewer sent it back". A graph can — without giving up determinism: 一條線性管線無法表達「審查把它退回去了」。圖可以——而且不必放棄確定性:

• Nodes are steps, not agents · 節點是步驟,不是 agent — one node = one tool. Swap the tool for a model and people call it an agent, but one skill, one tool is unchanged. 節點就是「一個工具的一步」;一 skill 一工具 一個字不改。
• Typed edges · 有型別的邊 — schema_ref makes the schema tag load-bearing: wrong tag or wrong shape is a hard failure. An untyped edge means the handoff contract is fiction. 邊沒有型別,交接協定就是假的。
• State is a declaration, not a container · 狀態是宣告,不是容器 — no state store, so nothing can drift from the artifacts. A field's value stays in its owner node's artifact and written_by is that artifact's own produced_by. Exactly one declaring writer per field; the run manifest records topology.owners and path_taken. 唯一 writer + 所有路徑保證寫過,就是「誰給誰什麼」的契約——這是稽核條文「黑板式共享狀態 = FAIL」的可執行版本,條文本身一字未改。
• Cycles are legal because they are bounded · 環合法是因為有界 — a backward goto must declare back:true + max_revisits. --plan refuses an unbounded cycle before anything runs, and lib/loop/'s progress sensor now measures per edge: identical routing state across revisits is an idle stall that stops the loop before the bound. 舊的 forward-only 從「禁止」改成「有界才准」。
• Retry history survives · 退回歷史不被覆寫 — a revisit archives the previous artifact (draft.visit1.json) instead of overwriting it. 一個會覆寫的中央 store 會讓第一次嘗試消失。

flowchart LR
    n0["draft<br/>draft@1"]
    n1["verdict<br/>verdict@1"]
    n2{{gate}}
    n3["accept<br/>accepted@1"]
    n0 --> n1
    n1 --> n2
    n2 -.->|"verdict == 'reject' (≤2)"| n0
    n2 -->|"default"| n3

The shipped graph.json example, drawn by run.py --graph. This block is generated from the flow and byte-compared by kit/tests/test_graph_docs.py — the picture cannot disagree with the pipeline.出貨的 graph.json,由 --graph 生成、由測試逐位元綁住——圖不可能與流程不一致。

Adopting nothing is free · 不宣告就零影響 — declare none of reads / writes / schema_ref / back and the engine behaves byte-identically to before, guarded by test_legacy_flow.py.

---

English

What. agentic-sop-kit is a Loop Engineering toolkit: it turns a process you do by hand (a "Human SOP") into a controlled agentic loop an LLM can run safely and repeatably — with bounded termination, observable health, and bounded state. A methodology + portable toolkit — not a chatbot. Built for regulated / high-stakes / must-be-correct work.

Why it's safe — it blocks the predictable LLM failures:

• Fabrication → facts come only from inputs; gaps marked 【待補】, never invented.
• Fake autonomy → deterministic work in code; hard gates are hermetic & LLM-free (self-eval only advisory, capped).
• Unaccountable output → every output is a DRAFT; controlled / high-risk calls stay human-owned.
• Mega-agent rot → an audit skill + a Stop-hook regression gate that re-verifies on every change.

What you get

3 Skills (auto-trigger by intent)	six-rung-ladder — minimalist "should I build this at all?" filter (decide) · agentic-sop — methodology + entry point + smart intake (build) · agentic-workflow-audit — read-only mega-agent auditor (audit)
Command /agentic-sop-kit:sop-flow	runs the kit's orchestration, reports a DRAFT
Hooks (project-scoped)	SessionStart dep-check · Stop regression gate — no-op until a project adopts the kit
Portable kit kit/	copy-into-any-project methodology + runnable example
Plugin second-opinion-honesty	adversarial honesty reviewer — checks a finished DRAFT's claims against its evidence (fabrication / overreach / invented IDs); deterministic findings are HARD, the LLM red-team layer is advisory and capped; reads a run dir read-only, never imports the kit
Plugin alcoa-guard	ALCOA+ data-integrity linter — deterministic checks for Attributable / Contemporaneous / Complete / Accurate / Consistent; surfaces the human-judgment slice as a 【待補】 checklist; pure stdlib; report is a DRAFT
Plugin plugin-forge	Claude Code plugin linter + scaffolder — lint validates a plugin or whole marketplace against a house grammar (strict superset of manifest/frontmatter checks + stdlib-only, hook-protocol, and test-harness invariants); scaffold generates a grammar-conformant plugin skeleton; self-hosting; pure stdlib

Engine (run.py) — deterministic, code-decided, additive:

• Per-step gates (block on fail, zero LLM): cmd_gate · schema_gate (+ schema_ref for a typed edge) · trace_gate (no fabrication) · recompute_gate · residual_gate (a required field still 【待補】).
• cmd steps (allowlisted; mutations need --allow-mutations) · --plan dry-run — lists every step and statically validates the whole topology (unreachable node · read-before-write · write conflict · unbounded cycle · dangling goto), exit 2 before anything runs.
• branch · bounded back-edges (back:true + max_revisits) · map_over (per-item) — control flow in code, never the model.
• --graph draws the topology as Mermaid · the run manifest carries topology (field owners, back-edges and their bounds) and path_taken (the walk actually performed, with archived earlier attempts).
• Examples — dependency-free FE / BE / DB / AI flows plus a four-node graph.json with a real bounded back-edge, in kit/workflow/examples/.
• Capped auto fix-loop — on a gate failure, /sop-flow auto-fixes & re-runs (run.py --max-fix-retries; code-enforced per run-id, capped by SOPKIT_MAX_FIX_RETRIES, default 3 — the same knob as the Stop-hook regression loop); exhausted → stop for a human; never patches output to pass.
• Loop control (Loop Engineering, in kit/lib/loop/) — keeps the loop bounded, observed, and bounded-in-state: stall stops on no verifiable progress (SOPKIT_STALL_WINDOW); health hard-gates a coverage drop and flags slowdown/flaky (advisory); state auto-rotates the run log and prunes run dirs on demand (run.py --prune). All deterministic.

Iron rules — facts only from inputs (【待補】 for gaps) · deterministic work in code, gates hermetic & LLM-free · DRAFT + human approval · gates check truth, not keywords · a shared state needs a contract: one declaring writer per field, guaranteed on every path. Real enforcement is the Stop-hook and the static topology gate, not prose.

Install — in Claude Code (incl. Claude Desktop's Code tab):

/plugin marketplace add s0912758806p/agentic-sop-to-work
/plugin install agentic-sop-kit@agentic-sop-to-work
/reload-plugins      # or restart the session

Requires Python 3.8+ as python3 (macOS/Linux out of the box; on Windows ensure python3 resolves). Verify: /help lists /agentic-sop-kit:sop-flow.

Build your own flow — adopt the kit: python3 <plugin>/kit/bootstrap.py --project <dir> → scaffold a step: new_skill.py --name <x> (fill DEPS / run()) → wire workflow/flow.json → make it conversation-triggerable: export_claude_skill.py --skill <x>. Details: kit/SOP.md.

Layout

agentic-sop-to-work/
├── .claude-plugin/marketplace.json
└── plugins/agentic-sop-kit/
    ├── .claude-plugin/plugin.json · skills/ · commands/ · hooks/
    └── kit/   # portable kit: lib/ · workflow/ · tests/ · templates/ · examples/ · SOP.md

License — MIT (LICENSE · NOTICE); keep the copyright/license notice in copies, including single files. Updating: git push → users run /plugin marketplace update agentic-sop-to-work; bump plugin.json version on each meaningful change.

---

繁體中文

是什麼。 agentic-sop-kit 是一套 Loop Engineering 工具包：把你手動做的流程（Human SOP）工程化成 LLM 能安全、可重複執行的受控 agentic 迴圈——有界終止 ＋ 可觀測健康 ＋ 有界狀態。是一套方法論 ＋ 可攜工具包，不是聊天機器人。為受監管／高風險／不能錯的工作而生。

為何可信 — 逐一封堵 LLM 的可預期失敗：

• 臆造 → 事實只來自輸入；缺的標 【待補】，絕不杜撰。