@gordon.gan/specflow 1.5.0-beta → 1.8.0-alpha

package/prompts/approval/multi-repo-guidance.md

@@ -1,202 +0,0 @@
-# Approval · Multi-Repo (多仓) Guidance
-
-> Used by `/specflow:approval` when the user **自然语言指定多仓**、workset 含多个规划根、或
-> design/tasks 明确跨 `talos` / `talos-web` / `talos-worker` 等仓库。
->
-> **目的**:按各仓四件套与锚点生成技术审批文档,并 **询问用户** 产出 **一份合订** 还是 **多份分仓**;
-> 合订时 **必须** 指定 **主仓** 存放 `approval.md` 与 `approval/` 工作区。
-
----
-
-## 0. When to run
-
-| 信号 | 动作 |
-|------|------|
-| 用户说「三仓 / talos+web+worker / 多仓合订 / 前后端一体」 | 启用 `multi_repo.enabled=true` |
-| `specflow workset` / 会话上下文含多个 git 规划根 | 列出候选仓,请用户确认 |
-| 仅单仓 change,无跨仓表述 | `multi_repo.enabled=false`,走单仓流程 |
-| Hub + Spoke 联邦 | 见 §5;各 Spoke 可有不同 change id |
-
-Announce:
-
-```text
-Multi-repo approval: enabled | single-repo
-Repos in scope: talos(scenario-job-compile), talos-web(web-scenario-cases), …
-Document mode: (pending user) unified | per_repo
-Primary repo (if unified): (pending user)
-```
-
----
-
-## 1. Resolve repos (硬顺序)
-
-1. **Parse user natural language** — 仓名、别名(平台/控制台/Worker)、change 名。
-2. **Cross-check workset** — `specflow workset list` / 用户给出的绝对路径;成员顺序 **不** 等于主仓。
-3. **Per repo, verify** (Read-only):
-   - `specflow/changes/<change>/.specflow.yaml` → `phase: refined`
-   - 四件套:`proposal.md`, `specs/**`, `design.md`, `tasks.md`
-4. **Record** in `approval/index.yaml` → `multi_repo.repos[]`:
-
-```yaml
-multi_repo:
-  enabled: true
-  document_mode: unified   # unified | per_repo — 用户确认后写入
-  primary_repo: talos      # unified 时必填
-  repos:
-    - id: talos
-      label: 平台
-      role: platform
-      change: scenario-job-compile
-      root_hint: /path/to/talos    #  agent 读取用,可选
-    - id: talos-web
-      label: 控制台
-      role: web
-      change: web-scenario-cases
-    - id: talos-worker
-      label: Worker
-      role: worker
-      change: scenario-execution
-```
-
-**禁止**在未 Read 各仓四件套前假设内容一致;change id **可以** 各仓不同。
-
----
-
-## 2. User gate — 一份还是多份 (硬)
-
-在 Pass 1 之前或 Stage 12a 之前,**必须** 询问:
-
-```text
-本需求跨 N 个仓库,审批技术文档如何产出?
-
-A) 一份合订文档 (unified) — 单份 approval.md,含各仓决策/接口/前端/Worker 切片
-B) 多份分仓文档 (per_repo) — 每个仓库各自一份 approval.md,仅写本仓范围
-
-请选择 A 或 B。
-```
-
-### 2.1 Unified（一份合订）
-
-再询问:
-
-```text
-合订文档存放在哪个主仓?(approval.md 与 approval/ 工作区写在该仓 change 目录下)
-
-1) talos (平台)
-2) talos-web (控制台)
-3) talos-worker (Worker)
-…
-
-请选主仓 id。
-```
-
-**硬规则**:
-
-- `multi_repo.document_mode: unified`
-- `multi_repo.primary_repo: <id>` **必填**
-- **工作区路径**(分片模式):
-  - `specflow/changes/<primary.change>/approval/index.yaml`
-  - `specflow/changes/<primary.change>/approval/parts/*.md`
-  - 产出:`specflow/changes/<primary.change>/approval.md`
-- CLI:`specflow approval assemble <primary.change>` **在主仓规划根**执行
-- 文档 §1.2 / §2.3 / 附录 B **必须** 按仓分表;Pass 6 锚点 **分仓列举**
-- 合订 **不是** 只写主仓 design;须合并各仓 specs/design/tasks 的跨端语义
-
-写入 `multi_repo.outputs.unified`:
-
-```yaml
-outputs:
-  unified:
-    repo: talos
-    change: scenario-job-compile
-    path: specflow/changes/scenario-job-compile/approval.md
-```
-
-### 2.2 Per-repo（多份分仓）
-
-**硬规则**:
-
-- `multi_repo.document_mode: per_repo`
-- **每个** `repos[]` 条目独立:
-  - 在该仓 `specflow/changes/<repo.change>/approval/`(分片)或 `approval.md`(单体)
-  - 内容 **仅** 本仓 scope;交叉引用用「见 `<other-repo>` approval §x」
-- 各仓分别 `specflow approval assemble <repo.change>`(若在主仓 CLI,需 `--store` 或 cd 到该根)
-- **禁止**只在主仓写一份然后复制到其它仓
-
-写入 `multi_repo.outputs.per_repo[]`:
-
-```yaml
-outputs:
-  per_repo:
-    - repo: talos
-      change: scenario-job-compile
-      path: specflow/changes/scenario-job-compile/approval.md
-    - repo: talos-web
-      change: web-scenario-cases
-      path: specflow/changes/web-scenario-cases/approval.md
-```
-
----
-
-## 3. Analysis & Map 上下文
-
-| 模式 | Read 范围 | index 库存 |
-|------|-----------|------------|
-| unified | 各仓四件套 + 各仓锚点 + 各仓约定 | `interfaces/pages/tables` 带 `repo` 字段(推荐) |
-| per_repo | **当前仓**四件套 + 本仓锚点 | 仅本仓实体 |
-
-**Unified 分片建议**:
-
-- `02-design-review` — 三仓决策表
-- `04.5-api` — 按 `repo` 或 L1/L2/L3/L4 分批;Worker 切片须 Read `api-guidance.md` + worker OpenAPI 路径
-- `04.6-*` — 仅 `ui_in_scope` 且 web 仓
-- 附录 B — 按仓允许/禁止路径
-
-**Inventory 扩展**(可选列):
-
-```yaml
-interfaces:
-  - id: I4
-    short: 逐步上报
-    change: scenario-job-compile
-    part: 04.5-api-worker
-    repo: talos-worker
-```
-
----
-
-## 4. Document header (unified)
-
-合订 `approval.md` 头部 **必须** 声明:
-
-```markdown
-> **覆盖变更（多仓合订,主仓: talos）**:
-> - 平台 `talos/scenario-job-compile`
-> - 控制台 `talos-web/web-scenario-cases`
-> - Worker `talos-worker/scenario-execution`
-> **存放路径**: `specflow/changes/scenario-job-compile/approval.md`
-```
-
----
-
-## 5. Hub / Federated 注意
-
-- Hub change id 可与 Spoke change id **同名或不同**;`multi_repo.repos[].change` 用 **各规划根内真实目录名**。
-- Hub 合同摘要可读 `--store`;Spoke approval **不**替代 Hub archive。
-- `coordination.yaml`(若有)可 Read;无则 chat 列出各仓 phase。
-
----
-
-## 6. 自检
-
-- [ ] 用户已选 unified **或** per_repo
-- [ ] unified → `primary_repo` 已选且工作区在该仓
-- [ ] per_repo → 每仓输出路径已写入 `outputs.per_repo`
-- [ ] 各仓四件套已 Read;非主仓内容已进合订正文或分仓文档
-- [ ] Gate 摘要中列出 **所有** 将写入的 `approval.md` 路径
-
----
-
-## 7. 与单仓关系
-
-`multi_repo.enabled=false` 时忽略本章;`change` 字段为当前规划根 change,行为与旧版一致。

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

