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

package/prompts/approval/project-conventions-guidance.md

@@ -0,0 +1,171 @@
+# Approval · Project Conventions Router
+
+> Used by `/specflow:approval` before drafting **§3 架构 / §4.4 数据 / §4.5 接口 / §4.6 前端**
+> (frontend when `uiInScope=yes`).  
+> **目的**:让方案贴合**本仓库**的 skill / rule / 工程约定，而不是只套 SpecFlow 通用 guidance。  
+> **懒加载**:按主题按需 `Read`，禁止一次灌入全部 IDE rules。  
+> **Not** an MCP tool; **禁止** `invoke /xxx skill` —— 一律解析路径后 `Read`。
+
+---
+
+## 0. Priority (冲突时必须遵守)
+
+```text
+① 项目约定 + 现网代码/DDL/OpenAPI   >   ② SpecFlow Guidance Pack   >   ③ LLM 常识
+```
+
+- ① 决定「能不能做、禁令、现网形状」。
+- ② 只补强「怎么写清楚」(如完整 CREATE TABLE、接口失败示例骨架)。
+- ②/③ **不得**覆盖 ①(例:项目约定「本迭代禁止迁移」时,不得按通用 skill 发明 `ALTER`)。
+
+Announce after resolve:
+
+```text
+Project conventions (architecture|api|database|frontend): <paths…> | none
+Conflict policy: project > SpecFlow guidance > LLM
+```
+
+---
+
+## 1. Topics (何时加载)
+
+| 主题 `topic` | 何时 **必须**跑本路由 | 典型要找的内容 |
+|--------------|----------------------|----------------|
+| `architecture` | 起草 **§3** 前 | 分层、模块边界、目录约定、禁止直连 |
+| `database` | 起草 **§4.4** 前(且有持久化) | 迁移工具禁令、命名、字符集、现网表规范 |
+| `api` | 起草 **§4.5** 前(且有对外/跨端接口) | 错误码、鉴权、契约/OpenAPI、通道 |
+| `frontend` | 起草 **§4.6** 前(且 `uiInScope=yes`) | 组件/状态/路由/API client/设计系统/**表单/测试/a11y** 等落地约定;须含 IDE skills/rules 扫描(见 `frontend-guidance.md` §3) |
+
+每个主题 **最多 Read 5 个文件**(配置列出的优先;自动探测时取最相关的前 5 个)。细节 references 仅在入口文件点名时再读(禁止 reference 链式跳转)。
+
+---
+
+## 2. Resolve paths (跨 IDE)
+
+### 2.1 显式配置(最高优先)
+
+读 `specflow/config.yaml` → `conventions.<topic>`(字符串路径数组,相对项目根)。  
+有配置则 **只 Read 这些路径**(仍受「最多 5 个」限制);缺文件 → WARNING。
+
+```yaml
+conventions:
+  architecture:
+    - docs/engineering/architecture.md
+  api:
+    - docs/api/guidelines.md
+  database:
+    - docs/db/conventions.md
+  frontend:
+    - docs/frontend/conventions.md
+```
+
+### 2.2 自动探测(无配置时)
+
+1. 判定 `activeIde`(本会话 IDE):Cursor / Claude / Codex。  
+2. **先**扫 activeIde 候选。  
+3. 若无命中:按 `cursor → claude → agents` 回退扫同主题候选。  
+4. 再扫**仓根中立**路径。  
+5. 仍无 → `none`(允许继续,但总则/架构说明须写「未发现项目级约定」)。
+
+#### 候选路径表
+
+**仓根中立(跨 IDE 推荐真相源)**
+
+| topic | 候选(存在则纳入) |
+|-------|------------------|
+| `architecture` | `docs/engineering/architecture.md`, `.specflow/conventions/architecture.md`, `ARCHITECTURE.md` |
+| `api` | `docs/api/guidelines.md`, `docs/engineering/api.md`, `.specflow/conventions/api.md` |
+| `database` | `docs/db/conventions.md`, `docs/engineering/database.md`, `.specflow/conventions/database.md` |
+| `frontend` | `docs/frontend/conventions.md`, `docs/frontend/patterns.md`, `docs/frontend/testing.md`, `docs/engineering/frontend.md`, `.specflow/conventions/frontend.md`, `agent_docs/tech_stack.md`, `agent_docs/code_patterns.md`, `agent_docs/testing.md` |
+
+**Cursor**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `.cursor/rules/**/*.mdc` 中文件名/标题含 architecture\|api\|database\|db\|frontend\|backend\|ui\|react\|vue\|component\|tailwind\|a11y\|playwright 的条目(每主题最多 2) |
+| skill | `.cursor/skills/**/SKILL.md` 目录名或 frontmatter `name`/`description` 匹配主题关键词 |
+
+**Claude**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `CLAUDE.md`, `.claude/CLAUDE.md`(整文件较大时只提取与主题相关章节) |
+| skill | `.claude/skills/**/SKILL.md`(主题关键词匹配) |
+| rules | `.claude/rules/**/*`(若存在;同名过滤) |
+
+**Codex**
+
+| topic | 候选 |
+|-------|------|
+| 通用 | `AGENTS.md`(提取与主题相关段落) |
+| skill | `.agents/skills/**/SKILL.md`(主题关键词匹配) |
+
+关键词提示:
+
+- `architecture|arch|分层|模块`
+- `api|openapi|rpc|接口|错误码`
+- `database|db|sql|迁移|schema`
+- `frontend|ui|react|vue|next|svelte|tailwind|component|控制台|页面|组件|表单|路由|a11y|playwright|vitest|样式|design.?system`
+
+> **前端专题**:`topic=frontend` 时 **必须**按 `frontend-guidance.md` §3 扩扫 IDE skills/rules
+> 与落地文档(状态/表单/测试/a11y 等);不要只命中一个泛化的「frontend」文件名就停。
+
+---
+
+## 3. How to apply (写入方案时)
+
+1. **用可读中文**把约定写进 §2.1 / §3 图要点 / §4.4 / §4.5 / §4.6(禁止代码腔堆砌)。
+2. **硬禁令**原样保留语义(例:「本迭代禁止 goose 迁移」)。  
+3. 与 SpecFlow DB/API 硬门槛同时满足:项目禁令优先;表达骨架用 SpecFlow 规则。  
+4. 在对应章节**标明来源路径**(总则「项目约定」列,或架构图要点首条)。  
+5. 若探测到约定文件但正文未体现关键禁令 → 确认摘要 / §8(若有)记 `WARNING`:  
+   `发现项目约定 <path> 但方案未采纳关键约束`。
+
+---
+
+## 4. Interaction with SpecFlow database guidance
+
+写 §4.4 时顺序固定:
+
+1. 本路由 `topic=database`(项目约定)  
+2. `prompts/approval/database-guidance.md`(SpecFlow pack + dbStack)  
+3. 现网 DDL / 迁移 / 锚点文件(Pass 6)  
+4. 起草:表形状与禁令 ← ①+③;DDL 完整度与类型惯例 ← ②  
+
+§4.4.1 总则必须同时填写:
+
+| 项 | 说明 |
+|----|------|
+| 项目约定 | 实际 Read 到的路径,或 **未发现** |
+| DB 技能 | SpecFlow guidance 路径或 `LLM-fallback` |
+| DDL 来源 | 迁移/基线路径或本迭代新增 |
+
+---
+
+## 4b. Interaction with frontend guidance
+
+写 §4.6 时顺序固定:
+
+1. 本路由 `topic=frontend`(项目约定 docs + IDE skills/rules 关键词匹配)  
+2. **强制**再跑 `prompts/approval/frontend-guidance.md` §3 —— 补扫开发落地维
+   (组件/路由/状态/表单/API client/样式/a11y/测试/lint);与步骤 1 **去重**,合计 ≤5 文件  
+3. 现网路由/布局/API client 锚点(Pass 6)  
+4. 起草:页面/组件边界与禁令 ← ①+②+③;章节骨架与 G5/G6 ← `frontend-guidance` 其余条款  
+
+§4.6.1 总则必须填写:
+
+| 项 | 说明 |
+|----|------|
+| 项目约定 | config + 中立 docs 路径,或 **未发现** |
+| IDE skills/rules | 实际 Read 的 `.cursor/.claude/.agents` skill/rule 路径,或 **未发现** |
+| FE 栈 | 五元组 |
+
+无 UI → 整章省略。发现约定但方案未采纳 → WARNING。
+
+---
+
+## 5. Why this shape
+
+- IDE 目录不同 → 用 **activeIde + 回退 + 中立 docs** 统一发现,不强迫业务仓只选一个 IDE。  
+- 上下文有限 → **按主题懒加载**,最多 3 文件。  
+- 贴合项目 → **优先级写死**,并要求总则可核对来源。

package/skills/GUIDANCE_PACKS.md

@@ -1,49 +1,70 @@
-# Guidance Packs（两层技能模型）
+# Guidance Packs 与项目约定
 
-SpecFlow 区分两类能力包，避免把内部知识暴露成可 `/` 调用的 IDE skill。
+审批写技术章时的取证优先级：
 
-## 两层模型
+```text
+① 项目约定 (conventions / IDE rules / docs)  >  ② SpecFlow Guidance Pack  >  ③ LLM
+```
+
+## SpecFlow 两层模型（包内）
 
 | 层 | 包内位置 | 业务仓落地 | IDE 可发现 |
 |----|----------|------------|------------|
 | **Workflow skill** | `skills/specflow-*` + `COMMAND_CATALOG` | `.cursor/skills/specflow-*`（及 claude/agents） | 是 |
-| **Guidance pack** | `skills/<pack>/` + 本注册表 | `{ide}/specflow/guidance/<pack>/` | **否** |
+| **Guidance pack** | `skills/<pack>/` + [`guidance-packs.yaml`](guidance-packs.yaml) | `{ide}/specflow/guidance/<pack>/` | **否** |
+
+Workflow 通过路由 `Read` 路径加载 guidance；禁止写成「invoke `/mysql` skill」。
+
+## 项目约定（仓内，懒加载）
 
-Workflow skill（如 `/specflow:approval`）通过路由文档指示 Agent **`Read` 文件路径**加载 guidance；禁止写成「invoke `/mysql` skill」。
+| 项 | 说明 |
+|----|------|
+| 路由 | `prompts/approval/project-conventions-guidance.md` |
+| 解析辅助 | `src/core/project-conventions.ts`（config + 仓根中立路径） |
+| 主题 | `architecture` → §3；`database` → §4.4；`api` → §4.5；`frontend` → §4.6（有 UI；含 IDE skills/rules 落地扫描） |
+| 上限 | 每主题约定文件最多 **3**（helper）；前端专题合计约定+IDE skills/rules ≤ **5**（见 `frontend-guidance.md` §3） |
 
-设计原则对齐 Anthropic Agent Skills 的 progressive disclosure（元数据 → 正文 → 按需 Read `references/`），并复用 SpecFlow 已有的 runtime assets（与 `prompts/` / `templates/` 同级安装）。
+另：前端详设结构由 `prompts/approval/frontend-guidance.md` 驱动（`uiInScope`、栈五元组、G5/G6、Visual Loop）；与 DB 的 `database-guidance.md` 对称，**暂无**独立 `skills/frontend` guidance pack。
 
-## 注册表
+```yaml
+# specflow/config.yaml（可选，优先于自动探测）
+conventions:
+  database:
+    - docs/db/conventions.md
+  api:
+    - docs/api/guidelines.md
+  architecture:
+    - docs/engineering/architecture.md
+```
 
-[`guidance-packs.yaml`](guidance-packs.yaml) 列出所有需随 `specflow init` / `--force-assets` 同步的 pack：
+无配置时：仓根中立文件（如 `docs/db/conventions.md`）+ Cursor/Claude/Codex 下 rules/skills（见路由文档，按 activeIde 优先再回退）。
+
+## Guidance Pack 注册表
 
 ```yaml
 packs:
   - id: database
