agentic-flow-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentic-flow-kit contributors
+
+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.md

@@ -0,0 +1,62 @@
+# agentic-flow-kit
+
+AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套。
+
+**装完即自包含**：引擎文件拷贝进项目（零 npm 运行时依赖，Node ≥ 18 即可跑），clone 后只差 `git config core.hooksPath .githooks`——init 会自动挂好。
+
+## 快速开始
+
+```bash
+cd <你的项目根>
+npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 显式确认安装
+# 或直接给参数
+npx agentic-flow-kit init --stack node --hosts zcode,opencode
+
+# 体检（布局 / git 钩子 / managed 台账 / 索引漂移 / check-loop）
+npx agentic-flow-kit doctor
+
+# 包出新版后升级（未改动→覆盖；本地已改→跳过并报告，--force 才覆盖；owned 永不触碰）
+npx agentic-flow-kit sync
+
+# 后补宿主 / 装门禁（dotnet-ca：Clean Architecture 红线守卫，装后归项目）
+npx agentic-flow-kit add-host opencode
+npx agentic-flow-kit add-gate dotnet-ca
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--stack` | `dotnet` / `node` / `python` / `go` / `none`（默认 none）——**门禁配置三处**：commit-check 条件编译检查（暂存对应扩展名时 commit 前自动构建）+ **质量检测**（`checks`：lint / 类型检查 / vet 等秒级确定性检查，存在对应配置文件（tsconfig / eslint / ruff / go.mod 等）才启用，没有则自动跳过；测试不放提交门——关单在 test.md 阶段门）、settings.json 自检验命令权限、AGENTS.md「项目适配区」命令预填 |
+| `--hosts` | `zcode` / `opencode` / `trae` / `omp` 逗号多选（默认 zcode）——生成对应宿主薄适配层；zcode/omp 为本地配置自动进 .gitignore |
+| `--board-port` | workflow 看板端口（默认 8933） |
+| `--dir` | 目标项目根（默认当前目录） |
+| `--force` | 覆盖已存在的同名文件（默认保守跳过） |
+
+init 不问项目名 / 描述：`AGENTS.md` 只生成「AI工作流 + Wiki」两章骨架 + 「项目适配区」；技术栈经 `--stack` 传入只用于门禁配置（编译检查与自检验命令初值），密钥白名单等其余细节在 `.agents/hooks/commit-check.config.json` 里按项目填。
+
+## 装了什么
+
+```
+.agents/            阶段命令×8 / 角色契约×3 / 门禁钩子 / 引擎脚本（检索·索引·看板·预算·聚合）/ 技能×2 / settings.json / kit.json 台账
+.githooks/          pre-commit（通用门禁编排+项目门禁挂载点）/ pre-push（闭环断档）/ commit-msg / post-commit / pre-merge-commit
+workflow/           intents/specs/plans/incidents 模板×4 + README 协议 + 台账三件（delegations/papercuts/regression-checklist）
+wiki/               INDEX 骨架 + 知识沉淀总览 + drafts-archive
+AGENTS.md           项目规范骨架（项目段占位待填）
+modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考实现，装进项目后归项目）
+```
+
+**两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
+
+**升级语义（sync）**：managed 文件三方比对（台账 sha / 磁盘 sha / 新版渲染 sha）——未改动 → 直接覆盖新版；本地已改 → 跳过并报告（`--force` 才覆盖，git diff 自查差异）；改动恰好等于新版 → 视为已最新。包内新增文件自动安装；包内已删文件仅报告不删盘；缺失的 managed 文件自动恢复。INDEX / wiki 看板等生成器目标不比对 sha，收尾重跑生成器走锚点重写。门禁模块（add-gate 装入）归项目所有，sync 永不覆盖。
+
+## 设计原则
+
+- **权威单源**：角色行为只在 `.agents/roles/`，流程只在 `.agents/commands/`，宿主适配层是纯转发薄层——换宿主不换流程。
+- **门禁即 git 钩子**：不依赖任何 agent 客户端自觉；项目专属门禁挂 `.agents/hooks/local-pre-commit`。
+- **中文优先**：文档协议、命令、检查输出全中文；frontmatter 受限子集供机器断言。
+- 抽取自真实项目长期运转的引擎（某真实项目），dogfooding 是后续路线（sync 升级 / add-host / add-gate / npm 发布）的一部分。
+
+## 路线
+
+- [x] v0.1.0：init（flags 模式）+ doctor + 4 宿主适配 + dotnet-ca 门禁模块
+- [x] v0.2.0：sync 升级（未动覆盖 / 已改跳过报告 + `--force` / 生成器锚点重写）+ add-host / add-gate
+- [ ] npm 发布

