@gordon.gan/specflow 1.4.3-beta → 1.4.4-beta

package/skills/specflow-approval/SKILL.md

@@ -80,13 +80,71 @@ change names, file paths, commands, and code in their original form.
    - `Cargo.toml` → Rust
    - `tsconfig.json` → TypeScript (refines Node detection)
    - If none match, set `techStack: unknown`
-5. **Detect database stack** (for §4.4 guidance). Follow
+5. Set `projectMode`:
+   - `greenfield` — no meaningful application source yet (no `src/`/`app/`/`internal/`/`lib/`
+     with real code, or only empty scaffold); Pass 6 will be SKIPPED greenfield
+   - `brownfield` — existing product code to ground against
+6. **Detect database stack** (for §4.4 guidance). Follow
    `prompts/approval/database-guidance.md` §1 — set
    `dbStack: mysql|postgresql|oracle|redis|elasticsearch|none`. Prefer OLTP
    (`mysql`/`postgresql`/`oracle`) over cache/search when multiple match.
-6. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
+7. **Scan four artifacts for tech selection coverage** (proposal / design / tasks / specs):
+   look for explicit choices on: 前端、后端、数据库与缓存、基础设施(含 CI/部署/云)。
+   Set `stackCoverage: complete | partial | missing`.
+8. **Detect `uiInScope`** (follow `prompts/approval/frontend-guidance.md` §1):
+   UI/控制台/页面/组件 signals → `uiInScope=yes|no`. When yes, check FE 五元组 coverage
+   (Framework / Styling / State / UI kit / FE testing); incomplete counts as
+   `stackCoverage=partial` for 前端.
+9. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
+
+Announce: "Generating technical approval document for change `<name>` (phase=refined,
+language=<lang>, projectMode=<greenfield|brownfield>, techStack=<stack>, dbStack=<db>,
+uiInScope=<yes|no>, stackCoverage=<complete|partial|missing>)."
 
-Announce: "Generating technical approval document for change `<name>` (phase=refined, language=<lang>, techStack=<stack>, dbStack=<db>)."
+---
+
+## Gate: Tech Stack Intake (0→1 / 四件套缺选型)
+
+**Trigger** (any):
+
+- `projectMode = greenfield`, **or**
+- `stackCoverage = missing | partial` for dimensions this change needs
+  (e.g. UI change needs 前端; persistence needs 数据库与缓存; ship needs 基础设施)
+
+**Do NOT** invent a full stack. **STOP and ask the user** in chat (structured), then wait:
+
+```text
+本变更需要补全技术选型（四件套未写清 / 0→1 绿场）。请确认或补充下列方向
+（可写「本变更不涉及」跳过某一维）:
+
+1. 前端：Framework / Styling / State / UI kit / FE testing（五元组；或不涉及前端）
+2. 后端：语言/框架、API 风格(HTTP/gRPC/…)、进程模型
+3. 数据库与缓存：主存(MySQL/PG/…)、缓存(Redis/…)、搜索(若有)
+4. 基础设施：运行环境(K8s/VM/Serverless)、CI/CD、对象存储/消息队列(若有)
+5. 其它约束：公司强制栈、禁止项、必须复用的现网组件
+
+若本变更含 UI 且前端仍不清，追问（可合并一次问完）:
+- 关键页面/路由清单（或「沿用现网，本迭代只改某页」）
+- 验证命令（dev / test / e2e / browser）
+- （可选）若用 v0/Lovable 等 AI builder：导出与本地可构建计划
+
+回复示例：
+前端 Next.js+TS / Tailwind / Zustand / shadcn / Vitest+Playwright；
+后端 Go+Gin；DB MySQL 8 + Redis；基础设施 K8s + GitHub Actions；
+禁止自建消息队列，复用公司 Kafka。
+```
+
+After the user answers:
+
+1. Record answers for §2.2 技术选型 + fold into §2.4 决策评审表 (new D-rows).
+2. Suggest (do not force) updating `design.md` via `/specflow:refine` later; approval may
+   proceed with chat-confirmed stack for this `approval.md` only.
+3. Re-run dbStack detection if the user named a DB; re-check FE 五元组 if UI in scope.
+4. Continue subsequent stages.
+
+If the user refuses to choose and the change clearly needs a stack → mark
+`[待 refine 澄清: 技术选型]` and **do not** fabricate architecture/DDL/页面树 around a
+guessed stack.
 
 ---
 
