朱子纯 / erp-workflow-plugin

Commit 2ee4c7fd6d6213dd0fc67bca58f359e1ae2e5007

Authored by zichun
1 parent cb9da34e

docs: sync plugin.json/README/CLAUDE-template to 9-skill + workflow layout

Inline Side-by-side
Showing 3 changed files with 144 additions and 221 deletions
.claude-plugin/plugin.json
  View file @2ee4c7f
1 1 {
2 2 "name": "erp-workflow",
3   - "description": "ERP 项目全流程框架：阶段 A 计划（一次性） + 阶段 B 编码（模块循环 + 功能循环），含完整 skill 流水线 + 守门 hook + 软规则留痕。",
4   - "version": "0.1.0",
5   - "skills": ["./skills/plan", "./skills/coding", "./skills/crosscut"]
  3 + "description": "ERP 项目全流程框架：阶段 A 计划（交互式 skill 链，9 个 skill + 4 个前移闸门） + 阶段 B 编码（单个静默 Workflow 脚本 coding.mjs，子代理自动跑后端+前端功能循环、测试闸门、本地里程碑 tag）。",
  4 + "version": "0.2.0",
  5 + "skills": ["./skills"]
6 6 }
... ...
README.md
  View file @2ee4c7f
... ... @@ -2,42 +2,45 @@
2 2  
3 3 Claude Code 插件：ERP / 后端管理系统全流程开发框架。
4 4  
5   -把"从零到 N 个模块上线 + 前端整体阶段"的整个流程固化成 **25 个 skill + 2 个 agent + 1 个 hook + 41 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、纯本地 git 的前提下推进编码。后端按模块循环依次打里程碑 tag，所有后端模块打里程碑后进入前端整体阶段（以项目根 `prototype/` 静态 HTML mockup 为页面权威）。
  5 +把"从零到 N 个模块上线 + 前端整体阶段"的整个流程固化成 **9 个 skill（Plan 阶段，交互式）+ 1 个 Workflow（`workflows/coding.mjs`，Coding 阶段，全自动静默）+ 1 个 reviewer agent + 4 个跨平台 Node 助手（`lib/*.mjs`）+ 24 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、纯本地 git 的前提下推进编码。Plan 阶段把全部需求/配置/前端约定问询前移（4 个闸门）；Coding 阶段整体是单个 Workflow 脚本，子代理无法弹窗 → 结构性静默，后端按模块循环依次打里程碑 tag，所有后端模块打里程碑后进入前端整体阶段（以项目根 `prototype/` 静态 HTML mockup 为页面权威）。
6 6  
7 7 ## 这个插件做什么
8 8  
9 9 ```
10   -📋 阶段 A：规划（一次性，入口 /erp-workflow:plan-start）
  10 +📋 阶段 A：规划（一次性，交互式 9 skill，入口 /erp-workflow:plan-start）
11 11  
12   - A0 初始化项目 → A1 锁范围（生成 REQ 卡片）
  12 + A0 project-init → A1 scope-lock（结构化 REQ 卡片 + secrets/commands 锁）
13 13 ↓
14 14 ⏸ 审阅 REQ → 重新运行 /plan-start
15 15 ↓
16   - A2 生成骨架 → A3 生成 DB 设计（REQ → docs/03 + 回填依赖表）
  16 + A2 skeleton-gen → A3 db-design-gen（REQ → docs/03 + 回填依赖表，ERP 约定可确认）
17 17 ↓
18 18 ⏸ 审阅 docs/03 → 重新运行 /plan-start
19 19 ↓
20   - A4 初始化 DB（docs/03 → V1 migration → 自动 apply 到本地 MySQL）
  20 + A4 db-init（docs/03 → V1 migration → 自动 apply 到本地 MySQL）
21 21 ↓
22   - A5 生成下游文档（docs/02 / docs/05 / docs/06 § 三 / docs/10）
  22 + A5 downstream-gen（docs/02 / docs/05 / docs/06 § 三 / docs/10）
  23 + ↓ ⛔ docs/05 + docs/02 评审闸（必须确认）
  24 + A6 frontend-scope-lock（项目级 UI 约定 / design tokens / 组件库；prototype/ 门禁）
  25 + ↓
  26 + ⛔ Plan 终结硬闸（全部前移闸门通过才放行）
23 27 ↓
24 28 用户显式 /erp-workflow:coding-start
25 29  
26   -🔁 阶段 B：编码（入口 /erp-workflow:coding-start）
27   -
28   - B-后端（按模块循环）
29   - 功能循环：Brainstorm → Plan → TDD → Verify → Review
30   - 模块循环：本地测试闸门 → 写模块报告 → 本地 merge 进默认分支 + 打 milestone/<id> tag → 自动回 coding-start → 下一模块
  30 +🔁 阶段 B：编码（单个 Workflow 脚本 workflows/coding.mjs，全自动静默）
31 31  
32   - ↓ 后端全部打里程碑后
  32 + coding-start（瘦入口 skill）校验 Plan 终结闸 → 启动 Workflow
33 33  
34   - B-前端（整体阶段，1 个里程碑 tag）
35   - 入口门禁：检查项目根 prototype/ 至少含 1 个 *.html mockup（缺失则 AskUserQuestion 提示用户补齐）
36   - FE 拆分：AI 自主推导功能清单（业务功能粒度，与 HTML 文件数无关）写入 docs/08 § 三；已有则加载——无人工审阅断点（全程无人工介入）
37   - FE 循环（每个 FE-NN）：fe-feature-brainstorm → -plan → -tdd → -verify → -review
38   - 收尾：test-gate(phase=frontend) → module-report(phase=frontend) → milestone-tag（分支 frontend-phase）→ 全部完成
  34 + coding.mjs Router → 解析 docs/08 § 二/§ 三 + git tag，列出待跑模块
  35 + │
  36 + ├─ B-后端（按模块循环，每模块一个里程碑 tag）
  37 + │ featureLoop(后端)：spec → plan → tdd → verify → review（有界 5 轮修复）
  38 + │ testGate(backend) → 跨模块记录 → 模块报告 → milestone（本地 merge --no-ff + tag）
  39 + │
  40 + └─ B-前端（后端全部打里程碑后，整体 1 个里程碑 tag）
  41 + featureLoop(前端，FE-NN，路径限 frontend/) → testGate(frontend) → milestone
39 42  
40   -⚙️ 后台守门：占位符未填 / 中断触发 / 跨模块改动未记录
  43 + 子代理无法弹窗 → 缺值即写阻塞点并 halt（终止态，非对话框）；fail-fast 后等人工修复重跑 coding-start
41 44 ```
42 45  
43 46 ## 首次使用
... ... @@ -56,179 +59,119 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。
56 59  
57 60 - **第一段（首次运行）**：执行 **A0 → A1**（创建骨架 / 锁技术栈 / 填需求 / 生成 REQ 卡片骨架）后**停下**，等你审阅并补全 `docs/01-需求清单/<module>/REQ-*.md`（CC 已起草 req_id / title / goal / rules / constraints / acceptance；输入 / 输出 各含一句简述 + N 张示例字段表，模板原样复制由你按业务编辑；依赖表 / 依赖接口保留 `TBD(A3/A5 自动补)` 由后续 skill 回填——Plan 阶段第一个人工关口：业务范围）
58 61 - **第二段（REQ 审阅完重新运行）**：继续 **A2 → A3**（生成骨架 / 从 REQ 正向设计 `docs/03-数据库设计文档.md` 并回填 REQ 依赖表）后再次**停下**，等你审阅 docs/03 的表 / 字段 / 索引 / 外键（第二个人工关口：数据库 schema —— A4 会基于它翻译 DDL 并 apply 到 MySQL，所以这关口与 REQ 审阅同等重要）
59   - - **第三段（docs/03 审阅完重新运行）**：执行 **A4 → A5**（解析 docs/03 → 生成 V1 migration → 自动 `DROP+CREATE` 本地 schema 并 apply → 生成下游文档），Plan 完成后再次**停下**
  62 + - **第三段（docs/03 审阅完重新运行）**：执行 **A4 → A5 → A6**（解析 docs/03 → 生成 V1 migration → 自动 `DROP+CREATE` 本地 schema 并 apply → 生成下游文档 → **docs/05 + docs/02 评审闸** → A6 `frontend-scope-lock` 锁定项目级前端约定 / design tokens / 组件库 + prototype/ 门禁），通过 **Plan 终结硬闸** 后再次**停下**
