agentic-flow-kit 0.2.0

package/templates/_agents/commands/design.md

@@ -0,0 +1,54 @@
+---
+description: Design 阶段:起 spec(L2/L3 强制,L1 可省略)
+stage: Design
+triggers:
+  - "起个 spec"
+  - "接着起 spec"
+  - "intent 看过了"
+  - "spec 走一下"
+delegation:
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: L3 spec 草稿完成且用户确认前
+    required: true
+    fallback: new-session
+approval_required: true
+next: .agents/commands/build.md
+---
+
+# Design · 起 spec
+
+> L2/L3 强制;L1 可省略(直接跳 `next: build.md`)。
+
+## 执行
+
+1. 确认同名入口文档已批准：新需求为 approved intent，修复为已确认的 incident 草稿；否则拒绝，分别回 `plan.md` / `maintain.md`
+2. 级别判断(对照 AGENTS.md 第 3 条):
+   - **L1**(实现级改动,未命中 L2/L3)→ 可省略 spec,直接跳 `next: build.md`
+   - **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
+   - **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
+3. 起草 spec:
+   - 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
+   - 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
+   - 约束映射必须对照根 `AGENTS.md`「Working rules」与改动域目录级 `AGENTS.md`（如有）逐条说明如何满足
+   - 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
+   - **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单（字段清单）」还是「选择器/弹窗」，禁止自行推定交互形态
+4. 起草后停下,输出草稿全文给用户过目
+5. L3 必须独立复核:宿主支持子智能体时调用 `independent-reviewer`,并要求其读取 `.agents/roles/independent-reviewer.md`;不支持时另开新会话。复核者读 spec + 根 AGENTS.md 与改动域目录级 AGENTS.md 的红线挑漏洞,结论写入 spec「确认与复核」节;复核未过不得确认
+
+## 技能辅助(可选,宿主级 skills)
+
+- 对话已充分、无需再访谈时:用 `to-spec` 直接综合成 spec 草稿;其"发布到 issue tracker"默认行为一律改为写入 `workflow/specs/` 同名文件,按 `_TEMPLATE.md` 格式
+- L2/L3 模块设计:用 `codebase-design`(深模块/接缝/接口收窄);术语混乱或需记 ADR:用 `domain-modeling`
+- 方案取舍需压力测试:用 `grilling`;技能产出不越过用户确认门,L3 独立复核流程不变
+
+## 委派约定
+
+- spec 起草、方案取舍与用户确认由主智能体负责,不委派;只有 L3 确认前的独立复核委派 `independent-reviewer`(必需输入:入口文档、spec、根 `AGENTS.md` + 改动域目录级 `AGENTS.md`、固定复核目标)。
+- 宿主不支持子智能体时必须 `fallback: new-session`,不得由原主智能体自查冒充独立复核。
+
+## 确认后
+
+- spec 状态 draft → approved
+- 不单独 commit(根 `AGENTS.md` 第 5 条)
+- 进 `next: .agents/commands/build.md`

package/templates/_agents/commands/maintain.md

