docs(README): drop duplicated diagrams, deleted-feature footnotes, and implementation rationale

zichun
1 parent be09a0b7
Showing 1 changed file with 7 additions and 72 deletions
README.md
@@ -2,7 +2,7 @@
  
 Claude Code 插件：ERP / 后端管理系统全流程开发框架。
  
-把"从零到 N 个模块上线 + 前端整体阶段"的整个流程固化成 **9 个 skill**（Plan 阶段 8 个交互 skill = `plan-start` 分发器 + A0~A6 七个；外加 B 阶段瘦入口 `coding-start`）**+ 1 个 Workflow（`workflows/coding.mjs`，Coding 阶段，全自动静默）+ 1 个 reviewer agent + 4 个跨平台 Node 助手（`lib/*.mjs`）+ 25 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、纯本地 git 的前提下推进编码。Plan 阶段把全部需求/配置/前端约定问询前移：A 阶段过程中各 skill 自承的小闸门 + `plan-start` 终结时统一跑的 5 项前移硬闸（REQ 真实数据 / secrets+config-vars / docs/04 § 零 命令 / docs/05+02 评审 / A6 前端 scope）；Coding 阶段整体是单个 Workflow 脚本，子代理无法弹窗 → 结构性静默，后端按模块循环依次打里程碑 tag，所有后端模块打里程碑后进入前端整体阶段（以项目根 `prototype/` 静态 HTML mockup 为页面权威）。
+从零到 N 模块上线的 ERP 全流程开发框架：Plan 阶段交互、Coding 阶段静默 Workflow。
  
 ## 这个插件做什么
  
@@ -69,24 +69,13 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。
    - **第二段（REQ 审阅完重新运行）**：继续 **A2 → A3**（生成骨架 / 从 REQ 正向设计 `docs/03-数据库设计文档.md` 并回填 REQ 依赖表）后再次**停下**，等你审阅 docs/03 的表 / 字段 / 索引 / 外键（第二个人工关口：数据库 schema —— A4 会基于它翻译 DDL 并 apply 到 MySQL，所以这关口与 REQ 审阅同等重要）
    - **第三段（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 终结硬闸** 后再次**停下**
  
