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

package/README.md

@@ -126,7 +126,7 @@ npm install -g @gordon.gan/specflow
 npm install -g github:Gordon-Gan-Jiang/specflow
 
 # 验证
-specflow --version   # 以 npm / package.json 为准（当前 1.4.2-beta）
+specflow --version   # 以 npm / package.json 为准（当前 1.4.3-beta）
 specflow --help
 ```
 

package/dist/integrations/claude/adapter.js

@@ -69,6 +69,7 @@ async function inspectClaude(projectRoot) {
     const promptsDir = join(projectRoot, '.claude', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.claude', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.claude', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.claude', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -98,6 +99,7 @@ async function inspectClaude(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/codex/adapter.js

@@ -40,6 +40,7 @@ function renderCodexAgentsBlock() {
         '- Use artifacts under specflow/changes/<change>/ before coding',
         '- Workflow skills: $specflow-explore, $specflow-propose, $specflow-refine, $specflow-apply, $specflow-review, $specflow-test, $specflow-verify, $specflow-archive, $specflow-fix, $specflow-snap',
         '- Runtime prompts live under .agents/specflow/prompts/',
+        '- Guidance packs (non-IDE skills) live under .agents/specflow/guidance/',
         '',
     ].join('\n');
 }
@@ -96,6 +97,7 @@ async function inspectCodex(projectRoot) {
     const promptsDir = join(projectRoot, '.agents', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.agents', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.agents', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.agents', 'specflow', 'guidance');
     let agentsFileExists = false;
     try {
         const agentsContent = await fs.readFile(agentsFile, 'utf-8');
@@ -134,6 +136,7 @@ async function inspectCodex(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/cursor/adapter.js

@@ -89,6 +89,7 @@ async function inspectCursor(projectRoot) {
     const promptsDir = join(projectRoot, '.cursor', 'specflow', 'prompts');
     const schemasDir = join(projectRoot, '.cursor', 'specflow', 'schemas');
     const templatesDir = join(projectRoot, '.cursor', 'specflow', 'templates');
+    const guidanceDir = join(projectRoot, '.cursor', 'specflow', 'guidance');
     const supported = [];
     const skillContentsByCommand = {};
     for (const command of COMMAND_CATALOG) {
@@ -119,6 +120,7 @@ async function inspectCursor(projectRoot) {
             runtimePromptsDir: { exists: await directoryExists(promptsDir), hash: await hashDirectoryTree(promptsDir) },
             runtimeSchemasDir: { exists: await directoryExists(schemasDir), hash: await hashDirectoryTree(schemasDir) },
             runtimeTemplatesDir: { exists: await directoryExists(templatesDir), hash: await hashDirectoryTree(templatesDir) },
+            runtimeGuidanceDir: { exists: await directoryExists(guidanceDir), hash: await hashDirectoryTree(guidanceDir) },
         },
     };
 }

package/dist/integrations/shared/parity-comparator.js

@@ -4,6 +4,7 @@ import { CAPABILITY_MANIFEST, IDE_ASSET_MANIFEST } from './parity-manifest.js';
 const PARITY_COMPARABLE_ASSET_KEYS = [
     'runtimeSchemasDir',
     'runtimeTemplatesDir',
+    'runtimeGuidanceDir',
 ];
 export function validateReportAgainstManifest(report) {
     const deltas = [];

package/dist/integrations/shared/parity-manifest.js

@@ -42,6 +42,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -53,6 +54,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
     {
@@ -63,6 +65,7 @@ export const IDE_ASSET_MANIFEST = [
             'runtimePromptsDir',
             'runtimeSchemasDir',
             'runtimeTemplatesDir',
+            'runtimeGuidanceDir',
         ],
     },
 ];

package/dist/integrations/shared/runtime-assets.d.ts

@@ -1,2 +1,15 @@
 import type { IdeTarget } from './types.js';
+export declare function ideRootDir(ide: IdeTarget): string;
+interface GuidancePackSpec {
+    readonly id: string;
+    readonly source: string;
+    readonly installAs: string;
+    readonly consumers?: readonly string[];
+}
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export declare function loadGuidancePacks(packageRoot: string): Promise<readonly GuidancePackSpec[]>;
 export declare function copyRuntimeAssets(packageRoot: string, projectRoot: string, ide: IdeTarget): Promise<readonly string[]>;
+export {};

package/dist/integrations/shared/runtime-assets.js

@@ -1,7 +1,9 @@
+import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
+import yaml from 'js-yaml';
 import { copyDirRecursive, copyDirRecursiveRendered } from './asset-copy.js';
 import { renderIdeContent } from './skill-renderer.js';
-function ideRootDir(ide) {
+export function ideRootDir(ide) {
     if (ide === 'claude') {
         return '.claude';
     }
@@ -10,12 +12,48 @@ function ideRootDir(ide) {
     }
     return '.agents';
 }
+/**
+ * Loads guidance pack registry from skills/guidance-packs.yaml.
+ * Missing or empty registry → no packs (non-fatal).
+ */
+export async function loadGuidancePacks(packageRoot) {
+    const registryPath = join(packageRoot, 'skills', 'guidance-packs.yaml');
+    let content;
+    try {
+        content = await fs.readFile(registryPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const parsed = yaml.load(content);
+    if (!parsed || !Array.isArray(parsed.packs)) {
+        return [];
+    }
+    return parsed.packs.filter((pack) => typeof pack?.id === 'string' &&
+        typeof pack?.source === 'string' &&
+        typeof pack?.installAs === 'string');
+}
+async function copyGuidancePacks(packageRoot, specflowRoot) {
+    const packs = await loadGuidancePacks(packageRoot);
+    for (const pack of packs) {
+        const src = join(packageRoot, ...pack.source.split('/'));
+        const dest = join(specflowRoot, ...pack.installAs.split('/'));
+        await copyDirRecursive(src, dest);
+    }
+}
 export async function copyRuntimeAssets(packageRoot, projectRoot, ide) {
-    const root = join(projectRoot, ideRootDir(ide), 'specflow');
+    const ideRoot = ideRootDir(ide);
+    const root = join(projectRoot, ideRoot, 'specflow');
     const promptsSrc = join(packageRoot, 'prompts');
     const promptsDest = join(root, 'prompts');
     await copyDirRecursiveRendered(promptsSrc, promptsDest, (content) => renderIdeContent(content, ide));
     await copyDirRecursive(join(packageRoot, 'schemas'), join(root, 'schemas'));
     await copyDirRecursive(join(packageRoot, 'templates'), join(root, 'templates'));
-    return [`${ideRootDir(ide)}/specflow/prompts`, `${ideRootDir(ide)}/specflow/schemas`, `${ideRootDir(ide)}/specflow/templates`];
+    await copyGuidancePacks(packageRoot, root);
+    return [
+        `${ideRoot}/specflow/prompts`,
+        `${ideRoot}/specflow/schemas`,
+        `${ideRoot}/specflow/templates`,
+        `${ideRoot}/specflow/guidance`,
+    ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.2-beta",
+  "version": "1.4.3-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [

package/prompts/approval/database-guidance.md

@@ -1,9 +1,11 @@
 # Approval · Database Guidance Router
 
 > Used by `/specflow:approval` when generating §4.4 (数据结构 / 数据模型).  
-> **本地技能**: `skills/database/`（本仓库长期维护）。  
+> **Guidance pack**: `database`（见 `skills/guidance-packs.yaml` / `skills/GUIDANCE_PACKS.md`）。  
+> **业务仓落地**: `{ide}/specflow/guidance/database/`（`specflow init` 同步；**不是** IDE skill）。  
 > **禁止**依赖远程 skill 仓库（禁止 `npx skills add` / clone / 运行时 fetch）。  
-> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.
+> **Not** an MCP tool — on hit, `Read` local matched skill files; on miss, LLM-only §4.4.  
+> **禁止**写成「invoke `/mysql` skill」——一律 `Read` 路径。
 
 ---
 
@@ -28,18 +30,35 @@ Scan the **project under review** (change's repo root), not SpecFlow itself. Col
 **Multi-hit**: pick primary OLTP store for §4.4 (prefer `mysql` / `postgresql` / `oracle` over
 `redis` / `elasticsearch`). Mention secondary stores in §4.7/架构 if relevant.
 
-**Announce** after detection:
+---
+
+## 2. Resolve guidance root (path priority)
+
+Before reading pack files, resolve `guidanceRoot` for stack `<stack>`:
+
+| Priority | Path | When |
+|----------|------|------|
+| 1 | `.cursor/specflow/guidance/database/<stack>/` | Cursor IDE assets present |
+| 1 | `.claude/specflow/guidance/database/<stack>/` | Claude IDE assets present |
+| 1 | `.agents/specflow/guidance/database/<stack>/` | Codex IDE assets present |
+| 2 | `skills/database/<stack>/` | SpecFlow package / self-repo fallback (relative to SpecFlow package root) |
+| 3 | *(missing)* | `LLM-fallback` |
+
+If multiple IDE roots exist, prefer the IDE the user is running in; otherwise the first existing path among cursor → claude → agents.
+
+**Announce** after detection + resolve:
 
 ```text
 DB stack for approval: <mysql|postgresql|oracle|redis|elasticsearch|none>