-    source: skills/database      # 相对 SpecFlow 包根
-    installAs: guidance/database # 相对 {ide}/specflow/
-    consumers: [approval]        # 文档用：哪些 workflow 会 Read
+    source: skills/database
+    installAs: guidance/database
+    consumers: [approval]
 ```
 
-## 新增一个 Guidance Pack
+## 新增 Guidance Pack
 
-1. 在 `skills/<id>/` 放置 `SKILL.md`（及可选 `references/`、`examples/`）。
+1. 在 `skills/<id>/` 放置 `SKILL.md`（及可选 `references/`）。
 2. 在 `guidance-packs.yaml` 增加一行。
-3. 在消费方 workflow 的 prompt/SKILL 中写明解析顺序：
-   - `{ide}/specflow/guidance/<id>/…`（业务仓标准路径）
-   - 回退：包内 `skills/<id>/…`（SpecFlow 自研仓）
-   - 仍缺失：显式 fallback + WARNING
-4. 「调用」语义：`Read …/SKILL.md`（及入口直接点名的 references），禁止链式跳转、禁止 MCP、禁止远程 `npx skills add`。
+3. 消费方 prompt 写清：业务仓 `{ide}/specflow/guidance/<id>/` → 包内回退 → fallback。
+
+## 数据库章节取证顺序
 
-## 共享 vs 包内 references
+1. 项目约定 `topic=database`
+2. SpecFlow `guidance/database/<stack>/`
+3. 现网 DDL / 迁移 / 锚点  
 
-| 场景 | 放哪里 |
-|------|--------|
-| 多个 workflow 共用 | Guidance pack（本机制） |
-| 仅单一 skill 使用 | 该 skill 目录下的 `references/`（Anthropic 包内资源） |
+§4.4.1 总则必须填写「项目约定」「DB 技能」「DDL 来源」。
 
 ## 当前 packs
 
 | id | consumers | 说明 |
 |----|-----------|------|
-| `database` | approval | §4.4 按 `dbStack` Read mysql/postgresql/oracle/redis/elasticsearch |
+| `database` | approval | 按 `dbStack` 补强 DDL 写法；不得覆盖项目禁令 |

package/skills/database/README.md

@@ -8,19 +8,20 @@
 
 | 项 | 约定 |
 |----|------|
-| 运行时依赖 | **无远程仓库依赖**。审批流程只读本地文件，禁止 `npx skills add`、禁止 clone/fetch 上游 |
-| 维护方式 | 在本仓库直接改 `SKILL.md` / `references/` / `examples/`，随 SpecFlow 发版 |
-| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read；未命中 → LLM-fallback |
-| init 安装目标 | `{ide}/specflow/guidance/database/`（与 prompts/templates 同级） |
-| IDE 全局技能 | **不**安装到 `.cursor/skills` / `.claude/skills` / `.agents/skills`（避免噪音与误发现） |
+| 与项目约定关系 | **项目约定优先**。先跑 `project-conventions-guidance.md`(`topic=database`)，再读本 pack |
+| 运行时依赖 | **无远程仓库依赖**。审批流程只读本地文件 |
+| 加载方式 | `database-guidance.md`：命中栈 → Read 本目录；未命中 → LLM-fallback |
+| init 安装目标 | `{ide}/specflow/guidance/database/` |
+| IDE 全局技能 | **不**安装到 `.cursor/skills` 等发现路径 |
 
-## 路径解析（业务仓）
+## 路径解析（业务仓 §4.4）
 
-1. `.cursor/specflow/guidance/database/<stack>/`（或 `.claude` / `.agents`）
-2. 回退：包内 `skills/database/<stack>/`（SpecFlow 自研仓）
-3. 仍缺失：`LLM-fallback` + §8 WARNING（建议 `specflow init --force-assets`）
+1. 项目约定（`conventions.database` 或 `docs/db/conventions.md` 等）
+2. `.cursor/specflow/guidance/database/<stack>/`（或 `.claude` / `.agents`）
+3. 回退：包内 `skills/database/<stack>/`
+4. 仍缺失：`LLM-fallback` + WARNING
 
-「调用」语义：`Read …/SKILL.md`（及路由直接点名的 references），**禁止** `invoke /mysql`。
+§4.4.1 总则须同时填写「项目约定」「DB 技能」「DDL 来源」。
 
 ## 目录