@@ -0,0 +1,91 @@
+---
+description: Maintain 阶段:立 incident + 复盘三件套(修复 / 防复发 / 规范条目)
+stage: Maintain
+triggers:
+  - "立个 incident"
+  - "线上出事了"
+  - "记一笔 incident"
+  - "出事了,根因 xxx"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: 用户已选定止血或结构性修复方案,复现路径与授权文件均明确,且任务满足角色契约
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/plan.md(若复盘需要新 intent)
+---
+
+# Maintain · 立 incident + 复盘三件套
+
+> 修复走 incident 流程;incident 在 L1+ 即 **intent 等价物**(check-loop 已认 incident≡intent),不必另造 intent。spec/plan 与 incident 同名即闭环。
+
+> 事故回到 Plan。复盘三件套缺一不可,防复发承诺不留在文档里。
+
+## 执行
+
+> **任务入口动作**：先跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），完成后在对话贴看板链接 http://127.0.0.1:{{BOARD_PORT}} 。
+
+### 0. 紧急止血(仍在事故中时)
+
+1. AI 先诊断:读日志 + 代码,给出止血选项(版本回退 / 数据回滚 / 热修 / 降级 / 暂不处理)与各自影响面、耗时
+   - **版本回退**(代码 / 配置,无数据影响):回退到上一 `release/<日期>` tag——运行时 / 管线类事故(认证管线 / DI 注册 / 中间件)的首选,须确认上一 tag 可复现构建
+   - **数据回滚**(库侧):按 `deploy.md` §5 的回滚预案执行——须有备份点、回滚 SQL 已在 dev 演练过;涉及数据安全,不得委派子智能体判断
+2. 止血方案由用户拍板;AI 只执行选定方案,不自行推送修复
+3. 热修代码后仍须补跑 `test.md` 静态门;止血完成再进下面的复盘流程(时间线从本节记起)
+
+### 1. 起草 incident
+
+1. **先检索同类 incident**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents`——命中同类先读其「根因 / 复盘三件套」，本次三件套须引用其防复发条目（review.md P2 对账项）
+2. 复制 `workflow/incidents/_TEMPLATE.md` → `workflow/incidents/YYYY-MM-DD-<主题>.md`（frontmatter 填 `模块:`，词表见 `.agents/workflow-modules.txt`）
+3. 填 4 节:时间线(发现→定位→止血→恢复,带时刻) / 影响面(页面/接口/数据范围) / 根因(一句话+深层原因) / 为什么之前没拦住(门禁/测试/规范各查一遍)
+
+### 2. 起草复盘三件套(缺一不可)
+
+> 目的:让事故真正回到 Plan,不让「防复发」承诺停留在文档里。
+
+**1. 结构性修复**
+- 修复 commit:<SHA + 改动文件清单>
+- 影响环境:dev / staging / prod(已上线模块若波及 prod,需附影响用户数 / 持续时长 / 是否回滚)
+- 是否需要新 intent(本 incident 即 intent 等价物,check-loop 已认 incident≡intent,spec/plan 与 incident 同名即闭环):
+  - 否 → 理由:<根因属实现 bug、单点修复已完成,incident 已含目标/约束,等同 intent>
+  - 是 → 根因属「门禁缺位 / 规范未落地 / 系统性问题」时强制立 `workflow/intents/YYYY-MM-DD-<主题>.md` 追踪(即使结构性修复已完成)
+
+**2. 防复发验证**(必须落到自动化用例或回归条目,禁止只写「已人工验证」)
+- 自动化用例:项目测试套件 `<文件>`(`<用例名 / 数量>`)
+- 或 verify 步骤:`.agents/commands/test.md` + <具体操作>
+- 或回归清单条目:`workflow/regression-checklist.md` 防复发验证节(追加一行)
+
+**3. 规范条目**(必须有可追溯落点)
+- 落点优先级(取最前者可行即止):`workflow/regression-checklist.md` 回归条目 / `.agents/hooks/` 或 `tests/` 断言(机器门)→ `.agents/skills/`、`.agents/notes/` → `workflow/` 文档 → `.agents/commands/`
+- **根 `AGENTS.md` 不再是落点**;**入册门槛**:已由机器门强制的内容只留一行指针,禁止在常驻面复述;**一进一出**:落点为常驻面时须在本 commit 内删除或下沉一条被取代条目
+- 常驻面体积预算由 pre-commit 硬拦(`sh .agents/scripts/rule-budget.sh --staged`,表 `.agents/rule-budgets.txt`)——超限先删再增
+- 引用:commit <SHA> / 文件:<路径>#L<行>;若无新增条目,理由:<已有条目覆盖,说明条目位置>
+
+### 3. 起草后停下
+
+输出草稿全文给用户过目;确认后才执行三件套落地。**确认点不合并**：incident 草稿、spec、plan 各自过目确认（plan 的两道门见 `build.md`）；确认后立即留痕（spec/plan 状态 `approved` + 「确认与复核」节，incident 时间线补「用户确认」条目），`done` 只在关单出现。
+
+### 4. 确认后落地
+
+1. **开工前先配 plan**：复制 `workflow/plans/_TEMPLATE.md` 建 incident 同名 plan（L1 极简形态填「改动面 + 验证方式」两节即可）——incident≡intent 免掉的是 intent，**plan 不可免**（pre-commit 增量配对门禁与 pre-push check-loop 均按同名硬拦）
+2. 结构性修复:L1 走 `build.md` → `test.md`;L2/L3 先走 `design.md` 再进 `build.md` → `test.md`
+3. 三件套落地:防复发验证按 §2②、规范条目按 §2③ 落点优先级逐条落
+4. 若选「需要新 intent」→ 进 `next: .agents/commands/plan.md` 立新 intent 追踪
+
+## 技能辅助(可选,宿主级 skills)
+
+- 根因诊断:难复现/跨层问题用 `diagnosing-bugs` 走诊断循环(红→最小化→假设→插桩→修复→回归)
+- 事故定性/分级:参考 `triage` 技能的状态机思路;产出仍落 incident 模板,不引外部 tracker
+- 处置决策需用户离线拍板:用 `to-questionnaire` 生成问卷
+
+## 子代理调用约定
+
+- 事故诊断、止血选项、根因定性、incident 与三件套起草均由主智能体负责,不委派;用户选定止血方案后,仅有明确复现路径、授权文件与验收条件的局部热修可委派 `implementer`(数据 / Schema / 权限 / 安全 / 破坏性操作不得委派)。
+- 常规结构性修复按级别回流(L1 走 `build.md`;L2/L3 走 `design.md`),不在 Maintain 绕过前置门禁;子智能体返回后由主智能体检查 diff 并补跑 `test.md`。
+
+## 确认后
+
+- incident 状态 → fixed(三件套全落地)
+- 防复发用例通过后 → closed
+- 若需新 intent → 进 `next: .agents/commands/plan.md`

package/templates/_agents/commands/new-task.md

@@ -0,0 +1,73 @@
+---
+description: AI-Native 闭环总入口:6 阶段指令索引(Plan→Design→Build→Test→Deploy→Maintain)
+stage: entry
+triggers:
+  - "开工"
+  - "发个任务"
+  - "走闭环"
+  - "从头跑"
+approval_required: true
+next: 按阶段路由
+---
+
+# New Task · 闭环总入口
+
+> 6 阶段指令索引。AI 读 AGENTS.md 后按阶段路由,不并阶段、不跳阶段。
+
+## 6 阶段指令索引
+
+| 阶段 | 指令 | 触发短语 | 可委派子智能体 | 确认点 |
+|------|------|---------|----------------|--------|
+| **Plan** | [.agents/commands/plan.md](.agents/commands/plan.md) | "起个 intent" / "要做个 <功能>" | 无 | intent 要点确认 |
+| **Design** | [.agents/commands/design.md](.agents/commands/design.md) | "起个 spec" / "intent 看过了" | `independent-reviewer`(L3) | spec 草稿确认(L3 加独立复核) |
+| **Build** | [.agents/commands/build.md](.agents/commands/build.md) | "起个 plan" → "动手吧" | `implementer`(确认后、范围明确时) | plan 确认 + 动手前确认 |
+| **Test** | [.agents/commands/test.md](.agents/commands/test.md) | "改完了" / "跑下 verify" | `ui-verifier`、`independent-reviewer` | 测试全过(L2/L3 独立复核)+ 关单；L1 结束 |
+| **Deploy** | [.agents/commands/deploy.md](.agents/commands/deploy.md) | "可以上了" / "过 release 清单" | 无 | 仅 prod：用户确认 + release tag |
+| **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
+| **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
+
+## 路由判断
+
+- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
+- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
+ - L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 plan → `test.md`
+ - L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
+ - 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
+- **改完代码要验证**:直接进 `test.md`（验证通过即关单；L1 到此结束）
+- **合入前评审**:直接进 `review.md`(横切,P0/P1/P2 分级清单 + L2/L3 独立复核)
+- **准备上线**:直接进 `deploy.md`（仅 prod；文档应已在 test 关单）
+
+## 级别判断(AGENTS.md 第 3 条)
+
+| 级别 | 改什么 | 流程 |
+|------|--------|------|
+| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
+| L1 | **实现级改动**(未命中 L2/L3) | 轻量入口文档(intent / incident) + plan |
+| L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
+| L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
+
+> 级别判定同上表"改什么"列;混合改动按最高档定级。
+
+**L2 触达面**(闭集,命中任一即 L2;本体不改但改其输入域 / 调用点校验同样命中):
+
+1. **编码权威**:项目内「一处生成、多处消费」的编码 / 命名 / 取号规则(编码模板、序列发生器、命名空间与去重约束——具体清单按项目 AGENTS.md)
+2. **共享契约**:跨模块共享的基类 / DTO 形状、跨模块公共接口签名
+3. **既有接口语义**:既有参数或端点的行为变化(由失效变生效、默认值或钳制口径改变)
+4. **全局横切口径**:错误响应出口、分页与校验口径、聚合投影键
+
+> **负例(落 L1)**:纯页面表现 / 文案 / 布局 / 交互实现;纯新增端点或参数且既有行为不变;单模块内部重构且无对外契约变化。
+> **自查句**:能否列出 ≥2 个受影响的消费方(模块 / 端点 / 页面)?能 → L2。
+> 先例:本仓 `workflow/specs/`、`workflow/intents/` 下同类历史(kb 检索主题词)。
+
+> **L1 是默认档**:红线全不勾即 L1,无需正列举——判级只回答「是否命中 L2 四类或 L3 结构面」。
+> **L3 的「DI 链」按组合根与运行时管线理解**:DI 注册、中间件/认证管线、服务构造器依赖变更(先例:本仓 workflow/ 留痕中无 schema 变更仍定 L3 的同类历史)。
+
+## intent 豁免(避免小改动也走完整闭环)
+
+- **L0 新需求**:可直接处理；**L1 新需求**:立轻量 intent + plan(不必 spec)
+- **docs 级改动**(AGENTS.md / workflow/ 模板 / .agents/ 脚本与 commands / yaml):豁免 intent,走 Conventional Commits 直接 commit;若同时触及代码,按代码部分级别立 intent
+- **bootstrap 类改动**(引入规则本身):豁免 intent,commit message 显式声明 `bootstrap`
+
+## 闭环兜底
+
+- 门禁清单与判据以 `.githooks/` / `.agents/hooks/` / `check-loop.sh` 头部注释为准(本文件不复述、不写项数);hard-block = 配对断裂 / 回路断档 / 新建 done 未勾验。本地机器门只有本地钩子,禁 `--no-verify`(见根 `AGENTS.md`)。

package/templates/_agents/commands/plan.md

@@ -0,0 +1,46 @@
+---
+description: Plan 阶段:立 intent(需求来源 / 目标 / 约束 / 触达红线)
+stage: Plan
+triggers:
+  - "起个 intent"
+  - "立 intent"
+  - "新需求 <主题>"
+  - "要做个 <功能>"
+approval_required: true
+next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
+---
+
+# Plan · 立 intent
+
+> AI 起草,用户确认。确认前不进下一阶段。
+
+## 执行
+
+> **任务入口动作**：先跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），完成后在对话贴看板链接 http://127.0.0.1:{{BOARD_PORT}} 。
+
+1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
+2. 否则起草新 intent:
+   - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
+   - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
+   - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
+   - 按 6 节填写:背景与问题 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线（L1 微改动可省非目标/约束两节，不硬填）
+   - 红线勾选对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
+3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
+4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
+
+## 技能辅助(可选,宿主级 skills)
+
+- 需求模糊、判据写不出时:用 `grilling`/`grill-me` 拷问需求,答完回填 6 节
+- 需要用户离线拍板的决策:用 `to-questionnaire` 生成问卷,问题清单随 intent 草稿一并列出
+- 讨论中需同时沉淀术语表/ADR:用 `grill-with-docs`,文档落 `workflow/` 下与主题同名
+- 技能只辅助澄清,产出仍按 `_TEMPLATE.md` 落 `workflow/intents/`,确认门不变
+
+## 执行主体
+
+- 需求澄清、级别判断与 intent 起草由主智能体负责,本阶段不委派子智能体。
+
+## 确认后
+
+- intent 状态 draft → approved
+- 不单独 commit(根 `AGENTS.md` 第 5 条)
+- L1 → `.agents/commands/build.md`；L2/L3 → `.agents/commands/design.md`

package/templates/_agents/commands/review.md

@@ -0,0 +1,59 @@
+---
+description: 代码评审标准（按风险分级：机器兜底 + AI 自查出清单，用户决策定性与合入）
+stage: review（横切：合入前使用，不占 6 阶段之一）
+triggers:
+  - "评审一下"
+  - "过 review 标准"
+  - "按评审标准过一遍"
+delegation:
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: 机器门禁完成且复核目标与 diff 基准已固定（L2 / L3 强制独立复核,宿主不支持时按正文「独立性兜底」另开新会话,不得回退主智能体）
+    required: false
+    fallback: new-session
+approval_required: true
+next: .agents/commands/build.md（仅 P0 / P1 未清时；清零后经用户确认合入）
+---
+
+# Review
+
+> 参考 Anthropic REVIEW.md 做法。宗旨是**用户决策 + AI 协作**：AI 跑机器门禁、自查、出分级清单与建议；用户确认问题定性与合入。把"该机器兜底"与"靠 AI 自查"分开列明，避免注意力耗在机械逐行上。
+> 本文件为通用骨架;项目专属红线 / 命名 / 组件约定的具体口径在项目适配区（目录级 `AGENTS.md` 与 `.agents/hooks/`）补充。
+
+## P0 必拦（优先机器兜底，hook 覆盖不到的靠 AI 自查）
+
+- **架构红线**：分层依赖方向约束(如领域 / 应用层禁直接引用基础设施实现;豁免清单见目录级 `AGENTS.md` / 项目适配区)
+  - 机器兜底：项目自有架构门禁(如有,`.agents/hooks/`)
+- **审计字段**：项目约定的公共审计字段必须由统一基础设施自动写入，禁业务代码手工补写
+  - 机器兜底：项目自有门禁(如有,比对新增审计赋值;统一基础设施与初始化写入合法)
+- **删除拦截**：删除前必须查子级 / 业务引用，被引用时按项目统一口径报错拒绝；无数据库外键兜底的引用(值引用 / 跨模块单据引用)必须服务层显式查
+  - 机器兜底：项目自有门禁(如有,删除调用点与 allowlist 比对) + AI 自查守卫正确性(每个调用点核对删前查引用)
+- **入参校验**：必填字符串判空，范围型字段范围校验，非法输入按项目统一错误口径拒绝
+  - 机器兜底：项目验证测试覆盖(如有) + AI 自查
+- **L2 / L3 改动无 spec**：拒收，先回 `workflow/specs/` 立 spec 确认通过
+
+## P1 应拦（自查重点）
+
+- **DB 命名与迁移**：遵循项目表 / 字段 / 外键命名规范与 schema 变更流程(见目录级 `AGENTS.md`);不得擅自引入项目未采用的迁移机制
+- **前端形态**：新增 / 编辑与大数据量选择等交互遵循项目组件约定(弹层 vs 跳页、选择器形态、表格与样式统一等)
+- **表单**：可选字段空值按项目约定归一化后再提交;禁改后端 DTO 规避校验
+- **状态管理**：遵循项目状态管理模式;store 调 API，组件只调 store
+- **API 入参边界**：写操作禁 `[FromBody]` 绑定领域实体（一律 DTO）；入参 DTO 禁含主键与审计字段
+- **导入信任边界**：导入执行端点服务端全量复验，禁信任客户端校验结果；解析失败进错误行汇总，禁静默丢弃
+- **Create/Update 校验同口径**：Create 已有校验 Update 必须同口径；被引用的标识符字段禁改
+- **查询分页与状态语义**：分页参数范围校验 + 服务层钳制；非法状态与不存在分离(按项目统一错误口径,如 400 / 404)
+- **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
+
+## P2 建议（提醒，不拦合入）
+
+- 样式统一性（深色 / 浅色主题、卡片样式）
+- 注释完整性（复杂逻辑处补注释，AGENTS.md 已说的不重复）
+- Conventional Commits 中文（feat / fix / docs / style / refactor / perf）
+- 历史同类 incident 的复盘三件套是否补齐
+
+## 审查分工（用户决策 + AI 协作）
+
+- **机器兜底**（pre-commit / pre-push / test 自动拦，无需人守）：门禁清单与判据以 `.githooks/`、`.agents/hooks/`、`check-loop.sh` 头部注释为准；`项目测试命令` 跑自动化用例。
+- **AI 复核**：机器门禁完成后优先委派 `independent-reviewer`，聚焦 P0 hook 未覆盖项 + 全部 P1（P2 视精力）——产出分级问题清单 + 修复建议。复核方法参考 `code-review` 技能（Standards×Spec 双轴）；每条 finding 报告前过 `review-verification-protocol` 防误报门（锚定 file:line、给出证据、校准严重级，不确定就降级为提问）。
+- **独立性**：L2 / L3 必须用独立子智能体，宿主不支持时另开新会话，不得由原作者自查冒充；L0 / L1 且宿主不支持子智能体时可由主智能体按同一复核契约执行。
+- **用户决策**：问题定性（误报驳回 / P0 成立必修 / P1、P2 处置裁量）+ 合入时机；git 历史即评审记录，追溯靠 commit 与 tag。

package/templates/_agents/commands/test.md

@@ -0,0 +1,80 @@
+---
+description: Test 阶段:静态门(架构红线 + build + test)+ UI 实测(headless Chrome)
+stage: Test
+triggers:
+  - "跑下 verify"
+  - "改完了"
+  - "跑下 verify 看看"
+  - "验证一下"
+delegation:
+  - role: ui-verifier
+    instructions: .agents/roles/ui-verifier.md
+    when: 涉及 UI 改动且静态门已通过
+    required: true
+    fallback: main
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: L2 或 L3 改动完成且 diff 已固定
+    required: true
+    fallback: new-session
+approval_required: true
+next: L1 关单结束 ；L2/L3 上 prod 时 → .agents/commands/deploy.md
+---
+
+# Test · 静态门 + UI 实测
+
+> 两道闸:静态门全过 + 涉及 UI 走浏览器实测。失败不放过。
+
+## 1. 静态门(代码改动后必跑)
+
+```bash
+# 项目自有门禁脚本(如有;清单以 .agents/hooks/ 与目录级 AGENTS.md 头部注释为准)
+项目构建命令                                      # 编译
+项目测试命令                                       # 自动化测试
+项目类型检查命令                                  # 前端类型检查/构建(涉及前端时跑)
+node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1 即先修台账再继续:跑 gen-wiki-board.mjs 补索引/看板;pre-commit 已按增量自动拦,此行用于改完即验)
+```
+
+> **环境注记**：本地服务占用构建产物导致编译失败、多会话并行时「谁跑静态门 / 提交谁先停服务」等约定——如有,见项目注记 `.agents/notes/runtime-env.md` §2,跑静态门前先过一眼。
+
+> **Windows / PowerShell 取码**：`bash` / `sh` 不在 PATH、命令不存在时 `$LASTEXITCODE` 保持旧值（假绿）——调法与取真码姿势见 `.agents/notes/runtime-env.md` §1(如有),断言「通过」前先确认命令真的跑了。
+
+任一失败 → 不进 UI 实测,回 `build.md` 修复;失败难复现(偶发/跨层)时先用 `diagnosing-bugs` 技能走诊断循环(红→最小化→假设→插桩→修复→回归),修复仍回 `build.md`。
+
+> **门禁 / 看板 / wiki 脚本改动**(`.agents/scripts/`、`.agents/hooks/`、`.agents/board/`):按改动对象跑对应 fixture 回归,须全绿——闭环门禁 `sh .agents/scripts/check-loop.test.sh`、wiki 生成器 `node .agents/scripts/gen-wiki-board.test.mjs`、提交前 hook 测试(如有);涉及看板告警规则时,用同批 workflow fixture 双跑 `check-loop.sh` 与看板 `/api/board`,断言 hard-block 集合被看板告警覆盖(防口径分叉)。
+
+## 2. 切库冒烟(切换 / 新增目标库后必跑)
+
+改了项目数据库连接配置(或新增目标库)时,静态门不足以保证库-代码一致(编译 / 类型检查不连库;自动化测试覆盖受既有用例限制),必须额外两步:
+
+1. **schema 比对**:代码期望的表与列 vs 目标库实际 schema。范围 = 近期 schema 变更脚本涉及对象 + 项目基础 / 平台只读表(如有)
+2. **接口探活**:跑项目自有冒烟脚本(如有,见 `.agents/commands/test.md` 项目适配区;脚本不可用再手工逐个 GET 关键端点),任一非 200 即判库未同步,**停在此步,不部署**
+
+防复发条目的断言增量登记在 `workflow/regression-checklist.md`(如有)。
+
+## 3. UI 实测(涉及前端改动时)
+
+调用项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`(如有)；环境细节(服务起法 / headless Chrome 参数 / CDP 注入 / 进程生命周期)见该技能与项目注记 `.agents/notes/runtime-env.md`(如有)。
+
+## 4. 独立复核(L2/L3 强制)
+
+- L2/L3 改动必须由 `independent-reviewer` 在独立上下文复核;宿主不支持子智能体时另开新会话,避免沿用原修改思路盲区
+- 复核者读入口文档(intent / incident) + spec + plan + diff,判断变更意图与风险
+- 复核意见交用户定性(采纳 / 驳回);采纳项回 `build.md` 修改
+
+## 子代理调用约定
+
+- 静态门不委派;UI 实测委派 `ui-verifier`(静态门通过后)、独立复核委派 `independent-reviewer`,均要求读取对应 `.agents/roles/*.md`;宿主不支持时按 frontmatter `fallback`(reviewer 必须另开新会话,不得主智能体自查冒充)。
+- 子智能体只返回证据与结论——失败项修复仍回 `build.md`,不得在 Test 阶段顺手改代码;修复后重跑本阶段,全过后用户确认再关单。
+
+## 确认后
+
+- 输出测试报告(通过项 / 失败项)
+- 失败项已修复并复测通过
+- **关单**（日常闭环点，不依赖是否上 prod）:
+  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」，intent → done；同名 spec（若有）仍 approved → done
+  - 修复：防复发验证已落地，incident → closed
+  - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
+  - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）
+- L1：本阶段结束，不进 deploy
+- L2/L3：仅当用户确认要上 prod 时进 `.agents/commands/deploy.md`

