@dawipong/opcflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dawi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,253 @@
+<div align="center">
+
+# opcflow
+
+**A drift-enforced, spec-anchored execution layer for AI coding.**
+
+One template turns Claude Code / Codex / OpenCode / Cursor into a contract-governed, multi-role development pipeline.
+
+![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-339933)
+![tests](https://img.shields.io/badge/tests-89%20passing-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+[简体中文](README.md) · **English**
+
+</div>
+
+---
+
+## What it is
+
+Once generation is effectively free, **verification is the only bottleneck**. opcflow forges every
+verification you make (approvals, 👍👎, rulings) into machine-readable, invalidatable, propagating
+assets: docs → tasks → outputs form a real relationship graph (a DAG + foreign keys), and any change
+**propagates along the chain and auto-dispatches re-reviews**. You do only three things: **approve
+contracts, thumbs-up/down outputs, and answer rulings**.
+
+- **Real relationship graph** — an artifact DAG + task foreign keys, not naming conventions
+- **Five-state trust anchors** — editing approved content auto-invalidates it, downstream auto-goes-stale (state is derived from file content; nobody has to "update the status")
+- **Five-role pipeline** — product-manager → architect → designer → developer → qa, each consuming approved upstream contracts, each with a gate
+- **Change propagation** — `sync` reconciles → invalidate → dispatch review along the graph (deduped)
+- **QA loop** — fail → auto rework → auto re-verify, no human in the loop
+- **Write-gate hooks** — block agents from editing an approved contract (observe mode by default)
+- **Feedback evolution** — 👍👎 and QA verdicts, half-life weighted → skill candidates / Red Flags
+- **Multi-platform** — one definition generates each platform's agent + MCP + hooks (see [PLATFORMS.md](PLATFORMS.md))
+- **Visual opcflow** — tree + markdown/mermaid/prototype/code rendering + review-queue diff + live SSE
+
+## Difference from GitHub Spec Kit
+
+[Spec Kit](https://github.com/github/spec-kit) is a scaffold for spec-driven development: `/specify →
+/plan → /tasks → implement`, where each phase produces a markdown artifact that feeds the next,
+giving the agent **structured context** instead of ad-hoc prompts. It solves "**how to write a good
+spec before handing it to an agent**."
+
+opcflow takes over **execution and verification after the spec**. The two are different layers and
+complementary:
+
+| | Spec Kit | opcflow |
+| --- | --- | --- |
+| Role of the spec | **One-shot context** for the agent (markdown) | A machine-enforced **approved contract**; a DAG node |
+| Approval | No enforced state; a human reads it | Five-state trust anchor (draft/pending/approved/invalidated), machine-derived |
+| After the spec changes | No linkage; humans must remember to sync | **Auto-invalidate + downstream stale + dispatch review** |
+| Roles | Essentially single-flow (one agent implements) | Five-role pipeline, each with its own gate and output channel |
+| Construction constraints | The spec is advisory | Gates block tasks whose upstream isn't approved; write-gate blocks edits to approved contracts; protocol lints as checkpoints |
+| Acceptance | Not covered | Two-stage QA + fail→rework→re-verify auto loop |
+| Evolution | Not covered | 👍👎/verdict half-life weighting → skill candidates / Red Flags |
+
+In one line: **Spec Kit treats the spec as "context for the agent"; opcflow treats it as "an
+approved contract that can go stale, propagate, and block construction," and governs the entire drift
+from contract to code to acceptance.**
+
+## Installation
+
+opcflow is an npm package — it **does not drop source into your project**. Bootstrap from your
+project root with npx, zero install:
+
+```bash
+# In your project root: pick platforms (multi-select) + endpoints, generate in one shot
+npx -y @dawipong/opcflow init --platforms=claude,cursor --endpoints=service,web
+#   backend-only:  --endpoints=service          (auto-prunes designer, qa kept)
+#   set models:    --model='{"codex":"gpt-5.1-codex"}'  or  --model=<single string> (defaults per platform)
+```
+
+It writes only **generated artifacts** — each platform's agent definitions, MCP registration, hooks,
+`workbench.config.json`, the `docs/` skeleton, and the `.workbench/` database; **no opcflow source**.
+The generated MCP / hook / CLI references all point at `npx -y @dawipong/opcflow <subcommand>`, so no
+reinstall across machines or teammates. `--platforms` defaults to `claude`.
+
+> Per-platform layout, Codex trust, Cursor main-agent model, etc. — see **[PLATFORMS.md](PLATFORMS.md)**.
+
+Requires Node ≥ 22.
+
+## Quick Start
+
+1. **Fill in code-dir conventions** — edit `codeRoots` in `workbench.config.json` (each endpoint's code dir, `{module}` placeholder).
+2. **Start the opcflow** (visual approval panel, connects to the project's `.workbench`):
+   ```bash
+   npx -y @dawipong/opcflow serve       # → http://127.0.0.1:5620 (--project sets the root, defaults to cwd)
+   ```
+3. **Give the AI your first requirement** (one sentence). It runs the five-role pipeline, producing contracts layer by layer and submitting them for review.
+4. **Nod in the review queue** — view diffs in the opcflow; approve / reject; thumbs-up prototypes.
+5. **Once all contracts are approved, dispatch:**
+   ```bash
+   npx -y @dawipong/opcflow plan --module=<module>   # dispatch architect/designer/developer/qa tasks
+   ```
+
+Every later change is tracked: edit an approved contract → auto-invalidate → downstream stale → a
+re-review task appears in the queue.
+
+## Agent Authoring Flow (five-role pipeline)
+
+```mermaid
+flowchart LR
+    U(["⬜ Requirement"]) --> PM["🟦 product-manager<br/>business contracts"]
+    PM --> AR["🟦 architect<br/>DB + API contracts"]
+    AR --> DE["🟦 designer<br/>design system + prototype"]
+    DE --> DV["🟦 developer<br/>code"]
+    DV --> QA["🟦 qa<br/>acceptance"]
+    QA --> DONE(["✅ module accepted"])
+    QA -.->|"fail → rework"| DV
+```
+
+> 🟦 agent action · ⬜ user gate (approval / 👍) · ⚙️ engine-automatic. Every output must **pass a user
+> gate** before it becomes trusted truth for downstream. All agents share one skeleton: **claim (pass
+> the gate) → consume approved upstream → produce → register → submit/👍/accept → pass the gate →
+> complete**.
+
+**The trust protocol, everywhere**: upstream `approved` = truth, use it directly (**no re-derivation, no
+re-confirming**); `draft/pending` = usable but flagged "unreviewed"; `invalidated / under re-review` =
+**forbidden**, wait for re-review; on a substantive objection, use `dispute` to leave a trace and stop —
+never silently deviate.
+
+| Role | When it enters / gate | Produces | How it becomes truth |
+| --- | --- | --- | --- |
+| **product-manager** | user gives a requirement | layered business contracts: project → roles/glossary → flow (with entity state machine) → module PRD → page PRD (with acceptance points) | submit layer by layer; **approval required to advance**; all approved → `plan` dispatches |
+| **architect** | gate: flow + module PRD approved | tech baseline (ARCHITECTURE/TECH, task #0), DB docs, API contracts; **sole owner of shared enums** | human approval; no module may start before the baseline is approved |
+| **designer** | gate: that endpoint's design system approved | design system (human-reviewed), design prompts (registered only, not submitted), HTML prototype | prototype released via **👍 = feedback + approval combined** |
+| **developer** | gate: contracts in place; frontend tasks require a 👍'd prototype | code per endpoint (maintained by directory-level scan, not manually registered) | complete gate: machineChecks / protocolLints pass |
+| **qa** | two-stage: define acceptance criteria first (submit), then run after developer completes | acceptance cases (`docs/acceptance/...`), pass/fail | pass → +1 verdict on the code; **fail → auto rework → auto re-verify** until pass |
+
+> **Two ways to produce the HTML prototype**: by default the currently connected model produces it
+> directly; or hand the approved **design system** + **page design prompts** to a third-party design
+> platform (e.g. v0, Lovable) to generate the HTML, then drop the file into the matching path
+> `docs/design/prototypes/<endpoint>/<module>/<page>.html` — once `scan` registers it, it goes through
+> the usual 👍 release. Both paths are equivalent in the system; both must pass a user 👍.
+
+## CLI Commands & Parameters
+
+Every command: `npx -y @dawipong/opcflow <command> [args]`. Global `--project=<path>` sets the project
+root (otherwise it searches upward for `workbench.config.json`). File-path arguments are separated with
+`--` (e.g. `submit --actor=x -- <path>`).
+
+**Tasks**
+
+| Command | Purpose | Parameters |
+| --- | --- | --- |
+| `list` | list tasks | `--status` `--assignee` `--module` `--role` `--endpoint` `--type` `--stale=true` |
+| `show <id>` | task detail (events / outputs / stale) | `--json=true` |
+| `create` | create a task | required `--role` `--creator`; opt `--module` `--endpoint` `--page` `--type` `--assignee` `--content` |
+| `claim <id>` | claim (passes the gate, auto-snapshots deps) | `--assignee=<role>` |
+| `update <id>` | change status | `--status` `--operator`; `--force=true` bypasses the stale block (traced) |
+| `remove <id>` | delete a task | `--operator`; `--force=true` |
+| `record <id> "note"` | add a note | `--operator` |
+| `input <id> -- <path>` | declare a dependency read outside the gate | `--operator` |
+
+**Outputs**
+
+| Command | Purpose | Parameters |
+| --- | --- | --- |
+| `output -- <path>` | register an output (auto-links your claimed task) | required `--role` `--endpoint`; opt `--module` `--page` `--task` |
+| `artifacts` | list artifacts | `--module` `--endpoint` `--page` `--kind` |
+| `scan` | full scan & register (docs + codeRoots), derive DAG edges | `--actor` |
+| `move --from=<> --to=<>` | move an artifact (keeps id, keeps approval) | `--actor` |
+
+**Trust**
+
+| Command | Purpose | Parameters |
+| --- | --- | --- |
+| `submit -- <path>` | submit for review | `--actor` |
+| `approve -- <path>` | approve | `--actor`; `--trivial=true` for tweaks: re-bless downstream + close derived reviews |
+| `reject -- <path>` | reject | `--actor` `--reason` |
+| `feedback -- <path>` | feedback / 👍👎 (release prototype) | `--actor` `--verdict=+1\|-1`; opt `--comment` `--task` |
+| `dispute -- <path>` | trace an objection to approved content and stop for a ruling | `--actor` `--reason` |
+| `queue` | review queue (pending + invalidated) | — |
+| `sync` | reconcile: invalidation propagation + dispatch review | `--actor` |
+
+**Flow**
+
+| Command | Purpose | Parameters |
+| --- | --- | --- |
+| `plan` | dispatch downstream tasks once contracts are approved | `--module`; opt `--creator` |
+| `qa <id>` | record acceptance result (fail auto-dispatches rework) | `--result=pass\|fail` `--operator`; fail needs `--reason` |
+| `audit` | module contract reconciliation report (settlement status) | `--module` |
+| `graph` | emit a Mermaid dependency graph | `--module` |
+| `lint` | run protocol lints | opt `--role` `--endpoint` |
+| `events` | event stream | `--taskId`/`<id>` `--module` `--event` `--limit` `--json` |
+| `intake` | pull GitHub issues into the queue (standard lane / hotfix) | — |
+
+**Evolution / Maintenance**
+
+| Command | Purpose | Parameters |
+| --- | --- | --- |
+| `retro` | retrospective: skill candidates / Red Flags / approval throughput | opt `--module` `--json` |
+| `export` | export events/feedback as jsonl | — |
+| `init` | bootstrap a new project | `--endpoints` (required); `--platforms` `--model` `--writehooks=false` `--preset=false` `--hooks=false` |
+| `gen-agents` | regenerate agent definitions from templates | — |
+| `register-meta` | register meta artifacts (agent-def/skill/plan) | `--actor` |
+| `install-hooks` | install git hooks | — |
+| `migrate` | migrate a legacy DB | `--from=<path>` |
+
+> On the AI side, prefer the MCP `wb_*` typed tools (same source & transaction as the CLI). **approve/reject are deliberately not exposed to the AI — those are your actions.**
+
+## Configuration (workbench.config.json)
+
+```jsonc
+{
+  "platforms": ["claude", "cursor"],          // target platforms (picked by init), default ["claude"]
+  "endpoints": ["service", "web"],            // your endpoints
+  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"], // role pipeline (excluded roles get no tasks)
+  "codeRoots": {                              // [required] code dir per endpoint, {module} placeholder
+    "service": ["service/src/modules/{module}"],
+    "web": ["web/src/pages/{module}"]
+  },
+  "moduleMapping": { "userProfile": "user" }, // merge fine modules into coarse ones
+  "machineChecks": { "enabled": false,        // run on developer complete
+    "service": ["cd service && npx tsc --noEmit"] },
+  "protocolLints": [                          // machine-checkable conventions → lints (violations block complete)
+    { "name": "no-page-size", "grep": "pageSize", "paths": ["service/src"] }
+  ],
+  "gates": {
+    "approvalMode": "warn",                   // warn = unreviewed only warns / enforce = blocks
+    "writeGate": "observe"                     // off / observe (log only) / enforce (block edits to approved contracts)
+  },
+  "git": { "taskTrailer": "off", "trailerKey": "Task" }  // on = inject a Task:#id attribution trailer on commit
+}
+```
+
+## Visual opcflow
+
+`npx -y @dawipong/opcflow serve` serves at `http://127.0.0.1:5620`: the artifact tree (colors update live), markdown /
+mermaid / HTML-prototype iframe / code rendering, the **review-queue diff** (approved version vs.
+current), an event timeline, and live SSE refresh. Approve, reject, and thumbs-up/down prototypes right
+here.
+
+## Scripts
+
+```bash
+pnpm start                # start the opcflow (build frontend + start server; use for first run)
+pnpm run serve            # server only, no frontend build (404 if web/dist is missing)
+pnpm run web:build        # build the frontend
+pnpm test                 # core unit tests
+pnpm run typecheck        # type check
+pnpm run check:isolation  # zero business-coupling check
+```
+
+## Tech Stack
+
+TypeScript · better-sqlite3 · Fastify · React 18 + antd 6 · Monaco · mermaid ·
+@modelcontextprotocol/sdk · smol-toml · tsx. Runtime Node ≥ 22.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,239 @@
+<div align="center">
+
+# opcflow
+
+**Drift-enforced、spec-anchored 的 AI 开发执行层。**
+
+一套模板,把 Claude Code / Codex / OpenCode / Cursor 变成受契约约束的多角色开发流水线。
+
+![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6)
+![Node](https://img.shields.io/badge/node-%E2%89%A522-339933)
+![tests](https://img.shields.io/badge/tests-89%20passing-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+
+**简体中文** · [English](README.en.md)
+
+</div>
+
+---
+
+## 这是什么
+
+生成无限快之后,**验证是唯一瓶颈**。opcflow 把你的每一次验证(审批、👍👎、裁决)铸成
+机器可读、可失效、可传播的资产:文档 → 任务 → 产出形成真实的关系链(DAG + 外键),任何一处
+变更都**自动沿链传播、自动派复审**。你只做三件事:**审批契约、给产物点 👍👎、回答裁决**。
+
+- **真实关系链** —— artifact DAG + 任务外键,不是命名约定
+- **五态信任锚点** —— approved 内容被改自动失效,下游自动 stale(状态由文件内容派生,无需谁去"更新状态")
+- **五角色流水线** —— product-manager → architect → designer → developer → qa,各消费上游 approved 契约,各有 gate
+- **变更传播** —— `sync` 对账 → 失效 → 沿图派 review(去重)
+- **QA 闭环** —— fail → 自动 rework → 自动复验,不消耗人
+- **写门禁 hooks** —— agent 改到已 approved 契约时拦截(默认 observe 观察期)
+- **反馈进化** —— 👍👎 与 QA verdict 半衰期加权 → skill 候选 / Red Flags
+- **多平台** —— 一套定义生成四家平台各自的 agent + MCP + hooks(见 [PLATFORMS.md](PLATFORMS.md))
+- **可视化工作台** —— 树 + markdown/mermaid/原型/代码渲染 + 待审队列 diff + SSE 实时
+
+## 与 GitHub Spec Kit 的区别
+
+[Spec Kit](https://github.com/github/spec-kit) 是 spec-driven development 的脚手架:`/specify → /plan
+→ /tasks → implement`,每个阶段产出一份 markdown 喂给下一阶段,给 agent **结构化上下文**而非
+临时提示词。它解决的是「**如何写出好 spec 再交给 agent**」。
+
+opcflow 接管 **spec 之后的执行与验证**,两者是不同层次、可互补:
+
+| | Spec Kit | opcflow |
+| --- | --- | --- |
+| spec 的角色 | 给 agent 的**一次性上下文**(markdown) | 机器强制的**已批契约**,是 DAG 节点 |
+| 审批 | 无强制状态;人读一读 | 五态信任锚点(draft/pending/approved/invalidated),机器派生 |
+| 改了 spec 之后 | 无联动,靠人记得同步 | **自动失效 + 下游 stale + 派复审** |
+| 角色 | 基本单流程(一个 agent 实现) | 五角色流水线,各有 gate 与产出通道 |
+| 施工约束 | spec 是建议 | gate 拦住上游未批的任务;写门禁拦改已批契约;协议 lint 卡点 |
+| 验收 | 不涉及 | 两段式 QA + fail→rework→复验自动闭环 |
+| 进化 | 不涉及 | 👍👎/verdict 半衰期加权 → skill 候选 / Red Flags |
+
+一句话:**Spec Kit 把 spec 当"给 agent 的上下文";opcflow 把 spec 当"会失效、会传播、卡得住施工
+的已批契约",并管住从契约到代码到验收的整条漂移。**
+
+## 安装
+
+opcflow 是一个 npm 包 —— **不往你的项目里塞源码**。在项目根用 npx 零安装引导:
+
+```bash
+# 在你的项目根:选平台(多选)+ 端,一键生成
+npx -y @dawipong/opcflow init --platforms=claude,cursor --endpoints=service,web
+#   纯后端:      --endpoints=service          (自动裁掉 designer,qa 保留)
+#   指定模型:    --model='{"codex":"gpt-5.1-codex"}'  或  --model=<单个串>(缺省用各平台默认)
+```
+
+它只往项目写**生成物** —— 各平台 agent 定义、MCP 注册、hooks、`workbench.config.json`、`docs/` 骨架、
+数据库 `.workbench/`;**不落任何 opcflow 源码**。生成的 MCP / hook / CLI 引用统一指向
+`npx -y @dawipong/opcflow <子命令>`,换机器 / 团队协作免重装。`--platforms` 缺省 `claude`。
+
+> 各平台落地格式、Codex trust、Cursor 主 agent 模型等注意点见 **[PLATFORMS.md](PLATFORMS.md)**。
+
+需要 Node ≥ 22。
+
+## 快速开始
+
+1. **填代码目录约定** —— 编辑 `workbench.config.json` 的 `codeRoots`(每个端的代码目录,`{module}` 占位)。
+2. **起工作台**(可视化审批面板,连接项目的 `.workbench`):
+   ```bash
+   npx -y @dawipong/opcflow serve       # → http://127.0.0.1:5620(--project 指定项目根,缺省 cwd)
+   ```
+3. **对 AI 提第一个需求**(一句话)。它走五角色流水线逐层产出契约并送审。
+4. **在待审队列点头** —— 工作台看 diff,approve / 打回 / 给原型 👍。
+5. **契约全 approved 后派发**:
+   ```bash
+   npx -y @dawipong/opcflow plan --module=<模块>   # 一键派发 architect/designer/developer/qa 任务
+   ```
+
+之后的每次改动都被追踪:改了已批契约 → 自动失效 → 下游 stale → 待审队列出现复审任务。
+
+## Agent 写作流程(五角色流水线)
+
+```mermaid
+flowchart LR
+    U(["⬜ 需求"]) --> PM["🟦 product-manager<br/>业务契约"]
+    PM --> AR["🟦 architect<br/>DB + API 契约"]
+    AR --> DE["🟦 designer<br/>设计系统 + 原型"]
+    DE --> DV["🟦 developer<br/>代码"]
+    DV --> QA["🟦 qa<br/>验收"]
+    QA --> DONE(["✅ 模块 accepted"])
+    QA -.->|"fail → rework"| DV
+```
+
+> 🟦 agent 动作 · ⬜ 用户关卡(审批 / 👍) · ⚙️ 引擎自动。每一环的产出都要**过用户关卡**才成为
+> 下游可信真相。所有 agent 共用一套 **claim(过 gate)→ 消费 approved 上游 → 产出 → 登记 → 送审/👍/验收
+> → 过关卡 → complete** 的骨架。
+
+**贯穿的信任协议**:上游 `approved` = 真相直接用(**禁重新推导、禁重复确认**);`draft/pending` = 可用但
+标注"未审";`invalidated / 复审中` = **禁用**等复审;有实质异议走 `dispute` 留痕停下,不擅自偏离。
+
+| 角色 | 何时介入 / gate | 产出 | 怎么成为真相 |
+| --- | --- | --- | --- |
+| **product-manager** | 用户提需求 | 逐层业务契约:project → roles/glossary → flow(含实体状态机)→ 模块 PRD → 页面 PRD(含验收要点) | 逐层送审,**批准才进下一层**;末层全批 → `plan` 派发 |
+| **architect** | gate:flow + 模块 PRD 已批 | 技术基线(ARCHITECTURE/TECH,0 号任务)、DB 文档、API 契约;**共享枚举唯一变更入口** | 人工审批;基线未批任何模块不得开工 |
+| **designer** | gate:该端设计系统已批 | 设计系统(人审)、设计提示词(仅登记不送审)、HTML 原型 | 原型靠 **👍 = 反馈+审批合一**放行 |
+| **developer** | gate:契约齐备;前端任务要求原型已 👍 | 各端代码(目录级 scan 维护,不手动登记) | complete 闸门:machineChecks / protocolLints 通过 |
+| **qa** | 两段式:先定验收标准(送审),developer 完成后执行 | 验收用例(`docs/acceptance/...`)、pass/fail | pass → 给 code +1 verdict;**fail → 自动 rework → 自动复验**直到 pass |
+
+> **HTML 原型的两种产出方式**:默认由当前接入的模型直接产出;也可把 approved 的**设计系统** +
+> **页面设计提示词**交给第三方设计平台(如 v0、Lovable 等)生成 HTML,再把产物文件丢到对应路径
+> `docs/design/prototypes/<端>/<模块>/<页面>.html`,`scan` 登记后照常走 👍 放行——两条路径产出的原型
+> 在体系里等价,都要过用户 👍。
+
+## CLI 命令参数
+
+所有命令:`npx -y @dawipong/opcflow <命令> [参数]`。全局 `--project=<路径>` 指定项目根(缺省向上找
+`workbench.config.json`)。文件路径参数用 `--` 分隔(如 `submit --actor=x -- <路径>`)。
+
+**任务**
+
+| 命令 | 作用 | 参数 |
+| --- | --- | --- |
+| `list` | 列任务 | `--status` `--assignee` `--module` `--role` `--endpoint` `--type` `--stale=true` |
+| `show <id>` | 任务详情(含事件/产出/stale) | `--json=true` |
+| `create` | 建任务 | 必填 `--role` `--creator`;选 `--module` `--endpoint` `--page` `--type` `--assignee` `--content` |
+| `claim <id>` | 领取(过 gate,自动快照依赖) | `--assignee=<角色>` |
+| `update <id>` | 改状态 | `--status` `--operator`;`--force=true` 越过 stale 拦截(留痕) |
+| `remove <id>` | 删任务 | `--operator`;`--force=true` |
+| `record <id> "备注"` | 加备注 | `--operator` |
+| `input <id> -- <路径>` | 补充申报 gate 之外读过的依赖 | `--operator` |
+
+**产出**
+
+| 命令 | 作用 | 参数 |
+| --- | --- | --- |
+| `output -- <路径>` | 登记产物(自动关联你领取的任务) | 必填 `--role` `--endpoint`;选 `--module` `--page` `--task` |
+| `artifacts` | 列产物 | `--module` `--endpoint` `--page` `--kind` |
+| `scan` | 全量扫描登记(docs + codeRoots),推导 DAG 边 | `--actor` |
+| `move --from=<> --to=<>` | 移动产物(保 id、不断审批) | `--actor` |
+
+**信任**
+
+| 命令 | 作用 | 参数 |
+| --- | --- | --- |
+| `submit -- <路径>` | 送审 | `--actor` |
+| `approve -- <路径>` | 批准 | `--actor`;`--trivial=true` 微调:re-bless 下游 + 关派生 review |
+| `reject -- <路径>` | 打回 | `--actor` `--reason` |
+| `feedback -- <路径>` | 反馈 / 👍👎(原型放行) | `--actor` `--verdict=+1\|-1`;选 `--comment` `--task` |
+| `dispute -- <路径>` | 对 approved 内容留痕异议,停下等裁决 | `--actor` `--reason` |
+| `queue` | 待审队列(pending + invalidated) | — |
+| `sync` | 对账:失效传播 + 沿图派 review | `--actor` |
+
+**流程**
+
+| 命令 | 作用 | 参数 |
+| --- | --- | --- |
+| `plan` | 契约全批后一键派发下游任务 | `--module`;选 `--creator` |
+| `qa <id>` | 记验收结果(fail 自动派 rework) | `--result=pass\|fail` `--operator`;fail 需 `--reason` |
+| `audit` | 模块契约对账报告(清算状态) | `--module` |
+| `graph` | 输出 Mermaid 依赖图 | `--module` |
+| `lint` | 跑协议 lint | 选 `--role` `--endpoint` |
+| `events` | 事件流 | `--taskId`/`<id>` `--module` `--event` `--limit` `--json` |
+| `intake` | 拉 GitHub issue 入队(标准道 / hotfix) | — |
+
+**进化 / 维护**
+
+| 命令 | 作用 | 参数 |
+| --- | --- | --- |
+| `retro` | 复盘:skill 候选 / Red Flag / 审批吞吐 | 选 `--module` `--json` |
+| `export` | 导出 events/feedback 为 jsonl | — |
+| `init` | 新项目引导 | `--endpoints`(必填);`--platforms` `--model` `--writehooks=false` `--preset=false` `--hooks=false` |
+| `gen-agents` | 从模板重生成 agent 定义 | — |
+| `register-meta` | 注册元产物(agent-def/skill/plan) | `--actor` |
+| `install-hooks` | 安装 git hooks | — |
+| `migrate` | 迁移旧库 | `--from=<路径>` |
+
+> AI 侧优先用 MCP 的 `wb_*` typed tools(与 CLI 同源同事务);**审批 approve/reject 刻意不暴露给 AI——那是你的动作**。
+
+## 配置(workbench.config.json)
+
+```jsonc
+{
+  "platforms": ["claude", "cursor"],          // 目标平台(init 选),缺省 ["claude"]
+  "endpoints": ["service", "web"],            // 你的端
+  "pipeline": ["product-manager", "architect", "designer", "developer", "qa"], // 角色流水线(不含的角色不派任务)
+  "codeRoots": {                              // 【必填】每端代码目录,{module} 占位
+    "service": ["service/src/modules/{module}"],
+    "web": ["web/src/pages/{module}"]
+  },
+  "moduleMapping": { "userProfile": "user" }, // 细模块归并到粗模块
+  "machineChecks": { "enabled": false,        // developer complete 时跑
+    "service": ["cd service && npx tsc --noEmit"] },
+  "protocolLints": [                          // 能机器查的约定 → 降级为 lint(违例阻断 complete)
+    { "name": "no-page-size", "grep": "pageSize", "paths": ["service/src"] }
+  ],
+  "gates": {
+    "approvalMode": "warn",                   // warn=未批只警告 / enforce=阻断
+    "writeGate": "observe"                     // off / observe(只记录)/ enforce(拦改 approved 契约)
+  },
+  "git": { "taskTrailer": "off", "trailerKey": "Task" }  // on=提交注入 Task:#id 归因 trailer
+}
+```
+
+## 可视化工作台
+
+`npx -y @dawipong/opcflow serve` 起在 `http://127.0.0.1:5620`:artifact 树(状态实时变色)、markdown / mermaid / HTML 原型
+iframe / 代码渲染、**待审队列 diff**(approved 版本 vs 当前)、事件时间线、SSE 实时刷新。审批、打回、
+给原型 👍👎 都在这里点。
+
+## 脚本
+
+```bash
+pnpm start                # 启动工作台(build 前端 + 起 server;首次用它)
+pnpm run serve            # 只起 server,不 build 前端(web/dist 未生成会 404)
+pnpm run web:build        # 构建前端
+pnpm test                 # core 单元测试
+pnpm run typecheck        # 类型检查
+pnpm run check:isolation  # 零业务耦合校验
+```
+
+## 技术栈
+
+TypeScript · better-sqlite3 · Fastify · React 18 + antd 6 · Monaco · mermaid ·
+@modelcontextprotocol/sdk · smol-toml · tsx。运行时 Node ≥ 22。
+
+## 许可
+
+[MIT](LICENSE)