-Guidance: skills/database/<stack>/SKILL.md | LLM-fallback
+Guidance: <.cursor|claude|agents>/specflow/guidance/database/<stack>/SKILL.md
+         | skills/database/<stack>/SKILL.md | LLM-fallback
 ```
 
 ---
 
-## 2. On hit — load **local** guidance (Read, do not invent, do not fetch)
+## 3. On hit — load **local** guidance (Read, do not invent, do not fetch)
 
-Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
+Base = resolved `guidanceRoot` above. From that directory:
 
 | Stack | Must Read | Also Read when §4.4 needs it |
 |-------|-----------|------------------------------|
@@ -49,31 +68,36 @@ Base: `skills/database/<stack>/`（相对 SpecFlow 仓库根；离线可读）
 | `redis` | `SKILL.md` | Only if change is cache/key design — **not** a substitute for relational DDL |
 | `elasticsearch` | `SKILL.md` | Only if change is index/mapping — **not** a substitute for relational DDL |
 
+Point to files **from the router entry** (no reference→reference chains).
+
 Apply guidance to §4.4 output:
 
 1. Prefer engine/charset/collation idioms from the local skill (MySQL: InnoDB + utf8mb4…).
 2. Prefer type/index gotchas from the skill (e.g. DECIMAL for money, no FLOAT amounts).
 3. Keep SpecFlow hard rules (ER, full CREATE TABLE, 本迭代用法, G3/G4) — skill **supplements**, does not replace.
 
-Cite in §4.4 总则, e.g. `DB 技能: skills/database/mysql (本地)`.
+Cite in §4.4 总则 the **actual** path used, e.g.  
+`DB 技能: .cursor/specflow/guidance/database/mysql` 或 `skills/database/mysql (package fallback)`.
 
 ---
 
-## 3. On miss — LLM fallback
+## 4. On miss — LLM fallback
 
-If `DB stack = none` (no durable store signals, or only unknown/custom DB):
+If `DB stack = none`, or stack set but **no** guidance root resolves:
 
 1. **Do not** force-load mysql/postgresql skills.
 2. Generate §4.4 with SpecFlow rules only (`generate.md` §4.4 + Quality Gates G3/G4).
 3. If design/tasks claim a DB but signals are absent → `WARNING` in §8:
    `design 声称落库但未检测到 DB 栈信号 — 已用 LLM 通用 DDL;建议 refine 标明引擎`.
-4. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
+4. If stack detected but guidance files missing → `WARNING` in §8:
+   `dbStack=<stack> 但未找到 guidance/database — 已用 LLM-fallback;建议 specflow init --force-assets`.
+5. Pure CLI/config changes → keep `不涉及数据库变更(...)`.
 
 ---
 
-## 4. Why not remote skills / MCP tools?
+## 5. Why not remote skills / MCP / IDE skills?
 
-- **Remote**: approval must work offline and must not drift with upstream installs; maintain
-  `skills/database/` in this repo.
-- **MCP tools**: these packs are markdown guidance, not APIs; routing chooses which local
-  files to `Read`.
+- **Remote**: approval must work offline; maintain pack in this repo + init sync.
+- **MCP tools**: markdown guidance, not APIs; routing chooses which local files to `Read`.
+- **IDE skills**: packs must **not** appear under `.cursor/skills` / `.claude/skills` / `.agents/skills`
+  (noise + false discoverability). They live only under `{ide}/specflow/guidance/`.

package/prompts/approval/generate.md

@@ -590,11 +590,12 @@ sequenceDiagram
 **适用范围**:涉及持久化、状态存储、数据模型的变更。纯 CLI/库项目若无数据库,覆盖配置结构 / 状态文件 / 缓存结构 / YAML schema 等"数据模型"(走下方「非库表路径」)。
 
 > **DB 技能路由(先于起草)**:执行 `prompts/approval/database-guidance.md`。  
-> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):`Read`  
->   `skills/database/<stack>/SKILL.md` 与路由表中的 DDL/索引/JSON 参考,用其惯例补强类型、引擎、字符集、索引与 Gotchas。  
-> - **未命中**(`dbStack=none`):不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
-> - 技能是 **Read 知识包**,不是 MCP tool;不得用「调 tool」替代读文件。  
-> - 在总则「DDL 来源」旁注明:`skills/database/<stack>`(本地) 或 `LLM-fallback`。
+> - **命中** `mysql` / `postgresql` / `oracle`(及确需时的 redis/es):按路径优先级 `Read`  
+>   `{ide}/specflow/guidance/database/<stack>/SKILL.md`(init 安装的 guidance pack)  
+>   或包内回退 `skills/database/<stack>/SKILL.md`,以及路由表中的 DDL/索引/JSON 参考。  
+> - **未命中**(`dbStack=none`)或文件缺失:不硬套某厂商 skill,**交给大模型**按下方 SpecFlow 硬门槛生成。  
+> - 技能是 **Read 知识包**,不是 MCP tool / IDE skill;不得「invoke `/mysql`」。  
+> - 在总则「DB 技能」列注明**实际路径**(如 `.cursor/specflow/guidance/database/mysql`)或 `LLM-fallback`。
 
 > **质量硬门槛(库表路径)**:只要本变更读写/依赖任何数据库表(含"零 DDL、只改读写语义"),§4.4 **必须**按下列结构输出,不得用一句话带过、不得省略 ER / DDL / 字段说明表。参考质量标杆:`scenario-job-compile` 类审批文档的「表与数据设计」章(总则结论表 → ER → 表一览 → 逐表 DDL+字段表 → 非表字段与回滚)。
 
@@ -627,7 +628,7 @@ sequenceDiagram
 | 新增 / 修改 / 删除列 | 列清单 / **无** |
 | 新增索引 | 索引清单 / **无** |
 | DDL 来源 | 仓库基线路径 或 本迭代新增 |
-| DB 技能 | `skills/database/<stack>`(本地) / `LLM-fallback` |
+| DB 技能 | `{ide}/specflow/guidance/database/<stack>` / `skills/database/<stack>`(fallback) / `LLM-fallback` |
 
 紧接一段 **本迭代变更语句** 代码块:
 
@@ -1207,10 +1208,11 @@ specflow init --artifact-language <language>
     summary table. PASS/SKIPPED → one short phrase; WARNING/FAIL → ≤3 concrete bullets.
 
 16. **§4.4 database skill routing**: before drafting relational DDL, run
-    `prompts/approval/database-guidance.md`. On stack hit, Read local
-    `skills/database/<stack>/…` (in-repo, no remote fetch) and apply idioms; on miss,
-    LLM-only SpecFlow §4.4 rules. Do not invent MCP tools; do not `npx skills add`.
-    Record `skills/database/<stack>` or `LLM-fallback` in the §4.4.1 总则 table.
+    `prompts/approval/database-guidance.md`. On stack hit, resolve then Read
+    `{ide}/specflow/guidance/database/<stack>/…` (init guidance pack) or package
+    fallback `skills/database/<stack>/…`; on miss, LLM-only SpecFlow §4.4 rules.
+    Do not invent MCP tools; do not `npx skills add`; do not install packs under
+    IDE `skills/` discovery. Record the **actual path** or `LLM-fallback` in §4.4.1.
 
 17. **§4.4 / §4.5 outline hygiene (hard rule)**: Markdown TOC must stay shallow.
     - §4.4 headings only: `#### 4.4.1–4.4.4` + per-table `##### \`table\`(中文名)`.