@@ -95,36 +153,30 @@ Announce: "Generating technical approval document for change `<name>` (phase=ref
 Read these files and follow them:
 
 1. `.claude/specflow/prompts/approval/generate.md` (or repo `prompts/approval/generate.md`)
-2. `prompts/approval/database-guidance.md` — DB **guidance pack** router for packs under
-   `{ide}/specflow/guidance/database/` (installed by init; **not** an IDE skill) with
-   package fallback `skills/database/`. **Not an MCP tool**: on `dbStack` hit, `Read`
-   matched `SKILL.md` + focused references; on `none` or missing files, LLM-only §4.4.
-   Never "invoke `/mysql` skill" — always `Read` a resolved path.
-
-`generate.md` + `database-guidance.md` together specify:
-
-- The 7-dimension closed-loop verification (Passes 1–7, each with AI self-prompt, verdict rules, evidence format)
-- The design quality assessment (over-engineering signals + extensibility signals)
-- The architecture design (Mermaid diagrams + **图要点说明** + core-component table)
-- The detailed design generation (设计要点一览 + Happy Path 完整时序 + 业务场景时序与说明 +
-  data ER/DDL + interfaces inventory/fields/examples/errors + logic/config/compat)
-- The test strategy (layered test matrix mapped to §5 acceptance criteria)
-- The deployment/release/rollback plan
-- The implementability assessment (7 dimensions with verdict rules)
-- The approval document structure and generation rules
-- Protocol-marker preservation and language policy enforcement
-- §1 绪论与边界 (proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**;
-  pain-point diagram, User Journey, Non-Goals with reasons)
-- Document order: §1 绪论 → §2 评估 → §3 架构 → §4 详细设计 → **§5 验收标准** → §6 测试 → …
-- **Quality Gates G1–G4** + **Style & Tone** (hard rules in generate.md Part E)
-- **DB guidance router** (`database-guidance.md` + guidance pack `database`): match project
-  stack → resolve `{ide}/specflow/guidance/database/<stack>/` (or package `skills/database/`)
-  → `Read`; miss → LLM-fallback. Packs are **not** installed under IDE `skills/` discovery.
-  stack → Read in-repo skill; no hit → LLM fallback; **never** fetch remote skills / MCP wrap
-- Anchor-file extraction and code-reading rules (depth: anchor file only, no recursion)
-
-You MUST read `generate.md` before performing any analysis or writing `approval.md`. Do not
-invent the assessment dimensions or document structure — they are defined in that prompt.
+2. `prompts/approval/database-guidance.md` — SpecFlow DB **guidance pack** router
+3. `prompts/approval/frontend-guidance.md` — UI scope + FE 五元组 + §4.6 contract
+4. `prompts/approval/project-conventions-guidance.md` — **project** skill/rule/docs
+   lazy-load (architecture / api / database / frontend); cross-IDE path resolve;
+   priority **project > SpecFlow guidance > LLM**
+
+`generate.md` + convention/DB/FE routers together specify:
+
+- The 7-dimension closed-loop verification (Passes 1–7)
+- Design quality, architecture, detailed design, test/deploy (optional chapters), implementability
+- Document order: §1 → §2 → §3 → §4 → **(optional §5)** → §6 → **(optional §7/§8)** → §9 → §10(签字栏 only)
+- **Quality Gates G1–G6** + **Style & Tone**(含禁止正文代码腔)
+- **Optional chapters** §5 / §7 / §8 — ask before write; **AI 预审** chat-only
+- **Project conventions** lazy-load before §3/§4.4/§4.5/§4.6; **project > SpecFlow guidance > LLM**
+- **DB guidance** after project DB conventions; resolve
+  `{ide}/specflow/guidance/database/<stack>/` (or package `skills/database/`); record
+  项目约定 + DB 技能 + `dbStack` in §4.4.1; never fetch remote / MCP
+- **FE guidance** when `uiInScope=yes`: `frontend-guidance.md` §3 **must** scan
+  IDE skills/rules + 落地文档(组件/路由/状态/表单/样式/a11y/测试) + `topic=frontend`;
+  §4.6 cites 项目约定 + IDE skills/rules; G5/G6; Visual Loop; never invent page trees
+- **Tech stack intake**: greenfield or four-artifacts missing 前端/后端/数据库与缓存/基础设施
+  → ask user before inventing stacks; FE needs 五元组; record in §2.2; never fabricate
+
+You MUST read `generate.md` before any analysis or writing `approval.md`.
 
 ---
 