package/templates/_agents/hooks/check-pairing-incremental.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan
+# 目的：把 check-loop.sh「配对断裂」hard-block 的发现时机从 pre-push 提前到 commit
+# （papercut 2026-09-15：maintain.md 只写「incident≡intent 免另立 intent」，未把配 plan 写成显式步骤，
+#  按文档字面执行三次 commit 全绿、push 才爆红，只能后补）
+# 口径与 check-loop.sh 对齐：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名；
+# 同 commit 携带 plan 合法（检查的是工作区文件存在，staged 新建 plan 同样命中）。
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+fail=0
+for f in $(git diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
+  # 闭环引擎启用前的回填件带「流程: legacy」豁免配对检查（与 check-loop 同口径）
+  if grep -q '^流程: legacy' "$f"; then
+    continue
+  fi
+  base=$(basename "$f" .md)
+  if [ ! -f "workflow/plans/$base.md" ]; then
+    echo "闭环配对（增量）— BLOCK:"
+    echo "  入口缺同名 plan: $f（应在 workflow/plans/$base.md）"
+    echo "  L1 极简 plan 只需「改动面 + 验证方式」两节（复制 workflow/plans/_TEMPLATE.md）"
+    fail=1
+  fi
+done
+
+if [ $fail -ne 0 ]; then
+  echo "pre-commit: 入口文档缺同名 plan，提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）" >&2
+fi
+exit $fail

package/templates/_agents/hooks/check-wiki-ledger.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# wiki 台账一致性（增量版）：本次暂存触及 wiki/ 时跑 verify 三方校验（磁盘 ↔ INDEX ↔ 看板 DATA）
+# 目的：给「登记动作」装触发点——verify 此前无任何钩子调用，只能靠「触及 wiki 时手跑」的文字纪律
+# （incident 2026-09-16-wiki-drift-and-verifier-gaps 认定的根因）；本脚本把发现时机提前到 commit。
+# 口径与 .agents/scripts/verify-wiki-consistency.mjs 一致：活层新增/删除/移动未登记、数据维护批次目录未入台账即拦。
+# 注意 `-c core.quotepath=off`：core.quotepath 为 git 默认 true 时中文路径被转义加引号——实测输出
+# `"wiki/\346\265\213\350\257\225..."`，`^wiki/` 前缀匹配失配 → 门禁静默跳过（本机 .gitconfig 恰好设 false，本地不复现）。
+
+cd "$(git rev-parse --show-toplevel)" || exit 1
+
+git -c core.quotepath=off diff --cached --name-only | grep -q '^wiki/' || exit 0
+
+if ! node .agents/scripts/verify-wiki-consistency.mjs; then
+  echo "wiki 台账（增量）— BLOCK:"
+  echo "  先跑 node .agents/scripts/gen-wiki-board.mjs 补 INDEX/看板（或补 wiki/数据维护/README.md 登记行），再原路重试提交"
+  exit 1
+fi
+exit 0

package/templates/_agents/hooks/commit-check.cjs

@@ -0,0 +1,140 @@
+// commit-check: git commit 前置验证（agentic-flow-kit 通用版）
+// 1) 敏感信息扫描（暂存区新增行含疑似密钥 -> BLOCK）
+// 2) 条件构建验证（按 .agents/hooks/commit-check.config.json 的 builds 配置；--full 全跑）
+// 3) 质量检测（config.checks：lint / 类型检查 / vet 等秒级确定性检查；--full 全跑）
+// config 由 flow-kit init 按技术栈生成初值，项目可自行增改；缺失或无 builds/checks 时跳过对应段。
+// 配置示例（.agents/hooks/commit-check.config.json）：
+//   {
+//     "knownPatterns": ["admin\\/123", "my-project-seed"],       // 项目已知种子/代码标识符白名单（正则源，i 标志）
+//     "builds": [
+//       { "name": "backend",  "command": "dotnet build", "ext": [".cs", ".sln", ".csproj"] },
+//       { "name": "frontend", "command": "npm run build", "ext": [".ts", ".tsx", ".vue", ".js", ".jsx"],
+//         "cwd": "frontend",
+//         "lockPattern": "MSB3026|MSB3027",                        // 可选：命中时按 lockHint 提示（文件锁类「与代码无关」失败）
+//         "lockHint": "构建被文件锁拦下——本地运行中的进程正占用产物，停进程后重试" }
+//     ],
+//     "checks": [
+//       { "name": "typecheck", "command": "npx tsc --noEmit", "ext": [".ts", ".tsx"], "when": ["tsconfig.json"] },
+//       { "name": "lint",      "command": "npx eslint .", "ext": [".ts", ".js"], "when": ["eslint.config.js", ".eslintrc.json"] }
+//     ]
+//   }
+// checks.when：路径数组，任一存在才启用（元素支持尾部 * 一层通配，如 "*.sln"）——
+//   没有对应配置的项目自动跳过并提示，不 fail-closed 误拦；无 when 字段 = 无条件启用。
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+process.chdir(path.resolve(__dirname, '../..'));
+
+function sh(cmd, cwd) {
+  try {
+    execSync(cmd, { stdio: 'pipe', encoding: 'utf8', cwd: cwd || undefined });
+    return { ok: true, out: '' };
+  } catch (e) {
+    return { ok: false, out: String((e.stdout || '') + (e.stderr || '')) };
+  }
+}
+
+let staged = [];
+try {
+  staged = execSync('git diff --cached --name-only', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+    .split('\n').map(s => s.trim()).filter(Boolean);
+} catch (e) {
+  console.log('BLOCK: 无法读取暂存区（git diff --cached 失败）');
+  process.exit(1);
+}
+
+// --- 0) 项目配置（可选） ---
+let config = { knownPatterns: [], builds: [] };
+try {
+  const raw = JSON.parse(fs.readFileSync('.agents/hooks/commit-check.config.json', 'utf8'));
+  config = { ...config, ...raw };
+} catch (e) { /* 无配置 = 敏感扫描用基线白名单 + 跳过构建验证 */ }
+
+// --- 1) 敏感信息扫描：暂存区新增行是否含疑似密钥（只认带引号的字符串字面量；排除类型/空值关键字） ---
+const SECRET = /(password|passwd|pwd|secret|token|apikey|api[_ -]?key|connectionstring|server=|bearer)["']?\s*[:=]\s*["'](?!["']?(string|number|boolean|unknown|any|never|void|object|null|undefined|true|false)\b)[^"'\r\n]{6,}["']/i;
+// 判据/白名单自身的定义行长得就像密钥赋值，须自豁免
+const SELF = /const (SECRET|KNOWN) = \//i;
+// KNOWN：项目已知种子与代码标识符白名单（config.knownPatterns 注入；本文件基线为空——通用包不带项目种子）
+let KNOWN = null;
+if (Array.isArray(config.knownPatterns) && config.knownPatterns.length) {
+  KNOWN = new RegExp(config.knownPatterns.join('|'), 'i');
+}
+let diffText = '';
+try {
+  diffText = execSync('git diff --cached', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+} catch (e) { /* 空暂存 */ }
+const added = diffText.split('\n').filter(l => l.startsWith('+') && !l.startsWith('+++'));
+const hits = added.filter(l => SECRET.test(l) && !(KNOWN && KNOWN.test(l)) && !SELF.test(l));
+if (hits.length) {
+  console.log('BLOCK: 暂存区疑似包含敏感信息（密钥/连接串/令牌），请检查:\n' + hits.slice(0, 5).join('\n'));
+  process.exit(1);
+}
+
+// --- 2) 条件构建验证 ---
+// --full：合并提交（pre-merge-commit / 冲突解决后手动 commit）使用——合并结果是没人验证过的新状态，
+// 按 ext/prefix 裁剪可能漏掉需要重跑的一侧，故不做条件选择、全部 builds 都跑。
+// 引擎自身文件（.agents/、.githooks/）不参与构建匹配——工作流引擎不是项目构建产物。
+const FULL = process.argv.includes('--full');
+const stagedForBuild = staged.filter(f => !f.startsWith('.agents/') && !f.startsWith('.githooks/'));
+let ranAny = false;
+for (const b of (config.builds || [])) {
+  if (!b || !b.command) continue;
+  const exts = Array.isArray(b.ext) ? b.ext : [];
+  const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (b.prefix ? f.startsWith(b.prefix) : false));
+  if (!match) continue;
+  ranAny = true;
+  const r = sh(b.command, b.cwd);
+  if (!r.ok) {
+    if (b.lockPattern && new RegExp(b.lockPattern).test(r.out)) {
+      console.log(`BLOCK: ${b.name} 构建被文件锁拦下（与代码无关）。${b.lockHint || '停掉占用进程后原路重试'}\n` +
+        '锁冲突行：\n' + r.out.split(/\r?\n/).filter(l => new RegExp(b.lockPattern).test(l)).slice(0, 3).join('\n'));
+    } else {
+      console.log(`BLOCK: ${b.name} 构建失败（${b.command}）\n` + r.out.slice(0, 1500));
+    }
+    process.exit(1);
+  }
+  console.log(`OK: ${b.name} 构建通过（${b.command}）`);
+}
+if (!ranAny) {
+  console.log(config.builds && config.builds.length
+    ? 'SKIP: 无匹配的源码变更，跳过构建验证'
+    : 'SKIP: 未配置 builds（.agents/hooks/commit-check.config.json），跳过构建验证');
+}
+
+// --- 3) 质量检测（checks：lint / 类型检查 / vet 等秒级确定性检查；测试不放这里——关单在 test.md 阶段门） ---
+// whenSatisfied：任一路径存在即启用；元素支持尾部 * 一层通配（如 *.sln = 仓库根存在 .sln 结尾文件）
+function whenSatisfied(when) {
+  if (!when) return true;
+  const list = Array.isArray(when) ? when : [when];
+  return list.some((w) => {
+    const star = w.indexOf('*');
+    if (star < 0) return fs.existsSync(w);
+    const suffix = w.slice(star + 1);
+    const dir = path.dirname(w.slice(0, star)) || '.';
+    try { return fs.readdirSync(dir).some((f) => f.endsWith(suffix)); } catch (e) { return false; }
+  });
+}
+let ranCheck = false;
+for (const c of (config.checks || [])) {
+  if (!c || !c.command) continue;
+  const exts = Array.isArray(c.ext) ? c.ext : [];
+  const match = FULL || stagedForBuild.some(f => exts.some(e => f.endsWith(e)) || (c.prefix ? f.startsWith(c.prefix) : false));
+  if (!match) continue;
+  ranCheck = true;
+  if (!whenSatisfied(c.when)) {
+    console.log(`SKIP: ${c.name}（未找到 ${Array.isArray(c.when) ? c.when.join(' / ') : c.when}，跳过质量检查——配置好后自动启用）`);
+    continue;
+  }
+  const r = sh(c.command, c.cwd);
+  if (!r.ok) {
+    console.log(`BLOCK: ${c.name} 质量检查未通过（${c.command}）\n` + r.out.slice(0, 1200));
+    process.exit(1);
+  }
+  console.log(`OK: ${c.name} 质量检查通过（${c.command}）`);
+}
+if (!ranCheck && config.checks && config.checks.length) {
+  console.log('SKIP: 无匹配的源码变更，跳过质量检测');
+}
+
+console.log('COMMIT_CHECK_OK');

package/templates/_agents/hooks/local-pre-commit

@@ -0,0 +1,6 @@
+#!/bin/sh
+# 项目门禁挂载点（.githooks/pre-commit 在通用门禁之后执行本文件；返回非零即阻断提交）
+# 把项目专属门禁逐行加在这里；npx agentic-flow-kit add-gate <门禁> 会自动接线（手动示例：）：
+#   sh .agents/hooks/check-architecture.sh
+# set -e：任一门禁非零即中止本脚本（退出码透传给 pre-commit 阻断提交）——不要在末尾加 exit 0
+set -e

package/templates/_agents/notes/runtime-env.md

@@ -0,0 +1,18 @@
+# 运行时环境注记
+
+> 记录本机/本项目的运行时差异，供 agent 与钩子脚本对照（shell 可用性 / 端口 / 进程名等）。
+> 本文件是骨架：项目按实际填写，不随 flow-kit 升级覆盖。
+
+## 1. 终端与 shell
+
+- <本机默认终端（如 PowerShell / Git Bash）；`sh` / `bash` 是否在 PATH；「命令不存在」时退出码取法与假绿风险示例>
+
+## 2. 本地端口与进程
+
+- API：<端口 / 进程名 / 启动停止命令>
+- 前端：<端口 / 启动命令>
+- workflow 看板：{{BOARD_PORT}}（`node .agents/scripts/workflow-board-server.mjs`，只读）
+
+## 3. 数据与密钥
+
+- <本地库连接约定（不写明文密钥）；含密钥/环境差异的配置文件走 `.gitattributes` 的 `merge=ours`（须 `git config merge.ours.driver true`）>