-   每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次运行同样的命令即可恢复。Plan 阶段把全部需求/配置/前端约定问询前移：A1 锁结构化 REQ 字段 + secrets/account/包名/命名 + 各 stack 的 build/lint/unit/e2e 命令；A5 后强制评审 docs/05 + docs/02；A6 锁前端约定。这些闸门全过，**Plan 终结硬闸** 才放行。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:coding-start`。
-
-   > 两个审阅断点的处理方式一致：A1 / A3 完成时 skill 已自动勾选 `docs/08-模块任务管理.md § 一` 该阶段的全部子项 + 顶层；审阅是隐式的——你看完 REQ 卡片 / docs/03 后直接重新运行 `/plan-start`，下次入口就会派发到下一阶段。如果审阅时发现需要修订，直接编辑 docs/01 / docs/03 即可，不依赖 docs/08 的勾选状态。
+   Plan 完成后不会自动进入编码，需手动 /erp-workflow:coding-start。
  
 3. **Coding 阶段入口**（单个 Workflow，后端模块循环 → 前端整体阶段，全自动静默）：
    ```
    /erp-workflow:coding-start
    ```
-   Plan 全部完成后由你显式触发。`coding-start` 是一个**瘦入口 skill**：校验 Plan 终结闸（docs/08 § 一 全勾、git 在默认分支、工作树干净）后，调用 `Workflow({scriptPath:"${CLAUDE_PLUGIN_ROOT}/workflows/coding.mjs", ...})` 启动整个编码阶段，然后告知"已在后台启动，跑完或 halt 时通知"。**所有编码逻辑都在 `coding.mjs` 里**，不再有 B 阶段 skill 链。
-
-   **`coding.mjs` 的阶段（子代理执行，无弹窗）**：
-
-   - **Router**：扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 `git tag -l`，产出结构化模块清单（`{id, done, reqs[], feItems[]}`），过滤出待跑模块。docs/08 字段与 git tag 不一致 → halt 报错（绝不静默假设完成状态）。Router 后做运行时互斥断言（后端模块 `feItems` 必空、`frontend-phase` 聚合模块 `reqs` 必空），契约违例直接 halt。
-   - **后端模块循环**（顶层 `for module`，fail-fast）：每模块依次 `runBranchSetup(module-<id>)`（**JS 编排**幂等切/建功能分支，见下方"JS 编排 vs LLM prompt"）→ `featureLoop(reqs, 'backend')` 顺序 for-await 跑（spec → plan → tdd → verify → review）。三类有界重试：tdd 同一测试连续修复超过 **10 次** → halt；review **5 轮**仍未 approve → halt；testGate 红色**自动重试 1 次**防 flaky、仍红 → halt。任一 halt 由顺序 for-await 冒泡到模块主循环 try → 捕获 → 整阶段 break。绿则继续 `runCrossModule`（**JS 编排** diff/分类/写日志）→ `reportPrompt`（LLM 12 节叙述报告）→ `runMilestone`（**JS 编排**本地 `git merge --no-ff` 进默认分支 + 打 `milestone/<id>` tag + 回写 docs/08 § 二 + 替换报告 § ⑫ 占位；跨重入幂等）。
-   - **前端阶段**（后端全部打里程碑后）：`runBranchSetup(frontend-phase)` → `featureLoop(feItems, 'frontend')`（FE-NN，路径限 `frontend/`，review 调统一 `code-reviewer` agent 附加前端 7 维 checklist）→ `testGate(frontend)` → `runMilestone`（docs/08 § 三 整体里程碑 `milestone/frontend-phase`）。
-   - **halt 终止态**：子代理缺值不弹窗 → 写阻塞点并抛错；整阶段 fail-fast，halt 后停下等人工修复，修好重跑 `/erp-workflow:coding-start` 从断点续跑（`runBranchSetup` / `runMilestone` 内的 read-then-decide 幂等支持续跑）。
-
-   `docs/08 § 二` 每后端模块占一行 bullet，`§ 三` 是前端阶段整体段，完成信号统一由本地 `git tag -l 'milestone/<id>'` 判定。
+   Plan 全部完成后由你显式触发；详细职责见下方 Skill 清单。详细流程见上方阶段 B 流程图。
  
 4. **中途恢复**：任何时候重跑 `/erp-workflow:coding-start`——`coding.mjs` 的 Router 根据 docs/08 § 二/§ 三 里程碑字段 + 本地 git tag 跳到当前该做的模块/阶段。
  
@@ -121,11 +110,7 @@ erp-workflow-plugin/
         └── coding-start/            # 启动 workflows/coding.mjs
 ```
  
-## Hook 清单（0 个）
-
-本插件**不再注册任何 hook**。原"跨模块改动留痕"hook（`log-cross-module.sh`）已删除，其职责由 `workflows/coding.mjs` 的 cross-module stage 在模块循环内承担。
-
-## Skill 清单（9 个，按阶段分组于 `skills/{plan,coding}/`；slug 由 SKILL.md frontmatter 决定，未受目录调整影响）
+## Skill 清单（9 个）
  
 ### 入口（2 个）
  
@@ -134,7 +119,7 @@ erp-workflow-plugin/
 | `plan-start` | **A 阶段入口 + Plan 终结硬闸**。读 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill（含 A6 → `frontend-scope-lock`）；A 全部完成时校验 5 项前移闸门（REQ 真实数据、`.env.local` secrets 全锁 + `config-vars.yaml` 配置字段全锁、docs/04 § 零 命令齐、docs/05+02 已评审、A6 前端 scope 已锁），全过才提示运行 `/erp-workflow:coding-start`，否则指出缺口不放行 | **用户手动** `/erp-workflow:plan-start` |
 | `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` |
  