@@ -181,9 +233,10 @@ After all 7 Passes:
 - `PASS WITH WARNINGS` if no `FAIL` but at least one `WARNING`
 - `PASS` if all Passes are `PASS` (a `SKIPPED` Pass does not affect the verdict)
 
-When writing `approval.md` **§8**, use the **single compact table** only (see generate.md
-Part E §8): no per-Pass long sections, no duplicate summary table. Expand evidence only
-for ⚠️/❌ rows (max 2–3 bullets).
+When writing `approval.md` **§8** (only if the user opted in), use the **single compact
+table** only (see generate.md Part E §8). Always run Passes 1–7 for the **chat** summary
+even when §8 is omitted from the document. Expand evidence only for ⚠️/❌ rows
+(max 2–3 bullets); PASS/SKIPPED stay one line.
 
 ---
 
@@ -227,9 +280,11 @@ Scan `design.md` for the 5 extensibility signals:
 
 ## Stage 6: Architecture Design
 
-Produce the **architecture design** section (approval.md **§3** 架构整体设计) defined in
-`generate.md` Part E. This answers "what modules make up the system, how they depend on
-and interact with each other, and what each module's responsibility and boundary is."
+**Before drafting §3**: follow `project-conventions-guidance.md` with `topic=architecture`
+(lazy-load ≤3 project convention files). Apply project bans to 图要点; cite path or「未发现」.
+
+Produce the **architecture design** section (approval.md **§3**) defined in
+`generate.md` Part E.
 
 It is complementary to Detailed Design: architecture is about **module-to-module
 relationships** (macro), detailed design is about **module-internal implementation**
@@ -278,22 +333,30 @@ Produce the **detailed design** section (approval.md **§4** 方案详细设计)
 
 **Selective** categories; uninvolved ones get explicit「不涉及 X」markers.
 
-Order and hard requirements (from `generate.md` §4.1–4.8):
+Order and hard requirements (from `generate.md` §4.1–4.9):
 
 1. **设计要点一览** — P1…Pn invariants from design decisions (required).
 2. **核心业务时序 · Happy Path** — complete Mermaid `sequenceDiagram` for the main success
    path + post-diagram「设计要点」(required).
 3. **业务场景时序** — each scenario: purpose + diagram + **设计要点说明** (required notes;
    bare diagrams fail quality).
-4. **数据结构** — Before drafting §4.4: follow `database-guidance.md`. If `dbStack` hit,
-   resolve then `Read` `{ide}/specflow/guidance/database/<stack>/SKILL.md` (init-installed
-   guidance pack) or package fallback `skills/database/<stack>/SKILL.md` (+ refs as needed).
-   If `none` or files missing, LLM-only with SpecFlow §4.4 hard bar (ER + full CREATE TABLE…).
-   Cite the actual path in §4.4 总则. **Never** install/invoke database as an IDE skill.
-   **Outline**: only `4.4.1–4.4.4` + `##### table`; DDL/字段说明/JSON = `**bold**`, not headings.
-5. **接口设计** — inventory + fields + examples + errors…
-   **Outline**: only `4.5.1–4.5.3` + `##### In`; 请求体字段/示例/错误 = `**bold**`, not headings.
-6. **核心算法 / 配置 / 兼容性** — as applicable.
+4. **数据结构** — Before §4.4: (1) `project-conventions-guidance.md` `topic=database`;
+   (2) `database-guidance.md` + SpecFlow guidance pack / `dbStack`; (3) live DDL/anchors.
+   Priority: **project + live DDL > SpecFlow pack > LLM**. §4.4.1 must list 项目约定 + DB 技能.
+   **Outline**: only `4.4.1–4.4.4` + `##### table`; DDL/字段说明/JSON = `**bold**`.
+5. **接口设计** — Before §4.5: `project-conventions-guidance.md` `topic=api`.
+   Then inventory + fields + examples + errors…
+   **Outline**: only `4.5.1–4.5.3` + `##### In`; 请求体字段/示例/错误 = `**bold**`.
+6. **前端 / UI** — When `uiInScope=yes`: before §4.6:
+   (1) `project-conventions-guidance.md` `topic=frontend`;
+   (2) **`frontend-guidance.md` §3** — 强制扫描 IDE skills/rules(`.cursor`/`.claude`/`.agents`)
+       与落地文档(组件命名、路由、状态、表单、API client、样式/token、a11y、测试命令、lint 禁令);
+       合计 ≤5 文件,禁止 `invoke` skill;
+   (3) live UI anchors from design/tasks.
+   Then write 五元组 + 页面/路由 + Page 详设(空/加载/错态) + 状态 + Visual Loop.
+   §4.6.1 must list **项目约定** + **IDE skills/rules**.
+   **Outline**: only `4.6.1–4.6.5` + `##### Page · …`. **G5/G6**. Omit chapter if no UI.
+7. **核心算法 / 配置 / 兼容性** — §4.7–4.9 as applicable.
 
 **Traceability**: every element → **§5** Requirement/Scenario and **§2** decision.
 If not implementer-ready, mark `[待 refine 澄清: <元素>]`.