package/skills/GUIDANCE_PACKS.md

@@ -0,0 +1,49 @@
+# Guidance Packs（两层技能模型）
+
+SpecFlow 区分两类能力包，避免把内部知识暴露成可 `/` 调用的 IDE skill。
+
+## 两层模型
+
+| 层 | 包内位置 | 业务仓落地 | IDE 可发现 |
+|----|----------|------------|------------|
+| **Workflow skill** | `skills/specflow-*` + `COMMAND_CATALOG` | `.cursor/skills/specflow-*`（及 claude/agents） | 是 |
+| **Guidance pack** | `skills/<pack>/` + 本注册表 | `{ide}/specflow/guidance/<pack>/` | **否** |
+
+Workflow skill（如 `/specflow:approval`）通过路由文档指示 Agent **`Read` 文件路径**加载 guidance；禁止写成「invoke `/mysql` skill」。
+
+设计原则对齐 Anthropic Agent Skills 的 progressive disclosure（元数据 → 正文 → 按需 Read `references/`），并复用 SpecFlow 已有的 runtime assets（与 `prompts/` / `templates/` 同级安装）。
+
+## 注册表
+
+[`guidance-packs.yaml`](guidance-packs.yaml) 列出所有需随 `specflow init` / `--force-assets` 同步的 pack：
+
+```yaml
+packs:
+  - id: database
+    source: skills/database      # 相对 SpecFlow 包根
+    installAs: guidance/database # 相对 {ide}/specflow/
+    consumers: [approval]        # 文档用：哪些 workflow 会 Read
+```
+
+## 新增一个 Guidance Pack
+
+1. 在 `skills/<id>/` 放置 `SKILL.md`（及可选 `references/`、`examples/`）。
+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`。
+
+## 共享 vs 包内 references
+
+| 场景 | 放哪里 |
+|------|--------|
+| 多个 workflow 共用 | Guidance pack（本机制） |
+| 仅单一 skill 使用 | 该 skill 目录下的 `references/`（Anthropic 包内资源） |
+
+## 当前 packs
+
+| id | consumers | 说明 |
+|----|-----------|------|
+| `database` | approval | §4.4 按 `dbStack` Read mysql/postgresql/oracle/redis/elasticsearch |

package/skills/database/README.md

@@ -1,15 +1,26 @@
 # SpecFlow 本地数据库技能 (`skills/database/`)
 
-本目录是 **SpecFlow 仓库内长期维护** 的数据库参考技能，供 `/specflow:approval` 生成 §4.4 时按项目栈按需 `Read`。
+本目录是 **Guidance Pack** `database`：SpecFlow 仓库内长期维护的数据库参考知识，供 `/specflow:approval` 生成 §4.4 时按项目栈按需 `Read`。
+
+详见 [`../GUIDANCE_PACKS.md`](../GUIDANCE_PACKS.md) 与 [`../guidance-packs.yaml`](../guidance-packs.yaml)。
 
 ## 硬性约定
 
 | 项 | 约定 |
 |----|------|
-| 运行时依赖 | **无远程仓库依赖**。审批流程只读本目录文件，禁止 `npx skills add`、禁止 clone/fetch 上游 |
+| 运行时依赖 | **无远程仓库依赖**。审批流程只读本地文件，禁止 `npx skills add`、禁止 clone/fetch 上游 |
 | 维护方式 | 在本仓库直接改 `SKILL.md` / `references/` / `examples/`，随 SpecFlow 发版 |
-| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read 本目录；未命中 → LLM-fallback |
-| IDE 全局技能 | **不**自动安装到用户 `.claude/skills`（避免噪音）；仅 approval 按需读取 |
+| 加载方式 | `prompts/approval/database-guidance.md` 路由：命中栈 → Read；未命中 → LLM-fallback |
+| init 安装目标 | `{ide}/specflow/guidance/database/`（与 prompts/templates 同级） |
+| IDE 全局技能 | **不**安装到 `.cursor/skills` / `.claude/skills` / `.agents/skills`（避免噪音与误发现） |
+
+## 路径解析（业务仓）
+
+1. `.cursor/specflow/guidance/database/<stack>/`（或 `.claude` / `.agents`）
+2. 回退：包内 `skills/database/<stack>/`（SpecFlow 自研仓）
+3. 仍缺失：`LLM-fallback` + §8 WARNING（建议 `specflow init --force-assets`）
+
+「调用」语义：`Read …/SKILL.md`（及路由直接点名的 references），**禁止** `invoke /mysql`。
 
 ## 目录
 
@@ -24,6 +35,13 @@ skills/database/
   README.md        # 本文件
 ```
 
