朱子纯 / erp-workflow-plugin

Commit 63ff719dd6079528cae6479b0087b8c6476c2dd2

Authored by zichun
1 parent af69f223

feat: 引入前端整体阶段（FE skills + coding-start 阶段分发） 

后端模块全部 merged 后进入前端整体阶段（1 个 MR）。

- 入口：coding-start 由模块循环器升级为阶段分发器，按 docs/08 §二/§三 + GitLab state 路由到 module-start 或 frontend-start
- 前端 skill：新增 frontend-start + fe-feature-brainstorm/plan/tdd/verify/review 共 6 个 skill；fe-code-reviewer agent 做 7 维 review
- 前端门禁：prototype/ 至少 1 个 *.html mockup；FE 清单由 AI 扫 prototype + docs/01 + docs/05 自主推导写入 docs/08 §三，无人工审阅断点
- 后端 skill 阶段化：feature-brainstorm/plan/tdd 加「阶段范围（后端）」标记；feature-tdd 增 frontend/ 路径硬护栏；module-start/test-gate/module-report/mr-create 接受 phase 参数（backend/frontend）
- 模板同步：CLAUDE-template / docs-08-initial / docs-06-static / docs-02 / mr-description / coding-start banner 更新含前端段落
- README：21→27 skill / 1→2 agent / 35→44 模板；A5 章节 docs/06 §五 改为 §三
Inline Side-by-side
Showing 31 changed files with 1045 additions and 228 deletions
README.md
  View file @63ff719
... ... @@ -2,7 +2,7 @@
2 2  
3 3 Claude Code 插件：ERP / 后端管理系统全流程开发框架。
4 4  
5   -把"从零到 N 个模块上线"的整个流程固化成 **21 个 skill + 1 个 agent + 2 个 hook + 35 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、人工审核可控的前提下推进编码。
  5 +把"从零到 N 个模块上线 + 前端整体阶段"的整个流程固化成 **27 个 skill + 2 个 agent + 2 个 hook + 44 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、人工审核可控的前提下推进编码。后端按模块循环依次提交 MR，所有后端 merged 后进入前端整体阶段（以项目根 `prototype/` 静态 HTML mockup 为页面权威）。
6 6  
7 7 ## 这个插件做什么
8 8  
... ... @@ -19,13 +19,23 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。
19 19 ↓
20 20 A4 初始化 DB（docs/03 → V1 migration → 自动 apply 到本地 MySQL）
21 21 ↓
22   - A5 生成下游文档（docs/02 / docs/05 / docs/06 § 五 / docs/10）
  22 + A5 生成下游文档（docs/02 / docs/05 / docs/06 § 三 / docs/10）
23 23 ↓
24 24 用户显式 /erp-workflow:coding-start
25 25  
26   -🔁 阶段 B：编码（按模块循环，入口 /erp-workflow:coding-start）
27   - 功能循环：Brainstorm → Plan → TDD → Verify → Review
28   - 模块循环：本地测试闸门 → 写模块报告 → 创建 GitLab MR → ⏸ 用户 Approve+Merge → 下次 coding-start 自动扫描 MR 状态为 merged → 下一模块
  26 +🔁 阶段 B：编码（入口 /erp-workflow:coding-start）
  27 +
  28 + B-后端（按模块循环）
  29 + 功能循环：Brainstorm → Plan → TDD → Verify → Review
  30 + 模块循环：本地测试闸门 → 写模块报告 → 创建 GitLab MR → ⏸ 用户 Approve+Merge → 下次 coding-start 自动扫描 MR 状态为 merged → 下一模块
  31 +
  32 + ↓ 后端全部 merged 后
  33 +
  34 + B-前端（整体阶段，1 个 MR）
  35 + 入口门禁：检查项目根 prototype/ 至少含 1 个 *.html mockup（缺失则 AskUserQuestion 提示用户补齐）
  36 + FE 拆分：AI 自主推导功能清单（业务功能粒度，与 HTML 文件数无关）写入 docs/08 § 三；已有则加载——无人工审阅断点（人工只在 MR Approve+Merge 处介入）
  37 + FE 循环（每个 FE-NN）：fe-feature-brainstorm → -plan → -tdd → -verify → -review
  38 + 收尾：test-gate(phase=frontend) → module-report(phase=frontend) → mr-create（分支 frontend-phase）→ ⏸ 用户 Approve+Merge → 全部完成
29 39  
30 40 ⚙️ 后台守门：占位符未填 / 中断触发 / 跨模块改动未记录
31 41 ```
... ... @@ -52,22 +62,33 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。
52 62  
53 63 > 两个审阅断点的处理方式一致：A1 / A3 完成时 skill 已自动勾选 `docs/08-模块任务管理.md § 一` 该阶段的全部子项 + 顶层；审阅是隐式的——你看完 REQ 卡片 / docs/03 后直接重新运行 `/plan-start`，下次入口就会派发到下一阶段。如果审阅时发现需要修订，直接编辑 docs/01 / docs/03 即可，不依赖 docs/08 的勾选状态。
54 64  
55   -3. **Coding 阶段入口**（模块循环）：
  65 +3. **Coding 阶段入口**（后端模块循环 → 前端整体阶段）：
56 66 ```
57 67 /erp-workflow:coding-start
58 68 ```
59   - Plan 全部完成后由你显式触发。**按 `docs/02 § 二` REQ 开发顺序清单**扫描，决定当前模块：
60   - 对每个 REQ 所属模块查询 `docs/08` 的 `MR:` 字段，必要时调 GitLab API 取 `state`：
61   - - `MR: —` → 该模块是当前模块（未建过 MR）
62   - - `MR: !<iid>` 且 API `state == merged` → 模块已完成，跳过
63   - - `MR: !<iid>` 且 API `state ∈ {opened, closed}` → 该模块是当前模块
64   - - `MR: !<iid>` 但 API HTTP 非 200 / 查不到 / state 非法 → **停下报错**让用户排查 token / API URL / project ID / iid（绝不静默假设未 merged）
  69 + Plan 全部完成后由你显式触发。`coding-start` 是阶段分发权威——每次入口都重新扫描 docs/08 § 二/§ 三 + GitLab API state，按当前进度决定派发：
  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` | 打印"所有阶段已完成"，停下 |
65 78  
66   - 之后**自动探测远程默认分支** → `git checkout <默认分支>` + `git pull --ff-only` 同步远程 → 派发到 `module-start`。
  79 + GitLab API HTTP 非 200 / 查不到 / state 非法 → 停下报错（绝不静默假设未 merged）。
67 80  
68   - **`docs/08 § 二` 每模块占一行 bullet**，完成信号由 MR merged state 判定；即使用户提前触发 coding-start，未 merged 的模块仍会被选中，不会跳过。
  81 + **后端阶段（module-start 内，单一职责）**：
  82 + - 切到 `module-<id>` 分支，跑功能循环（feature-brainstorm → ... → feature-review）→ 全 approve → test-gate → module-report → mr-create → ⏸ 人工 Approve+Merge → 用户重跑 coding-start，coding-start 再次路由
69 83  
70   -4. **中途恢复**：任何时候运行对应入口命令——根据 Plan § 一 checkbox 和 § 二 各模块 MR state 跳到当前该做的事。
  84 + **前端阶段（frontend-start 内，自带前置门禁）**：
  85 + - 步骤 1：prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion 提示用户补齐 → 停下）
  86 + - 步骤 2：准备 FE 清单（无审阅断点）。§ 三 占位则 AI 扫 prototype + docs/01 + docs/05 自主推导 FE 业务功能清单写入 § 三（每个 FE 标注关联 REQ + 关联原型；FE 数与 HTML 文件数无关）；§ 三 已有则直接加载
  87 + - 步骤 4-8：MR state 判定 → 切 `frontend-phase` 分支 → 跑 fe-feature 循环（fe-feature-brainstorm → ... → fe-feature-review，专用 `fe-code-reviewer` agent 做 7 维 review）→ 全 approve → test-gate(frontend) → module-report(frontend) → mr-create（docs/08 § 三 整体 MR）→ ⏸ 人工 Approve+Merge
  88 +
  89 + `docs/08 § 二` 每后端模块占一行 bullet，`§ 三` 是前端阶段整体段，完成信号统一由 MR merged state 判定。
  90 +
  91 +4. **中途恢复**：任何时候运行对应入口命令——根据 Plan § 一 checkbox、§ 二 各后端模块 MR state、§ 三 前端整体 MR state 跳到当前该做的事。