60 63  
61   - 每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次运行同样的命令即可恢复。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:coding-start`。
  64 + 每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次运行同样的命令即可恢复。Plan 阶段把全部需求/配置/前端约定问询前移：A1 锁结构化 REQ 字段 + secrets/account/包名/命名 + 各 stack 的 build/lint/unit/e2e 命令；A5 后强制评审 docs/05 + docs/02；A6 锁前端约定。这些闸门全过，**Plan 终结硬闸** 才放行。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:coding-start`。
62 65  
63 66 > 两个审阅断点的处理方式一致：A1 / A3 完成时 skill 已自动勾选 `docs/08-模块任务管理.md § 一` 该阶段的全部子项 + 顶层；审阅是隐式的——你看完 REQ 卡片 / docs/03 后直接重新运行 `/plan-start`，下次入口就会派发到下一阶段。如果审阅时发现需要修订，直接编辑 docs/01 / docs/03 即可，不依赖 docs/08 的勾选状态。
64 67  
65   -3. **Coding 阶段入口**（后端模块循环 → 前端整体阶段）：
  68 +3. **Coding 阶段入口**（单个 Workflow，后端模块循环 → 前端整体阶段，全自动静默）：
66 69 ```
67 70 /erp-workflow:coding-start
68 71 ```
69   - Plan 全部完成后由你显式触发。`coding-start` 是阶段分发权威——每次入口都重新扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 git tag，按当前进度决定派发：
70   -
71   - **路由规则（coding-start 真值表，只做分发）**：
72   -
73   - | `backend_done` | `frontend_done` | coding-start 派发 |
74   - |---|---|---|
75   - | `false` | 任意 | `module-start`（写后端） |
76   - | `true` | `false` | `frontend-start`（写前端） |
77   - | `true` | `true` | 打印"所有阶段已完成"，停下 |
  72 + Plan 全部完成后由你显式触发。`coding-start` 是一个**瘦入口 skill**：校验 Plan 终结闸（docs/08 § 一 全勾、git 在默认分支、工作树干净）后，调用 `Workflow({scriptPath:"${CLAUDE_PLUGIN_ROOT}/workflows/coding.mjs", ...})` 启动整个编码阶段，然后告知"已在后台启动，跑完或 halt 时通知"。**所有编码逻辑都在 `coding.mjs` 里**，不再有 B 阶段 skill 链。
78 73  
79   - docs/08 里程碑字段与 `git tag -l` 不一致（字段填了但 tag 不存在，或反之）→ 停下报错（绝不静默假设完成状态）。
  74 + **`coding.mjs` 的阶段（子代理执行，无弹窗）**：
80 75  
81   - **后端阶段（module-start 内，单一职责）**：
82   - - 切到 `module-<id>` 分支，跑功能循环（feature-brainstorm → ... → feature-review）→ 全 approve → test-gate → module-report → milestone-tag（本地 merge + 打 tag）→ 自动回 coding-start 再次路由
83   -
84   - **前端阶段（frontend-start 内，自带前置门禁）**：
85   - - 步骤 1：prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion 提示用户补齐 → 停下）
86   - - 步骤 2：准备 FE 清单（无审阅断点）。§ 三 占位则 AI 扫 prototype + docs/01 + docs/05 自主推导 FE 业务功能清单写入 § 三（每个 FE 标注关联 REQ + 关联原型；FE 数与 HTML 文件数无关）；§ 三 已有则直接加载
87   - - 步骤 3-7：里程碑 tag 判定 → 切 `frontend-phase` 分支 → 跑 fe-feature 循环（fe-feature-brainstorm → ... → fe-feature-review，专用 `fe-code-reviewer` agent 做 7 维 review）→ 全 approve → test-gate(frontend) → module-report(frontend) → milestone-tag（docs/08 § 三 整体里程碑）→ 自动回 coding-start → 全部完成
  76 + - **Router**：扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 `git tag -l`，产出结构化模块清单（`{id, done, reqs[], feItems[]}`），过滤出待跑模块。docs/08 字段与 git tag 不一致 → halt 报错（绝不静默假设完成状态）。
  77 + - **后端模块循环**（顶层 `for module`，fail-fast）：每模块依次 `featureLoop(reqs, 'backend')` →（spec → plan → tdd → verify → review，有界 5 轮修复，第 5 轮仍 request-changes 即 halt）→ `testGate(backend)`（红色自动重试 1 次防 flaky，仍红则 halt）→ 跨模块改动记录 → 模块报告 → milestone（本地 `git merge --no-ff` 进默认分支 + 打 `milestone/<id>` tag + 回写 docs/08 § 二）。
  78 + - **前端阶段**（后端全部打里程碑后）：`featureLoop(feItems, 'frontend')`（FE-NN，路径限 `frontend/`，review 调统一 `code-reviewer` agent 附加前端 7 维 checklist）→ `testGate(frontend)` → milestone（docs/08 § 三 整体里程碑）。
  79 + - **halt 终止态**：子代理缺值不弹窗 → 写阻塞点并抛错；整阶段 fail-fast，halt 后停下等人工修复，修好重跑 `/erp-workflow:coding-start` 从断点续跑。
88 80  
89 81 `docs/08 § 二` 每后端模块占一行 bullet，`§ 三` 是前端阶段整体段，完成信号统一由本地 `git tag -l 'milestone/<id>'` 判定。
90 82  
91   -4. **中途恢复**：任何时候运行对应入口命令——根据 Plan § 一 checkbox、§ 二 各后端模块里程碑 tag、§ 三 前端整体里程碑 tag 跳到当前该做的事。
  83 +4. **中途恢复**：任何时候重跑 `/erp-workflow:coding-start`——`coding.mjs` 的 Router 根据 docs/08 § 二/§ 三 里程碑字段 + 本地 git tag 跳到当前该做的模块/阶段。
92 84  
93 85 ## 目录结构
94 86  
95 87 ```
96 88 erp-workflow-plugin/
97 89 ├── .claude-plugin/
98   -│ └── plugin.json # 插件清单，声明 skills 四个子目录
  90 +│ └── plugin.json # 插件清单，声明 ./skills（9 skill）
99 91 ├── README.md # 本文档
100   -├── hooks/
101   -│ ├── hooks.json # hook 注册表（1 个 hook）
102   -│ └── scripts/*.sh # 1 个 hook 脚本
  92 +├── workflows/
  93 +│ └── coding.mjs # 阶段 B：整个编码阶段编排为单个静默 Workflow
  94 +├── lib/ # 跨平台 Node 助手（ESM，node:test 单测）
  95 +│ ├── merge-gitignore.mjs # .gitignore 逐行判重合并（替代 merge-gitignore.sh）
  96 +│ ├── render.mjs # 字面量安全模板渲染（替代 render.sh）
  97 +│ ├── validate-ddl.mjs # docs/03 ↔ DDL 5 维校验（替代 validate.sh）
  98 +│ ├── apply-ddl.mjs # 安全 env 解析 + mysql apply（替代内联 mysql bash）
  99 +│ └── *.test.mjs # 各助手的 node:test 单测
103 100 ├── agents/
104   -│ ├── superpower-code-reviewer.md # 后端 code-reviewer agent（feature-review 调用）
105   -│ └── fe-code-reviewer.md # 前端专用 reviewer（fe-feature-review 调用，硬编码 7 维 review）
106   -└── skills/
107   - ├── plan/ # 阶段 A：6 个一次性规划 skill
108   - ├── coding/ # 阶段 B：15 个 skill = 9 个后端模块/功能循环 + frontend-start + 5 个 fe-feature-*
109   - └── crosscut/ # 横切：2 个入口 + 1 中断守门 + 1 留痕 skill
  101 +│ └── code-reviewer.md # 统一 reviewer（coding.mjs review stage 调用，phase 选维度集）
  102 +└── skills/ # 阶段 A：9 个 skill（扁平，无中间层）
  103 + ├── plan-start/ # A 阶段入口 + Plan 终结硬闸
  104 + ├── project-init/ # A0
  105 + ├── scope-lock/ # A1
  106 + ├── skeleton-gen/ # A2
  107 + ├── db-design-gen/ # A3
  108 + ├── db-init/ # A4
  109 + ├── downstream-gen/ # A5
  110 + ├── frontend-scope-lock/ # A6
  111 + └── coding-start/ # B 阶段瘦入口（启动 coding.mjs）
110 112 ```
111 113  
112   -## Hook 清单（1 个，在 hooks/hooks.json 注册）
  114 +## Hook 清单（0 个）
  115 +
  116 +本插件**不再注册任何 hook**。原"跨模块改动留痕"hook（`log-cross-module.sh`）已删除，其职责由 `workflows/coding.mjs` 的 cross-module stage 在模块循环内承担。
  117 +
  118 +## Skill 清单（9 个，扁平于 `skills/`）