@@ -302,24 +365,34 @@ Present the detailed design to the user as part of the confirmation summary.
 
 ---
 
-## Stage 8: Acceptance Criteria (after design)
+## Stage 8: Acceptance Criteria (optional)
+
+**Ask the user** whether to include **§5 验收标准** in `approval.md`.
 
-Produce **§5 验收标准** only **after** §3 architecture and §4 detailed design are drafted
-in the document order. Exhaustive Requirement + Scenario list with 3-level testability.
-Do not place acceptance before the design chapters.
+- If **yes**: produce §5 only **after** §3/§4 are drafted; exhaustive Requirement +
+  Scenario list with 3-level testability.
+- If **no**: omit the entire chapter (no placeholder).
 
 ---
 
 ## Stage 9: Test Strategy
 
-Produce the **test strategy** section (approval.md **§6** 测试策略). Every §5 acceptance
-criterion maps to ≥1 test layer with tools and verifiable goals.
+Produce **§6 测试策略**. If §5 is included, every criterion maps to ≥1 test layer.
+If §5 was omitted, map layers to named Requirement/Scenario from delta specs.
 
 ---
 
-## Stage 10: Deployment & Release
+## Stage 10: Deployment & Release (optional)
 
-Produce the **deployment / release / rollback** section (approval.md **§7**).
+**Ask the user** whether to include **§7 部署/发布/回滚**. If yes, produce the section;
+if no, omit entirely.
+
+---
+
+## Stage 10b: Closed-Loop table (optional)
+
+Closed-loop **analysis** (Passes 1–7) always runs. **Ask the user** whether to include
+**§8 闭环性检查表** in the document. If no, omit §8; still report overall verdict in chat.
 
 ---
 
@@ -350,52 +423,69 @@ Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) wit
 Following the document structure and generation rules in `generate.md` Part E, produce
 `approval.md` inside the change directory at `specflow/changes/<name>/approval.md`.
 
-Document chapter order (hard):
+Document chapter order (hard for included chapters):
 
-1. §1 绪论与边界 (proposal + optional explore + AI; includes What/Impact; **no 变更摘要**)
-2. §2 技术方案评估
-3. §3 架构整体设计 (图 + **图要点说明** + 组件)
-4. §4 方案详细设计 (设计要点 + Happy Path + 业务场景说明 + 数据/接口…)
-5. §5 验收标准 (**after** design)
-6. §6 测试策略 → §7 部署 → §8 闭环 → §9 可实施性 → §10 审批
+1. §1 绪论与边界
+2. §2 技术方案评估 — **可读中文**写现状与约束(禁止代码腔堆砌)
+3. §3 架构整体设计
+4. §4 方案详细设计
+5. §5 验收标准 — **仅用户确认要时**
+6. §6 测试策略
+7. §7 部署 — **仅用户确认要时**
+8. §8 闭环表 — **仅用户确认要时**(分析仍必做)
+9. §9 可实施性评估
+10. §10 审批 — **仅人工签字栏**(无 AI 预审小节)
 
 Key rules:
 