71 92  
72 93 ## 目录结构
73 94  
... ... @@ -80,10 +101,11 @@ erp-workflow-plugin/
80 101 │ ├── hooks.json # hook 注册表（2 个 hook）
81 102 │ └── scripts/*.sh # 2 个 hook 脚本
82 103 ├── agents/
83   -│ └── superpower-code-reviewer.md # code-reviewer agent（feature-review 调用）
  104 +│ ├── superpower-code-reviewer.md # 后端 code-reviewer agent（feature-review 调用）
  105 +│ └── fe-code-reviewer.md # 前端专用 reviewer（fe-feature-review 调用，硬编码 7 维 review）
84 106 └── skills/
85 107 ├── plan/ # 阶段 A：6 个一次性规划 skill
86   - ├── coding/ # 阶段 B：9 个模块/功能循环 skill
  108 + ├── coding/ # 阶段 B：15 个 skill = 9 个后端模块/功能循环 + frontend-start + 5 个 fe-feature-*
87 109 ├── crosscut/ # 横切：2 个入口 + 1 中断守门 + 1 留痕 skill
88 110 └── internal/ # superpowers 本地 fork：2 个无门 brainstorming / writing-plans
89 111 ```
... ... @@ -95,7 +117,7 @@ erp-workflow-plugin/
95 117 | 拒绝 no-verify | `deny-no-verify.sh` | PreToolUse / Bash | CC 尝试 `git push --no-verify` | 硬拦截，强制 `.githooks/pre-push` 生效 |
96 118 | 跨模块改动留痕 | `log-cross-module.sh` | PostToolUse / Edit \| Write | 当前处于 `module-*` 分支 且 编辑目标路径落在 `docs/08 § 二` 中**非当前模块**的 path 范围内（无论目标模块 MR 是否已 merged） | 把改动追加为 `TBD(CC 补)` 存根到 `<current_module>-cross-module.md`；通过 `additionalContext` 软提示 CC 调 `cross-module-log` skill **自主推断**补「原因 / 影响评估」两列。即时性由 CC 自己决定；**最迟在 `module-report` § ⑦ 硬闸门处**（TBD 未清空会阻断模块完成报告），保证模块完成前所有 TBD 必被 CC 填实 |
97 119  
98   -## Skill 清单（21 个）
  120 +## Skill 清单（27 个）
99 121  
100 122 ### Plan 阶段（6 个，`skills/plan/`）
101 123  
... ... @@ -106,59 +128,102 @@ erp-workflow-plugin/
106 128 | A2 | `skeleton-gen` | • 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09<br>• 生成工具脚本：scripts/*.sh、.githooks/pre-push、.env.local<br>• 创建 `sql/migrations/` 空目录（Flyway 准备）<br>• 合并 .gitignore（逐行判重） | `plan-start` |
107 129 | A3 | `db-design-gen` | • 从 docs/01 REQ 卡片正向设计 `docs/03-数据库设计文档.md`（schema SSoT）<br>• 回填 REQ 卡片依赖表（`TBD(A3 自动补)` → 实际表名）<br>• **停下**等人工审阅 docs/03，审阅完毕用 `/plan-start` 恢复续进 A4 | A2 |
108 130 | 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 |
109   -| 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 +| 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 |
110 132  
111   -### Coding 阶段（9 个，`skills/coding/`）
  133 +### Coding 阶段（15 个，`skills/coding/`）
112 134  
113 135 **触发与顺序**（`coding-start` 是唯一由用户手动触发的入口，下面所有 skill 都由 skill 链自动调用）：
114 136  
115 137 ```
116   -/erp-workflow:coding-start ← 用户每次手动触发
  138 +/erp-workflow:coding-start ← 用户每次手动触发；阶段分发器（只做分发）
  139 + │
  140 + │ ① Plan 完成校验（docs/08 § 一 A0~A5）
  141 + │ ② 后端完成性检查（§ 二 + GitLab state）
  142 + │ ├ 未完成 → 立即派发 module-start，结束
  143 + │ └ 已完成 → 继续 ③
  144 + │ ③ 前端完成性检查（§ 三 整体 MR + state）
  145 + │ ├ 已完成 → 打印"所有阶段已完成"，结束
  146 + │ └ 未完成 → 派发 frontend-start，结束
  147 + │
  148 + ├─ 后端未完成 → 派发 module-start（写后端）
  149 + │ │
  150 + │ │ 切 module-<id> 分支，对每个未完成 REQ：
  151 + │ │ feature-brainstorm → -plan → -tdd → -verify → -review
  152 + │ │
  153 + │ │ review approve → 回 module-start（下一 REQ）
  154 + │ │ request-changes (<5) → fix → 回 feature-verify
  155 + │ │ request-changes (=5) → 停下（升级给人）
  156 + │ │
  157 + │ │ 本模块所有 REQ approve：
  158 + │ │ test-gate(phase=backend) → module-report → mr-create
  159 + │ │ （docs/08 § 二 写 MR iid）
  160 + │ │
  161 + │ └─ ⏸ 停下等人工 Approve + Merge
  162 + │ （合并后用户重跑 coding-start → coding-start 再次路由）
117 163 │
118   - │ 扫描 docs/02 REQ 序 + docs/08 MR 字段 + GitLab API state 判定当前模块：
119   - │ - 所有模块都 merged → 打印"所有模块已完成"
120   - │ - 找到第一个非 merged 模块 → 派发
121   - │ 派发前自动探测远程默认分支（main / master），git checkout + git pull --ff-only 同步远程 base
  164 + ├─ 后端完成 & 前端完成 → 打印"所有阶段已完成"，停下
122 165 │
123   - └─→ module-start（幂等可重入，切 module-<id> 分支）
124   - │
125   - │ 对每个未完成 REQ，按序串链：
126   - │ feature-brainstorm → -plan → -tdd → -verify → -review
127   - │
128   - │ review approve → 回 module-start（推进下一 REQ）
129   - │ review request-changes (<5) → fix commit → 回 feature-verify 重新执行
130   - │ review request-changes (=5) → 停下（升级给人）
131   - │
132   - │ 模块全部 REQ approve →
133   - │ test-gate（commit test-gate.md）
134   - │ → module-report（commit 模块报告 + cross-module log）
135   - │ → mr-create（worktree clean 校验 → push 代码+evidence → 创建 MR
136   - │ → 追 MR URL 到报告 + commit → 写 MR iid 到 docs/08 + commit
137   - │ → 再 push）
138   - │
139   - └─ ⏸ 停下等人工 Approve + Merge
140   - （人工合并后再次运行 coding-start，扫描到 state=merged 自动跳过
141   - → pull 默认分支 → 推进下一模块）
  166 + └─ 后端完成 & 前端未完成 → 派发 frontend-start（写前端）
  167 + │
  168 + │ frontend-start 自带前置门禁（coding-start 不做）：
  169 + │ ① prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion）
  170 + │ ② 准备 FE 清单（无审阅断点）：
  171 + │ § 三 已有 FE bullet → 加载
  172 + │ § 三 仅占位 → AI 推导写入
  173 + │ ③ 切 frontend-phase 分支
  174 + │
  175 + │
  176 + │ 准备 FE 清单（无审阅断点）：
  177 + │ § 三 占位 → 扫 prototype + docs/01 + docs/05
  178 + │ → AI 自主推导 FE 业务功能清单写入 § 三
  179 + │ （含 fe_id / 功能名 / 关联 REQ / 关联原型）
  180 + │ § 三 已有 FE bullet → 直接加载
  181 + │
  182 + │ 切 frontend-phase 分支
  183 + │ FE 是业务功能粒度（与 HTML 文件数无关，
  184 + │ 一个 HTML 可拆多个 FE / 多 HTML 可合一个 FE）
  185 + │
  186 + │ 对每个未完成 FE：
  187 + │ fe-feature-brainstorm → -plan → -tdd → -verify → -review
  188 + │ （review 委托 fe-code-reviewer agent，硬编码 7 维 checklist）
  189 + │
  190 + │ review approve → 回 frontend-start（下一 FE）
  191 + │ request-changes (<5) → fix → 回 fe-feature-verify
  192 + │ request-changes (=5) → 停下
  193 + │
  194 + │ 全部 FE approve：
  195 + │ test-gate(phase=frontend)（vitest + playwright，子会话跑）
  196 + │ → module-report(phase=frontend)
  197 + │ → mr-create（docs/08 § 三 整体 MR）
  198 + │
  199 + └─ ⏸ 停下等人工 Approve + Merge
  200 + （合并后再跑 coding-start → "所有阶段已完成"）
142 201 ```
143 202  
144 203 | Skill | 做什么 | 谁触发它 |
145 204 |---|---|---|
146   -| `module-start` | 定位当前模块（docs/02 REQ 序）+ 切换或创建 `module-<id>` 分支 + 扫描 `docs/superpowers/reviews/*.md` 的 `verdict=approve` 计算已完成 REQ + 推进第一个未完成 REQ 的功能循环。全部完成 → `test-gate`。**幂等可重入**（中途断开后重新运行会自动跳过已 approve 的 REQ） | `coding-start` 派发；`feature-review` approve 后回调 |
  205 +| `module-start` | **后端模块循环单一职责**（不感知前端阶段）。切 `module-<id>` 分支，扫 `docs/superpowers/reviews/*.md` 的 `verdict=approve` 计算已完成 REQ，推进第一个未完成 REQ；本模块全 approve → `test-gate`。**幂等可重入** | `coding-start` 派发（仅当后端有未 merged 模块时）；`feature-review` approve 后回调 |
147 206 | `feature-brainstorm` | 功能循环步骤 1：交互 brainstorm → 生成 `docs/superpowers/specs/*.md` | `module-start` 推进 REQ 时调用 |
148 207 | `feature-plan` | 功能循环步骤 2：spec → 任务级 plan（文件路径 + API 签名 + 测试意图 + 完成判据，代码由 TDD 阶段产出），输出 `docs/superpowers/plans/*.md` | `feature-brainstorm` 链式调用 |
149   -| `feature-tdd` | 功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 `module-<id>` 分支） | `feature-plan` 链式调用 |
  208 +| `feature-tdd` | 功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 `module-<id>` 分支）；路径硬护栏：`impl_file` 落 `frontend/` 前缀 → 硬停（UI 推迟到前端阶段） | `feature-plan` 链式调用 |
150 209 | `feature-verify` | 功能循环步骤 4：将全量测试派发到子会话执行一次，用模板渲染 evidence | `feature-tdd` 链式调用；`feature-review` 在 request-changes 修复后重新调用 |
151 210 | `feature-review` | 功能循环步骤 5：AI 自审，写 `docs/superpowers/reviews/*.md`。approve → 回 `module-start`；request-changes → 逐项 Edit + fix commit → 回 `feature-verify` 重新执行（最多 5 轮，第 5 轮仍 request-changes 则停下） | `feature-verify` 链式调用 |
152   -| `test-gate` | MR 前硬闸门：子会话执行 `scripts/test.sh`（脚本内部 drop+create 空库、Flyway apply `sql/migrations/V*.sql`、再执行测试）；通过 → 写 `<module_id>-test-gate.md` 并 `git add + commit`（evidence 提交到 module 分支）；失败停下 | `module-start` 在本模块所有 REQ approve 后调用 |
153   -| `module-report` | 中断检查 → 生成 12 节模块完成报告 `docs/superpowers/module-reports/<date>-<module_id>.md` → `git add + commit`（报告 + cross-module log 提交到 module 分支，mr-create 的 worktree clean 前置条件依赖此步） | `test-gate` 链式调用 |
154   -| `mr-create` | 中断检查 → 验证当前分支 = `module-<id>` 且 `git status --porcelain` worktree 干净 → `git push` 推代码与全部 evidence → 用 curl 调 GitLab REST API 创建 MR（模块报告嵌入 MR 描述）→ 追加 MR URL 到报告并 commit → 把 docs/08 该模块的 `MR: —` 回写为 `MR: !<iid>` 并 commit → 再次 push；**停下等人工 Approve+Merge**。完成由 MR state 判定 | `module-report` 链式调用 |
  211 +| `test-gate` | MR 前硬闸门。按当前分支推 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 后） |
  212 +| `module-report` | 中断检查 → 生成 12 节完成报告 `docs/superpowers/module-reports/<date>-<phase_id>.md`（前端阶段 § ④/§ ⑥ 写 N/A）→ commit 到当前分支（后端：module-* 分支；前端：frontend-phase 分支） | `test-gate` 链式调用 |
  213 +| `mr-create` | 中断检查 → 验证当前分支 = `module-<id>` 或 `frontend-phase` 且 `git status --porcelain` worktree 干净 → `git push` 推代码与全部 evidence → 用 curl 调 GitLab REST API 创建 MR（完成报告嵌入 MR 描述）→ 追加 MR URL 到报告并 commit → 把 docs/08 § 二 该模块的 `MR: —`（后端） / § 三 `整体 MR: —`（前端） 回写为 `!<iid>` 并 commit → 再次 push；**停下等人工 Approve+Merge**。完成由 MR state 判定 | `module-report` 链式调用 |
  214 +| `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 后回调 |
  215 +| `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[] }` |
  216 +| `fe-feature-plan` | 前端功能循环步骤 2：spec → 任务级计划（组件/路由/hook/API client，`impl_file` 必须 `frontend/` 前缀） | `fe-feature-brainstorm` 链式调用 |
  217 +| `fe-feature-tdd` | 前端功能循环步骤 3：jsdom 组件测试 + Playwright E2E（E2E 派子会话）；commit trailer `REQ_ID: FE-NN`；路径硬护栏 `frontend/` | `fe-feature-plan` 链式调用 |
  218 +| `fe-feature-verify` | 前端功能循环步骤 4：派子会话跑 vitest + playwright，按模板渲染证据 | `fe-feature-tdd` 链式调用；`fe-feature-review` request-changes 修复后重调 |
  219 +| `fe-feature-review` | 前端功能循环步骤 5：委托 `fe-code-reviewer` agent 做 7 维 review。approve → 回 `frontend-start`；request-changes 5 轮上限 | `fe-feature-verify` 链式调用 |
155 220  
156 221 ### Crosscut（4 个，`skills/crosscut/`）
157 222  
158 223 | Skill | 作用 | 流程中谁调用 |
159 224 |---|---|---|
160 225 | `plan-start` | **A 阶段入口**。读取 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:plan-start` |
161   -| `coding-start` | **B 阶段入口**。先验证 Plan 已完成；**按 `docs/02 § 二` REQ 序扫描**，对每个 REQ 所属模块查询 `MR:` 字段 + GitLab API `state`：`merged` 跳过；`—`/opened/closed 选为当前模块；查不到则停下报错。派发前自动探测远程默认分支（main / master），`git checkout + git pull --ff-only` 同步远程 base，然后调用 `module-start` | **用户手动**运行 `/erp-workflow:coding-start` |
  226 +| `coding-start` | **B 阶段入口 + 阶段分发器（只做分发）**。① 验证 Plan 已完成（docs/08 § 一 A0~A5 全勾选）② 后端完成性检查（§ 二 + GitLab state）③ 前端完成性检查（§ 三 整体 MR）④ 真值表派发：`backend=false` → `module-start`；`backend=true & frontend=false` → `frontend-start`；都 done → "全部完成"。前端阶段的 prototype/ 门禁由 `frontend-start` 自带，不在此处 | **用户手动**运行 `/erp-workflow:coding-start` |
162 227 | `interrupt-check` | 检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
163 228 | `cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根批量补「原因 / 影响评估」 | `module-report` § ⑦ 硬验收时一次性调用（CC 编辑中途不主动调）；`module-start` 初始化日志文件时也会用其模板 |
164 229  
... ... @@ -171,11 +236,12 @@ erp-workflow-plugin/
171 236 | `superpower-brainstorming` | `superpowers:brainstorming` 5.0.7 | `<HARD-GATE>` 整块、Anti-Pattern 段、Checklist 里 Visual Companion / approve-design / review-spec 三项、User Review Gate、Visual Companion 整节、终点 `invoke writing-plans` |
172 237 | `superpower-writing-plans` | `superpowers:writing-plans` 5.0.7 | Execution Handoff 整节（"Which approach?" 问询）、"Complete code in every step" 硬要求（改为"API 签名 + 测试意图"粒度，完整代码留给 TDD） |
173 238  
174   -## Agent 清单（1 个）
  239 +## Agent 清单（2 个）
175 240  
176 241 | Agent | 源 | 用途 | 谁调用 |
177 242 |---|---|---|---|
178   -| `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)` |
  243 +| `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)` |
  244 +| `fe-code-reviewer` | 自写（前端专用） | 对前端 FE-NN diff 做 7 维 AI 自审：prototype 一致性 / Design Tokens / 无障碍 / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖。明确禁止给后端建议 | `fe-feature-review` 步骤 1：`Agent(subagent_type=fe-code-reviewer)` |
179 245  
180 246 ## Banners 清单（7 份，`bash cat` 直接输出，绕开 LLM 复读）
181 247  
... ... @@ -193,7 +259,7 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
193 259  
194 260 **字节对齐保证**:每个文件 17 行,每行 visible width = 58 cell(内宽 56 + 2 个 `│` 边框)。改动需重新校准。
195 261  
196   -## Templates 清单（37 份）
  262 +## Templates 清单（44 份）
197 263  
198 264 | 所属 Skill | 模板文件 | 用途 |
199 265 |---|---|---|
... ... @@ -204,7 +270,7 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
204 270 | scope-lock | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片骨架（6 个 `{{...}}` 占位符由 CC 替换；输入 / 输出 各含一句简述 + N 张示例字段表，模板原样复制由人工编辑） |
205 271 | scope-lock | `_module-template.md` | 模块子目录的 `_module.md` 模块头（4 行：模块代码-名 / 简述 / 依赖模块 TBD / 涉及表 TBD） |
206 272 | skeleton-gen | `docs-04-skeleton-template.md` | docs/04 § 一+ 编码规范大纲（HTML 注释引导 LLM） |
207   -| skeleton-gen | `docs-06-static-template.md` | docs/06 § 一~四 UI 模式大纲 |
  273 +| skeleton-gen | `docs-06-static-template.md` | docs/06 § 一~二 大纲（通用交互 + Design Tokens；布局以 prototype/ 为权威） |
208 274 | skeleton-gen | `docs-07-env-template.md` | docs/07 环境配置大纲 |
209 275 | skeleton-gen | `docs-09-structure-template.md` | docs/09 目录结构大纲 |
210 276 | skeleton-gen | `scripts-setup-test-db-template.sh` | 运行时 drop + create 空库脚本（0 槽位）；schema apply 交给 Flyway |
... ... @@ -217,7 +283,7 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
217 283 | downstream-gen | `docs-02-template.md` | docs/02 开发计划 |
218 284 | downstream-gen | `docs-05-header-template.md` | docs/05 API 契约头部 |
219 285 | downstream-gen | `docs-05-endpoint-template.md` | docs/05 单接口小节 |
220   -| downstream-gen | `docs-06-module-pagelist-template.md` | docs/06 § 五 单模块页面清单 |
  286 +| downstream-gen | `docs-06-module-pagelist-template.md` | docs/06 § 三 单模块页面清单 |
221 287 | downstream-gen | `docs-08-module-row-template.md` | docs/08 § 二 单模块 bullet 行 |
222 288 | downstream-gen | `docs-10-header-template.md` | docs/10 验收清单（项目级 SOP，零槽位 + 引用指针） |
223 289 | module-start | `module-start-banner-template.md` | 模块启动横幅 |
... ... @@ -233,6 +299,13 @@ step 0 流程图被抽到独立 `.txt` 文件,SKILL.md 步骤 0 改为 `bash cat
233 299 | interrupt-check | `interrupt-block-template.md` | Blocker 节追加模板 |
234 300 | cross-module-log | `cross-module-log-template.md` | cross-module 日志头（由 hook log-cross-module.sh 在首次跨模块改动时渲染创建；skill 自身不再读取） |
235 301 | cross-module-log | `cross-module-log-row-template.md` | 单条改动行模板 |
  302 +| frontend-start | `frontend-start-banner-template.md` | 前端阶段启动横幅 |
  303 +| fe-feature-brainstorm | `fe-feature-spec-template.md` | 前端功能规格结构（组件树 / 状态机 / API / 业务校验复刻 / token 引用） |
  304 +| fe-feature-plan | `fe-feature-plan-template.md` | 前端功能计划结构（组件 / 路由 / hook / API client，`impl_file` 必须 `frontend/`） |
  305 +| fe-feature-tdd | `commit-message-template.md` | 前端 TDD commit 信息（与后端共用格式，但 `req_id` = FE-NN） |
  306 +| fe-feature-verify | `fe-feature-verify-evidence-template.md` | 前端验证证据（vitest + playwright 双段） |
  307 +| fe-feature-review | `fe-feature-review-template.md` | 前端自审报告结构（含 7 维核查表） |
  308 +| fe-feature-review | `commit-message-template.md` | 前端 review fix commit 信息 |
236 309  
237 310 **流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。
238 311  
... ...
agents/fe-code-reviewer.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-code-reviewer
  3 +description: |
  4 + Use this agent when fe-feature-review delegates a frontend code review for a single FE-NN business feature (which may span multiple prototype HTML files / regions). Specializes in React/Vue components, styling, accessibility, prototype fidelity, and Design Tokens. Does NOT review SQL/migration/controller/service — those are the backend reviewer's domain.
  5 +model: inherit
  6 +---
  7 +
  8 +You are a Senior Frontend Code Reviewer with deep expertise in component architecture, accessibility, design systems, and visual fidelity to design mockups. Your role is to review frontend code changes for a single FE-NN business feature (which may span multiple prototype HTML files or regions) against its associated prototypes, specification, and the project's design tokens.
  9 +
  10 +**Strict scope rules**:
  11 +
  12 +- Review ONLY frontend code (under `frontend/` or the project's frontend root per `docs/09-项目目录结构.md`).
  13 +- Do NOT propose SQL, migration, controller, service, repository, transaction, or DTO suggestions. If the diff contains backend files, flag this as a path violation and return `request-changes` with a single must-fix entry pointing the reviewee back to `feature-tdd` (backend phase).
  14 +- Do NOT recommend backend architectural changes; the backend phase is already merged.
  15 +
  16 +When reviewing, you will evaluate the following 7 dimensions in order. For each dimension, classify findings as Critical (must fix) / Important (should fix) / Suggestions (nice to have).
  17 +
  18 +## 1. Prototype 一致性
  19 +
  20 +- Compare the rendered DOM structure (inferred from JSX/template) against the FE's `associated_prototypes` (listed in the spec header). One FE may span multiple prototype files or specific regions (anchored like `prototype/dashboard.html#metrics-section`).
  21 +- For each associated prototype / region, check: top navigation placement, grid columns, primary action button position, key region layout (header / filters / table / pagination).
  22 +- Allowed: implementation differences (class naming, component library syntax, framework idioms).
  23 +- Not allowed: structural deviation (e.g., moving the primary action from top-right to bottom-center, dropping a filter region the prototype shows).
  24 +
  25 +## 2. Design Tokens
  26 +
  27 +- All color values MUST use `var(--color-*)` per `docs/06 § 二`.
  28 +- Hard-coded hex / rgb values → `request-changes` with file:line.
  29 +- New tokens introduced in code without registration in `docs/06 § 二` and `tokens.css` → `request-changes`.
  30 +
  31 +## 3. 无障碍 (Accessibility)
  32 +
  33 +- Form controls have `<label>` or `aria-label`.
  34 +- Interactive elements are keyboard reachable (correct tab order, Enter/Space triggers).
  35 +- Dangerous operations (delete / irreversible) have a confirmation dialog.
  36 +- Sufficient color contrast for text (best-effort; flag obvious failures).
  37 +
  38 +## 4. 响应式 (Responsive)
  39 +
  40 +- At the minimum resolution declared in `docs/06 § 一通用交互规则`, no horizontal scrollbar.
  41 +- Critical operations do not depend on hover-only interactions (must work on touch).
  42 +
  43 +## 5. 业务校验前端复刻
  44 +
  45 +- Cross-reference the spec's "业务规则前端复刻" section.
  46 +- Each business rule listed in the spec must be implemented as form-level validation (not only relying on backend errors).
  47 +- Error messages must match backend semantics or convey equivalent meaning.
  48 +
  49 +## 6. API 调用一致性
  50 +
  51 +- Endpoints and request/response field names must match `docs/05-API接口契约.md`.
  52 +- API calls must go through the project's unified API client; raw `fetch` / `axios` with hand-built URLs → `request-changes`.
  53 +
  54 +## 7. 状态机覆盖
  55 +
  56 +- The 5 states from the spec (loading / empty / error / 正常 / 提交中) must each be handled in code.
  57 +- Missing state handling → `request-changes` for the specific state.
  58 +
  59 +## Output format
  60 +
  61 +Return a structured review with:
  62 +
  63 +- `verdict`: `approve` or `request-changes`
  64 +- `must_fix[]`: each item with `severity` (critical/important), `file`, `line`, `issue`, `suggestion`
  65 +- `nice_to_have[]`: lighter suggestions
  66 +- `dimensions{}`: per-dimension status (`pass` / `fail`) and brief notes for the 7 dimensions
  67 +- `gaps`: test coverage or scope gaps
  68 +
  69 +Be thorough but actionable. Always explain WHY a finding matters (e.g., "hard-coded hex breaks the token rotation in dark mode"). When you approve, briefly acknowledge what was done well before closing.
... ...
skills/coding/fe-feature-brainstorm/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-feature-brainstorm
  3 +description: 前端功能循环第 1 步。针对单个 FE-NN 页面（prototype/*.html）做交互式头脑风暴，产出前端功能规格到 docs/superpowers/specs/。
  4 +user-invocable: false
  5 +allowed-tools: Read Write Skill Glob Grep
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# fe-feature-brainstorm
  11 +
  12 +## 阶段范围（前端）
  13 +
  14 +本 skill 服务于**前端阶段**。产出范围限定为：组件树 / 页面状态机 / 交互流程 / API 调用 / Design Tokens 引用 / 业务校验前端复刻。**不涉及** SQL / migration / controller / service / DTO（这些已在后端阶段完成）。
  15 +
  16 +一个 FE 是**业务功能**粒度，可能关联多个 prototype 文件区域和多个 REQ。
  17 +
  18 +## 执行步骤
  19 +
  20 +1. 确定本次 FE 上下文（由 `frontend-start` 派发时传入 `{ fe_id, name, associated_reqs[], associated_prototypes[] }`），收集证据：
  21 + - **页面骨架**：Read 所有 `associated_prototypes[]`（如 `prototype/dashboard.html` + `prototype/dashboard.html#metrics-section`；含 anchor 时聚焦相应区域），作为本 FE 涉及页面的布局权威
  22 + - **业务规则**：Read 所有 `associated_reqs[]` 对应的 `docs/01-需求清单/<module>/<REQ-id>.md`，提取业务校验规则、acceptance、UI 描述
  23 + - **API 契约**：Read `docs/05-API接口契约.md`，按 `associated_reqs[]` 过滤出本 FE 消费的端点
  24 + - **Design Tokens**：Read `docs/06-UI交互规范.md § 二`，作为色值/状态色的引用源
  25 + - **前端组件库**：Read `docs/04-技术规范.md § 零` 找 `frontend.ui_lib`（如 Ant Design / Element Plus），决定组件选型
  26 +
  27 +2. 委托 `superpowers:brainstorming`，把上述上下文 + 落盘路径 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md` 作为 caller-provided path 传入。caller-provided 上下文显式标注：
  28 +
  29 + > 本次为前端阶段头脑风暴。关注组件树、页面状态机、交互流程、API 调用一致性、Design Tokens 引用、业务校验前端复刻。**不要**讨论 SQL / migration / controller / service / DTO。本 FE 关联的 REQ 与原型清单见上下文中 `associated_reqs` / `associated_prototypes`。
  30 +
  31 + 文件已存在 → 征求用户确认后覆盖。
  32 +
  33 +3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md` 渲染头脑风暴输出，写入推导路径。规格至少含：
  34 + - 关联 REQ + 关联原型（来自 frontend-start 派发的入参）
  35 + - 组件树（多个 prototype 文件 / 区域则按页面分块；推导自 prototype DOM）
  36 + - 页面状态机（loading / empty / error / 正常 / 表单提交中 至少 5 态；多页则按页列出）
  37 + - 消费的后端端点（与 docs/05 对齐，按本 FE 的 `associated_reqs[]` 过滤）
  38 + - 业务规则前端复刻清单（逐条，每条标注：规则描述 / 触发时机 / 报错文案 / 来源 REQ）
  39 + - Design Tokens 引用清单（本 FE 用到的 var(--color-*) 名称）
  40 +
  41 +4. **验证**：所有顶级节非空；**全文不得出现** `TBD`、`@todo`、`controller`、`SQL`、`service`、`migration` 字样——前者代表 spec 未完成，后五者属于后端范畴不应出现。命中 → 修正后重渲染。
  42 +
  43 +5. 输出 `fe-feature-brainstorm: <fe_id> → <path>`，立即调用 `Skill(fe-feature-plan)`。
  44 +
  45 +## 参考
  46 +
  47 +- `${CLAUDE_SKILL_DIR}/templates/fe-feature-spec-template.md`
  48 +- 委托：`superpowers:brainstorming`（本插件 `skills/internal/superpower-brainstorming/`）
  49 +- 上游：`frontend-start`（每个未完成 FE 派发到此）
  50 +- 下游：`fe-feature-plan`
... ...
skills/coding/fe-feature-brainstorm/templates/fe-feature-spec-template.md 0 → 100644
  View file @63ff719
  1 +# 前端功能规格 — {{fe_id}} {{name}}
  2 +
  3 +> 关联 REQ：{{associated_reqs}}
  4 +> 关联原型：{{associated_prototypes}}
  5 +> 日期：{{date}}
  6 +
  7 +## 一、功能概述
  8 +
  9 +{{feature_overview}}
  10 +
  11 +## 二、组件树
  12 +
  13 +<!-- 基于关联原型的 DOM 结构推导。多页则按页面分块；每层缩进表示嵌套关系。 -->
  14 +
  15 +```
  16 +{{component_tree}}
  17 +```
  18 +
  19 +## 三、页面状态机
  20 +
  21 +| # | 状态 | 触发条件 | 视觉表现 | 用户可执行操作 |
  22 +|---|------|---------|---------|--------------|
  23 +{{state_machine_rows}}
  24 +
  25 +至少包含：loading / empty / error / 正常 / 提交中 五态。
  26 +
  27 +## 四、消费的后端端点
  28 +
  29 +| # | 方法 | 路径 | 触发时机 | 关联 REQ |
  30 +|---|------|------|---------|---------|
  31 +{{endpoint_rows}}
  32 +
  33 +## 五、业务规则前端复刻清单
  34 +
  35 +| # | 规则描述 | 触发时机 | 报错文案 | 来源 REQ |
  36 +|---|---------|---------|---------|---------|
  37 +{{validation_rows}}
  38 +
  39 +> **要求**：每条规则必须在前端 form-level 校验中复刻，不仅依赖后端报错。文案与后端语义一致。
  40 +
  41 +## 六、Design Tokens 引用清单
  42 +
  43 +<!-- 列出本页面用到的 token 变量名（不写 hex），如 var(--color-primary) / var(--color-bg-card)。来源见 docs/06 § 二。 -->
  44 +
  45 +```
  46 +{{token_list}}
  47 +```
  48 +
  49 +## 七、交互流程关键路径
  50 +
  51 +{{interaction_flow}}
  52 +
  53 +## 八、备注与开放问题
  54 +
  55 +{{open_questions}}
... ...
skills/coding/fe-feature-plan/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-feature-plan
  3 +description: 前端功能循环第 2 步。将 FE 规格转化为任务级实现计划（每任务 2-5 分钟，含组件路径、props 契约、测试意图），输出到 docs/superpowers/plans/。
  4 +user-invocable: false
  5 +allowed-tools: Read Write Grep Skill
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# fe-feature-plan
  11 +
  12 +## 阶段范围（前端）
  13 +
  14 +把当前 FE 的规格转成任务级实现计划，委托 `superpowers:writing-plans` 起草。任务粒度限定为：**组件文件 / 路由配置 / store hook / API client 包装函数**。**不允许**生成涉及后端文件（controller / service / repository / SQL）的任务。
  15 +
  16 +## 执行步骤
  17 +
  18 +1. 收集输入：
  19 + - 当前 FE 的规格文件 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md`（不存在则报错）
  20 + - `docs/04-技术规范.md § 一前端架构`（路由 / 状态库 / 组件目录约定 / 测试栈）
  21 + - `docs/09-项目目录结构.md § 前端目录结构`（文件落盘位置规范）
  22 + - 相关代码指针（待修改的现有前端文件，通过 grep 在 `frontend/` 下定位）
  23 +
  24 +2. 委托 `superpowers:writing-plans`，把上下文 + 落盘路径 `docs/superpowers/plans/<YYYY-MM-DD>-<fe_id>.md` 作为 caller-provided path 传入。caller-provided 上下文显式标注：
  25 +
  26 + > 本次为前端阶段任务计划。任务粒度 = 组件 / 路由 / hook / API client。每个任务必须含：`test_file::test_name` + `impl_file` + 完成判据。`impl_file` 必须落在 `frontend/` 目录下（具体根路径见 docs/09 § 前端目录结构）。每个任务标注"测试先行类型" = jsdom 组件测试 OR Playwright E2E。
  27 +
  28 +3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` 渲染输出，写入推导路径。
  29 +
  30 +4. **验证**：
  31 + - 每个任务必须含 `test_file::test_name`、`impl_file`、完成标准
  32 + - **每个任务的 `impl_file` 路径必须以 `frontend/` 开头**（或 docs/09 声明的前端根目录），命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染
  33 + - 全文不得出现 `TBD` / `【人工填写：...】`——查不到值用 `AskUserQuestion` 问用户
  34 +
  35 +5. 输出 `fe-feature-plan: <fe_id> → <path>`，立即调用 `Skill(fe-feature-tdd)`。
  36 +
  37 +## 参考
  38 +
  39 +- `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md`
  40 +- 委托：`superpowers:writing-plans`（本插件 `skills/internal/superpower-writing-plans/`）
  41 +- 上游：`fe-feature-brainstorm`
  42 +- 下游：`fe-feature-tdd`
... ...
skills/coding/fe-feature-plan/templates/fe-feature-plan-template.md 0 → 100644
  View file @63ff719
  1 +# 前端功能计划 — {{fe_id}} {{name}}
  2 +
  3 +> 规格：docs/superpowers/specs/{{date}}-{{fe_id}}.md
  4 +> 关联原型：{{associated_prototypes}}
  5 +> 关联 REQ：{{associated_reqs}}
  6 +> 日期：{{date}}
  7 +
  8 +## 一、依赖与前置条件
  9 +
  10 +- 前置 FE：{{prerequisite_fes}}
  11 +- 共享组件：{{shared_components}}
  12 +- 路由配置文件：{{router_file}}
  13 +
  14 +## 二、任务清单
  15 +
  16 +每行一个任务，2-5 分钟可完成。`test_file::test_name` 先行写失败测试，`impl_file` 写最小实现使其通过。
  17 +
  18 +| # | 任务 | 测试先行类型 | test_file::test_name | impl_file | 完成判据 |
  19 +|---|------|-------------|---------------------|-----------|---------|
  20 +{{task_rows}}
  21 +
  22 +> **路径约束**：所有 `impl_file` 必须以 `frontend/`（或 docs/09 声明的前端根目录）开头。
  23 +> **测试先行类型**：`jsdom`（组件单测，vitest/jest）或 `e2e`（Playwright）。
  24 +
  25 +## 三、组件 props 契约
  26 +
  27 +| 组件 | props | 类型 | 必填 | 说明 |
  28 +|------|-------|------|------|------|
  29 +{{props_rows}}
  30 +
  31 +## 四、状态管理
  32 +
  33 +<!-- store hook 名 / 持有的 state 字段 / 暴露的 actions。如本 FE 不引入新 store，写"复用 <既有 store>"。 -->
  34 +
  35 +{{state_management}}
  36 +
  37 +## 五、API client 包装
  38 +
  39 +| 函数名 | HTTP 方法 | 路径 | 入参 | 返回 |
  40 +|--------|----------|------|------|------|
  41 +{{api_client_rows}}
  42 +
  43 +> 函数实现必须基于项目统一 API client（见 docs/04 § 一），不允许直接 `fetch` / `axios` 拼路径。
  44 +
  45 +## 六、风险与回退
  46 +
  47 +{{risks}}
... ...
skills/coding/fe-feature-review/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-feature-review
  3 +description: 前端功能循环第 5 步。AI 自审 FE 的 diff（专用前端 reviewer），approve 则回 frontend-start；request-changes 则自修复 + 重 verify，循环上限 5 轮。
  4 +user-invocable: false
  5 +allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *)
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# fe-feature-review
  11 +
  12 +委托 `fe-code-reviewer` agent（前端专用 reviewer，不复用 superpower-code-reviewer）对当前 FE 引入的代码改动做 AI 自审。`approve` 回 frontend-start 推进下一 FE；`request-changes` 自修复 must-fix 并重新 verify，最多 5 轮。
  13 +
  14 +## 执行步骤
  15 +
  16 +1. 派发 `Agent(subagent_type=fe-code-reviewer)`，把本 FE 引入的代码 diff、规格（`docs/superpowers/specs/<date>-<fe_id>.md`）、本 FE 关联的所有 prototype 文件（spec 顶部的 `关联原型` 列表）作为输入。
  17 +
  18 +2. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-review-template.md` 渲染审阅报告，写入 `docs/superpowers/reviews/<YYYY-MM-DD>-<fe_id>.md`。`verdict` 取 `approve` 或 `request-changes`。
  19 +
  20 +3. 按 `verdict` 分派：
  21 +
  22 + **approve**
  23 + - `Edit docs/08-模块任务管理.md § 三`，把本 FE 下 `- [ ] <fe_id> ...` 改为 `- [x] <fe_id> ...`（仅 FE 级可视化；前端阶段完成仍以 `整体 MR:` + GitLab API state 为准）
  24 + - 输出 `fe-feature-review: <fe_id> round <N> 通过`，调用 `Skill(frontend-start)` 推进下一 FE 或进入 test-gate(phase=frontend)
  25 +
  26 + **request-changes（round < 5）**
  27 + - 逐项编辑 `must_fix[]` 指向的代码文件
  28 + - 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit：`fix(<scope>): 修复 review round <N> must-fix REQ_ID: <fe_id>`
  29 + - 调用 `Skill(fe-feature-verify)` 重新验证；verify 通过后会再次链回本 skill，round `<N+1>` 重审
  30 +
  31 + **request-changes（round == 5）**
  32 + - 停止并打印摘要，升级给用户手工介入；不再自动修复，不回调 frontend-start
  33 +
  34 +## 参考
  35 +
  36 +- `${CLAUDE_SKILL_DIR}/templates/fe-feature-review-template.md`
  37 +- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md`
  38 +- 委托：`fe-code-reviewer` agent（本插件 `agents/fe-code-reviewer.md`，前端专用，硬编码 7 维 review checklist）
  39 +- 上游：`fe-feature-verify`
  40 +- 下游：`frontend-start`（approve）/ `fe-feature-verify`（request-changes 时重验）
... ...
skills/coding/fe-feature-review/templates/commit-message-template.md 0 → 100644
  View file @63ff719
  1 +{{type}}({{scope}}): {{subject}} {{req_id}}
... ...
skills/coding/fe-feature-review/templates/fe-feature-review-template.md 0 → 100644
  View file @63ff719
  1 +---
  2 +fe_id: {{fe_id}}
  3 +date: {{date}}
  4 +round: {{round}}
  5 +reviewer: fe-code-reviewer
  6 +---
  7 +
  8 +# Review: {{fe_id}} — round {{round}}
  9 +
  10 +## 结论
  11 +{{verdict}} （approve / request-changes）
  12 +
  13 +## Must-fix
  14 +{{#each must_fix}}
  15 +- [{{severity}}] {{file}}:{{line}} — {{issue}}（建议：{{suggestion}}）
  16 +{{/each}}
  17 +
  18 +## Nice-to-have
  19 +{{#each nice_to_have}}
  20 +- {{file}}:{{line}} — {{suggestion}}
  21 +{{/each}}
  22 +
  23 +## 维度核查（fe-code-reviewer 7 维）
  24 +
  25 +| # | 维度 | 状态 | 备注 |
  26 +|---|------|------|------|
  27 +| 1 | prototype 一致性 | {{dim_prototype}} | {{dim_prototype_note}} |
  28 +| 2 | Design Tokens | {{dim_tokens}} | {{dim_tokens_note}} |
  29 +| 3 | 无障碍 | {{dim_a11y}} | {{dim_a11y_note}} |
  30 +| 4 | 响应式 | {{dim_responsive}} | {{dim_responsive_note}} |
  31 +| 5 | 业务校验前端复刻 | {{dim_validation}} | {{dim_validation_note}} |
  32 +| 6 | API 调用一致性 | {{dim_api}} | {{dim_api_note}} |
  33 +| 7 | 状态机覆盖 | {{dim_state}} | {{dim_state_note}} |
  34 +
  35 +## 反例 / 测试覆盖缺口
  36 +
  37 +{{gaps}}
... ...
skills/coding/fe-feature-tdd/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-feature-tdd
  3 +description: 前端功能循环第 3 步。按 plan 逐任务做 TDD（失败测试 → 实现 → 通过 → commit），组件测试用 jsdom，E2E 派子会话跑 Playwright。
  4 +user-invocable: false
  5 +allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *)
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# fe-feature-tdd
  11 +
  12 +按 plan 文件逐任务做 TDD：写失败测试 → 写最小实现 → 确认通过 → commit。**所有测试运行强制派发到 Agent 子会话**，主会话只接收 JSON 结果。
  13 +
  14 +## 路径护栏（前端阶段）
  15 +
  16 +- 任务的 `impl_file` 路径若**不以** `frontend/`（或项目实际前端根目录，从 `docs/09-项目目录结构.md § 前端目录结构` 取）开头 → 硬停并打印：`fe-feature-tdd 不允许写非前端文件：<impl_file>。前端阶段任务的 impl_file 必须落在前端目录下。`
  17 +- 命中 `backend/` / `sql/` / `scripts/` → 同上硬停
  18 +- 不允许在主会话直接 `pnpm playwright` / `pnpm test` / `pnpm e2e`，必须派发子会话
  19 +
  20 +## 执行步骤
  21 +
  22 +1. 加载计划文件 `docs/superpowers/plans/<YYYY-MM-DD>-<fe_id>.md`。
  23 +
  24 +2. 从 `docs/04-技术规范.md § 零 frontend` 取测试栈：
  25 + - `frontend.unit_test_runner`：vitest / jest（默认 vitest）
  26 + - `frontend.e2e_runner`：playwright（默认 playwright）
  27 + - `frontend.test_command` / `frontend.e2e_command`：执行命令（缺失则用 `pnpm test:ci` / `pnpm e2e:ci`）
  28 +
  29 +3. 按顺序处理每个任务：
  30 +
  31 + a. 在 `test_file::test_name` 处写**失败**测试：
  32 + - `测试先行类型 = jsdom`：在 jsdom 环境下用 vitest/jest 写组件单测（render + 断言 DOM / 交互后状态变化）
  33 + - `测试先行类型 = e2e`：在 `frontend/e2e/` 写 Playwright 测试（headless）
  34 +
  35 + b. 派发 Agent 子会话（general-purpose）运行该测试，子会话只返回 `{command, exit_code, failing_assertion}` JSON，确认失败。
  36 +
  37 + c. 在 `impl_file` 处写**最小**实现使测试通过。**严格遵守**：
  38 + - 路径必须以 `frontend/`（或 docs/09 声明的前端根）开头（违反 → 硬停，见护栏）
  39 + - 色值用 `var(--color-*)`（来自 spec § 六），不硬编码 hex
  40 + - 业务校验按 spec § 五 在 form-level 复刻
  41 +
  42 + d. 再次派发子会话确认通过。
  43 +
  44 + e. 同一测试 >10 次修复仍失败 → 调用 `Skill(interrupt-check)`（中断 #1：测试反复失败）。
  45 +
  46 + f. 按 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 格式 commit：
  47 + - `scope` = 任务模块（如组件名 `dashboard` / `user-form`）
  48 + - `subject` ≤ 50 字符
  49 + - 必含 trailer `REQ_ID: <fe_id>`（如 `REQ_ID: FE-01`）
  50 +
  51 +4. 全部任务完成 → 调用 `Skill(fe-feature-verify)`。
  52 +
  53 +## 护栏
  54 +
  55 +- **绝不**在主会话直接跑 `pnpm test` / `pnpm e2e` / `pnpm playwright`，必须通过子会话
  56 +- **绝不**在 `impl_file` 中写非 `frontend/` 路径（路径护栏会硬停）
  57 +- 每次 commit 必须含 `REQ_ID: FE-NN` trailer；不混合无关改动到同一 commit
  58 +- 不硬编码颜色 hex；token 引用必须对齐 spec § 六
  59 +
  60 +## 参考
  61 +
  62 +- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md`
  63 +- 守门：`interrupt-check`（仅在步骤 3.e 触发，条件 1）
  64 +- 上游：`fe-feature-plan`
  65 +- 下游：`fe-feature-verify`
... ...
skills/coding/fe-feature-tdd/templates/commit-message-template.md 0 → 100644
  View file @63ff719
  1 +{{type}}({{scope}}): {{subject}} {{req_id}}
... ...
skills/coding/fe-feature-verify/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: fe-feature-verify
  3 +description: 前端功能循环第 4 步。把 FE 的组件测试 + E2E 派发到子会话执行，按模板渲染证据。无证据不声称完成。
  4 +user-invocable: false
  5 +allowed-tools: Skill Read Agent
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# fe-feature-verify
  11 +
  12 +把当前 FE 的测试派发到 Agent 子会话执行，按模板把结构化结果渲染成证据。**主会话从不直接跑测试**，也不自由编写证据。
  13 +
  14 +## 执行步骤
  15 +
  16 +1. 从 plan 文件确定本 FE 的测试目标：
  17 + - 单测目标：plan § 二中所有 `测试先行类型 = jsdom` 的 test_file 列表 → 拼成 vitest/jest 过滤模式
  18 + - E2E 目标：所有 `测试先行类型 = e2e` 的 test_file 列表 → 拼成 Playwright spec 过滤模式
  19 +
  20 +2. 派发 Agent 子会话（general-purpose）依次运行两个目标，子会话只返回结构化 JSON（不输出描述文字）：
  21 +
  22 + ```json
  23 + {
  24 + "unit": {
  25 + "command": "<vitest/jest 命令>",
  26 + "exit_code": <int>,
  27 + "passed": <int>,
  28 + "failed": <int>,
  29 + "failed_list": ["<test>", ...],
  30 + "stdout_excerpt": "<最后 30 行或最相关的失败片段>"
  31 + },
  32 + "e2e": {
  33 + "command": "<playwright 命令>",
  34 + "exit_code": <int>,
  35 + "passed": <int>,
  36 + "failed": <int>,
  37 + "failed_list": ["<spec>", ...],
  38 + "stdout_excerpt": "<最后 30 行或最相关的失败片段>"
  39 + }
  40 + }
  41 + ```
  42 +
  43 + 命令从 `docs/04-技术规范.md § 零 frontend.test_command` / `frontend.e2e_command` 取，缺失则用默认 `pnpm test:ci` / `pnpm e2e:ci`。
  44 +
  45 +3. 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-verify-evidence-template.md` 渲染证据并打印到会话。
  46 +
  47 +4. **任一目标 `exit_code != 0` 或 `failed > 0`** → 停止，不进入 review。
  48 +
  49 +5. 全部通过 → 调用 `Skill(fe-feature-review)`。
  50 +
  51 +## 护栏
  52 +
  53 +- **绝不**在主会话直接跑测试，必须通过子会话
  54 +- **绝不**自由编写证据正文，必须从模板渲染
  55 +- 不要把原始 stdout 全文塞进主会话（`stdout_excerpt` ≤ 30 行）
  56 +
  57 +## 参考
  58 +
  59 +- `${CLAUDE_SKILL_DIR}/templates/fe-feature-verify-evidence-template.md`
  60 +- 上游：`fe-feature-tdd`
  61 +- 下游：`fe-feature-review`
... ...
skills/coding/fe-feature-verify/templates/fe-feature-verify-evidence-template.md 0 → 100644
  View file @63ff719
  1 +## Verify evidence — {{fe_id}}
  2 +
  3 +### 单元测试（jsdom）
  4 +
  5 +- 命令: `{{unit.command}}`
  6 +- 子会话: {{unit.subagent_id}}
  7 +- 退出码: {{unit.exit_code}}
  8 +- 通过用例数: {{unit.passed}}
  9 +- 失败用例数: {{unit.failed}}
  10 +- 失败列表: {{unit.failed_list}}
  11 +
  12 +关键 stdout 片段 (≤30 行):
  13 +
  14 +```
  15 +{{unit.stdout_excerpt}}
  16 +```
  17 +
  18 +### E2E 测试（Playwright）
  19 +
  20 +- 命令: `{{e2e.command}}`
  21 +- 子会话: {{e2e.subagent_id}}
  22 +- 退出码: {{e2e.exit_code}}
  23 +- 通过用例数: {{e2e.passed}}
  24 +- 失败用例数: {{e2e.failed}}
  25 +- 失败列表: {{e2e.failed_list}}
  26 +
  27 +关键 stdout 片段 (≤30 行):
  28 +
  29 +```
  30 +{{e2e.stdout_excerpt}}
  31 +```
  32 +
  33 +结论: {{conclusion}} （pass = 两段都 pass / fail = 任一 fail）
... ...
skills/coding/feature-brainstorm/SKILL.md
  View file @63ff719
... ... @@ -9,6 +9,10 @@ allowed-tools: Read Write Skill Bash(mysql *)
9 9  
10 10 # feature-brainstorm
11 11  
  12 +## 阶段范围（后端）
  13 +
  14 +本 skill 服务于**后端阶段**。产出范围限定为 controller / service / repository / DTO / 校验 / SQL migration / REST 契约。读 docs/01 REQ 卡片时**忽略 UI 描述**（输入控件类型、按钮位置、列表布局等），但**校验规则、业务规则**仍要落到后端 DTO + service。UI 实现统一推迟到前端阶段（fe-feature-*）。
  15 +
12 16 针对单个 REQ，委托 `superpower-brainstorming` 做交互式头脑风暴，把输出按规格模板渲染，产出单页功能规格。
13 17  
14 18 ## 执行步骤
... ...
skills/coding/feature-plan/SKILL.md
  View file @63ff719
... ... @@ -9,6 +9,10 @@ allowed-tools: Read Write Grep Skill
9 9  
10 10 # feature-plan
11 11  
  12 +## 阶段范围（后端）
  13 +
  14 +本 skill 服务于**后端阶段**。任务粒度限定为后端模块文件：controller / service / repository / DTO / 校验 / SQL migration。**禁止**生成 `frontend/` 路径下的实现任务——UI 实现统一推迟到前端阶段（fe-feature-*）。
  15 +
12 16 把当前 REQ 的功能规格转成任务级实现计划，委托 `superpower-writing-plans` 起草，按计划模板渲染落盘。
13 17  
14 18 ## 执行步骤
... ...
skills/coding/feature-tdd/SKILL.md
  View file @63ff719
... ... @@ -33,6 +33,7 @@ allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *)
33 33 - **绝不**在主会话直接跑 `mvn test` / `pnpm test` / `scripts/test.sh`，必须通过子会话
34 34 - **绝不**在主会话直接 `mysql -e "ALTER ..."`；业务 schema 改动一律走 `sql/migrations/V*.sql` 文件（只读查询 / 临时调试除外）
35 35 - 每次 commit 必须含 `REQ-XXX-NNN` 标签；不混合无关改动到同一 commit
  36 +- **后端阶段路径硬护栏**：任务表里的 `impl_file` 路径以 `frontend/` 开头 → 硬停并打印 `feature-tdd 后端阶段不允许写前端代码：<impl_file>。请检查 plan 任务定义；UI 推迟到前端阶段（fe-feature-*）`，不再继续 TDD 循环
36 37  
37 38 ## 参考
38 39  
... ...
skills/coding/frontend-start/SKILL.md 0 → 100644
  View file @63ff719
  1 +---
  2 +name: frontend-start
  3 +description: 前端阶段循环入口。AI 自主推导 FE 业务功能清单写入 docs/08 § 三（已有则加载），定位未完成 FE 派发 fe-feature-brainstorm 或 test-gate（前端阶段）。幂等可重入。
  4 +user-invocable: false
  5 +allowed-tools: Read Write Edit Skill Glob Grep AskUserQuestion Bash(git branch *) Bash(git checkout *) Bash(git rev-parse *) Bash(git pull *) Bash(git status *) Bash(git symbolic-ref *) Bash(curl *) Bash(jq *) Bash(find *) Bash(ls *)
  6 +---
  7 +
  8 +**所有输出必须使用中文。**
  9 +
  10 +# frontend-start
  11 +
  12 +## 执行步骤
  13 +
  14 +### 步骤 1：检查 prototype
  15 +
  16 +项目根 `prototype/` 至少含 1 个 `*.html` → 通过，进入步骤 2；缺失 → 用 `AskUserQuestion` 让用户补齐 prototype 后重跑入口，停止。
  17 +
  18 +### 步骤 2：准备 FE 清单
  19 +
  20 +读 docs/08 § 三 "功能:" 项：
  21 +
  22 +- 已有 `- [ ] FE-NN ...` 或 `- [x] FE-NN ...` 行 → **加载**：逐行解析得 `fe_list[]`，每项 `{ fe_id, name, status, associated_reqs[], associated_prototypes[] }`。行格式不符 → 硬停打印问题行
  23 +- 仅有 HTML 注释占位（无 FE bullet）→ **推导**：
  24 + 1. 读 `prototype/**/*.html` + `docs/01-需求清单/**/*.md` + `docs/05-API接口契约.md`
  25 + 2. 以**业务功能**为单位拆分（同流程多屏可合 1 FE；一 HTML 多功能可拆多 FE；无 UI 的 REQ 不产生 FE）。每个 FE：`{ fe_id: FE-NN, name, associated_reqs[], associated_prototypes[] }`，prototype 路径可带 anchor 区分文件内多区域
  26 + 3. **写入 § 三 "功能:" 项**（替换占位 HTML 注释），行格式：
  27 +
  28 + ```
  29 + - [ ] FE-NN 功能名 ｜ 关联 REQ：REQ-A, REQ-B ｜ 关联原型：prototype/<file>.html
  30 + ```
  31 +
  32 + 保留 `- 整体 MR: —` 不动；写入后解析得 `fe_list[]`，继续步骤 3
  33 +
  34 +### 步骤 3：检查前端 MR 状态
  35 +
  36 +读 § 三 `整体 MR:` 调 GitLab API：
  37 +
  38 +- `merged` → 打印"前端阶段已完成"并停（冗余保护，正常由 coding-start 拦掉）
  39 +- 其它（`—` / opened / closed）→ 进入步骤 4
  40 +- API 异常 → 硬停 + 诊断
  41 +
  42 +### 步骤 4：切到 frontend-phase 分支
  43 +
  44 +目标分支 `frontend-phase`，分支管理逻辑同 module-start 步骤 3：已在 → 继续；存在 → checkout；不存在 → 切默认分支 fast-forward 后 `git checkout -b frontend-phase`。任何错误硬停 + 诊断，不自动 stash / 覆盖。
  45 +
  46 +### 步骤 5：识别已完成的 FE
  47 +
  48 +扫 `docs/superpowers/reviews/<日期>-FE-*.md`，`verdict: approve` 的收入 `done_fes[]`。每次进入重新计算，不缓存。
  49 +
  50 +### 步骤 6：报告进度
  51 +
  52 +按 `${CLAUDE_SKILL_DIR}/templates/frontend-start-banner-template.md` 渲染：当前分支 + prototype HTML 数 + FE 进度（done / total）+ 下一 FE。
  53 +
  54 +### 步骤 7：进入下一环节
  55 +
  56 +- 存在未完成 FE → `Skill(fe-feature-brainstorm)`，参数 `{ fe_id, name, associated_reqs[], associated_prototypes[] }`
  57 +- 全 FE 完成 → `Skill(test-gate)` 带 `phase=frontend`
  58 +
  59 +## 参考
  60 +
  61 +- `${CLAUDE_SKILL_DIR}/templates/frontend-start-banner-template.md`
  62 +- `docs/08-模块任务管理.md § 三`（前端阶段元数据：整体 MR + FE 清单）
  63 +- `prototype/`（HTML mockup，FE 拆分粒度与文件数无关）
  64 +- `docs/superpowers/reviews/*-FE-*.md`（verdict=approve 即完成）
  65 +- 上游：`coding-start`（步骤 4 派发，仅当后端完成 + 前端未完成）；`fe-feature-review` approve 后回调
  66 +- 下游：`fe-feature-brainstorm`（每 FE）/ `test-gate`（phase=frontend，全完成时）
  67 +- 前置门禁：本 skill 步骤 1 自承（coding-start 不做）
... ...
skills/coding/frontend-start/templates/frontend-start-banner-template.md 0 → 100644
  View file @63ff719
  1 +## 前端阶段（frontend-phase）
  2 +
  3 +- 分支：frontend-phase
  4 +- 整体 MR：{{overall_mr}}
  5 +- FE 进度（`x` = 已完成 review approve；FE 是业务功能粒度，与 prototype/ HTML 文件数无关）：
  6 +{{#each fes}}
  7 + - [{{status}}] {{fe_id}} {{name}} ｜ 关联 REQ：{{reqs}} ｜ 关联原型：{{prototypes}}
  8 +{{/each}}
  9 +- 下一步：{{next_action}}
... ...
skills/coding/module-report/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: module-report
3   -description: 本地测试闸门通过后，生成标准化 12 节模块完成报告并 commit 到 module 分支供 MR 嵌入。
  3 +description: 本地测试闸门通过后，生成标准化 12 节完成报告（后端模块 OR 前端阶段）并 commit 到当前分支供 MR 嵌入。
4 4 user-invocable: false
5   -allowed-tools: Read Write Glob Grep Skill Bash(git diff *) Bash(git log *) Bash(git add *) Bash(git commit *)
  5 +allowed-tools: Read Write Glob Grep Skill Bash(git diff *) Bash(git log *) Bash(git add *) Bash(git commit *) Bash(git branch *)
6 6 ---
7 7  
8 8 **所有输出必须使用中文。**
9 9  
10 10 # module-report
11 11  
12   -`test-gate` 绿色后渲染 12 节模块完成报告，commit 到 module 分支供 MR 嵌入。**只读摘要，不读 diff 正文进上下文**。
  12 +`test-gate` 绿色后渲染 12 节完成报告，commit 到当前分支供 MR 嵌入。**只读摘要，不读 diff 正文进上下文**。
  13 +
  14 +按当前分支自动推断 `phase`：
  15 +
  16 +- `module-<id>` → `phase=backend`，`phase_id=<id>`
  17 +- `frontend-phase` → `phase=frontend`，`phase_id=frontend-phase`
  18 +- 其它分支 → 硬停
13 19  
14 20 ## 执行步骤
15 21  
16   -1. 验证上游 `test-gate` 已绿；红色则停。
  22 +### 步骤 0：推断 phase 与上下文
  23 +
  24 +从 `git branch --show-current` 取分支名，按上述规则推出 `phase` 与 `phase_id`。
  25 +
  26 +1. 验证上游 `test-gate` 已绿（读 `docs/superpowers/module-reports/<phase_id>-test-gate.md`）；红色则停。
  27 +
17 28 2. 收集输入（核心约束：取 git 摘要而非 diff 正文）：
18   - - § ③ 文件变更：用 `git diff --stat` / `--name-status` / `git log --oneline` 摘要（区间：module 分支起点 → HEAD）
19   - - § ② / § ⑨：直接 Read `docs/superpowers/{specs,plans,reviews}/<日期>-<本模块的 REQ>.md`（小文件可全读）
20   - - § ⑤：Read `docs/superpowers/module-reports/<module_id>-test-gate.md`
  29 +
  30 + **后端阶段 (phase=backend)**：
  31 + - § ③ 文件变更：`git diff --stat` / `--name-status` / `git log --oneline`（区间：module 分支起点 → HEAD）
  32 + - § ② / § ⑨：Read `docs/superpowers/{specs,plans,reviews}/<日期>-<本模块的 REQ>.md`
  33 + - § ⑤：Read `docs/superpowers/module-reports/<phase_id>-test-gate.md`
21 34 - § ⑥ Migration：`git diff --name-only --diff-filter=A -- 'sql/migrations/V*.sql'` 列新增 migration，每个 Read 第一行作说明
22   - - § ⑦ 跨模块改动：Read `docs/superpowers/module-reports/<module_id>-cross-module.md`（如存在）
  35 + - § ⑦ 跨模块改动：Read `docs/superpowers/module-reports/<phase_id>-cross-module.md`（如存在）
23 36 - § ④ 读写的表：用 grep 定位涉 SQL 的文件后按需读片段，**不全量读 docs/03**
  37 +
  38 + **前端阶段 (phase=frontend)**：
  39 + - § ① 模块信息：`module_id` 填 `frontend-phase`，`module_name` 填 `前端阶段（整体）`
  40 + - § ② 改为"FE 完成清单"：扫 `docs/superpowers/{specs,plans,reviews}/<日期>-FE-*.md`，按 FE-NN 顺序列出
  41 + - § ③ 文件变更：`git diff --stat` 区间 `frontend-phase` 分支起点 → HEAD
  42 + - § ④ 数据库使用表：填 `N/A（前端阶段）`
  43 + - § ⑤：Read `docs/superpowers/module-reports/frontend-phase-test-gate.md`
  44 + - § ⑥ Migration：填 `N/A（前端阶段）`
  45 + - § ⑦：填 `N/A（前端阶段不涉及跨模块代码改动；token 漂移见 § ⑧）`
  46 + - § ⑧ 偏离清单：除常规偏离外，额外审查"实际渲染 DOM 与各 FE 关联原型主结构的差异"，逐 FE 列出（关联原型清单见每个 FE 的 spec）
  47 + - § ⑪ 下一模块预览：填"上线/部署后续步骤"
  48 +
24 49 3. 按 `${CLAUDE_SKILL_DIR}/templates/module-report-template.md` 渲染 12 节。
  50 +
25 51 4. **硬验证**：
26   - - § ⑦：跨模块日志中任何 `TBD(CC 补)` 或敷衍填充 → 调用 `Skill(cross-module-log)` 一次性批量补齐，补完回本步骤重验（**整模块周期内唯一补 TBD 的时机**）
27   - - § ⑧：必须列举所有偏离规格之处；若无，写"无偏离"
28   -5. 写入 `docs/superpowers/module-reports/<YYYY-MM-DD>-<module_id>.md`，连同跨模块日志（如存在）一起 commit 到 module 分支：
  52 + - § ⑦（仅 backend）：跨模块日志中任何 `TBD(CC 补)` 或敷衍填充 → 调用 `Skill(cross-module-log)` 一次性批量补齐，补完回本步骤重验（**整模块周期内唯一补 TBD 的时机**）
  53 + - § ⑧：必须列举所有偏离之处；若无，写"无偏离"
  54 +
  55 +5. 写入 `docs/superpowers/module-reports/<YYYY-MM-DD>-<phase_id>.md`，连同跨模块日志（如存在）一起 commit 到当前分支：
29 56 ```bash
30   - git add docs/superpowers/module-reports/<YYYY-MM-DD>-<module_id>.md
31   - [ -f docs/superpowers/module-reports/<module_id>-cross-module.md ] && \
32   - git add docs/superpowers/module-reports/<module_id>-cross-module.md
33   - git commit -m "docs(<module_id>): add module completion report + cross-module log"
  57 + git add docs/superpowers/module-reports/<YYYY-MM-DD>-<phase_id>.md
  58 + [ -f docs/superpowers/module-reports/<phase_id>-cross-module.md ] && \
  59 + git add docs/superpowers/module-reports/<phase_id>-cross-module.md
  60 + git commit -m "docs(<phase_id>): add completion report + cross-module log"
34 61 ```
35 62 commit 是必需的——`mr-create` 的 worktree-clean 前置条件依赖此步。
  63 +
36 64 6. 调用 `Skill(mr-create)` 推送并创建 MR。
37 65  
38 66 ## 参考
39 67  
40   -- `${CLAUDE_SKILL_DIR}/templates/module-report-template.md`（12 节）
  68 +- `${CLAUDE_SKILL_DIR}/templates/module-report-template.md`（12 节，后端 + 前端共用）
41 69 - 上游：`test-gate`（绿色时派发）
42   -- 下游：`mr-create`
  70 +- 下游：`mr-create`（phase 由当前分支推断）
... ...
skills/coding/module-start/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: module-start
3   -description: 模块循环入口。定位当前模块与未完成 REQ，派发到 feature-brainstorm（每个 REQ 一次）或 test-gate（本模块全部完成）。幂等可重入。
  3 +description: 后端模块循环入口。定位当前未 merged 模块与未完成 REQ，派发 feature-brainstorm 或 test-gate；幂等可重入。阶段路由由 coding-start 负责，本 skill 不感知前端阶段。
4 4 user-invocable: false
5 5 allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *) Bash(git rev-parse *) Bash(git pull *) Bash(git status *) Bash(git symbolic-ref *) Bash(curl *) Bash(jq *)
6 6 ---
... ... @@ -9,13 +9,17 @@ allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *
9 9  
10 10 # module-start
11 11  
  12 +## 职责说明
  13 +
  14 +本 skill 单一职责：推进**后端模块循环**。`coding-start` 已在派发前确认存在未 merged 后端模块；本 skill 不再做"后端是否全完"的判定，也不感知前端阶段。
  15 +
12 16 ## 执行步骤
13 17  
14 18 ### 步骤 1：定位当前模块与本模块 REQ 列表
15 19  
16 20 按 `docs/02 § 二 开发顺序清单` 的 REQ 顺序扫描，找到第一个所属模块尚未 merged 的模块作为 `current_module`，并抽取本模块 REQ 序列。
17 21  
18   -模块状态判定（`MR:` 字段 × GitLab API state 三种组合的语义和应对动作）参见 `CLAUDE.md § ✅ 模块完成判定规则 § 模块状态语义`。
  22 +模块状态判定（`MR:` 字段 × GitLab API state 三种组合的语义和应对动作）参见 `CLAUDE.md § ✅ 阶段完成判定规则 § 状态语义`。
19 23  
20 24 找到 `current_module` 后，从 docs/02 § 二 的 REQ 列表里取出所有 `module_id == current_module` 的项，按原序得 `req_list[]`（A5 约束保证同模块 REQ 连续）。模块名、需求卡目录等其它字段由后续步骤按需从 `docs/08 § 二` 或 `docs/01-需求清单/` 取，不在本步骤预读。
21 25  
... ... @@ -25,9 +29,12 @@ allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *
25 29 - API 异常（HTTP 非 2xx / 找不到 MR / state 非合法值）一律硬停，**禁止静默假设未 merged**，向用户打印诊断信息，引导核查上述凭据与 docs/08 的 iid
26 30 - 任何文件读取或解析失败 → 打印错误并停止
27 31  
28   -### 步骤 2：所有模块都完成时结束
  32 +### 步骤 2：找不到未 merged 后端模块的处理
  33 +
  34 +如果步骤 1 没找到任何未 merged 的后端模块——理论上不应触达此分支（`coding-start` 步骤 3 已确认存在未 merged 模块才会派发到本 skill），属于异常调用：
29 35  
30   -如果步骤 1 没找到任何未 merged 的模块（即整个项目已做完），打印"所有模块已完成"提示用户，结束流程，不再进入后续步骤。
  36 +- 打印诊断："`module-start` 未发现未 merged 后端模块。请通过 `/erp-workflow:coding-start` 入口重新驱动——coding-start 会按 docs/08 § 二/§ 三 自动路由到正确阶段（后端 / 前端 / 全部完成）。"
  37 +- 结束本 skill，不派发下游
31 38  
32 39 ### 步骤 3：确保处于模块分支
33 40  
... ... @@ -57,7 +64,10 @@ allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *
57 64 ## 参考
58 65  
59 66 - `docs/02-开发计划.md § 二 开发顺序清单`（分发权威）
60   -- `docs/08-模块任务管理.md § 二`（模块元数据，含 `MR:` 字段；完成判定以 MR state 为准）
  67 +- `docs/08-模块任务管理.md § 二`（后端模块元数据，含 `MR:` 字段；完成判定以 MR state 为准）
61 68 - `docs/superpowers/reviews/*.md`（REQ 级进度事实——verdict=approve 即完成）
62 69 - `${CLAUDE_SKILL_DIR}/templates/module-start-banner-template.md`
63   -- 下游：`feature-brainstorm`（每个 REQ）/ `test-gate`（本模块完成）
  70 +- 下游：
  71 + - `feature-brainstorm`（每个未完成 REQ）
  72 + - `test-gate`（本模块全部 REQ approve 后；phase=backend 由分支推断）
  73 +- 上游：`coding-start`（步骤 3 派发到此；后端模块全 merged 时不会派发到此）
... ...
skills/coding/mr-create/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: mr-create
3   -description: 模块报告完成后，把 module 分支推到远程并创建 GitLab MR，把 MR iid 回写 docs/08 + URL 回写报告 § ⑫，停下等人工 Approve + Merge。
  3 +description: 完成报告生成后，把当前分支（module-* 后端 / frontend-phase 前端）推到远程并创建 GitLab MR，把 MR iid 回写 docs/08（§ 二 模块行 / § 三 整体 MR）+ URL 回写报告 § ⑫，停下等人工 Approve + Merge。
4 4 user-invocable: false
5 5 allowed-tools: Read Edit Bash(git *) Bash(bash *)
6 6 ---
... ... @@ -11,15 +11,19 @@ allowed-tools: Read Edit Bash(git *) Bash(bash *)
11 11  
12 12 ## 前置条件
13 13  
14   -- `module-report` 已生成报告并 commit 到 module 分支
15   -- `test-gate` 绿色，test-gate.md 已 commit 到 module 分支
16   -- 当前分支 = `module-<module_id>`（由 `module-start` 步骤 3 切入）
  14 +- `module-report` 已生成报告并 commit 到当前分支
  15 +- `test-gate` 绿色，test-gate.md 已 commit 到当前分支
  16 +- 当前分支 = `module-<module_id>` 或 `frontend-phase`（由 `module-start` 步骤 3 / `frontend-start` 步骤 4 切入）
17 17  
18 18 ## 执行步骤
19 19  
20   -### 步骤 1：验证当前分支
  20 +### 步骤 1：验证当前分支并推断 phase
21 21  
22   -`git branch --show-current` 必须匹配 `module-*`，否则停下报错（不自动建分支——分支职责在 `module-start` 步骤 3）。从分支名取 `module_id` = 去掉 `module-` 前缀。
  22 +`git branch --show-current`：
  23 +
  24 +- 匹配 `module-*` → `phase=backend`，`phase_id=` 去掉 `module-` 前缀
  25 +- 等于 `frontend-phase` → `phase=frontend`，`phase_id=frontend-phase`
  26 +- 其它 → 停下报错（不自动建分支——分支职责在上游 `module-start` / `frontend-start`）
23 27  
24 28 ### 步骤 2：验证 worktree 干净
25 29  
... ... @@ -46,10 +50,10 @@ allowed-tools: Read Edit Bash(git *) Bash(bash *)
46 50 ### 步骤 4：调脚本创建（或复用）MR
47 51  
48 52 ```bash
49   -bash "${CLAUDE_SKILL_DIR}/scripts/create-mr.sh" <module_id> <current_branch> <YYYY-MM-DD>
  53 +bash "${CLAUDE_SKILL_DIR}/scripts/create-mr.sh" <phase_id> <current_branch> <YYYY-MM-DD>
50 54 ```
51 55  
52   -脚本内部完成：加载 `.env.local` → 探测目标分支 → 从 docs/08 取 `module_name` 与 test-gate.md 取结论 → 渲染 description → 查已有 opened MR → 否则创建新 MR。
  56 +`<phase_id>` = 后端模块 id（如 `module_sys`）或前端常量 `frontend-phase`。脚本内部完成：加载 `.env.local` → 探测目标分支 → 取 `module_name`（后端从 docs/08 § 二，前端使用常量"前端阶段（整体）"）→ test-gate.md 取结论 → 渲染 description → 查已有 opened MR → 否则创建新 MR。
53 57  
54 58 输出（stdout）：单行 `<MR_IID> <MR_URL>`，由本步骤捕获供后续步骤使用。失败时脚本写诊断到 stderr 并 exit 1，本 skill 停下。
55 59  
... ... @@ -57,20 +61,23 @@ bash &quot;${CLAUDE_SKILL_DIR}/scripts/create-mr.sh&quot; &lt;module_id&gt; &lt;current_branch&gt; &lt;YY
57 61  
58 62 **先于步骤 6 执行**——若步骤 6 失败，重跑时步骤 4 脚本能识别已有 MR + docs/08 已含 IID，状态一致。
59 63  
60   -`Edit docs/08-模块任务管理.md`：把当前模块的 ` - MR: —` 改为 ` - MR: !<MR_IID>`。
  64 +`Edit docs/08-模块任务管理.md`：
  65 +
  66 +- **phase=backend**：在 § 二 中找到当前模块的 ` - MR: —` 改为 ` - MR: !<MR_IID>`
  67 +- **phase=frontend**：在 § 三 中找到 `- 整体 MR: —` 改为 `- 整体 MR: !<MR_IID>`
61 68  
62 69 ```bash
63 70 git add docs/08-模块任务管理.md
64   -git commit -m "chore(<module_id>): record MR !<MR_IID> in docs/08"
  71 +git commit -m "chore(<phase_id>): record MR !<MR_IID> in docs/08"
65 72 ```
66 73  
67   -### 步骤 6：追加 MR URL 到模块报告 § ⑫ 并 commit
  74 +### 步骤 6：追加 MR URL 到完成报告 § ⑫ 并 commit
68 75  
69   -`Edit docs/superpowers/module-reports/<date>-<module_id>.md` 的 § ⑫，把 `{{mr_url}}` 替换为 `<MR_URL>`（已替换则追加一行）。
  76 +`Edit docs/superpowers/module-reports/<date>-<phase_id>.md` 的 § ⑫，把 `{{mr_url}}` 替换为 `<MR_URL>`（已替换则追加一行）。
70 77  
71 78 ```bash
72   -git add docs/superpowers/module-reports/<date>-<module_id>.md
73   -git commit -m "docs(<module_id>): record MR !<MR_IID> link in module report"
  79 +git add docs/superpowers/module-reports/<date>-<phase_id>.md
  80 +git commit -m "docs(<phase_id>): record MR !<MR_IID> link in completion report"
74 81 ```
75 82  
76 83 ### 步骤 7：再次 push 同步新 commits
... ... @@ -81,11 +88,14 @@ git commit -m &quot;docs(&lt;module_id&gt;): record MR !&lt;MR_IID&gt; link in module report&quot;
81 88  
82 89 ### 步骤 8：打印 MR URL，停下等 Approve + Merge
83 90  
84   -向会话打印 `<MR_URL>`，结束本 skill。用户在 GitLab merge 后再运行 `/erp-workflow:coding-start`，入口扫描到 `state=merged` 后自动推进下一模块。
  91 +向会话打印 `<MR_URL>`，结束本 skill。
  92 +
  93 +- **phase=backend**：用户在 GitLab merge 后再运行 `/erp-workflow:coding-start`；coding-start 重新做后端完成性检查，未完则推进下一模块，全 merged 则路由到 `frontend-start`（frontend-start 自带 prototype/ 门禁）
  94 +- **phase=frontend**：用户在 GitLab merge 后再运行 `/erp-workflow:coding-start`，扫描到 § 三 整体 MR `state=merged` → 打印"所有阶段已完成"
85 95  
86 96 ## 参考
87 97  
88   -- `${CLAUDE_SKILL_DIR}/scripts/create-mr.sh`（步骤 4 主流程脚本）
  98 +- `${CLAUDE_SKILL_DIR}/scripts/create-mr.sh`（步骤 4 主流程脚本，按 phase_id 自动选 backend / frontend 行为）
89 99 - `${CLAUDE_SKILL_DIR}/templates/mr-title-template.md`
90 100 - `${CLAUDE_SKILL_DIR}/templates/mr-description-template.md`
91 101 - 上游：`module-report`
... ...
skills/coding/mr-create/scripts/create-mr.sh
  View file @63ff719
... ... @@ -2,7 +2,9 @@
2 2 # create-mr.sh — mr-create 主流程：渲染 description、查已有 MR / 创建新 MR
3 3 #
4 4 # 用法：
5   -# bash create-mr.sh <module_id> <current_branch> <date>
  5 +# bash create-mr.sh <phase_id> <current_branch> <date>
  6 +#
  7 +# <phase_id> = 后端模块 id（如 module_sys）或前端常量 "frontend-phase"
6 8 #
7 9 # 输出（stdout，单行，由调用方读取）：
8 10 # <MR_IID> <MR_URL>
... ... @@ -10,13 +12,14 @@
10 12 # 失败：诊断写 stderr，exit 1。
11 13 #
12 14 # 设计要点：
13   -# - 模块报告整文只经 sed + awk 管道流入 description 与 GitLab API（curl --rawfile），
  15 +# - 报告整文只经 sed + awk 管道流入 description 与 GitLab API（curl --rawfile），
14 16 # 全程不进 LLM 上下文。
15 17 # - 幂等：同一 source_branch 已有 opened MR 时，复用其 iid/url，不再创建。
  18 +# - phase 自动：phase_id == "frontend-phase" 时跳过 docs/08 § 二 lookup，使用常量名。
16 19  
17 20 set -euo pipefail
18 21  
19   -MODULE_ID="${1:?usage: create-mr.sh <module_id> <current_branch> <date>}"
  22 +MODULE_ID="${1:?usage: create-mr.sh <phase_id> <current_branch> <date>}"
20 23 CURRENT_BRANCH="${2:?missing current_branch}"
21 24 DATE="${3:?missing date (YYYY-MM-DD)}"
22 25  
... ... @@ -28,7 +31,7 @@ TITLE_TPL=&quot;$TPL_DIR/mr-title-template.md&quot;
28 31 REPORT="docs/superpowers/module-reports/${DATE}-${MODULE_ID}.md"
29 32 TEST_GATE="docs/superpowers/module-reports/${MODULE_ID}-test-gate.md"
30 33  
31   -[ -f "$REPORT" ] || { echo "[create-mr] ⚠️ 模块报告不存在: $REPORT" >&2; exit 1; }
  34 +[ -f "$REPORT" ] || { echo "[create-mr] ⚠️ 完成报告不存在: $REPORT" >&2; exit 1; }
32 35 [ -f "$TEST_GATE" ] || { echo "[create-mr] ⚠️ test-gate evidence 不存在: $TEST_GATE" >&2; exit 1; }
33 36  
34 37 # 1. 加载凭据
... ... @@ -44,11 +47,16 @@ TARGET_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2&gt;/dev/null | sed &#39;s|r
44 47 [ -n "$TARGET_BRANCH" ] || TARGET_BRANCH=$(git branch -r --format='%(refname:short)' | grep -E '^origin/(main|master)$' | head -1 | sed 's|^origin/||' || true)
45 48 [ -n "$TARGET_BRANCH" ] || { echo "[create-mr] ⚠️ 无法探测默认分支（origin/main 或 origin/master）" >&2; exit 1; }
46 49  
47   -# 3. 从 docs/08 § 二 提取 module_name
48   -MODULE_NAME=$(awk -v mid="$MODULE_ID" '
49   - $0 ~ "^- "mid" " { sub("^- "mid" ", ""); print; exit }
50   -' docs/08-模块任务管理.md)
51   -[ -n "$MODULE_NAME" ] || { echo "[create-mr] ⚠️ docs/08 § 二 找不到模块 $MODULE_ID" >&2; exit 1; }
  50 +# 3. 取 module_name
  51 +if [ "$MODULE_ID" = "frontend-phase" ]; then
  52 + MODULE_NAME="前端阶段（整体）"
  53 +else
  54 + # 从 docs/08 § 二 提取后端模块 module_name
  55 + MODULE_NAME=$(awk -v mid="$MODULE_ID" '
  56 + $0 ~ "^- "mid" " { sub("^- "mid" ", ""); print; exit }
  57 + ' docs/08-模块任务管理.md)
  58 + [ -n "$MODULE_NAME" ] || { echo "[create-mr] ⚠️ docs/08 § 二 找不到模块 $MODULE_ID" >&2; exit 1; }
  59 +fi
52 60  
53 61 # 4. 从 test-gate evidence 提取 conclusion + subagent_id
54 62 TEST_SUBAGENT_ID=$(awk '/^- 子会话: / { sub("^- 子会话: ", ""); print; exit }' "$TEST_GATE")
... ...
skills/coding/mr-create/templates/mr-description-template.md
  View file @63ff719
1   -## 模块完成报告
  1 +## 完成报告
2 2  
3 3 见 `docs/superpowers/module-reports/{{date}}-{{module_id}}.md`（本 MR 仓库内完整贴入下方）。
4 4  
... ... @@ -10,9 +10,9 @@
10 10  
11 11 ## 本地闸门证据
12 12  
13   -- test.sh: {{test_gate_conclusion}}（subagent: {{test_subagent_id}}）
  13 +- 测试: {{test_gate_conclusion}}（subagent: {{test_subagent_id}}）
14 14  
15 15 ## 审核入口
16 16  
17   -- 本 MR = 模块 `{{module_id}}` 的唯一人工介入点
18   -- Approve + Merge 后，下次用户运行 `/erp-workflow:coding-start` 时入口会自动扫描到 GitLab API `state=merged`，探测默认分支后 `git pull --ff-only` 同步并推进下一模块
  17 +- 本 MR = `{{module_id}}` 的唯一人工介入点（后端模块 / 前端阶段共用）
  18 +- Approve + Merge 后，下次用户运行 `/erp-workflow:coding-start` 时入口会自动扫描 GitLab API `state=merged`，探测默认分支后 `git pull --ff-only` 同步并推进下一模块（后端阶段）或宣告全部完成（前端阶段）
... ...
skills/coding/test-gate/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: test-gate
3   -description: MR 创建前的硬闸门。子会话跑 scripts/test.sh 全量测试，绿则进入 module-report，红则停下并按失败类型引导用户。
  3 +description: MR 创建前的硬闸门。后端阶段子会话跑 scripts/test.sh，前端阶段跑前端测试命令；绿则进入 module-report，红则停下并按失败类型引导用户。
4 4 user-invocable: false
5   -allowed-tools: Read Write Skill Agent Bash(git add *) Bash(git commit *)
  5 +allowed-tools: Read Write Skill Agent Bash(git add *) Bash(git commit *) Bash(git branch *)
6 6 ---
7 7  
8 8 **所有输出必须使用中文。**
9 9  
10 10 # test-gate
11 11  
12   -模块所有 REQ 完成后的硬闸门：子会话跑 `./scripts/test.sh`（含本模块新增 + 已合并模块回归），按模板渲染证据并 commit 到 module 分支。绿色继续，红色停下，按失败类型给用户恢复路径。
  12 +模块（后端阶段）或整个前端阶段所有功能完成后的硬闸门。按当前分支自动推断 `phase`：
  13 +
  14 +- `module-*` 分支 → `phase=backend`：子会话跑 `./scripts/test.sh`（含本模块新增 + 已合并模块回归）
  15 +- `frontend-phase` 分支 → `phase=frontend`：子会话跑前端测试命令（vitest + playwright）
  16 +
  17 +按模板渲染证据并 commit 到当前分支。绿色继续，红色停下。
13 18  
14 19 ## 执行步骤
15 20  
16   -1. 派发 Agent 子会话（general-purpose）运行 `./scripts/test.sh`，子会话只返回结构化 JSON（不输出描述文字）：
  21 +### 步骤 0：推断 phase 与目标命令
  22 +
  23 +`git branch --show-current`：
  24 +
  25 +- `module-<id>` → `phase=backend`，`phase_id=<id>`，`command=./scripts/test.sh`
  26 +- `frontend-phase` → `phase=frontend`，`phase_id=frontend-phase`；命令从 `docs/04-技术规范.md § 零 frontend.test_command` / `frontend.e2e_command` 拼接（缺失则 `pnpm test:ci && pnpm e2e:ci`）
  27 +- 其它分支 → 硬停打印 `test-gate 仅在 module-* 或 frontend-phase 分支可调用，当前 <branch>`
  28 +
  29 +1. 派发 Agent 子会话（general-purpose）运行上述 `command`，子会话只返回结构化 JSON（不输出描述文字）：
17 30 ```json
18 31 {
19   - "command": "./scripts/test.sh",
  32 + "command": "<command>",
20 33 "exit_code": <int>,
21 34 "passed": <int>,
22 35 "failed": <int>,
23 36 "stdout_excerpt": "<最后 30 行，含 FAIL 摘要>"
24 37 }
25 38 ```
26   -2. 按 `${CLAUDE_SKILL_DIR}/templates/test-gate-result-template.md` 渲染证据，写入 `docs/superpowers/module-reports/<module_id>-test-gate.md`。
27   -3. Commit evidence 到 module 分支（保证证据随 MR 合并进默认分支可审计）：
  39 +2. 按 `${CLAUDE_SKILL_DIR}/templates/test-gate-result-template.md` 渲染证据，写入 `docs/superpowers/module-reports/<phase_id>-test-gate.md`（后端：`<module_id>-test-gate.md`；前端：`frontend-phase-test-gate.md`）。
  40 +3. Commit evidence 到当前分支（保证证据随 MR 合并进默认分支可审计）：
28 41 ```bash
29   - git add docs/superpowers/module-reports/<module_id>-test-gate.md
30   - git commit -m "chore(<module_id>): add local test-gate evidence"
  42 + git add docs/superpowers/module-reports/<phase_id>-test-gate.md
  43 + git commit -m "chore(<phase_id>): add local test-gate evidence"
31 44 ```
32 45 4. **`exit_code = 0`** → 调用 `Skill(module-report)`。
33 46 5. **失败** → 打印以下横幅并停止，不调用下游 skill；不自动重试、不自动修复（失败分类需人工判断）：
34 47  
35 48 ```
36 49 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
37   - [test-gate] ⚠️ 未通过
  50 + [test-gate] ⚠️ 未通过 (phase=<phase>)
38 51 失败清单: <子会话 JSON 的 failed 摘要>
39   - 详细证据: docs/superpowers/module-reports/<module_id>-test-gate.md
  52 + 详细证据: docs/superpowers/module-reports/<phase_id>-test-gate.md
40 53  
41 54 按失败类型选恢复路径：
42 55 ① 测试脆弱（偶发 flakey）→ 重跑 /erp-workflow:coding-start
43   - （module-start 幂等：reviews 已全 approve 会跳过功能循环，直接重跑本闸门）
44   - ② 真有回归（某 REQ 破坏其它 REQ 或已合并模块）
45   - → rm docs/superpowers/reviews/*-<REQ-id>.md
46   - → 重跑 /erp-workflow:coding-start（module-start 视该 REQ 未完成，重走功能循环）
47   - ③ 环境/依赖问题（DB 连不上 / 外部 API 失败 / 证书失效）
  56 + （module-start / frontend-start 幂等：reviews 已全 approve 会跳过功能循环，直接重跑本闸门）
  57 + ② 真有回归
  58 + 后端：rm docs/superpowers/reviews/*-<REQ-id>.md
  59 + → 重跑 /erp-workflow:coding-start（module-start 视该 REQ 未完成，重走功能循环）
  60 + 前端：rm docs/superpowers/reviews/*-FE-<NN>.md
  61 + → 重跑 /erp-workflow:coding-start（frontend-start 视该 FE 未完成，重走功能循环）
  62 + ③ 环境/依赖问题（DB 连不上 / 外部 API 失败 / 证书失效 / Playwright 浏览器未装）
48 63 → Skill(interrupt-check) 追加 Blocker 到任一 plan 文件 → 修复环境 → 重跑
49 64 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
50 65 ```
51 66  
52 67 ## 护栏
53 68  
54   -- **绝不**在主会话直接执行 `./scripts/test.sh`，必须通过子会话
  69 +- **绝不**在主会话直接执行 `./scripts/test.sh` / `pnpm test` / `pnpm e2e`，必须通过子会话
55 70 - **绝不**通过 `git push --no-verify` 绕过（hook `deny-no-verify.sh` 会硬拦）
56 71  
57 72 ## 参考
58 73  
59 74 - `${CLAUDE_SKILL_DIR}/templates/test-gate-result-template.md`
60   -- 上游：`module-start`（本模块 REQ 全 approve 后派发到此）
61   -- 下游：`module-report`（绿色时）
  75 +- 上游：`module-start`（后端阶段 REQ 全 approve 后派发到此）；`frontend-start`（前端阶段 FE 全 approve 后派发到此）
  76 +- 下游：`module-report`（绿色时；后端 + 前端共用，phase 由当前分支推断）
... ...
skills/crosscut/coding-start/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: coding-start
3   -description: B 阶段（Coding）入口。验证 Plan 已完成后派发到 module-start；模块定位、分支管理与远程同步全部由 module-start 负责。
  3 +description: B 阶段（Coding）入口与阶段分发器。验证 Plan 完成后做后端 + 前端的完成性检查，每段检查后立即派发：后端未完成 → module-start（写后端）；后端已完成 + 前端未完成 → frontend-start（写前端）；都完成 → 全部完成。本 skill 只做分发，不做 prototype/ 门禁。
4 4 user-invocable: true
5   -allowed-tools: Skill Read Glob Grep Bash(cat *)
  5 +allowed-tools: Skill Read Glob Grep Bash(cat *) Bash(curl *) Bash(jq *)
6 6 ---
7 7  
8 8 **所有输出必须使用中文。**
9 9  
10   -B 阶段（Coding）的入口分发器。
  10 +B 阶段（Coding）的入口分发器。**`module-start` 写后端，`frontend-start` 写前端**——coding-start 在每次入口时按"先后端、再前端"的次序检查并立即派发。本 skill **只做分发，不做 prototype/ 门禁**——前端阶段的前置检查由 `frontend-start` 内部承担。
  11 +
  12 +`module-start` 与 `frontend-start` 互不感知对方。
11 13  
12 14 ## 执行步骤
13 15  
14 16 ### 步骤 0：打印 B 阶段整体流程图
15 17  
16   -每次入口都先展示总图，再做后续校验和派发：
17   -
18 18 ```bash
19 19 cat "${CLAUDE_PLUGIN_ROOT}/skills/crosscut/coding-start/banners/flow-overview.txt"
20 20 ```
21 21  
22 22 ### 步骤 1：确认 docs/08 存在
23 23  
24   -检查 `docs/08-模块任务管理.md`存在。
  24 +检查 `docs/08-模块任务管理.md` 存在。
25 25 - 不存在 → 打印"⚠️ 项目尚未初始化，请先运行 `/erp-workflow:plan-start`"并停下。
26 26  
27 27 ### 步骤 2：Plan 完成性检查
... ... @@ -31,13 +31,30 @@ cat &quot;${CLAUDE_PLUGIN_ROOT}/skills/crosscut/coding-start/banners/flow-overview.tx
31 31 - 任一未勾选 → 提示用户先运行 `/erp-workflow:plan-start` 完成 A 阶段，并停下
32 32 - 全部勾选 → 进入步骤 3
33 33  
34   -### 步骤 3：派发到 module-start
  34 +### 步骤 3：后端完成性检查 + 派发
  35 +
  36 +读 `docs/08 § 二`，对每个后端模块的 `MR:` 字段：
  37 +
  38 +- **任一模块 `MR: —` 或 state ∈ {`opened`, `closed`}** → 后端未完成，打印 `[coding-start] 后端未完成 → 派发 module-start（写后端）`，立即用 Skill 工具调用 module-start，本 skill 结束，不进入步骤 4。
  39 +
  40 +- **所有模块 `MR: !<iid>` 且 state == `merged`**（用API检查）→ 后端已完成，进入步骤 4。
  41 +
  42 +### 步骤 4：前端完成性检查 + 派发
  43 +
  44 +读 `docs/08 § 三 整体 MR:` 字段：
  45 +
  46 +- **`MR: !<iid>` 且 state == `merged`**（用API检查）→ 前端已完成，打印 `所有阶段已完成（后端模块 + 前端阶段均已 merged）`，结束本 skill。
35 47  
36   -打印一句 `[coding-start] → invoke module-start` 后立即用 `Skill` 工具调用 `module-start`。当前模块的定位、MR 状态、分支管理与 REQ 列表全部由 `module-start` 自行处理。
  48 +- **`MR: —` 或 state ∈ {`opened`, `closed`}** → 前端未完成，打印 `[coding-start] 后端已完成、前端未完成 → 派发 frontend-start（写前端）`，立即用 Skill 工具调用 frontend-start，本 skill 结束。
37 49  
38 50 ## 参考
39 51  
40   -- `docs/08-模块任务管理.md § 一`（A0~A5 进度勾选，本 skill 步骤 2 读取）
41   -- `module-start`（下游：模块定位 + REQ 列表 + 推进）
  52 +- `docs/08-模块任务管理.md § 一`（A0~A5 进度勾选，步骤 2 读取）
  53 +- `docs/08-模块任务管理.md § 二`（后端模块元数据 + MR 字段，步骤 3 读取）
  54 +- `docs/08-模块任务管理.md § 三`（前端阶段整体 MR，步骤 4 读取）
  55 +- `.env.local`（GitLab API 凭据，步骤 3 / 4 读取）
  56 +- 下游：
  57 + - `module-start`（写后端：步骤 3 派发）
  58 + - `frontend-start`（写前端：步骤 4 派发）
42 59 - `plan-start`（姊妹入口，A 阶段）
43 60 - `CLAUDE.md`（项目指令）
... ...
skills/crosscut/coding-start/banners/flow-overview.txt
  View file @63ff719
1 1 ┌────────────────────────────────────────────────────────┐
2   -│ 🛠️ 阶段 B：编码（按模块循环） │
  2 +│ 🛠️ 阶段 B：编码（后端模块循环 → 前端整体阶段） │
3 3 │ │
4   -│ coding-start │
5   -│ （Plan 完成校验） │
6   -│ ↓ │
7   -│ module-start │
8   -│ （定位当前模块 + 推进未完成 REQ） │
9   -│ ↓ │
10   -│ ┌─ 功能循环（每个 REQ）─────────────┐ │
11   -│ │ feature-brainstorm │ │
12   -│ │ ↓ │ │
13   -│ │ feature-plan │ │
14   -│ │ ↓ │ │
15   -│ │ feature-tdd │ │
16   -│ │ ↓ │ │
17   -│ │ feature-verify │ │
18   -│ │ ↓ │ │
19   -│ │ feature-review │ │
20   -│ │ ├ approve → 回 module-start │
21   -│ │ └ request-changes ↺ 重跑 verify │
22   -│ │ （自修复 ≤5 轮） │
23   -│ └────────────────────────────────────┘ │
24   -│ ↓ （本模块所有 REQ approve） │
25   -│ test-gate （子会话跑 ./scripts/test.sh） │
26   -│ ↓ │
27   -│ module-report （生成 12 节模块完成报告） │
28   -│ ↓ │
29   -│ mr-create （push + 创建 GitLab MR） │
30   -│ ↓ │
31   -│ 停下，等待人工 Approve + Merge │
32   -│ ↺ 用户重跑 coding-start │
33   -│ ╰──→ 回到 module-start（下一模块） │
  4 +│ coding-start （只做分发） │
  5 +│ ① Plan 完成校验（docs/08 § 一 A0~A5） │
  6 +│ ② 后端完成性检查（§ 二 + GitLab state） │
  7 +│ ├ 未完成 → 立即派发 module-start，结束 │
  8 +│ └ 已完成 → 继续 ③ │
  9 +│ ③ 前端完成性检查（§ 三 整体 MR + state） │
  10 +│ ├ 已完成 → 打印"全部完成"，结束 │
  11 +│ └ 未完成 → 派发 frontend-start，结束 │
  12 +│ │
  13 +│ ┌────┴───────────────────────┐ │
  14 +│ ▼ 写后端 ▼ 写前端 │
  15 +│ │
  16 +│ module-start frontend-start │
  17 +│ 切 module-<id> 分支 ① 检查 prototype │
  18 +│ 缺失 → AskUserQuestion│
  19 +│ ② 准备 FE 清单 │
  20 +│ § 三 已有 → 加载 │
  21 +│ § 三 占位 → AI 推导写入│
  22 +│ （无审阅断点） │
  23 +│ ③ 切 frontend-phase 分支 │
  24 +│ │
  25 +│ ┌─ 后端功能循环（每 REQ）────────┐ │
  26 +│ │ feature-brainstorm │ │
  27 +│ │ ↓ │ │
  28 +│ │ feature-plan │ │
  29 +│ │ ↓ │ │
  30 +│ │ feature-tdd（路径硬护栏） │ │
  31 +│ │ ↓ │ │
  32 +│ │ feature-verify │ │
  33 +│ │ ↓ │ │
  34 +│ │ feature-review │ │
  35 +│ │ ├ approve → 回 module-start │ │
  36 +│ │ └ request-changes ↺ ≤5 轮 │ │
  37 +│ └────────────────────────────────┘ │
  38 +│ ↓ 本模块所有 REQ approve │
  39 +│ test-gate（phase=backend） │
  40 +│ ↓ │
  41 +│ module-report → mr-create │
  42 +│ ↓ 停下，等人工 Approve + Merge │
  43 +│ ↺ 用户重跑 coding-start → coding-start 再分发 │
  44 +│ │
  45 +│ ┌─ 前端功能循环（每 FE-NN）─────┐ │
  46 +│ │ fe-feature-brainstorm │ │
  47 +│ │ ↓ │ │
  48 +│ │ fe-feature-plan │ │
  49 +│ │ ↓ │ │
  50 +│ │ fe-feature-tdd（jsdom + E2E）│ │
  51 +│ │ ↓ │ │
  52 +│ │ fe-feature-verify │ │
  53 +│ │ ↓ │ │
  54 +│ │ fe-feature-review │ │
  55 +│ │ （fe-code-reviewer agent） │ │
  56 +│ │ ├ approve → 回 frontend-start │
  57 +│ │ └ request-changes ↺ ≤5 轮 │ │
  58 +│ └───────────────────────────────┘ │
  59 +│ ↓ 全部 FE approve │
  60 +│ test-gate（phase=frontend） │
  61 +│ ↓ │
  62 +│ module-report → mr-create │
  63 +│ （分支 frontend-phase，docs/08 § 三 整体 MR） │
  64 +│ ↓ 停下，等人工 Approve + Merge │
  65 +│ ↺ 用户重跑 coding-start → 全部完成 │
34 66 └────────────────────────────────────────────────────────┘
... ...
skills/plan/downstream-gen/SKILL.md
  View file @63ff719
1 1 ---
2 2 name: downstream-gen
3   -description: A5 下游文档生æˆâ€”—基于 docs/01 å’Œ docs/03 æŽ¨å¯¼ï¼Œä¸€æ¬¡æ€§ç”Ÿæˆ docs/02 + docs/05 + docs/06 § 五 + docs/10，回填 REQ å¡ç‰‡ä¾èµ–接å£ï¼ŒæŠŠæ¨¡å—清å•è¿½åŠ åˆ° docs/08 § 二。
  3 +description: A5 下游文档生æˆâ€”—基于 docs/01 å’Œ docs/03 æŽ¨å¯¼ï¼Œä¸€æ¬¡æ€§ç”Ÿæˆ docs/02 + docs/05 + docs/06 § 三 + docs/10，回填 REQ å¡ç‰‡ä¾èµ–接å£ï¼ŒæŠŠæ¨¡å—清å•è¿½åŠ åˆ° docs/08 § 二。
4 4 user-invocable: false
5 5 allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(cat *) Bash(cp *)
6 6 ---
... ... @@ -60,10 +60,10 @@ cat &quot;${CLAUDE_PLUGIN_ROOT}/skills/plan/downstream-gen/banners/flow.txt&quot;
60 60  
61 61 ### C. docs/06 — 页é¢æ¸…å•
62 62  
63   -对æ¯ä¸ªæœ‰å‰ç«¯é¡µé¢çš„模å—：读å–并填充 `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`，追加到 `docs/06-UI交互规范.md` § 五。
  63 +对æ¯ä¸ªæœ‰å‰ç«¯é¡µé¢çš„模å—：读å–并填充 `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`，追加到 `docs/06-UI交互规范.md` § 三。
64 64  
65 65 完æˆåŽï¼Œç”¨ `Edit` 在 `docs/08-模å—任务管ç†.md` 中勾选：
66   -- ` - [ ] docs/06 § 五 页é¢æ¸…å•å·²å¡«å…¥`
  66 +- ` - [ ] docs/06 § 三 页é¢æ¸…å•å·²å¡«å…¥`
67 67  
68 68 ### D. docs/08 — 追加模å—清å•
69 69  
... ... @@ -151,7 +151,7 @@ cp &quot;${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md&quot; docs/10-验收检æ
151 151 - `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`
152 152 - `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md`
153 153 - `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md`
154   -- `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`
  154 +- `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`（追加到 docs/06 § 三）
155 155 - `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`ï¼ˆæ¨¡å— bullet 行模æ¿ï¼‰
156 156 - `${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md`
157 157 - `${CLAUDE_SKILL_DIR}/scripts/derive-gitlab.sh`（**用户å¯é€‰è¾…助**：在 add origin 之åŽæ‰‹åŠ¨è·‘一次，自动派生 GITLAB_PROJECT_ID / GITLAB_API_URL 写入 .env.local）
... ...
skills/plan/downstream-gen/templates/docs-02-template.md
  View file @63ff719
... ... @@ -20,5 +20,7 @@
20 20 | {{index}} | **{{req_id}}** | {{module_id}} | {{rationale}} | {{note}} |
21 21 {{/each}}
22 22  
  23 +> **后端模块全部 merged 后**：用户重跑 `/erp-workflow:coding-start` → coding-start 检测到 `backend_done=true && frontend_done=false` → 派发 `frontend-start`。`frontend-start` 步骤 1 自带 prototype/ 门禁（≥ 1 个 `*.html` mockup，缺失则 AskUserQuestion 提示用户补齐）。前端阶段以业务功能（不是 HTML 文件数）为粒度拆分 FE，每个 FE 跑一次 feature 循环（fe-feature-*），最后整个阶段合 1 个 MR（分支 `frontend-phase`，记录在 `docs/08 § 三 整体 MR`）。
  24 +
23 25 ## 三、关键说明
24 26 {{notes}}
... ...
skills/plan/project-init/templates/CLAUDE-template.md
  View file @63ff719
... ... @@ -13,32 +13,61 @@
13 13  
14 14 ---
15 15  
16   -## 🔄 B 阶段开发流程（模块循环 + 功能循环）
  16 +## 🔄 B 阶段开发流程（后端模块循环 → 前端整体阶段）
17 17  
18   -两层嵌套循环**全部固化到 skills**。入口：`/erp-workflow:coding-start`。
  18 +B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-start`。
19 19  
20   -- **模块循环（外）**：`module-start` → `test-gate` → `module-report` → `mr-create` → 人工 Approve MR → 下一模块
  20 +### 阶段路由（coding-start 内，只做分发）
  21 +
  22 +`coding-start` 每次入口做两段完成性检查后真值表派发：
  23 +
  24 +- 后端完成性检查 → `backend_done`（扫 docs/08 § 二 + GitLab state）
  25 +- 前端完成性检查 → `frontend_done`（扫 docs/08 § 三 整体 MR + state）
  26 +
  27 +| `backend_done` | `frontend_done` | 派发 |
  28 +|---|---|---|
  29 +| `false` | 任意 | `module-start`（写后端） |
  30 +| `true` | `false` | `frontend-start`（写前端） |
  31 +| `true` | `true` | "所有阶段已完成" |
  32 +
  33 +前端阶段前置（prototype/ 门禁）由 `frontend-start` 自带，不在 coding-start。`module-start` 与 `frontend-start` **互不感知对方**。
  34 +
  35 +### 后端阶段（每模块一个 MR）
  36 +
  37 +- **模块循环（外）**：`module-start` → `test-gate(phase=backend)` → `module-report` → `mr-create` → 人工 Approve MR → 用户重跑 coding-start → coding-start 再次路由
21 38 - **功能循环（内，每 REQ-XXX-NNN 一遍）**：`feature-brainstorm` → `feature-plan` → `feature-tdd` → `feature-verify` → `feature-review`
  39 +- 后端阶段任务严格落在 `backend/` 路径下；docs/01 REQ 卡片的 UI 描述在此阶段忽略，UI 推迟到前端阶段。
  40 +
  41 +### 前端阶段（整体一个 MR，所有后端模块 merged 后启动）
  42 +
  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 / mr-create 在整体 MR 提交时一并校核（人工只在 MR Approve+Merge 处介入）。
  44 +- **FE 循环（外）**：`frontend-start` → fe-feature 循环 → `test-gate(phase=frontend)` → `module-report(phase=frontend)` → `mr-create`（分支 `frontend-phase`，docs/08 § 三 整体 MR）。
  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）
  46 +- 前端阶段任务严格落在 `frontend/` 路径下；布局以 `prototype/` 为权威。
22 47  
23   -MR 前测试闸门：
24   - - `test-gate`（子会话跑 `scripts/test.sh` 全量——本模块所有 REQ + 已完成模块回归）；
25   - - `.githooks/pre-push` 兜底
26   - - `git push --no-verify` 被 `deny-no-verify.sh` 硬拦。
  48 +### MR 前测试闸门
  49 +
  50 +- `test-gate`：后端阶段子会话跑 `scripts/test.sh`（含本模块新增 + 已合并模块回归）；前端阶段子会话跑 vitest + playwright。
  51 +- `.githooks/pre-push` 兜底；`git push --no-verify` 被 `deny-no-verify.sh` 硬拦。
27 52  
28 53 ---
29 54  
30   -## ✅ 模块完成判定规则
  55 +## ✅ 阶段完成判定规则
  56 +
  57 +`docs/08-模块任务管理.md` 分两段：
  58 +- `§ 二`：后端模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / MR iid / 功能子项）
  59 +- `§ 三`：前端阶段元数据（整体 MR + FE 子项清单，由 `frontend-start` 在所有后端模块 merged 后填入）
31 60  
32   -`docs/08-模块任务管理.md § 二` 是**模块元数据表**——每个模块记录依赖 / 路径 / MR iid / 功能（REQ）子项清单。**模块完成由 `MR:` 字段 + `GitLab API state=merged` 判定**；功能子项勾选只作可视化进度，不参与模块完成判定。
  61 +**阶段完成判定**统一以 `MR:` 字段（§ 二 各模块） / `整体 MR:` 字段（§ 三）+ `GitLab API state=merged` 判定；子项勾选只作可视化进度，不参与完成判定。
33 62  
34   -### 规则定义
  63 +### 后端模块格式
35 64  
36   -每个模块在 docs/08 § 二 中长这样：
  65 +每个后端模块在 docs/08 § 二 中长这样：
37 66  
38 67 ```markdown
39 68 - module_0 系统管理
40 69 - 依赖: —
41   - - 路径: backend/module/sys/, frontend/pages/sys/
  70 + - 路径: backend/module/sys/
42 71 - MR: —
43 72 - 功能:
44 73 - [ ] REQ-SYS-001 用户登录
... ... @@ -46,16 +75,30 @@ MR 前测试闸门：
46 75 ```
47 76  
48 77 - `MR:` 字段由 `mr-create` 在创建 MR 时从 `—` 改为 `!<iid>`。
49   -- 每个 `REQ-*` 子项由 `feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`
50   -- 子项全部勾选不等于模块完成，模块完成判定仍以 `MR:` + GitLab API state 为准。
  78 +- 每个 `REQ-*` 子项由 `feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。
  79 +- 路径限定为后端目录（如 `backend/module/sys/`）；前端代码不在此阶段产生。
  80 +
  81 +### 前端阶段格式（§ 三）
  82 +
  83 +```markdown
  84 +- 整体 MR: —
  85 +- 功能:
  86 + - [ ] FE-01 用户登录与注册 ｜ 关联 REQ：REQ-SYS-001, REQ-SYS-002 ｜ 关联原型：prototype/auth.html
  87 + - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html
  88 +```
  89 +
  90 +- `整体 MR:` 字段由 `mr-create` 在创建前端 MR 时从 `—` 改为 `!<iid>`。
  91 +- "功能:" 列表由 `frontend-start` 进入时由 AI 自主推导写入（无人工审阅断点）。FE 是业务功能粒度，与 prototype HTML 文件数无关；合理性由 fe-feature-review / 整体 MR 时统一校核。
  92 +- 每个 `FE-NN` 子项由 `fe-feature-review` 在 `verdict=approve` 时自动勾选为 `[x]`。
  93 +- 进入前端阶段前 `frontend-start` 步骤 1 自带 prototype/ 门禁，强制检查项目根 `prototype/` 至少含 1 个 `*.html` mockup。
51 94  
52   -### 模块状态语义
  95 +### 状态语义（后端模块 + 前端阶段共用）
53 96  
54 97 | `MR:` 字段 | `GitLab API state` | 含义 | 你（Claude Code）的行为 |
55 98 |---|---|---|---|
56   -| `—` | — | 模块未开始（未创建 MR） | ✅ 开始本模块开发 |
57   -| `!<iid>` | `opened` / `closed` | 模块开发中 / 打回 | ✅ 继续推进该模块 |
58   -| `!<iid>` | `merged` | 模块**已完成** | 🟢 进入下一未完成模块 |
  99 +| `—` | — | 该阶段未开始（未创建 MR） | ✅ 开始该阶段开发 |
  100 +| `!<iid>` | `opened` / `closed` | 阶段开发中 / 打回 | ✅ 继续推进该阶段 |
  101 +| `!<iid>` | `merged` | 阶段**已完成** | 🟢 后端：进入下一未完成模块；后端全完 → 前端阶段；前端 merged → 全部完成 |
59 102  
60 103 ### 模块完成报告
61 104  
... ... @@ -90,7 +133,7 @@ MR 前测试闸门：
90 133 ### 你禁止做的 🚫
91 134  
92 135 1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约
93   -2. **手动 Edit `docs/08 § 二` 的 `MR:` 字段**，必须要由 `mr-create` 自动回写
  136 +2. **手动 Edit `docs/08 § 二/§ 三` 的 `MR:` / `整体 MR:` 字段**，必须要由 `mr-create` 自动回写
94 137  
95 138 ### Schema 演化规约（Flyway migration）
96 139  
... ...
skills/plan/project-init/templates/docs-08-initial-template.md
  View file @63ff719
... ... @@ -36,21 +36,35 @@
36 36 - [ ] A5 下游文档生成 — downstream-gen
37 37 - [ ] docs/02 开发计划已生成
38 38 - [ ] docs/05 API 契约已生成
39   - - [ ] docs/06 § 五 页面清单已填入
  39 + - [ ] docs/06 § 三 页面清单已填入
40 40 - [ ] docs/10 验收清单已生成
41 41 - [ ] 下方模块列表已填入
42 42 - [ ] REQ 卡片依赖接口已回填
43 43  
44   -## 二、Coding 阶段（按模块循环）
  44 +## 二、Coding 阶段（后端模块循环）
45 45  
46   -（A5 填入后，每行一个模块。每个模块的 `MR:` 字段在 `—` 和 `!<iid>` 之间变化，完成由 GitLab API `state=merged` 判定。`coding-start` 每次按 docs/02 REQ 序扫每模块的 MR state 决定派发。）
  46 +（A5 填入后，每行一个后端模块。每个模块的 `MR:` 字段在 `—` 和 `!<iid>` 之间变化，完成由 GitLab API `state=merged` 判定。`coding-start` 每次按 docs/02 REQ 序扫每模块的 MR state 决定派发。后端模块全部 merged 后自动进入 § 三 前端阶段。）
47 47  
48 48 <!-- 模块格式示例（由 A5 downstream-gen 追加；功能子项由 feature-review 在 approve 时勾选）：
49 49 - module_0 系统管理
50 50 - 依赖: —
51   - - 路径: backend/module/sys/, frontend/pages/sys/
  51 + - 路径: backend/module/sys/
52 52 - MR: —
53 53 - 功能:
54 54 - [ ] REQ-SYS-001 用户登录
55 55 - [ ] REQ-SYS-002 用户注册
56 56 -->
  57 +
  58 +## 三、Coding 阶段（前端整体）
  59 +
  60 +（`frontend-start` 进入时扫 prototype/ + docs/01 + docs/05 → AI 自主推导 FE 业务功能清单写到下方"功能:"项（无人工审阅断点；合理性由整体 MR 时统一校核）。已有清单则直接加载。整个前端阶段 1 个 MR，分支 `frontend-phase`。）
  61 +
  62 +- 整体 MR: —
  63 +- 功能:
  64 + <!-- AI 进入时按以下行格式写入（每行 1 个 FE，可关联多个 REQ / 多份原型）：
  65 + - [ ] FE-NN 功能名 ｜ 关联 REQ：REQ-A, REQ-B ｜ 关联原型：prototype/<file>.html, prototype/<other>.html
  66 +
  67 + 示例：
  68 + - [ ] FE-01 用户登录与注册 ｜ 关联 REQ：REQ-SYS-001, REQ-SYS-002 ｜ 关联原型：prototype/auth.html
  69 + - [ ] FE-02 仪表盘总览 ｜ 关联 REQ：REQ-DASH-001 ｜ 关联原型：prototype/dashboard.html
  70 + -->
... ...
skills/plan/skeleton-gen/templates/docs-06-static-template.md
  View file @63ff719
1 1 <!--
2   -本文件是 docs/06-UI交互规范.md 的 § 一~四 大纲（§ 五由 downstream-gen 追加）。
  2 +本文件是 docs/06-UI交互规范.md 的 § 一~二 大纲（§ 三由 downstream-gen 追加）。
3 3 skeleton-gen 读取 docs/04 § 零 和 docs/01 index，按下述大纲生成项目专属内容。
4   -UI 细节（布局参数、颜色、组件选型）来自 § 零 前端 UI 组件库。
  4 +布局/页面骨架以项目根的 prototype/ 静态 HTML mockup 为权威，本文件仅承载跨页面通用规则与 Design Tokens。
5 5 -->
6 6  
7 7 # 06-UI交互规范
8 8  
9   -## 一、整体布局
  9 +> 本项目所有页面布局以项目根 `prototype/` 目录下的静态 HTML mockup 为权威。前端阶段（fe-feature-*）实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。
10 10  
11   -### 1.1 页面框架
12   -<!-- 基于 § 零 UI 组件库（如 Ant Design Layout）描述整体骨架：Header / Sider / Content。 -->
  11 +## 一、通用交互规则
13 12  
14   -### 1.2 布局参数
15   -<!-- 表格形式：Header 高度 / Sidebar 宽度 / 内边距 / 最小分辨率，给出默认值。 -->
16   -
17   -## 二、标准页面类型
18   -<!-- 根据 docs/01 index 的模块索引推断业务可能出现的页面类型（通常列表/表单/详情/树形 4 类，根据项目裁剪）。 -->
19   -
20   -### 2.1 列表页
21   -<!-- 顶部操作区 + 搜索栏 + 表格 + 分页，关键组件选型。 -->
22   -
23   -### 2.2 表单页
24   -<!-- Drawer 还是独立页；校验时机；提交按钮位置。 -->
25   -
26   -### 2.3 详情页
27   -<!-- Descriptions + Tabs 的组合方式。 -->
28   -
29   -### 2.4 树形管理页
30   -<!-- 如项目有组织架构/权限树/分类树才生成此节，否则删除。 -->
31   -
32   -## 三、通用交互规则
33   -
34   -### 3.1 操作反馈
  13 +### 1.1 操作反馈
35 14 <!-- 成功/失败消息；危险操作二次确认；长耗时按钮 loading 态。 -->
36 15  
37   -### 3.2 数据展示
  16 +### 1.2 数据展示
38 17 <!-- 空状态 / 加载 / 异常 的统一组件与文案。 -->
39 18  
40   -### 3.3 权限控制（前端）
  19 +### 1.3 权限控制（前端）
41 20 <!-- 菜单级 / 按钮级 / 路由级的控制方式，关联后端 RBAC。 -->
42 21  
43   -## 四、Design Tokens
  22 +## 二、Design Tokens
44 23  
45 24 <!-- 所有色值统一以 CSS 变量定义于 src/styles/tokens.css；命名规范见 docs/04 § 2.5。 -->
46 25  
47   -### 4.1 全局调色板
  26 +### 2.1 全局调色板
48 27 <!-- 与 § 零 UI 库主题对齐：列名 = 语义 / 变量名 / 默认值 / 用途。
49 28 至少含：主色/成功/警告/错误/主文字/次文字/边框/背景。 -->
50 29  
51   -### 4.2 组件级状态色
  30 +### 2.2 组件级状态色
52 31 <!-- 场景 × 状态映射表：列名 = 序号 / 组件 / 编辑bg / 只读bg / 悬浮bg / 编辑fg / 只读fg / 悬浮fg / 备注。
53 32 单元格写 token 名（var(--color-xxx) 形式），不写 hex；"—" 表示该状态不适用。
54 33 表后追加「Token 默认值」表，列出每个 --color-xxx 在 tokens.css 的默认值。 -->
55 34  
56   -### 4.3 引用约定
  35 +### 2.3 引用约定
57 36 <!-- 一句话三条：
58 37 - 组件样式只用 var(--color-xxx)，禁止硬编码
59   - - 新增 token 须先登记到 § 4.1/4.2 再补 tokens.css
  38 + - 新增 token 须先登记到 § 2.1/2.2 再补 tokens.css
60 39 - 修改色值只改 tokens.css 一处，不允许组件覆盖 -->
61 40  
62   -## 五、页面清单
  41 +## 三、页面清单
63 42 （由 `downstream-gen` 按模块追加段落）
... ...