113 119  
114   -| Hook | 脚本 | 事件 | 触发条件 | 作用 |
115   -|---|---|---|---|---|
116   -| 跨模块改动留痕 | `log-cross-module.sh` | PostToolUse / Edit \| Write | 当前处于 `module-*` 分支 且 编辑目标路径落在 `docs/08 § 二` 中**非当前模块**的 path 范围内（无论目标模块是否已打里程碑） | 把改动追加为 `TBD(CC 补)` 存根到 `<current_module>-cross-module.md`；通过 `additionalContext` 软提示 CC 调 `cross-module-log` skill **自主推断**补「原因 / 影响评估」两列。即时性由 CC 自己决定；**最迟在 `module-report` § ⑦ 硬闸门处**（TBD 未清空会阻断模块完成报告），保证模块完成前所有 TBD 必被 CC 填实 |
  120 +### 入口（2 个）
117 121  
118   -## Skill 清单（25 个）
  122 +| Skill | 作用 | 谁调用 |
  123 +|---|---|---|
  124 +| `plan-start` | **A 阶段入口 + Plan 终结硬闸**。读 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill（含 A6 → `frontend-scope-lock`）；A 全部完成时校验全部前移闸门（REQ 真实数据、docs/07 secrets 全锁、docs/04 § 零 命令齐、docs/05+02 已评审、A6 前端 scope 已锁），全过才提示运行 `/erp-workflow:coding-start`，否则指出缺口不放行 | **用户手动** `/erp-workflow:plan-start` |
  125 +| `coding-start` | **B 阶段瘦入口**（`allowed-tools: Read Glob Workflow`）。校验 Plan 终结闸（docs/08 § 一 全勾、git 在默认分支、工作树干净）→ 读 docs/08 § 二/§ 三 + `git tag -l 'milestone/*'` 概述进度 → 调用 `Workflow({scriptPath:"${CLAUDE_PLUGIN_ROOT}/workflows/coding.mjs", args:{projectRoot}})` 启动整个编码阶段 → 告知"已在后台启动" | **用户手动** `/erp-workflow:coding-start` |
119 126  
120   -### Plan 阶段（6 个，`skills/`）
  127 +### Plan 阶段 A skill（7 个 = A0~A6，均由 `plan-start` 按 docs/08 § 一 顺序派发）