package/bin/flow-kit.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2));

package/modules/gates/dotnet-ca/README.md

@@ -0,0 +1,24 @@
+# dotnet-ca — Clean Architecture 门禁模块（可选）
+
+Clean Architecture（Application/Domain/Infrastructure/API 分层）红线守卫参考实现，抽自真实项目实战门禁。五条红线：Application 禁引 Infrastructure/DbContext、API Controller 禁直注 DbContext、EF 模型层解耦（无关系映射/无导航属性/无 Include）、InnerException 禁透传响应。
+
+## 接线（一次性，装进项目本地）
+
+已装 agentic-flow-kit 的项目直接：
+
+```sh
+npx agentic-flow-kit add-gate dotnet-ca
+```
+
+（装 .agents/hooks/check-architecture.sh + 自动接线 local-pre-commit；装后归项目所有，sync 不覆盖。）
+
+手动装法等价于：
+
+```sh
+mkdir -p .agents/hooks
+cp <包内 modules/gates/dotnet-ca/check-architecture.sh> .agents/hooks/
+# .agents/hooks/local-pre-commit（pre-commit 的项目门禁挂载点，没有则新建）：
+echo 'sh .agents/hooks/check-architecture.sh' >> .agents/hooks/local-pre-commit
+```
+
+然后改脚本头部 `CONFIG` 块的目录/类型名。红线不适用（如不用 EF）的条目自行删除——本模块是参考实现，装进项目后归项目所有。

package/modules/gates/dotnet-ca/check-architecture.sh