@@ -1,171 +0,0 @@
-# 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、通道;然后 **`api-guidance.md`**(分层、RPC 锁名、proto 可生成包) |
-| `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/prompts/approval/segmented-generation.md

@@ -1,151 +0,0 @@
-# Approval · Segmented Generation (Map → CLI Reduce)
-
-> Used by `/specflow:approval` **Stage 12** when `mode=segmented` (default for non-trivial §4).
-> **Reduce 禁止 LLM**：拼接必须 `specflow approval assemble <change>` 或 `specflow approval check <change>`。
-
----
-
-## 0. When to segment
-
-| Condition | Mode |
-|-----------|------|
-| `tables > 2` OR `interfaces > 3` OR `pages > 2` OR `optional.s5=true` | **segmented** (mandatory) |
-| Else | ask user: segmented (recommended) or monolithic |
-| User chose monolithic | write `approval.md` directly OR parts + single assemble |
-
-Copy template: `templates/approval-index.yaml` → `approval/index.yaml`.
-
----
-
-## 1. Pipeline (hard order)
-
-```text
-12a Index + Skeleton  →  index.yaml + analysis.json + parts 01–03 + 04-detail-core + stubs
-Gate                  →  user confirms index + optional chapters + mode
-12b Map Append        →  parts 04.4* / 04.5* / 04.6* / 04.7–04.9 (batched)
-12c Optional          →  parts 05* / 07 / 08 (only if optional.s5/s7/s8)
-12d CLI Reduce        →  specflow approval check → specflow approval assemble --force
-```
-
-**Never** skip 12d. **Never** paste assembled markdown from memory instead of running CLI.
-
----
-
-## 2. Anti-lazy rules (Map — LLM MUST NOT)
-
-| # | Forbidden | Required instead |
-|---|-----------|------------------|
-| L1 | One-shot full `approval.md` when `mode=segmented` | Write parts; assemble via CLI |
-| L2 | Empty part, `< 20` chars, or only HTML comments | Full section content per generate.md |
-| L3 | `TODO` / `待补充` / `此处省略` / bare `TBD` | Concrete text or `[待 refine 澄清: <元素>]` with reason |
-| L4 | `详见 design/tasks` without §/In/Page id | Cross-ref `§4.5 I2` / `Page·列表` / `P1` |
-| L5 | Invent new table/interface/page ids not in index | Update index.yaml first, then write part |
-| L6 | Skip §4.4 DDL/字段表/失败示例 because "same as design" | Minimum per G2–G6; **不变**仍须完整 §4.5 |
-| L6b | L2 HTTP only +「内部 I7」stub; or L4 one-liner | **分层** L2/L3/L4 各 `In`; `api-guidance.md` §1 |
-| L6c | RPC「暂定/如/实现时」 | **冻结**名 + proto 字段号; `api-guidance.md` §2–§3 |
-| L7 | Skip IDE skills/rules scan for §4.6 | frontend-guidance.md §3 before Map |
-| L8 | Paste skill/rule bodies verbatim | Readable Chinese + path in §4.6.1 table |
-| L9 | Write `## 4.` or foreign `## N.` in parts | Parts use `###`/`####`/`#####` only; CLI injects `## 4` |
-| L10 | Mark part `ok` without `specflow approval check` passing | Run check; fix errors; then assemble |
-
----
-
-## 3. Stage 12a — Index + Skeleton
-
-**Write first:**
-
-1. `approval/index.yaml` — full `parts_order`, all `tables[]`/`interfaces[]`/`pages[]` with `part` paths  
-2. `approval/analysis.json` — Pass 1–7 + quality + implementability (chat-only fields ok)  
-3. Parts (minimum):
-   - `01-intro.md` … `03-architecture.md`
-   - `04-detail-core.md` (§4.1–4.3 only)
-   - `06-test.md`, `09-implementability.md`, `10-signoff.md` (may be stub-length only for structure in 12a, fill before assemble)
-
-**Chat gate:** show table/interface/page list from index; ask user to confirm before 12b.
-
----
-
-## 4. Stage 12b — Map Append
-
-For each batch, **Read only**:
-
-- `approval/index.yaml`
-- `approval/analysis.json` (verdicts, not full Pass essays)
-- design/tasks/specs **snippets** for this batch's ids
-- lazy-loaded conventions (per topic caps)
-- anchor files for this batch (Pass 6 depth: file only)
-
-**Batching:** use `index.batching.*_per_call`. One part file per batch unit OR per index `part` field.
-
-**After each part write:** update `approval/manifest.json` part entry (`status: draft|ok`).
-
-### §4.4 part minimum (per table batch)
-
-- 4.4.1 row in batch leader file if first batch
-- ER if new entities
-- per-table: CREATE TABLE + 字段说明 + 本迭代用法
-- G3/G4 when applicable
-
-### §4.5 part minimum (per interface)
-
-- Run **`api-guidance.md`** before batch
-- **One `In` per contract surface** (L2 Worker HTTP / L3 RPC+http / L4 client RPC) — no B2-style collapse
-- meta + fields + success req/resp + **failure example (G2)** + error table (**含不变**)
-- **新增/改 HTTP binding**: `**Proto 草案**` block — frozen RPC name, field numbers, `google.api.http`, Gateway registration, Worker OpenAPI path
-- HTTP examples for L2: **all** required work auth headers (not body-only)
-- **Forbidden**: 暂定 / 如 XxxRpc / 实现时命名 / 内部经 I7 一行代替 L4 详设
-
-### §4.6 part minimum (per page)
-
-- route + components + states + ≥1 of 空/加载/错态 (G6) + §4.5 `In` refs
-
----
-
-## 5. Stage 12c — Optional chapters
-
-Only if user opted in AND `optional.s5/s7/s8: true` in index:
-
-- Insert `05-*` / `07-deploy` / `08-closed-loop` into `parts_order` at correct positions
-- §8: **one table only** (from analysis.json)
-
----
-
-## 6. Stage 12d — CLI Reduce
-
-```bash
-specflow approval check <change>
-specflow approval assemble <change> --force
-```
-
-- `check` MUST pass with **zero errors** before assemble  
-- Warnings (orphan parts) should be fixed or removed  
-- Report paths: `specflow/changes/<name>/approval.md`
-
----
-
-## 7. manifest.json (agent-maintained)
-
-```json
-{
-  "schema": "specflow.approval.manifest/v1",
-  "change": "<name>",
-  "parts": [
-    { "id": "01-intro", "path": "approval/parts/01-intro.md", "status": "ok" }
-  ]
-}
-```
-
-CLI overwrites manifest on successful assemble with sha256 sums.
-
----
-
-## 8. Retry
-
-| Failure | Action |
-|---------|--------|
-| `lazy_part_content` on one part | Rewrite that part only; re-check |
-| `missing_part` | Write missing part or fix index |
-| `id_part_mismatch` | Align index `part` field with filename |
-| index wrong | Edit index.yaml; delete wrong parts; rerun affected Map batches |
-
-Do **not** rerun Pass 1–7 unless analysis is stale.