121 128  
122 129 | # | Skill | 作用 | 流程中谁调用 |
123 130 |---|---|---|---|
124   -| A0 | `project-init` | • 依赖检查（`mysql` 在 PATH，缺失则尝试自动安装）<br>• 空目录初始化：`cp` 模板创建 CLAUDE.md / docs/01/index.md / docs/08<br>• `git init` | `plan-start` |
125   -| A1 | `scope-lock` | • 引导填项目概述 / 技术栈 / 需求索引<br>• 按 `docs/01-需求清单/<module>/{_module.md, REQ-*.md}` 子目录结构生成 REQ 卡片骨架（CC 起草 req_id / title / goal / rules / constraints / acceptance；输入 / 输出 各含一句简述 + N 张示例字段表（输入 8 列 / 输出 3 列），全部原样复制自模板，由人工按业务编辑；`依赖表 / 依赖接口` 留 `TBD(A3/A5 自动补)`）<br>• **停下**等人工审阅 + 改输入 / 输出，审阅完毕用 `/plan-start` 恢复续进 A2 | A0 |
126   -| A2 | `skeleton-gen` | • 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09<br>• 生成工具脚本：scripts/*.sh、.env.local<br>• 创建 `sql/migrations/` 空目录（Flyway 准备）<br>• 合并 .gitignore（逐行判重） | `plan-start` |
127   -| A3 | `db-design-gen` | • 从 docs/01 REQ 卡片正向设计 `docs/03-数据库设计文档.md`（schema SSoT）<br>• 回填 REQ 卡片依赖表（`TBD(A3 自动补)` → 实际表名）<br>• **停下**等人工审阅 docs/03，审阅完毕用 `/plan-start` 恢复续进 A4 | A2 |
128   -| A4 | `db-init` | • LLM 解析 docs/03 → `sql/migrations/V1__initial_schema.sql`（DDL only）<br>• **5 维度全量校验** DDL ↔ docs/03（表名 / 列名+列序 / 类型+nullable+默认值 / 索引名 / FK 名），fail-closed<br>• 验证 MySQL 连接<br>• 调 `scripts/setup-test-db.sh` 复用三层防护（与 B 阶段 test.sh 共用）→ DROP+CREATE 空库<br>• apply V1 + `SHOW TABLES` 行数自检 | A3 |
129   -| A5 | `downstream-gen` | • 一次性生成 docs/02 / docs/05 / docs/06 § 三 / docs/10<br>• 回填 REQ 卡片依赖接口（`TBD(A5 自动补)` → 实际 endpoint）<br>• 追加模块清单到 docs/08 § 二<br>• 最终占位符扫描（TBD 自动补 + `【人工填写：】` QA 循环）<br>• 打印 Plan 完成横幅并**停下**（不自动进 B） | A4 |
  131 +| A0 | `project-init` | • **依赖检查**：检测 git / mysql / node 是否在 PATH，缺失则按 OS（darwin/win32/linux）打印安装指引并 halt（**不自动 brew/apt 安装**）<br>• 空目录初始化：用 Read/Write/Glob 工具拷模板创建 CLAUDE.md / docs/01/index.md / docs/08<br>• `git init` | `plan-start` |
  132 +| A1 | `scope-lock` | • 引导填项目概述 / 技术栈 / 需求索引<br>• 按 `docs/01-需求清单/<module>/{_module.md, REQ-*.md}` 子目录结构生成**结构化** REQ 卡片（每字段一行：字段名/类型/必填/校验/业务规则/示例值，示例值必须替换为真实约束）<br>• **A1 终结校验**：REQ 字段非空且非占位、docs/07 secret/account/包名/namespace 字段清单已锁、各 stack 的 build/lint/unit/e2e 命令写入 docs/04 § 零；缺失则在此（Plan 期）用 `AskUserQuestion` 问清<br>• 用 `node ${CLAUDE_PLUGIN_ROOT}/lib/render.mjs` 渲染模板<br>• **停下**等人工审阅，审阅完毕用 `/plan-start` 续进 A2 | A0 |
  133 +| A2 | `skeleton-gen` | • 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09<br>• 生成跨平台工具脚本：`scripts/*.mjs`、.env.local（**无 chmod**）<br>• 创建 `sql/migrations/` 空目录（Flyway 准备）<br>• 用 `node ${CLAUDE_PLUGIN_ROOT}/lib/merge-gitignore.mjs` 合并 .gitignore（逐行判重） | `plan-start` |
  134 +| A3 | `db-design-gen` | • A3 起始用 `AskUserQuestion` 确认 ERP 约定（主键策略 / 租户列 / 列前缀规则，默认值可覆盖），结果写 docs/04 + CLAUDE.md<br>• 从 docs/01 REQ 卡片正向设计 `docs/03-数据库设计文档.md`（schema SSoT）<br>• 回填 REQ 卡片依赖表（`TBD(A3 自动补)` → 实际表名）<br>• **停下**等人工审阅 docs/03，审阅完毕用 `/plan-start` 续进 A4 | A2 |
  135 +| A4 | `db-init` | • LLM 解析 docs/03 → `sql/migrations/V1__initial_schema.sql`（DDL only）<br>• `node ${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs` 校验 DDL ↔ docs/03（5 维：表/列名/列类型/索引/FK），fail-closed<br>• `node ${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs .env.local V1.sql`（安全 env 解析 + mysql2 apply，**无 shell-source**） | A3 |
  136 +| A5 | `downstream-gen` | • 一次性生成 docs/02 / docs/05 / docs/06 § 三 / docs/10<br>• 回填 REQ 卡片依赖接口（`TBD(A5 自动补)` → 实际 endpoint）<br>• 追加模块清单到 docs/08 § 二<br>• **docs/05 + docs/02 评审闸**：用 `AskUserQuestion` 让用户确认 API 端点/字段无误 + 构建顺序可接受，未确认不勾 A5<br>• 最终占位符 + 结构残留扫描 | A4 |
  137 +| A6 | `frontend-scope-lock` | • `user-invocable:false`，由 plan-start 在 A5 后派发<br>• **prototype/ 门禁**：项目根 `prototype/*.html` 缺失则 `AskUserQuestion` 要求补齐（Plan 期可问）<br>• 从 prototype + docs/01 + docs/05/06 提炼项目级 UI 约定 / design tokens / 组件库选型，逐一 `AskUserQuestion` 确认<br>• 写入 docs/06（UI 交互规范）+ docs/04（前端栈） | `plan-start` |
130 138  
131   -### Coding 阶段（15 个，`skills/coding/`）
  139 +### Coding 阶段（1 个 Workflow，非 skill）
132 140  
133   -**触发与顺序**（`coding-start` 是唯一由用户手动触发的入口，下面所有 skill 都由 skill 链自动调用）：
  141 +整个编码阶段不再是 skill 链，而是单个 Workflow 脚本 **`workflows/coding.mjs`**（由瘦入口 skill `coding-start` 启动）。子代理无法弹窗 → 缺值即写阻塞点并 halt（结构性静默）。
134 142  
135 143 ```
136   -/erp-workflow:coding-start ← 用户每次手动触发；阶段分发器（只做分发）
  144 +coding-start（skill）校验 Plan 终结闸 → Workflow({scriptPath:"…/workflows/coding.mjs"})
137 145 │
138   - │ ① Plan 完成校验（docs/08 § 一 A0~A5）
139   - │ ② 后端完成性检查（§ 二 + git tag）
140   - │ ├ 未完成 → 立即派发 module-start，结束
141   - │ └ 已完成 → 继续 ③
142   - │ ③ 前端完成性检查（§ 三 整体里程碑 + tag）
143   - │ ├ 已完成 → 打印"所有阶段已完成"，结束
144   - │ └ 未完成 → 派发 frontend-start，结束
  146 + ▼ coding.mjs（各 stage 派 agent 子代理执行，无弹窗）
  147 + Router ── 解析 docs/08 § 二/§ 三 + git tag → 结构化模块清单（schema 校验）
  148 + │ docs/08 字段与 git tag 不一致 → halt
145 149 │
146   - ├─ 后端未完成 → 派发 module-start（写后端）
147   - │ │
148   - │ │ 切 module-<id> 分支，对每个未完成 REQ：
149   - │ │ feature-brainstorm → -plan → -tdd → -verify → -review
150   - │ │
151   - │ │ review approve → 回 module-start（下一 REQ）
152   - │ │ request-changes (<5) → fix → 回 feature-verify
153   - │ │ request-changes (=5) → 停下（升级给人）
154   - │ │
155   - │ │ 本模块所有 REQ approve：
156   - │ │ test-gate(phase=backend) → module-report → milestone-tag
157   - │ │ （本地 merge 进默认分支 + 打 milestone/<id>，写 docs/08 § 二）
158   - │ │
159   - │ └─ 自动回 coding-start → 再次路由（无人工介入）
  150 + 顶层 for module（fail-fast，halt 后 break）：
160 151 │
161   - ├─ 后端完成 & 前端完成 → 打印"所有阶段已完成"，停下
  152 + ├─ 后端：featureLoop(module.reqs, 'backend')
  153 + │ spec → plan → tdd → verify → reviewWithFixLoop（有界 5 轮：
  154 + │ review(code-reviewer) approve → 过；request-changes → fix → 重审；
  155 + │ 第 5 轮仍未过 → throw HALT）
  156 + │ → testGate(backend)（红色自动重试 1 次防 flaky，仍红 → HALT）
  157 + │ → 跨模块改动记录 → 模块报告
  158 + │ → milestone（git merge --no-ff 进默认分支 + tag milestone/<id> + 回写 docs/08 § 二）
162 159 │
163   - └─ 后端完成 & 前端未完成 → 派发 frontend-start（写前端）
164   - │
165   - │ frontend-start 自带前置门禁（coding-start 不做）：
166   - │ ① prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion）
167   - │ ② 准备 FE 清单（无审阅断点）：
168   - │ § 三 已有 FE bullet → 加载
169   - │ § 三 仅占位 → AI 推导写入
170   - │ ③ 切 frontend-phase 分支
171   - │
172   - │
173   - │ 准备 FE 清单（无审阅断点）：
174   - │ § 三 占位 → 扫 prototype + docs/01 + docs/05
175   - │ → AI 自主推导 FE 业务功能清单写入 § 三
176   - │ （含 fe_id / 功能名 / 关联 REQ / 关联原型）
177   - │ § 三 已有 FE bullet → 直接加载
178   - │
179   - │ 切 frontend-phase 分支
180   - │ FE 是业务功能粒度（与 HTML 文件数无关，
181   - │ 一个 HTML 可拆多个 FE / 多 HTML 可合一个 FE）
182   - │
183   - │ 对每个未完成 FE：
184   - │ fe-feature-brainstorm → -plan → -tdd → -verify → -review
185   - │ （review 委托 fe-code-reviewer agent，硬编码 7 维 checklist）
186   - │
187   - │ review approve → 回 frontend-start（下一 FE）
188   - │ request-changes (<5) → fix → 回 fe-feature-verify
189   - │ request-changes (=5) → 停下
190   - │
191   - │ 全部 FE approve：
192   - │ test-gate(phase=frontend)（vitest + playwright，子会话跑）
193   - │ → module-report(phase=frontend)
194   - │ → milestone-tag（docs/08 § 三 整体里程碑）
195   - │
196   - └─ 自动回 coding-start → "所有阶段已完成"（无人工介入）
  160 + └─ 前端（module.feItems 非空时，后端全部打里程碑后）：
  161 + featureLoop(feItems, 'frontend')（FE-NN，路径限 frontend/，
  162 + review 调 code-reviewer + 前端 7 维 checklist）
  163 + → testGate(frontend) → milestone（docs/08 § 三 整体里程碑）
197 164 ```
198 165  
199   -| Skill | 做什么 | 谁触发它 |
200   -|---|---|---|
201   -| `module-start` | **后端模块循环单一职责**（不感知前端阶段）。切 `module-<id>` 分支，扫 `docs/superpowers/reviews/*.md` 的 `verdict=approve` 计算已完成 REQ，推进第一个未完成 REQ；本模块全 approve → `test-gate`。**幂等可重入** | `coding-start` 派发（仅当后端有未打里程碑模块时）；`feature-review` approve 后回调 |
202   -| `feature-brainstorm` | 功能循环步骤 1：交互 brainstorm → 生成 `docs/superpowers/specs/*.md` | `module-start` 推进 REQ 时调用 |
203   -| `feature-plan` | 功能循环步骤 2：spec → 任务级 plan（文件路径 + API 签名 + 测试意图 + 完成判据，代码由 TDD 阶段产出），输出 `docs/superpowers/plans/*.md` | `feature-brainstorm` 链式调用 |
204   -| `feature-tdd` | 功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 `module-<id>` 分支）；路径硬护栏：`impl_file` 落 `frontend/` 前缀 → 硬停（UI 推迟到前端阶段） | `feature-plan` 链式调用 |
205   -| `feature-verify` | 功能循环步骤 4：将全量测试派发到子会话执行一次，用模板渲染 evidence | `feature-tdd` 链式调用；`feature-review` 在 request-changes 修复后重新调用 |
206   -| `feature-review` | 功能循环步骤 5：AI 自审，写 `docs/superpowers/reviews/*.md`。approve → 回 `module-start`；request-changes → 逐项 Edit + fix commit → 回 `feature-verify` 重新执行（最多 5 轮，第 5 轮仍 request-changes 则停下） | `feature-verify` 链式调用 |
207   -| `test-gate` | 里程碑 tag 前硬闸门。按当前分支推 phase：`module-*` → 跑 `scripts/test.sh`（drop+create 空库、Flyway apply、测试）；`frontend-phase` → 跑 vitest + playwright（命令取自 docs/04 § 零）。通过 → 写 `<phase_id>-test-gate.md` 并 commit 到当前分支；失败停下 | `module-start`（后端 REQ 全 approve 后）/ `frontend-start`（FE 全 approve 后） |
208   -| `module-report` | 中断检查 → 生成 12 节完成报告 `docs/superpowers/module-reports/<date>-<phase_id>.md`（前端阶段 § ④/§ ⑥ 写 N/A）→ commit 到当前分支（后端：module-* 分支；前端：frontend-phase 分支） | `test-gate` 链式调用 |
209   -| `milestone-tag` | 验证当前分支 = `module-<id>` 或 `frontend-phase` 且 `git status --porcelain` worktree 干净 → 探测本地默认分支 → `git merge --no-ff` 本地集成进默认分支 → 把 docs/08 § 二 该模块的 `里程碑: —`（后端） / § 三 `整体里程碑: —`（前端） 回写为 `milestone/<id>` 并 commit → `git tag -a milestone/<id>` 打里程碑 → 追加 tag 名到报告并 commit → **自动回调 coding-start 推进下一阶段（无人工介入）**。完成由本地 `git tag -l` 判定 | `module-report` 链式调用 |
210   -| `frontend-start` | 写前端阶段单一职责。步骤 1 自带 prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion）。步骤 2 准备 FE 清单（无审阅断点）：§ 三 占位则 AI 自主推导写入；§ 三 已有则加载。后续切 `frontend-phase` 分支 + 计算未完成 FE + 推进第一个 FE 的 fe-feature 循环；全 approve → `test-gate(phase=frontend)` | `coding-start` 派发（仅当 `backend_done=true && frontend_done=false`）；`fe-feature-review` approve 后回调 |
211   -| `fe-feature-brainstorm` | 前端功能循环步骤 1：基于 FE 关联的 `associated_prototypes[]` + `associated_reqs[]` + docs/05 + docs/06 § 二 + docs/04 § 零前端 → spec | `frontend-start` 推进 FE 时调用，传 `{ fe_id, name, associated_reqs[], associated_prototypes[] }` |
212   -| `fe-feature-plan` | 前端功能循环步骤 2：spec → 任务级计划（组件/路由/hook/API client，`impl_file` 必须 `frontend/` 前缀） | `fe-feature-brainstorm` 链式调用 |
213   -| `fe-feature-tdd` | 前端功能循环步骤 3：jsdom 组件测试 + Playwright E2E（E2E 派子会话）；commit trailer `REQ_ID: FE-NN`；路径硬护栏 `frontend/` | `fe-feature-plan` 链式调用 |
214   -| `fe-feature-verify` | 前端功能循环步骤 4：派子会话跑 vitest + playwright，按模板渲染证据 | `fe-feature-tdd` 链式调用；`fe-feature-review` request-changes 修复后重调 |
215   -| `fe-feature-review` | 前端功能循环步骤 5：委托 `fe-code-reviewer` agent 做 7 维 review。approve → 回 `frontend-start`；request-changes 5 轮上限 | `fe-feature-verify` 链式调用 |
216   -
217   -### Crosscut（4 个，`skills/crosscut/`）
218   -
219   -| Skill | 作用 | 流程中谁调用 |
220   -|---|---|---|
221   -| `plan-start` | **A 阶段入口**。读取 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:plan-start` |
222   -| `coding-start` | **B 阶段入口 + 阶段分发器（只做分发）**。① 验证 Plan 已完成（docs/08 § 一 A0~A5 全勾选）② 后端完成性检查（§ 二 + git tag）③ 前端完成性检查（§ 三 整体里程碑 + tag）④ 真值表派发：`backend=false` → `module-start`；`backend=true & frontend=false` → `frontend-start`；都 done → "全部完成"。前端阶段的 prototype/ 门禁由 `frontend-start` 自带，不在此处 | **用户手动**运行 `/erp-workflow:coding-start`；`milestone-tag` 每模块完成后自动回调 |
223   -| `interrupt-check` | 检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
224   -| `cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根批量补「原因 / 影响评估」 | `module-report` § ⑦ 硬验收时一次性调用（CC 编辑中途不主动调）；`module-start` 初始化日志文件时也会用其模板 |
  166 +`coding.mjs` 内部用 `pipeline` 把后端/前端功能链同构为一个 `featureLoop(items, phase)`（替代旧 10 个克隆 skill）；`reviewWithFixLoop` 有界 5 轮；`testGate` 失败自动重试 1 次。完成信号统一由本地 `git tag -l 'milestone/<id>'` 判定，**不依赖任何远程仓库 / push**。
225 167  
226   -## Agent 清单（2 个）
  168 +> 旧 B 阶段的 15 个 skill（`module-start` / `feature-*` / `frontend-start` / `fe-feature-*` / `test-gate` / `module-report` / `milestone-tag`）与 2 个横切 skill（`interrupt-check` / `cross-module-log`）已删除，其意图融入 `coding.mjs` 的各 stage prompt 与 `lib/` 助手；中断/跨模块留痕由 workflow 的 halt 终止态 + `crossModulePrompt` stage 承担（替代被删 hook）。
227 169  
228   -| Agent | 源 | 用途 | 谁调用 |
229   -|---|---|---|---|
230   -| `superpower-code-reviewer` | `superpowers:code-reviewer` 5.0.7 agent，仅改 name | 对后端 REQ diff 做 AI 自审，产出 `must_fix[]` / `nice_to_have[]` / `gaps` | `feature-review` 步骤 1：`Agent(subagent_type=superpower-code-reviewer)` |
231   -| `fe-code-reviewer` | 自写（前端专用） | 对前端 FE-NN diff 做 7 维 AI 自审：prototype 一致性 / Design Tokens / 无障碍 / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖。明确禁止给后端建议 | `fe-feature-review` 步骤 1：`Agent(subagent_type=fe-code-reviewer)` |
  170 +## Agent 清单（1 个）
  171 +
  172 +| Agent | 用途 | 谁调用 |
  173 +|---|---|---|
  174 +| `code-reviewer` | 统一 reviewer。`phase=backend` 跑通用代码审查维度；`phase=frontend` 附加前端 7 维 checklist（prototype 一致性 / design tokens / a11y / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖，主观维度仅标记明显问题不触发 request-changes）。非交互，返回结构化 verdict，绝不弹窗 | `workflows/coding.mjs` 的 review stage：`agent(..., {agentType:'code-reviewer'})` |
232 175  
233 176 ## Banners 清单（7 份，`bash cat` 直接输出，绕开 LLM 复读）
234 177  
... ... @@ -242,28 +185,29 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
242 185 | db-design-gen | `banners/flow.txt` | A 阶段流程图(▶ 标在 A3) |
243 186 | db-init | `banners/flow.txt` | A 阶段流程图(▶ 标在 A4) |
244 187 | downstream-gen | `banners/flow.txt` | A 阶段流程图(▶ 标在 A5) |
245   -| plan-start | `banners/flow-done.txt` | A 阶段流程图(▶ 标在"规划阶段到此结束"，仅 2.1 Plan 完成分支) |
  188 +| plan-start | `banners/flow-overview.txt` | A 阶段整体流程图(入口处打印) |
246 189  
247 190 **字节对齐保证**:每个文件 17 行,每行 visible width = 58 cell(内宽 56 + 2 个 `│` 边框)。改动需重新校准。
248 191  
249   -## Templates 清单（41 份）
  192 +## Templates 清单（24 份）
250 193  
251 194 | 所属 Skill | 模板文件 | 用途 |
252 195 |---|---|---|
253 196 | project-init | `CLAUDE-template.md` | 项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定） |
254 197 | project-init | `docs-01-index-template.md` | 需求清单索引骨架，等用户填模块表 |
255   -| project-init | `docs-08-initial-template.md` | 工作流进度文件骨架（Plan A0~A5 checkbox） |
256   -| project-init | `docs-04-stack-template.md` | docs/04 § 零 默认技术栈总览（零槽位，cp 即可） |
257   -| scope-lock | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片骨架（6 个 `{{...}}` 占位符由 CC 替换；输入 / 输出 各含一句简述 + N 张示例字段表，模板原样复制由人工编辑） |
258   -| scope-lock | `_module-template.md` | 模块子目录的 `_module.md` 模块头（4 行：模块代码-名 / 简述 / 依赖模块 TBD / 涉及表 TBD） |
  198 +| project-init | `docs-04-stack-template.md` | docs/04 § 零 默认技术栈总览（零槽位，拷即可） |
  199 +| project-init | `docs-08-initial-template.md` | 工作流进度文件骨架（Plan A0~A6 checkbox） |
  200 +| scope-lock | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片骨架（结构化字段表：字段名/类型/必填/校验/业务规则/示例值，示例值须替换为真实约束） |
  201 +| scope-lock | `_module-template.md` | 模块子目录的 `_module.md` 模块头（模块代码-名 / 简述 / 依赖模块 TBD / 涉及表 TBD） |
259 202 | skeleton-gen | `docs-04-skeleton-template.md` | docs/04 § 一+ 编码规范大纲（HTML 注释引导 LLM） |
260 203 | skeleton-gen | `docs-06-static-template.md` | docs/06 § 一~二 大纲（通用交互 + Design Tokens；布局以 prototype/ 为权威） |
261 204 | skeleton-gen | `docs-07-env-template.md` | docs/07 环境配置大纲 |
262 205 | skeleton-gen | `docs-09-structure-template.md` | docs/09 目录结构大纲 |
263   -| skeleton-gen | `scripts-setup-test-db-template.sh` | 运行时 drop + create 空库脚本（0 槽位）；schema apply 交给 Flyway |
264   -| skeleton-gen | `scripts-test-template.sh` | test.sh 骨架（4 个命令槽位：{{build_cmd}} / {{lint_cmd}} / {{test_cmd}} / {{e2e_cmd}}，由 skeleton-gen 按技术栈推断填充） |
265   -| skeleton-gen | `env-local-template` | 6 字段凭据模板（DB_* + JWT_SECRET） |
  206 +| skeleton-gen | `scripts-setup-test-db-template.mjs` | 跨平台 drop + create 空库脚本（安全 env 解析，无 shell-source）；schema apply 交给 Flyway |
  207 +| skeleton-gen | `scripts-test-template.mjs` | test.mjs 骨架（命令槽位 {{TEST_CMD}} / {{E2E_CMD}}，`spawnSync(shell:true)` 跨平台执行） |
  208 +| skeleton-gen | `env-local-template` | 凭据模板（DB_* + JWT_SECRET） |
266 209 | skeleton-gen | `gitignore-append-template` | 插件推荐忽略项（`.env.local`、`.tmp/`、构建产物等） |
  210 +| skeleton-gen | `styles-tokens-template.css` | 前端 design tokens CSS 变量骨架 |
267 211 | db-design-gen | `docs-03-header-template.md` | docs/03 数据库设计头部 |
268 212 | db-design-gen | `docs-03-table-template.md` | docs/03 单表小节模板 |
269 213 | downstream-gen | `docs-02-template.md` | docs/02 开发计划 |
... ... @@ -272,34 +216,18 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
272 216 | downstream-gen | `docs-06-module-pagelist-template.md` | docs/06 § 三 单模块页面清单 |
273 217 | downstream-gen | `docs-08-module-row-template.md` | docs/08 § 二 单模块 bullet 行 |
274 218 | downstream-gen | `docs-10-header-template.md` | docs/10 验收清单（项目级 SOP，零槽位 + 引用指针） |
275   -| module-start | `module-start-banner-template.md` | 模块启动横幅 |
276   -| feature-brainstorm | `feature-spec-template.md` | 功能 spec 结构 |
277   -| feature-plan | `feature-plan-template.md` | 功能 plan 结构 |
278   -| feature-tdd | `commit-message-template.md` | TDD 每步 commit 信息 |
279   -| feature-verify | `feature-verify-evidence-template.md` | 验证证据渲染模板 |
280   -| feature-review | `feature-review-template.md` | 自审报告结构 |
281   -| test-gate | `test-gate-result-template.md` | 闸门结果渲染 |
282   -| module-report | `module-report-template.md` | 12 节模块报告 |
283   -| interrupt-check | `interrupt-block-template.md` | Blocker 节追加模板 |
284   -| cross-module-log | `cross-module-log-template.md` | cross-module 日志头（由 hook log-cross-module.sh 在首次跨模块改动时渲染创建；skill 自身不再读取） |
285   -| cross-module-log | `cross-module-log-row-template.md` | 单条改动行模板 |
286   -| frontend-start | `frontend-start-banner-template.md` | 前端阶段启动横幅 |
287   -| fe-feature-brainstorm | `fe-feature-spec-template.md` | 前端功能规格结构（组件树 / 状态机 / API / 业务校验复刻 / token 引用） |
288   -| fe-feature-plan | `fe-feature-plan-template.md` | 前端功能计划结构（组件 / 路由 / hook / API client，`impl_file` 必须 `frontend/`） |
289   -| fe-feature-tdd | `commit-message-template.md` | 前端 TDD commit 信息（与后端共用格式，但 `req_id` = FE-NN） |
290   -| fe-feature-verify | `fe-feature-verify-evidence-template.md` | 前端验证证据（vitest + playwright 双段） |
291   -| fe-feature-review | `fe-feature-review-template.md` | 前端自审报告结构（含 7 维核查表） |
292   -| fe-feature-review | `commit-message-template.md` | 前端 review fix commit 信息 |
293   -
294   -**流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。
  219 +| frontend-scope-lock | `fe-scope-template.md` | A6 前端 scope：UI 约定 / design tokens / 组件库 / 每个 FE-NN 设计决策表 |
  220 +
  221 +**流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。Coding 阶段的渲染/校验逻辑改由 `lib/*.mjs` 助手承担，不再用 skill 模板。
295 222  
296 223 ## 前置依赖
297 224  
  225 +- **Node.js ≥ 18**：`lib/*.mjs` 助手 + `workflows/coding.mjs` + 生成进目标项目的 `scripts/*.mjs` 均为 ESM；CC 运行时自带。A0 `project-init` 检测 git / mysql / node 在 PATH，缺失则按 OS 打印安装指引并 halt（不自动安装）
298 226 - **MySQL 8.x** 实例已就绪（推荐本地 / `*.local` host；A4 `db-init` 的安全守护要求 host 在白名单且 schema 名含 `test`/`dev`/`local`，避免误删生产库）
299   -- **`mysql` 命令行**：A4 `db-init` 验证连接 + 自动 `DROP+CREATE` schema 后 apply V1；`scripts/setup-test-db.sh` 在测试闸门前后 drop+create 空库
300   -- **Spring Boot + Flyway**（**必需**）：pom.xml 声明 `flyway-core` + `flyway-mysql`；Spring 启动时自动 apply `sql/migrations/V*.sql`。本插件生成的 `setup-test-db.sh` 只清库，schema 必须由 Flyway 应用
301   -- **本地 git 仓库**（纯本地，无需远程）：A0 `project-init` 执行 `git init`；B 阶段每模块由 `milestone-tag` 本地 `git merge --no-ff` 进默认分支并 `git tag -a milestone/<id>`，完成信号由 `git tag -l` 判定。**不依赖任何远程仓库 / push / GitLab**
302   -- **本地可运行 `mvn test` / `pnpm test`**：测试闸门 `scripts/test.sh` 由 `skeleton-gen` 生成
  227 +- **`mysql2`（目标项目侧）**：A4 `db-init` 经 `lib/apply-ddl.mjs` 用 mysql2 连接 + 安全 env 解析 apply V1；生成的 `scripts/setup-test-db.mjs` 在测试闸门前后 drop+create 空库
  228 +- **Spring Boot + Flyway**（**必需**）：pom.xml 声明 `flyway-core` + `flyway-mysql`；Spring 启动时自动 apply `sql/migrations/V*.sql`。本插件生成的 `setup-test-db.mjs` 只清库，schema 必须由 Flyway 应用
  229 +- **本地 git 仓库**（纯本地，无需远程）：A0 `project-init` 执行 `git init`；B 阶段每模块由 `coding.mjs` 的 milestone stage 本地 `git merge --no-ff` 进默认分支并 `git tag -a milestone/<id>`，完成信号由 `git tag -l` 判定。**不依赖任何远程仓库 / push / GitLab**
  230 +- **本地可运行 `mvn test` / `pnpm test`**：测试命令由 A1 写入 docs/04 § 零，生成的 `scripts/test.mjs` 由 `skeleton-gen` 产出，`coding.mjs` 的 testGate stage 调用
303 231  
304 232 ## 设计原则
305 233  
... ...
skills/project-init/templates/CLAUDE-template.md
  View file @2ee4c7f
... ... @@ -15,40 +15,35 @@
15 15  
16 16 ## 🔄 B 阶段开发流程（后端模块循环 → 前端整体阶段）
17 17  
18   -B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-start`。
  18 +B 阶段整体是**一个静默 Workflow 脚本 `workflows/coding.mjs`**（由瘦入口 skill 启动）。入口：`/erp-workflow:coding-start`。子代理无法弹窗 → 缺值即写阻塞点并 halt（结构性静默）。
19 19  
20   -### 阶段路由（coding-start 内，只做分发）
  20 +### 入口与路由（coding-start skill → coding.mjs Router）
21 21  
22   -`coding-start` 每次入口做两段完成性检查后真值表派发：
  22 +`/erp-workflow:coding-start` 是瘦入口：校验 Plan 终结闸（docs/08 § 一 全勾、git 在默认分支、工作树干净）后，调用 `Workflow({scriptPath:"…/workflows/coding.mjs", args:{projectRoot}})` 启动整个编码阶段。`coding.mjs` 的 **Router** stage 扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 `git tag -l`，产出结构化模块清单（`{id, done, reqs[], feItems[]}`），过滤待跑模块；docs/08 字段与 git tag 不一致 → halt。
23 23  
24   -- 后端完成性检查 → `backend_done`（扫 docs/08 § 二 里程碑字段 + `git tag -l`）
25   -- 前端完成性检查 → `frontend_done`（扫 docs/08 § 三 整体里程碑 + `git tag -l`）
26   -
27   -| `backend_done` | `frontend_done` | 派发 |
  24 +| `backend_done` | `frontend_done` | 行为 |
28 25 |---|---|---|
29   -| `false` | 任意 | `module-start`（写后端） |
30   -| `true` | `false` | `frontend-start`（写前端） |
  26 +| `false` | 任意 | Router 列出待跑后端模块，进入后端模块循环 |
  27 +| `true` | `false` | 进入前端阶段（`feItems` 非空的模块） |
31 28 | `true` | `true` | "所有阶段已完成" |
32 29  
33   -前端阶段前置（prototype/ 门禁）由 `frontend-start` 自带，不在 coding-start。`module-start` 与 `frontend-start` **互不感知对方**。
34   -
35 30 ### 后端阶段（每模块一个里程碑 tag）
36 31  
37   -- **模块循环（外）**：`module-start` → `test-gate(phase=backend)` → `module-report` → `milestone-tag`（本地 merge 进默认分支 + 打 `milestone/<id>` tag）→ 自动回调 coding-start 路由下一阶段（无人工介入）
38   -- **功能循环（内，每 REQ-XXX-NNN 一遍）**：`feature-brainstorm` → `feature-plan` → `feature-tdd` → `feature-verify` → `feature-review`
  32 +- **模块循环（顶层 `for module`，fail-fast）**：`featureLoop(reqs,'backend')` → `testGate('backend')`（红色自动重试 1 次防 flaky，仍红 → HALT）→ 跨模块改动记录 → 模块报告 → milestone（本地 `git merge --no-ff` 进默认分支 + 打 `milestone/<id>` tag + 回写 docs/08 § 二）→ 下一模块（无人工介入）
  33 +- **功能循环（内，每 REQ-XXX-NNN 一遍，同构 `featureLoop`）**：spec → plan → tdd → verify → review（`reviewWithFixLoop` 有界 5 轮：approve 即过；request-changes → fix → 重审；第 5 轮仍未过 → HALT）
39 34 - 后端阶段任务严格落在 `backend/` 路径下；docs/01 REQ 卡片的 UI 描述在此阶段忽略，UI 推迟到前端阶段。
40 35  
41 36 ### 前端阶段（整体一个里程碑 tag，所有后端模块打里程碑后启动）
42 37  
43   -- **FE 清单（AI 自主推导，无审阅断点）**：`frontend-start` 进入时扫 prototype + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写入 `docs/08 § 三`（已有则加载）。**FE 是业务功能粒度，与 prototype HTML 文件数无关**——一个 HTML 可拆多个 FE，多个 HTML 也可合成一个 FE。FE 清单的合理性由 fe-feature-review / milestone-tag 在整体里程碑标记时一并校核（全程无人工介入）。
44   -- **FE 循环（外）**：`frontend-start` → fe-feature 循环 → `test-gate(phase=frontend)` → `module-report(phase=frontend)` → `milestone-tag`（分支 `frontend-phase`，docs/08 § 三 整体里程碑）。
45   -- **FE 功能循环（内，每个 FE-NN 一遍）**：`fe-feature-brainstorm` → `fe-feature-plan` → `fe-feature-tdd` → `fe-feature-verify` → `fe-feature-review`（专用 `fe-code-reviewer` agent，硬编码 7 维 review checklist）
  38 +- **FE 清单（AI 自主推导，无审阅断点）**：FE 业务功能清单在 Plan 阶段 A6 + Router 阶段确定并写入 `docs/08 § 三`。**FE 是业务功能粒度，与 prototype HTML 文件数无关**——一个 HTML 可拆多个 FE，多个 HTML 也可合成一个 FE。
  39 +- **FE 循环（外）**：`featureLoop(feItems,'frontend')` → `testGate('frontend')` → milestone（分支 `frontend-phase`，docs/08 § 三 整体里程碑）。
  40 +- **FE 功能循环（内，每个 FE-NN 一遍，同构 `featureLoop`）**：spec → plan → tdd → verify → review（统一 `code-reviewer` agent，`phase=frontend` 附加 7 维 checklist）
46 41 - 前端阶段任务严格落在 `frontend/` 路径下；布局以 `prototype/` 为权威。
47 42  
48 43 ### 里程碑前测试闸门
49 44  
50   -- `test-gate`：后端阶段子会话跑 `scripts/test.sh`（含本模块新增 + 已合并模块回归）；前端阶段子会话跑 vitest + playwright。
51   -- `test-gate` 是打里程碑 tag 前唯一的硬测试门；红色不得跳过进入 `module-report` / `milestone-tag`。
  45 +- `coding.mjs` 的 **testGate** stage：后端阶段子代理跑 `scripts/test.mjs`（含本模块新增 + 已合并模块回归）；前端阶段跑 vitest + playwright（命令取自 docs/04 § 零）。
  46 +- testGate 是打里程碑 tag 前唯一的硬测试门；红色重试 1 次仍红 → HALT，不得跳过进入 report / milestone stage。
52 47  
53 48 ---
54 49  
... ... @@ -56,7 +51,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
56 51  
57 52 `docs/08-模块任务管理.md` 分两段：
58 53 - `§ 二`：后端模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / 里程碑 tag / 功能子项）
59   -- `§ 三`：前端阶段元数据（整体里程碑 + FE 子项清单，由 `frontend-start` 在所有后端模块打里程碑后填入）
  54 +- `§ 三`：前端阶段元数据（整体里程碑 + FE 子项清单，由 Plan 阶段 A6 + `coding.mjs` 在所有后端模块打里程碑后填入）
60 55  
61 56 **阶段完成判定**统一以 `里程碑:` 字段（§ 二 各模块） / `整体里程碑:` 字段（§ 三）+ 本地 `git tag -l 'milestone/<id>'` 判定；子项勾选只作可视化进度，不参与完成判定。
62 57  
... ... @@ -74,8 +69,8 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
74 69 - [ ] REQ-SYS-002 用户注册
75 70 ```
76 71  
77   -- `里程碑:` 字段由 `milestone-tag` 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。
78   -- 每个 `REQ-*` 子项由 `feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。
  72 +- `里程碑:` 字段由 `coding.mjs` 的 milestone stage 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。
  73 +- 每个 `REQ-*` 子项由 `coding.mjs` 的 review stage 在 `verdict=approve` 时自动勾选为 `[x]`。
79 74 - 路径限定为后端目录（如 `backend/module/sys/`）；前端代码不在此阶段产生。
80 75  
81 76 ### 前端阶段格式（§ 三）
... ... @@ -87,10 +82,10 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
87 82 - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html
88 83 ```
89 84  
90   -- `整体里程碑:` 字段由 `milestone-tag` 在打前端里程碑 tag 时从 `—` 改为 `milestone/frontend-phase`。
91   -- "功能:" 列表由 `frontend-start` 进入时由 AI 自主推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关；合理性由 fe-feature-review / 整体里程碑标记时统一校核。
92   -- 每个 `FE-NN` 子项由 `fe-feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。
93   -- 进入前端阶段前 `frontend-start` 步骤 1 自带 prototype/ 门禁，强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。
  85 +- `整体里程碑:` 字段由 `coding.mjs` 的 milestone stage 在打前端里程碑 tag 时从 `—` 改为 `milestone/frontend-phase`。
  86 +- "功能:" 列表由 Plan 阶段 A6（`frontend-scope-lock`）+ `coding.mjs` 推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关。
  87 +- 每个 `FE-NN` 子项由 `coding.mjs` 的 review stage 在 `verdict=approve` 时自动勾选为 `[x]`。
  88 +- prototype/ 门禁在 Plan 阶段 A6 `frontend-scope-lock` 强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。
94 89  
95 90 ### 状态语义（后端模块 + 前端阶段共用）
96 91  
... ... @@ -101,7 +96,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
101 96  
102 97 ### 模块完成报告
103 98  
104   -由 `module-report` skill 产出，模板位于 由 module-report skill 持有（12 节标准化，含跨模块改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告，仅填模板。
  99 +由 `coding.mjs` 的 report stage 产出（12 节标准化，含跨模块改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告。
105 100  
106 101 ---
107 102  
... ... @@ -112,7 +107,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
112 107 | 格式 | 谁填 | 使用阶段 | 说明 |
113 108 |------|-----|---------|------|
114 109 | `【人工填写：<简短说明>】` | 人 | 仅 A 阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值；B 阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户 |
115   -| `TBD(<责任人>)` | CC 自动 | A 或 B | 后缀附带责任方（如 `TBD(A3 自动补)` / `TBD(A5 自动补)`）；由对应 skill 就地补填，`module-report` § ⑦ 检查 `TBD(CC 补)` 残留 |
  110 +| `TBD(<责任人>)` | CC 自动 | A 或 B | 后缀附带责任方（如 `TBD(A3 自动补)` / `TBD(A5 自动补)`）；由对应 skill / `coding.mjs` stage 就地补填，模块完成报告 § ⑦ 检查 `TBD(CC 补)` 残留 |
116 111  
117 112 **HTML 注释 `<!-- ... -->`**：提示占位，是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**，指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释，最终产物里注释不会保留。
118 113  
... ... @@ -132,15 +127,15 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
132 127 ### 你禁止做的 🚫
133 128  
134 129 1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约
135   -2. **手动 Edit `docs/08 § 二/§ 三` 的 `里程碑:` / `整体里程碑:` 字段**，必须要由 `milestone-tag` 自动回写
  130 +2. **手动 Edit `docs/08 § 二/§ 三` 的 `里程碑:` / `整体里程碑:` 字段**，必须要由 `coding.mjs` 的 milestone stage 自动回写
136 131  
137 132 ### Schema 演化规约（Flyway migration）
138 133  
139 134 1. **文件命名**：`sql/migrations/V<n>__<snake_case_desc>.sql`，例：`V5__add_user_email_unique_index.sql`
140 135 2. **版本号分配**：建文件前 `ls sql/migrations/V*.sql` 查当前最大 n，新文件 `n_max + 1`
141   -3. **Apply 方式**：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖）。`scripts/setup-test-db.sh` 只负责清空库，不做 apply
  136 +3. **Apply 方式**：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖）。`scripts/setup-test-db.mjs` 只负责清空库，不做 apply
142 137 4. **已合并的 migration 永不修改**：发现错了写一个补救 migration（如 `V7__fix_V5_index_name.sql`），旧 `V_n.sql`
143   -5. **临时调试 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.sh` 会 drop+create 清掉
  138 +5. **临时调试 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.mjs` 会 drop+create 清掉
144 139 6. **A4 生成的 V1**：`V1__initial_schema.sql` 是 A 阶段由 `db-init` 从 `docs/03-数据库设计文档.md`（A3 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由 B 阶段每个 REQ 按需写入，**同时**反向同步更新 docs/03 对应表小节以保持 SSoT 一致
145 140  
146 141 ---
... ... @@ -184,9 +179,9 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
184 179  
185 180 **触发中断时的固定动作：**
186 181  
187   -1. 在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`（报告格式由 `interrupt-check` 的 `interrupt-block-template.md` 持有）
188   -2. 停止后续所有功能的静默执行
189   -3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复
  182 +1. `coding.mjs` 子代理在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`（记录原因 / 阻塞点），并 throw 进入 HALT 终止态
  183 +2. 整阶段 fail-fast：halt 后停止后续所有模块/功能的静默执行
  184 +3. Workflow 返回结构化诊断（halt 原因 + blocker 文件路径），等人修复后重跑 `/erp-workflow:coding-start` 从断点续跑
190 185  
191 186 ---
192 187  
... ... @@ -197,7 +192,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
197 192 | # | 软规则 | 允许动作 | 强制后续 |
198 193 | - | ----- | ------- | ------- |
199 194 | S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 |
200   -| S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | ① hook `log-cross-module.sh` 自动落存根 ② `module-report` 一次性调用 `cross-module-log` skill 批量补齐「原因 / 影响评估」+ 「跨模块改动」节完整贴入《模块完成报告》 |
  195 +| S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | `coding.mjs` 的 cross-module stage 在模块循环内记录改动并补「原因 / 影响评估」，「跨模块改动」节完整贴入《模块完成报告》 |
201 196  
202 197 ---
203 198  
... ...