-### Plan 阶段 A skill（7 个 = A0~A6，均由 `plan-start` 按 docs/08 § 一 顺序派发）
+### Plan 阶段 A skill（A0~A6，共 7 个）
  
 | # | Skill | 作用 | 流程中谁调用 |
 |---|---|---|---|
@@ -148,53 +133,7 @@ erp-workflow-plugin/
  
 ### Coding 阶段（1 个 Workflow，非 skill）
  
-整个编码阶段不再是 skill 链，而是单个 Workflow 脚本 **`workflows/coding.mjs`**（由瘦入口 skill `coding-start` 启动）。子代理无法弹窗 → 缺值即写阻塞点并 halt（结构性静默）。
-
-```
-coding-start（skill）校验 Plan 终结闸 → Workflow({scriptPath:"…/workflows/coding.mjs"})
-        │
-        ▼  coding.mjs（各 stage 派 agent 子代理执行，无弹窗）
-   Router  ── 解析 docs/08 § 二/§ 三 + git tag → 结构化模块清单（schema 校验）
-        │     docs/08 字段与 git tag 不一致 → halt；运行时断言 reqs/feItems 互斥
-        │
-   顶层 for module（fail-fast，halt 后 break）：
-        │
-        ├─ 后端：
-        │      runBranchSetup(module-<id>)        ← JS 编排（5 微 agent）
-        │   → featureLoop(module.reqs, 'backend')  ← 顺序 for-await
-        │      spec → plan → tdd → verify → reviewWithFixLoop（有界 5 轮：
-        │      review(code-reviewer) approve → 过；request-changes → fix → 重审；
-        │      第 5 轮仍未过 → throw HALT，由 for-await 冒泡到主循环）
-        │   → testGate(backend)（红色自动重试 1 次防 flaky，仍红 → HALT）
-        │   → runCrossModule(module)              ← JS 编排（4 微 agent：默认分支 → diff → 分类 → 写日志）
-        │   → reportPrompt（LLM 12 节叙述报告）
-        │   → runMilestone(module)                ← JS 编排（10+ 微 agent，跨重入幂等）
-        │      wt → default → 已合入? → merge → 字段当前值? → 写字段 + commit
-        │      → tag 存在? → 打 tag → 报告 § ⑫ 当前值? → 替换占位 + commit
-        │
-        └─ 前端（module.feItems 非空时，后端全部打里程碑后）：
-               runBranchSetup(frontend-phase)
-            → featureLoop(feItems, 'frontend')（FE-NN，路径限 frontend/，
-              review 调 code-reviewer + 前端 7 维 checklist）
-            → testGate(frontend) → runMilestone（docs/08 § 三 整体里程碑）
-```
-
-#### featureLoop 顺序 for-await（非 pipeline）
-
-`coding.mjs` 把后端/前端功能链同构为一个 `featureLoop(items, phase)`（替代旧 10 个克隆 skill），实现上采用**顺序 for-await**（**非 pipeline**）：tdd/fix stage 共享单工作树 + 同一功能分支做 git commit，并发会争 `.git/index.lock` 且撞 migration `V<n>` 版本号；同时 pipeline 的"stage throw → item null"语义会吞掉 `reviewWithFixLoop`/`verify`/`tdd` 的 HALT throw 而让残缺模块照打 tag。顺序 for-await 让 throw 自然冒泡到主循环 try → fail-fast。`reviewWithFixLoop` 有界 5 轮且要求 reviewer 返回 `request-changes` 时 `issues` 非空（否则 halt 暴露 reviewer 契约违例）；`testGate` 失败自动重试 1 次。
-
-#### JS 编排 vs LLM prompt：哪些是 `run*` 哪些是 `*Prompt`
-
-`coding.mjs` 里两种 stage 实现形态，按"步骤是否需要 LLM 判断"分：
-
-| 形态 | 适用 | 示例 stage | 工作方式 |
-|---|---|---|---|
-| **`run*`（JS 编排）** | 纯机械的 git/文件操作 + 条件跳过；步骤本身有结构化 in/out | `runBranchSetup` / `runMilestone` / `runCrossModule` | JS 把流程切成多个单职责微 `agent()`，每个微 agent 带强 schema 返回（`WT_SCHEMA` / `DEFAULT_BRANCH_SCHEMA` / `FIELD_VALUE_SCHEMA` / `EXISTS_SCHEMA` / …）。所有"已是目标态则跳过"的分支由 **JS 在结构化返回上判定**，不再依赖子代理读"1. 2. 3. 若 X 则跳过"散文。action 步统一返回 `ACTION_RESULT_SCHEMA = {success, error?, detail?}`，JS 在 `success=false` 时显式抛 `HALT …` 让主循环 try catch break。idempotency 因此结构性可靠——续跑时同一微 agent 再读一次状态、JS 再判一次、得到同一决策。 |
-| **`*Prompt`（LLM 叙述）** | 真正需要 LLM 判断 / 上下文综合 / 文本生成的 stage | `routerPrompt` / `deriveSpecPrompt` / `planPrompt` / `tddPrompt` / `verifyPrompt` / `gatePrompt` / `reviewPrompt` / `fixPrompt` / `reportPrompt` | 一段较长的中文 prompt 文本，子代理读完后自由发挥实现意图（写 spec / 写 plan / 跑 TDD / 出 12 节报告 等）。结构化的部分仍走 schema（router / review / gate 都用 schema 约束最终结论）。 |
-
-> 完成信号统一由本地 `git tag -l 'milestone/<id>'` 判定，**不依赖任何远程仓库 / push**。
-
-> 旧 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` 的各 `*Prompt` 与 `run*` 编排函数；中断/跨模块留痕由 workflow 的 halt 终止态 + `runCrossModule` 承担（替代被删 hook）。
+整个编码阶段不再是 skill 链，而是单个 Workflow 脚本 **`workflows/coding.mjs`**（由瘦入口 skill `coding-start` 启动）。子代理无法弹窗 → 缺值即写阻塞点并 halt（结构性静默）。完整流程见本文档顶部「阶段 B：编码」流程图。
  
 ## Agent 清单（1 个）
  
@@ -232,8 +171,6 @@ coding-start（skill）校验 Plan 终结闸 → Workflow({scriptPath:&quot;…/workf
 | downstream-gen | `docs-10-header-template.md` | docs/10 验收清单（项目级 SOP，零槽位 + 引用指针） |
 | frontend-scope-lock | `fe-scope-template.md` | A6 前端 scope：UI 约定 / design tokens / 组件库 / 每个 FE-NN 设计决策表 |
  
-**流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。Coding 阶段的渲染/校验逻辑改由 `lib/*.mjs` 助手承担，不再用 skill 模板。
-
 ## 前置依赖
  
 - **Node.js ≥ 18**：`lib/*.mjs` 助手 + `workflows/coding.mjs` + 生成进目标项目的 `scripts/*.mjs` 均为 ESM；CC 运行时自带。A0 `project-init` 检测 git / mysql / node 在 PATH，缺失则按 OS 打印安装指引并 halt（不自动安装）
@@ -245,6 +182,4 @@ coding-start（skill）校验 Plan 终结闸 → Workflow({scriptPath:&quot;…/workf
  
 ## 设计原则
  
-参见 `skills/project-init/templates/CLAUDE-template.md` 末尾的「🧭 通用工作准则」4 条：① Think Before Coding ② Simplicity First ③ Surgical Changes ④ Goal-Driven Execution。
-
-最关键的 1 条："**所有测试与验证派发到全新子会话执行，主会话只接收结构化结论**"——避免主会话被测试输出污染，并让测试结果作为独立证据存档。
+参见 `skills/plan/project-init/templates/CLAUDE-template.md` 末尾的「🧭 通用工作准则」。