@@ -0,0 +1,128 @@
+#!/bin/sh
+# check-architecture（agentic-flow-kit · dotnet-ca 门禁模块）：Clean Architecture 红线参考实现
+# 红线：Application 禁引用 Infrastructure / 禁 DbContext / EF 模型层解耦（无关系映射/无导航/无 Include）/ 异常详情不透传
+# 违例输出到 stderr 并 exit 1；干净无输出 exit 0
+#
+# 接线（项目一次性）：把本文件复制/引用到 .agents/hooks/ 下并在 .agents/hooks/local-pre-commit 里执行——
+#   mkdir -p .agents/hooks && cp <包内路径>/check-architecture.sh .agents/hooks/
+#   echo 'sh .agents/hooks/check-architecture.sh' >> .agents/hooks/local-pre-commit
+cd "$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "check-architecture: 不在 git 仓库内,门禁 fail-closed,不静默放行" >&2; exit 1; }
+
+# ---- CONFIG：按项目改成你的目录/类型名（其余为通用逻辑，升级只动 CONFIG） ----
+APP_DIR="backend/src/YourApp.Application"
+API_DIR="backend/src/YourApp.API"
+DBCTX_FILE="backend/src/YourApp.Infrastructure/Data/AppDbContext.cs"
+DOMAIN_ENTITIES_DIR="backend/src/YourApp.Domain/Entities"
+CONTROLLERS_DIR="backend/src/YourApp.API/Controllers"
+DBCTX_CLASS="AppDbContext"
+INFRA_USING="using YourCompany.YourApp.Infrastructure"
+EXEMPT_CTRL="ExemptedController"      # 冒号分隔的豁免 Controller 名（原生 LINQ 等历史豁免）
+SHARED_TYPES="Staff,Company"          # 跨模块共享实体名（红线 4.3 白名单）
+# -------------------------------------------------------------------------
+
+# 门禁目标存在性：目标缺失时 fail-closed（不静默放行）
+require_target() {
+  [ -d "$1" ] || [ -f "$1" ] || { echo "check-architecture: 门禁目标缺失（$1）——fail-closed,不静默放行" >&2; exit 1; }
+}
+require_target "$APP_DIR"
+require_target "$API_DIR"
+violations=""
+exempt_grep=$(printf '%s' "$EXEMPT_CTRL" | tr ':' '|')
+
+# 红线 1：Application csproj 不得引用 Infrastructure 项目
+if grep -q "Infrastructure" "$APP_DIR"/*.csproj 2>/dev/null; then
+  violations="$violations
+- csproj 引用了 Infrastructure 项目（Application 只允许依赖 Domain 与共享层）"
+fi
+
+# 红线 2：Application 代码不得出现 DbContext / Infrastructure 命名空间
+hits=$(grep -rn -e "$DBCTX_CLASS" -e "$INFRA_USING" "$APP_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/")
+if [ -n "$hits" ]; then
+  violations="$violations
+- Application 代码出现 DbContext / Infrastructure 引用：
+$hits"
+fi
+
+# 红线 3：API 层 Controller 禁直接注入 DbContext（豁免清单内的 Controller 除外）
+api_hits=$(grep -rn "$DBCTX_CLASS" "$API_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/" -e "$exempt_grep")
+if [ -n "$api_hits" ]; then
+  violations="$violations
+- API 层出现 DbContext 直接引用（应走仓储/服务接口，豁免仅 $EXEMPT_CTRL）：
+$api_hits"
+fi
+
+# 红线 4.1：DbContext 禁关系映射配置（模型层解耦，关联一律显式 JOIN/分步查询）
+require_target "$DBCTX_FILE"
+rel_hits=$(grep -nE "HasOne|HasMany|WithOne|WithMany|HasForeignKey|OnDelete" "$DBCTX_FILE" 2>/dev/null)
+if [ -n "$rel_hits" ]; then
+  violations="$violations
+- $DBCTX_CLASS 出现关系映射（模型层已解耦）：
+$rel_hits"
+fi
+
+# 红线 4.2：Application / API 禁代码级 .Include(（注释里的「原 Include(...)」无前导点，不误报）
+inc_hits=$(grep -rnE "\.Include\(" "$APP_DIR" "$API_DIR" --include="*.cs" 2>/dev/null | grep -v -e "/obj/" -e "/bin/")
+if [ -n "$inc_hits" ]; then
+  violations="$violations
+- Application/API 出现 EF Include（导航已移除，明细/参照数据经仓储分步查询或显式 JOIN）：
+$inc_hits"
+fi
+
+# 红线 4.3：Domain 实体禁导航属性（按实体类名交叉扫描；枚举/标量属性不误伤）
+require_target "$DOMAIN_ENTITIES_DIR"
+PY_BIN=""
+for c in python python3 py; do
+    if command -v "$c" >/dev/null 2>&1; then PY_BIN="$c"; break; fi
+done
+if [ -z "$PY_BIN" ]; then
+  violations="$violations
+- 红线 4.3 无法执行：未找到 python/python3/py（Domain 导航属性扫描依赖 Python；门禁 fail-closed，不静默放行）"
+else
+    nav_hits=$(DOMAIN_ENTITIES_DIR="$DOMAIN_ENTITIES_DIR" SHARED_TYPES="$SHARED_TYPES" "$PY_BIN" - <<'PYEOF'
+import re, glob, os
+from os import environ
+d = environ['DOMAIN_ENTITIES_DIR']
+shared = {s.strip() for s in environ.get('SHARED_TYPES', '').split(',') if s.strip()}
+files = glob.glob(d + '/**/*.cs', recursive=True)
+names = set()
+for f in files:
+    with open(f, encoding='utf-8-sig') as fh:
+        names |= set(re.findall(r'public\s+(?:sealed\s+|abstract\s+|partial\s+)*(?:class|record)\s+(\w+)', fh.read()))
+hits = []
+for f in files:
+    with open(f, encoding='utf-8-sig') as fh:
+        for i, line in enumerate(fh, 1):
+            m = re.match(r'\s*public\s+(?:virtual\s+)?([\w<>,\s\.\?]+?)\s+(\w+)\s*\{', line)
+            if not m:
+                continue
+            typ = m.group(1).strip()
+            mm = re.search(r'(?:ICollection|List|IEnumerable|IReadOnlyCollection|IReadOnlyList)<\s*(\w+)\s*>', typ)
+            core = mm.group(1) if mm else (typ.rstrip('?') if re.fullmatch(r'\w+\??', typ) else None)
+            if core and (core in names or core in shared):
+                hits.append(f"{os.path.basename(f)}:{i} {m.group(2)} : {typ}")
+if hits:
+    print('\n'.join(hits))
+PYEOF
+    )
+fi
+if [ -n "$nav_hits" ]; then
+  violations="$violations
+- Domain 实体出现导航属性（模型层已解耦，关联只保留外键标量列）：
+$nav_hits"
+fi
+
+# 红线 5：Controller 禁把 InnerException 原文透传进响应体（详情只许进日志）
+inner_hits=$(grep -rn "InnerException" "$CONTROLLERS_DIR" --include="*.cs" 2>/dev/null \
+  | grep -v -e "/obj/" -e "/bin/" \
+  | grep -vE "Log(Warning|Error|Information|Debug|Trace)")
+if [ -n "$inner_hits" ]; then
+  violations="$violations
+- Controller 出现 InnerException 透传进响应（数据库异常统一翻译；详情只许进日志）：
+$inner_hits"
+fi
+
+if [ -n "$violations" ]; then
+  printf '架构红线违例（dotnet-ca 门禁）：\n%s\n' "$violations" >&2
+  exit 1
+fi
+exit 0