-- §1 truthful: pains from proposal/design/confirmed explore; User Journey → §5; Non-Goals with reasons; What/Impact in §1.2.
-- Decision Review includes every `design.md` decision.
-- §5 Acceptance exhaustive with 3-level testability; placed after §3/§4.
-- §3 every architecture diagram has「设计说明 / 图要点」; component table with「不做什么」.
-- §4 has 设计要点一览, complete Happy Path sequence + notes, each business scenario with 设计要点; DB/API hard bars (§4.4/§4.5); outline hygiene (no heading for 请求体字段/DDL/字段说明 — bold labels only).
-- **Quality Gates G1–G4**: >5-line prose flow → Mermaid; interfaces need failure examples; JSON/new-column need存量填充策略; rollback data compatibility explicit.
-- **Style & Tone**: plain language; gloss obscure abbreviations on first use; ban「尽量/大概/一般情况下」; use「必须/禁止/采用 XX 方案」.
-- **§8 闭环**: one compact table only; PASS one line; ⚠️/❌ ≤3 bullets; no per-Pass essays.
-- Test Strategy maps every §5 criterion to ≥1 layer.
-- Deployment selective; Code Grounding cites real files; sign-off blank; never recommend approve if any verdict is `FAIL`.
+- §1 truthful; Journey traces to §5 if present else named specs; Non-Goals with reasons.
+- **§2.2 技术选型**: required for greenfield or when four artifacts lack needed stack
+  dimensions; only after Tech Stack Intake (user confirm); never invent full stack.
+  Frontend (when UI) needs 五元组, not「React」alone.
+- Decision Review includes every `design.md` decision (plus D-FE/D-BE/D-DB/D-Infra when intake ran).
+- §5 when included: exhaustive + after §3/§4.
+- §3/§4 hard bars + outline hygiene; **G1–G6**; Style & Tone including **no code-dump prose**.
+- §4.6 when `uiInScope`: pages/routes + G5/G6 + Visual Loop; **must Read** IDE
+  skills/rules/落地规约 before draft; cite paths in §4.6.1; omit if no UI.
+- §8 when included: one compact table; always report closed-loop verdict in chat.
+- Test Strategy maps to §5 or specs names; Deployment only if opted in.
+- Sign-off blank; **never** write AI pre-approval into the file; never recommend approve if any verdict is `FAIL`.
 
 ---
 
 ## Gate: User Confirmation
 
-Present a summary to the user:
+Present a summary to the user (**chat only** — these are not document chapters):
 
 - Closed-loop overall verdict (PASS / PASS WITH WARNINGS / FAIL)
 - Design quality verdict (PASS / WARNING / FAIL)
 - Implementability overall verdict (READY / NEEDS REFINEMENT / BLOCKED)
-- AI pre-approval recommendation (建议批准 / 有条件批准 / 退回 refine / 拒绝)
+- **AI pre-approval recommendation** (建议批准 / 有条件批准 / 退回 refine / 拒绝) + 理由
 - The path where `approval.md` will be written
 
-Ask explicitly:
+Ask explicitly about **optional chapters**:
+
+```text
+是否将以下章节写入审批文档?
+- §5 验收标准: 要 / 不要
+- §7 部署/发布/回滚: 要 / 不要
+- §8 闭环性检查表: 要 / 不要
+```
+
+Then ask:
 
 > "确认生成审批文档并写入 `specflow/changes/<name>/approval.md`?"
 
-Do NOT write the file until the user confirms. If the user wants changes to the assessment,
-re-run the relevant Pass or dimension and update the summary before re-asking.
+Do NOT write the file until the user answers the optional-chapter choices **and** confirms.
+If the user wants changes to the assessment, re-run the relevant Pass or dimension and
+update the summary before re-asking.
 
 On confirmation:
 
-1. Write `approval.md` to the change directory.
-2. Do NOT change `phase` — it remains `refined`.
-3. Report the file path and next-step suggestions.
+1. Write `approval.md` including only the optional chapters the user accepted.
+2. Do **not** include「AI 预审建议」in the file.
+3. Do NOT change `phase` — it remains `refined`.
+4. Report the file path and next-step suggestions.
 
 ---