+业务仓 init 后对应：
+
+```text
+.cursor/specflow/guidance/database/mysql/SKILL.md
+…
+```
+
 ## 历史种子（非依赖）
 
 初版内容种子自 [full-stack-skills/database-skills](https://github.com/full-stack-skills/database-skills)（Apache-2.0）。  

package/skills/guidance-packs.yaml

@@ -0,0 +1,10 @@
+# Guidance packs: private knowledge installed under {ide}/specflow/guidance/
+# NOT copied into IDE skills discovery paths (.cursor/skills, .claude/skills, .agents/skills).
+# See skills/GUIDANCE_PACKS.md
+
+packs:
+  - id: database
+    source: skills/database
+    installAs: guidance/database
+    consumers:
+      - approval

package/skills/specflow-approval/SKILL.md

@@ -95,10 +95,11 @@ 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 skill router for **local** packs under
-   `skills/database/` (in-repo maintenance; **no remote skill dependency**). **Not an MCP
-   tool**: on `dbStack` hit, `Read` matched `SKILL.md` + focused references; on `none`,
-   LLM-only §4.4.
+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:
 
@@ -116,7 +117,9 @@ Read these files and follow them:
   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` + local `skills/database/`): match project
+- **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)
 
@@ -283,8 +286,10 @@ Order and hard requirements (from `generate.md` §4.1–4.8):
 3. **业务场景时序** — each scenario: purpose + diagram + **设计要点说明** (required notes;
    bare diagrams fail quality).
 4. **数据结构** — Before drafting §4.4: follow `database-guidance.md`. If `dbStack` hit,
-   `Read` `skills/database/<stack>/SKILL.md` (+ DDL/index/JSON refs as needed).
-   If `none`, LLM-only with SpecFlow §4.4 hard bar (ER + full CREATE TABLE + field tables…).
+   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.

package/templates/approval.md

@@ -222,8 +222,8 @@ sequenceDiagram
 
 ### 4.4 数据结构 / 数据模型变更 (Data Structures)
 
-<!-- 库表硬门槛 + DB 技能路由:命中 skills/database/<stack> 则 Read 补强;
-     未命中 LLM-fallback。总则表填写「DB 技能」列。详见 prompts/approval/database-guidance.md。
+<!-- 库表硬门槛 + DB guidance pack:init 安装到 {ide}/specflow/guidance/database/;
+     路由见 prompts/approval/database-guidance.md。总则表填写实际「DB 技能」路径。
      大纲硬门槛:仅 4.4.1–4.4.4 + ##### 表名;DDL/字段说明/JSON 用 **加粗**,禁止再开标题。 -->
 
 #### 4.4.1 总则与本迭代结构变更结论
@@ -235,7 +235,7 @@ sequenceDiagram
 | 新增/修改/删除列 | <清单 / 无> |
 | 新增索引 | <清单 / 无> |
 | DDL 来源 | <migrations 路径 / 本迭代新增> |
-| DB 技能 | <skills/database/mysql|…(本地) / LLM-fallback> |
+| DB 技能 | <.cursor|…/guidance/database/mysql 或 LLM-fallback> |
 
 ```sql
 -- 本迭代变更语句