package/modules/gates/dotnet-ca/local-pre-commit.line

@@ -0,0 +1 @@
+sh .agents/hooks/check-architecture.sh

package/modules/hosts/omp/agents/implementer.md

@@ -0,0 +1,12 @@
+---
+name: implementer
+description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria. 中文：在已批准且边界明确的工作包内实现改动或补测试；超出授权文件范围即停。
+tools: read, grep, glob, bash, edit, write
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/implementer.md`，并**完全遵循**该角色契约（必需输入 / 授权文件 / 验收与停止条件）。
+
+宿主适配说明（本机 omp）：
+- 只改派单**授权文件**范围内的内容；需偏离（改公共接口 / 动未列文件 / 引新依赖 / 改验收判据）→ **停下报 blocker**，不自行扩大范围。
+- **禁** `git commit` / `git push` / `git reset --hard`；提交与推送由主智能体在复核后执行。
+- 不跑全量静态门（`项目构建命令` / `项目测试命令` / `项目类型检查命令`、项目自有架构门）——由主智能体在改动面收敛后统一跑；本角色只做与工作包直接相关的最小验证。
+- 派单缺授权文件清单或可执行验收判据时，**返回 blocker 且不动文件**。

package/modules/hosts/omp/agents/independent-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: independent-reviewer
+description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files. 中文：对已固定的 spec / plan / 代码 diff 做独立复核，产出分级问题清单；只读，禁改文件。
+tools: read, grep, glob, bash
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/independent-reviewer.md`，并**完全遵循**该角色契约（复核基准 / 分级口径 / 输出格式 / 独立性要求）。
+
+宿主适配说明（本机 omp）：
+- `bash` **仅限只读用途**：`git diff` / `git log` / `git show` / `git status` 与只读查询；**禁**改文件、**禁**跑构建 / 测试 / DDL / 写库。
+- 独立性：本角色不得沿用原作者思路（不得由修改者自查冒充）；派单未固定复核目标（spec/plan/diff 基准）与验收来源时，**返回 blocker**。
+- 每条 finding 须过 `skill://review-verification-protocol`（锚定 file:line、给出证据、校准严重级；不确定降级为提问；纯风格不报），输出格式 `path:line: <severity> <problem>. <fix>.` + 一句结论。

package/modules/hosts/omp/agents/ui-verifier.md

@@ -0,0 +1,12 @@
+---
+name: ui-verifier
+description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files. 中文：对已实现的 UI 改动做浏览器实测并返回可复核证据；只验证不修复，禁改仓库文件。
+tools: read, grep, glob, bash, eval
+---
+开工前读项目根 `AGENTS.md` 与 `.agents/roles/ui-verifier.md`，并**完全遵循**该角色契约（必需输入 / 步骤 / 证据要求 / 停止条件）。
+
+宿主适配说明（本机 omp）：
+- 浏览器实测经 `eval` 的 `browser` 能力（headless Chrome + CDP）；环境细节见项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md` 与项目注记（如有，`.agents/notes/runtime-env.md`）。
+- 只验证不改仓：**禁** `edit`/`write`；临时脚本写到仓库外（系统临时目录），收尾删除；**禁** `git commit` / `git push` / `git reset --hard`。
+- 数据安全：只删自己创建的数据，且必须用创建响应返回的 ID；**严禁**按「列表第一行 / 最近一条 / 名称匹配」等启发式取单删除。
+- 若宿主策略拒绝了所需工具（如 `eval` 被 deny），或派单缺路线 / 步骤 / 可观察预期：**返回 blocker，不启动服务、不改任何文件**。

package/modules/hosts/opencode/agents/implementer.md

@@ -0,0 +1,14 @@
+---
+description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria
+mode: subagent
+permission:
+  edit: allow
+  bash:
+    "*": allow
+    "git commit*": deny
+    "git push*": deny
+    "git reset --hard*": deny
+  task: deny
+---
+
+Before acting, read `AGENTS.md` and `.agents/roles/implementer.md` from the project root and follow them completely. If the dispatch does not provide the required inputs defined there, return a blocker without editing files.

package/modules/hosts/opencode/agents/independent-reviewer.md

@@ -0,0 +1,10 @@
+---
+description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files
+mode: subagent
+permission:
+  edit: deny
+  bash: deny
+  task: deny
+---
+
+Before reviewing, read `AGENTS.md` and `.agents/roles/independent-reviewer.md` from the project root and follow them completely. If the dispatch does not identify a fixed review target and acceptance source, return a blocker.

package/modules/hosts/opencode/agents/ui-verifier.md

@@ -0,0 +1,10 @@
+---
+description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files
+mode: subagent
+permission:
+  edit: deny
+  bash: allow
+  task: deny
+---
+
+Before verifying, read `AGENTS.md` and `.agents/roles/ui-verifier.md` from the project root and follow them completely. If the dispatch lacks a route, steps, or observable expectations, return a blocker without starting services.

package/modules/hosts/opencode/commands/build.md

@@ -0,0 +1,13 @@
+---
+description: Build 阶段 · 起 plan + 实现代码 + 自验（两道确认门，确认后才动代码）
+---
+
+严格按 AGENTS.md 与 .agents/commands/build.md 执行：Build 阶段 · 起 plan + 写代码。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 两道确认门：① plan 草稿全文确认（draft→approved）② 计划模式列改动文件清单确认——两道全过才动代码。
+- 范围明确的工作包可委派 `implementer`（`.opencode/agents/implementer.md`，契约读 `.agents/roles/implementer.md`，权限已禁 git commit/push）；不满足角色契约时按 `fallback: main` 由主智能体执行。
+- 实现中需偏离已确认 plan（公共接口 / 未列文件 / 新依赖 / 判据影响）→ 停下向用户说明，确认后再继续。
+- 完成后进 test。

package/modules/hosts/opencode/commands/deploy.md

@@ -0,0 +1,12 @@
+---
+description: Deploy 阶段 · prod 上线清单（静态门 / 配对 / 回归 / DB / 授权 / 24h 观察；关单在 test）
+---
+
+严格按 AGENTS.md 与 .agents/commands/deploy.md 执行：Deploy 阶段 · prod 上线清单（静态门 / 配对检查 / 回归 / DB / 授权 / 24h 观察；文档关单在 test，本阶段不重复关单）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 确认门：上线授权 = 用户对话内一句确认 + release/<日期> tag 留痕；无第二审批人，AI 不得自行上线、不得 `git push` 绕门禁。
+- 本阶段不委派子智能体；回滚 SQL 等数据安全判断由主智能体做、用户拍板。
+- 异常进 maintain；用户确认无异常 = prod 闭环，AI 不得自行宣告。

package/modules/hosts/opencode/commands/design.md

@@ -0,0 +1,12 @@
+---
+description: Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 build）
+---
+
+严格按 AGENTS.md 与 .agents/commands/design.md 执行：Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 build）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 确认门：spec 草稿经用户确认；L3 另有独立复核门，复核未过不得确认。
+- L3 独立复核委派 `independent-reviewer`（`.opencode/agents/independent-reviewer.md`，契约读 `.agents/roles/independent-reviewer.md`）——subagent 天然独立上下文，权威命令 `fallback: new-session` 的隔离要求即满足。
+- 确认后进 build。

package/modules/hosts/opencode/commands/maintain.md

@@ -0,0 +1,12 @@
+---
+description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物）
+---
+
+严格按 AGENTS.md 与 .agents/commands/maintain.md 执行：Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物，不必另造 intent）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 确认门：止血方案由用户拍板（AI 只执行选定方案）；三件套草稿经用户确认后才落地。
+- 配 plan 的时点与形态以权威文件为准——incident≡intent 免掉的是 intent，plan 不可免（commit / push 两处门禁按同名硬拦）。
+- 复现路径与验收明确的局部热修可委派 `implementer`（`.opencode/agents/implementer.md`）；事故诊断、根因定性与三件套起草不委派。

package/modules/hosts/opencode/commands/new-task.md

@@ -0,0 +1,12 @@
+---
+description: AI-Native 闭环总入口 · 6 阶段路由（新需求 → plan / 修复 → maintain）+ 级别判断（L0-L3）
+---
+
+严格按 AGENTS.md 与 .agents/commands/new-task.md 执行：闭环总入口 · 路由判断（新需求 intent → plan / 修复 incident → maintain）+ 级别判断（L0-L3）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 输出路由结论与级别，指明进入哪个 .agents/commands/*.md 阶段；不并阶段、不跳阶段。
+- approval_required 阶段产出未经用户对话内一句话确认，不得进入下一阶段。
+- opencode 无宿主级即时钩子；机器门禁以 `.githooks/`（git 提交时硬拦）为准，`git commit/merge/push` 三处禁 `--no-verify`。

package/modules/hosts/opencode/commands/plan.md

@@ -0,0 +1,12 @@
+---
+description: Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）
+---
+
+严格按 AGENTS.md 与 .agents/commands/plan.md 执行：Plan 阶段 · 立 intent（AI 起草、用户确认）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 确认门：intent 草稿全文输出给用户过目，一句"可以"即确认（draft→approved），确认前不进下一阶段。
+- 已有 approved intent 时按级别跳转：L1 → build；L2/L3 → design。
+- 本阶段不委派子智能体，由主智能体起草；任务入口动作（ensure-board.ps1 看板）与红线勾选口径以权威文件为准。

package/modules/hosts/opencode/commands/review.md

@@ -0,0 +1,12 @@
+---
+description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）
+---
+
+严格按 AGENTS.md 与 .agents/commands/review.md 执行：Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 顺序：机器门禁自动拦（`.githooks/`）→ `independent-reviewer` 复核（L2/L3 强制独立，经 `.opencode/agents/independent-reviewer.md` 派 subagent，天然独立上下文）→ 分级清单交用户定性与决定合入时机。
+- 确认门：P0/P1 未清回 build；清零且用户确认后才可合入。
+- finding 报告门（防误报）与机器兜底清单以权威文件为准。

package/modules/hosts/opencode/commands/test.md

@@ -0,0 +1,14 @@
+---
+description: Test 阶段 · 静态门 + 切库冒烟 + UI 实测 + L2/L3 独立复核（关单在本阶段）
+---
+
+严格按 AGENTS.md 与 .agents/commands/test.md 执行：Test 阶段 · 静态门全过 + 切库冒烟（如触发）+ UI 实测 + L2/L3 独立复核。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【OpenCode 宿主注记】
+- 终端是 PowerShell：取真退出码、`$LASTEXITCODE` 假绿陷阱、Git Bash 绝对路径调法见 `.agents/notes/runtime-env.md` §1，断言"通过"前先确认命令真的跑了。
+- 跑静态门前先看 `.agents/notes/runtime-env.md` §2（本地 API 进程锁 bin 下 DLL，谁跑门谁先停 API）。
+- UI 实测委派 `ui-verifier`（`.opencode/agents/ui-verifier.md`）；L2/L3 独立复核委派 `independent-reviewer`——本宿主 subagent 原生可用，`fallback: new-session` 的独立上下文天然满足。
+- 失败项修复仍回 build，不在本阶段顺手改代码；全过后用户确认才关单（勾验收 / incident 状态 / 委派留痕口径以权威文件为准）。
+- L1 到此结束；L2/L3 仅当用户确认要上 prod 才进 deploy。

package/modules/hosts/trae/agents/implementer.md

@@ -0,0 +1,9 @@
+---
+name: implementer
+description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria
+tools: Read, Glob, Grep, Edit, Write, Bash, LSP
+---
+
+Before acting, read the root `AGENTS.md`, the directory-level `AGENTS.md` for the area you will touch (if present), and `.agents/roles/implementer.md` from the project root, and follow them completely. If the dispatch does not provide the required inputs defined there (task goal, entry docs, owned file list, acceptance criteria), return a blocker without editing files.
+
+Hard constraint (Trae subagents cannot deny specific commands the way the OpenCode permission block does): never run `git commit`, `git push`, or `git reset --hard`; the role contract forbids any commit, push, or destructive git operation. The main agent's PreToolUse hook (`.trae/hooks/pre-shell-check.cjs`) enforces this — do not assume it, and do not attempt to reach those commands by another route.

package/modules/hosts/trae/agents/independent-reviewer.md

@@ -0,0 +1,8 @@
+---
+name: independent-reviewer
+description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files
+tools: Read, Glob, Grep
+disallowedTools: Edit, Write, Bash
+---
+
+Before reviewing, read the root `AGENTS.md`, the directory-level `AGENTS.md` for the touched area (if present), and `.agents/roles/independent-reviewer.md` from the project root, and follow them completely. If the dispatch does not identify a fixed review target and acceptance source, return a blocker. Read-only: do not edit, write, or run state-changing commands.

package/modules/hosts/trae/agents/ui-verifier.md

@@ -0,0 +1,12 @@
+---
+name: ui-verifier
+description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files
+tools: Read, Glob, Grep, Bash, Skill
+disallowedTools: Edit, Write
+---
+
+Before verifying, read the root `AGENTS.md`, the directory-level `AGENTS.md` for the frontend change area (if present), and `.agents/roles/ui-verifier.md` from the project root, and follow them completely. Then follow the project's UI verification skill `.agents/skills/verify-ui/SKILL.md` (if present) to start the API, frontend, and headless Chrome.
+
+Trae host notes: the terminal is PowerShell on Windows, so `bash` is not on PATH — call `& "C:\Program Files\Git\bin\bash.exe" <script>` for shell scripts. Start long-lived services (API / frontend dev server / Chrome with CDP on 9222; ports per project notes) as detached processes; background task lifetime is not dependable.
+
+If the dispatch lacks a route, steps, or observable expectations, return a blocker without starting services. Do not edit or write any repository file; close the background processes you started.

package/modules/hosts/trae/commands/wf-build.md

@@ -0,0 +1,14 @@
+---
+name: wf-build
+description: Build 阶段 · 起 plan + 实现代码 + 自验（两道确认门，确认后才动代码）
+---
+
+严格按 AGENTS.md 与 .agents/commands/build.md 执行：Build 阶段 · 起 plan + 实现代码 + 自验。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 两道确认门：① plan 草稿确认（draft→approved）② 计划模式列改动文件清单确认——两道全过才动代码。
+- 范围明确的工作包可委派 implementer（.trae/agents/implementer.md）；子智能体未开启时按 fallback: main 由主智能体按同一角色契约执行。
+- 实现中需偏离已确认 plan（公共接口 / 未列文件 / 新依赖 / 判据影响）→ 停下向用户说明，确认后再继续。
+- 完成后进 wf-test。

package/modules/hosts/trae/commands/wf-deploy.md

@@ -0,0 +1,13 @@
+---
+name: wf-deploy
+description: Deploy 阶段 · prod 上线清单（静态门 / 配对 / 回归 / DB / 授权 / 24h 观察；关单在 wf-test）
+---
+
+严格按 AGENTS.md 与 .agents/commands/deploy.md 执行：Deploy 阶段 · prod 上线清单（静态门 / 配对检查 / 回归 / DB / 授权 / 24h 观察；文档关单在 wf-test，本阶段不重复关单）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：上线授权 = 用户对话内一句确认 + release/<日期> tag 留痕；无第二审批人，AI 不得自行上线。
+- 本阶段不委派子智能体；回滚 SQL 等数据安全判断由主智能体做、用户拍板。
+- 异常进 wf-maintain；用户确认无异常 = prod 闭环，AI 不得自行宣告。

package/modules/hosts/trae/commands/wf-design.md

@@ -0,0 +1,13 @@
+---
+name: wf-design
+description: Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）
+---
+
+严格按 AGENTS.md 与 .agents/commands/design.md 执行：Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：spec 草稿经用户确认；L3 另有独立复核门，复核未过不得确认。
+- L3 独立复核委派 independent-reviewer（.trae/agents/independent-reviewer.md）；子智能体未开启时按 fallback: new-session 另开新会话，不得由原会话自查冒充。
+- 确认后进 wf-build。

package/modules/hosts/trae/commands/wf-maintain.md

@@ -0,0 +1,13 @@
+---
+name: wf-maintain
+description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物）
+---
+
+严格按 AGENTS.md 与 .agents/commands/maintain.md 执行：Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物，不必另造 intent）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：止血方案由用户拍板（AI 只执行选定方案）；三件套草稿经用户确认后才落地。
+- 配 plan 的时点与形态以权威文件为准——incident≡intent 免掉的是 intent，plan 不可免（commit / push 两处门禁按同名硬拦）。
+- 复现路径与验收明确的局部热修可委派 implementer（.trae/agents/implementer.md）；事故诊断、根因定性与三件套起草不委派。

package/modules/hosts/trae/commands/wf-new-task.md

@@ -0,0 +1,13 @@
+---
+name: wf-new-task
+description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复 → wf-maintain）+ 级别判断（L0-L3）
+---
+
+严格按 AGENTS.md 与 .agents/commands/new-task.md 执行：闭环总入口 · 路由判断（新需求 intent → wf-plan / 修复 incident → wf-maintain）+ 级别判断（L0-L3）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 输出路由结论与级别，指明进入哪个 wf-*.md；不并阶段、不跳阶段。
+- approval_required 阶段产出未经用户对话内一句话确认，不得进入下一阶段。
+- 宿主级差异（规则惰性加载 / 终端 shell / 子智能体开关 / 门禁冗余）见 alwaysApply 规则 `.trae/rules/project-workflow.md`，不在此重复。

package/modules/hosts/trae/commands/wf-plan.md

@@ -0,0 +1,13 @@
+---
+name: wf-plan
+description: Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）
+---
+
+严格按 AGENTS.md 与 .agents/commands/plan.md 执行：Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：intent 草稿全文输出给用户过目，一句"可以"即确认（draft→approved），确认前不进下一阶段。
+- 已有 approved intent 时按级别跳转：L1 → wf-build；L2/L3 → wf-design。
+- 本阶段不委派子智能体，由主智能体起草；任务入口动作与红线勾选口径以权威文件为准。

package/modules/hosts/trae/commands/wf-review.md

@@ -0,0 +1,13 @@
+---
+name: wf-review
+description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）
+---
+
+严格按 AGENTS.md 与 .agents/commands/review.md 执行：Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 顺序：机器门禁自动拦 → independent-reviewer 复核（L2/L3 强制独立，子智能体未开启时另开新会话）→ 分级清单交用户定性与决定合入时机。
+- 确认门：P0/P1 未清回 wf-build；清零且用户确认后才可合入。
+- finding 报告门（防误报）与机器兜底清单以权威文件为准。

package/modules/hosts/trae/commands/wf-test.md

@@ -0,0 +1,14 @@
+---
+name: wf-test
+description: Test 阶段 · 静态门 + 切库冒烟 + UI 实测 + L2/L3 独立复核（关单在本阶段）
+---
+
+严格按 AGENTS.md 与 .agents/commands/test.md 执行：Test 阶段 · 静态门全过 + 切库冒烟（如触发）+ UI 实测 + L2/L3 独立复核。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：全过后用户确认才关单；**关单在本阶段**（勾验收 / incident 状态 / 委派留痕的口径以权威文件为准）。
+- UI 实测委派 ui-verifier（.trae/agents/ui-verifier.md）；L2/L3 独立复核委派 independent-reviewer，子智能体未开启时另开新会话。
+- 失败项修复仍回 wf-build，不在本阶段顺手改代码。
+- L1 到此结束；L2/L3 仅当用户确认要上 prod 才进 wf-deploy。