@double-codeing/flow2spec 2.2.3 → 3.0.7

package/templates/skills/f2s-kb-upgrade/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: f2s-kb-upgrade
+description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V1** 须先 f2s-kb-migrate 再在流程内代跑 flow2spec init；**现行库（流程代号 V2+，含已用 .Knowledge 的 Flow2Spec npm v3.x 等项目）** 则代跑 init 以对齐 manifest-routing + matchers 分片（包内 `manifest-matchers.json` 仅作 init 合并种子，不落盘 .Knowledge）。触发：f2s-kb-upgrade、一键升级迁移、旧项目升级、知识库模板升级。注意：不要把单独的 flow2spec init 称作「升级命令」；**V1/V2+ 为技能内分流代号，不等于 npm 包主版本号**。
+---
+
+> 执行口径：本技能用于「代替用户跑 shell」完成 **按本 SKILL 定义的** Flow2Spec **模板与配置根对齐**；其中一步会代跑 **`flow2spec init`**，但 **`init` 不是「升级命令」**，**升级命令 / 知识库升级** 仅指 **`f2s-kb-upgrade` 本技能全流程**。
+
+# f2s-kb-upgrade（知识库模板升级技能）
+
+**术语（必须）**：**「升级」「升级命令」「知识库升级」** 仅指按本文件 **`f2s-kb-upgrade`** 执行的完整技能流程。**`flow2spec init`** 是 CLI **初始化/落盘**命令；本技能 **步骤 2** 会代跑它，**禁止**把用户单独执行的 `init` 或 CLI 帮助里的 `init` 表述为「升级命令」。
+
+## 边界（避免误区）
+
+- **`flow2spec init` 不写业务知识**：不替代 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等对 `stock-docs` / `req-docs` / `topics` 正文与业务向路由词条的维护。
+- 本技能跑通的是 **包版本下的目录、模板占位、路由结构对齐**；用户若说「把新能力写进知识库」，应引导 **`f2s-kb-sync` / `f2s-doc-add`** 等，而非仅 `f2s-kb-upgrade`。
+
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本节不复述。
+- **子 agent 职责**（仅当 `subAgent=true`）：代跑 `flow2spec init` 等 shell 命令；仅承接命令执行，不承担知识库正文落盘。
+- **主必控**（主 agent 不可下放）：
+  1. **版本分流**：**V1** 先走 `f2s-kb-migrate` 再进入本技能；**现行库（V2+）** 直接进入 `init` 流程（含 Flow2Spec **npm v3.x** 等，只要已满足步骤 0 中「现行库」条件，均走此支，**勿**因主版本为 3 再单独设一套流程）。
+  2. **`init` 后重读**：从磁盘重读 `f2s-kb-upgrade/SKILL.md`，对比标识是否变化。
+  3. **整技能重跑**：SKILL 有变化时，按新版字面从头再跑一轮，直至连续两轮无变化。
+  4. **步骤 3b 融合**：`.Knowledge/index.md` 的维护区保留 + 包版对齐融合由主 agent 执行。
+  5. **校验摘要**：校验结论与输出摘要由主 agent 汇总。
+- **写权硬约束**：`.Knowledge/index.md` **只由主 agent 落盘**，子 agent **不得触碰**；`manifest-routing.json` 同属主落盘。
+- 本 SKILL 不绑定交叉校验；落盘侧自验。
+
+## 与 `f2s-kb-migrate` 为何并存
+
+| 技能 | 解决的问题 |
+| --- | --- |
+| **`f2s-kb-migrate`** | **结构搬家**：`docs-index.md` / `index-doc.md`、`rules/main.md(c)`、业务 `skills/`、散落 `stock-docs`/`req-docs` → **迁入 `.Knowledge`**，落盘 `migration-report.md`、删除清单需用户确认。不代跑 npm 包升级。 |
+| **本技能 `f2s-kb-upgrade`** | **包与模板对齐**：代跑 **`flow2spec init`**，合并 **`manifest-routing.json`** 与 **`matchers/*.json`**（包内 `manifest-matchers.json` 仅作 init 合并种子，**不落盘**到 `.Knowledge`），刷新各 agent **`rules`/`skills`**（或 Codex **`AGENTS.md`**）；`init` 另将包内 **`index.md` → `.Knowledge/template/index.template.md`** 作对照快照，**`.Knowledge/index.md`** 由步骤 3b **diff 对齐**，init **不**自动改其正文。 |
+
+- **旧项目一键闭环**：**先 `f2s-kb-migrate`** → **再本技能**（`init`）。禁止仅用 `init` 代替完整迁移。
+- **已是新版 `.Knowledge` 的项目**：**只跑本技能**，勿重复 migrate。
+
+**为何 Cursor / Claude / Codex 下各有一份同名 `SKILL.md`？**  
+各工具只加载**本配置根**下的 `skills/`（例如 Codex 仅 `.codex/skills/`）。内容应以 **`templates/skills/`**（或包发布物）为源保持一致；`flow2spec init` 会向所选 agent 目录**同步落盘**。
+
+## 目标
+
+当用户说「帮我升级知识库模板 / 跑 f2s-kb-upgrade / 同步最新 Flow2Spec」时，Agent **按本技能 `f2s-kb-upgrade` 全文流程执行**（含代跑 `flow2spec init`、清理、校验、摘要）；**勿**把仅执行 `init` 等同于完成本技能。
+
+## 默认行为
+
+1. 本技能步骤 2 代跑 **`flow2spec init`** 时，默认 **增量落盘**（不带 `--reset-knowledge`）。
+2. 仅当用户明确要求「覆盖重置」时，才在 `init` 末尾追加 `--reset-knowledge`。
+3. 优先写入用户指定的 agent；未指定时默认 `cursor claude codex`。
+
+## init 与技能自更新（必须）
+
+本技能在 **步骤 2** 会执行 **`flow2spec init`**；`init` 会把包内 **`templates/skills/`** 等同步到各 agent **配置根**，因此 **`init` 成功结束后**，本仓库里的 **`skills/f2s-kb-upgrade/SKILL.md`** **可能被新版本覆盖**，与当前对话里已缓存的旧说明不一致。
+
+**闭环（防旧条令）**：
+
+1. **`init` 前**（推荐）：记下当前配置根内 **`skills/f2s-kb-upgrade/SKILL.md`** 的标识（如 `mtime`、文件大小或正文 hash）。  
+2. **`init` 成功结束后**：**重新读取磁盘上** 该 **`SKILL.md` 全文**（Cursor：`.cursor/skills/f2s-kb-upgrade/SKILL.md`；Claude：`.claude/skills/...`；Codex：`.codex/skills/...`，与本次 `init` 写入的 agent 一致）。  
+3. **若相对步骤 1 有变化**（或刚升级 Flow2Spec 包、无法确认是否无变）：**必须以最新 SKILL 为准**，**从下文「步骤 0」起完整再执行一遍**本技能（含版本分流、是否再次 `init`、校验与摘要——一律按新版字面）；可循环直至**连续两轮**读到的 SKILL **无变化**，或用户明确要求停止。  
+4. **若无变化**：继续执行步骤 3 及以后。
+
+> 口径：**本技能步骤 2 执行 `init` 后** → 再读最新 `f2s-kb-upgrade/SKILL.md` → 有变则 **整技能重跑**；不要仅凭会话记忆执行 **本技能**。
+
+## 强制流程
+
+### 步骤 0：版本判定与分流（必须，先于 init）
+
+> **命名说明**：下文 **「V1」「现行库（V2+）」** 为本技能**流程分流代号**。**npm 包为 v3.x、v4.x…** 且仓库**已**是 `.Knowledge` + `manifest-routing` 形态时，仍走 **「现行库（V2+）」** 支（仅 `init` 对齐），**不要**把 npm 主版本数字当成这里的「V2」字面限制。
+
+**V1 — 旧版知识组织（须先迁移再 init）**  
+命中**任一**强信号则按 V1：
+
+- 配置根仍有 **`docs-index.md` 或 `index-doc.md`**，且主要仍经 **`rules/main.md` / `rules/main.mdc`** 收口；或  
+- 业务 **`stock-docs` / `req-docs` 与规则、业务 skills** 仍以配置根旧树为主，**未**稳定落在 `.Knowledge`。
+
+**动作**：先按 **`f2s-kb-migrate`** 全流程执行（含 `migration-report`、删除清单确认），**再**进入步骤 1–5 执行 `flow2spec init`。
+
+**现行库（V2+）— 已上 `.Knowledge` + 新版路由（仅包级 / 形态对齐）**  
+同时满足：
+
+- 存在 **`.Knowledge/manifest-routing.json`**，且 **`topicPaths` / `taskToTopicRules`** 可用；  
+- 业务文档已以 **`.Knowledge/stock-docs`、`req-docs`、`topics`** 为主（可与 V1 刚结束状态衔接）。
+
+**历史口径**：若仓库里仍有遗留 **单文件 `manifest.json`**，**不得**再当作机读事实源；机读以 **`manifest-routing.json` + `matcherPath` 指向的 `matchers/*.json`** 为准，`init` 负责与模板**合并 / 回填分片**。
+
+**动作**：直接进入步骤 1–5；**无需** migrate，除非用户明确要求重做迁移。
+
+### 步骤 1：确认本技能内 `init` 模式（必须）
+
+- 若用户未明确「覆盖重置」，本技能步骤 2 默认 **增量 `init`**。
+- 若用户提到「全部按模板覆盖/重置」，二次确认后再使用 `--reset-knowledge`。
+
+### 步骤 2：执行命令（代用户跑 shell）
+
+在目标项目根目录执行以下其一：
+
+1. 优先（推荐升级到最新包）：
+   - `npx @double-codeing/flow2spec@latest init <agents...>`
+2. 若项目已固定使用本地安装：
+   - `npx flow2spec init <agents...>`
+3. 覆盖重置时：
+   - 在上述命令末尾追加 `--reset-knowledge`
+
+> `<agents...>` 示例：`cursor claude codex`。
+
+**步骤 2 完成后**：立刻执行上文 **「init 与技能自更新」**：重读 **`skills/f2s-kb-upgrade/SKILL.md`**；若有更新则 **从步骤 0 整技能重跑**，再回到步骤 3（避免用旧版 SKILL 做后续校验）。
+
+### 步骤 3：旧主题模板清理与引用修复（若存在则必须执行）
+
+**本技能步骤 2** `flow2spec init` 成功后，先执行「旧文件清理 + 引用修复」：
+
+1. 清理旧主题文件（仅在文件存在时删除）：
+   - `.Knowledge/topics/flow2spec-architecture.md`
+   - `.Knowledge/topics/implement-tech-design.md`
+   - `.Knowledge/topics/stock-docs-vs-req-docs.md`
+   - `templates/knowledge/topics/implement-tech-design.md`
+   - `templates/knowledge/topics/stock-docs-vs-req-docs.md`
+2. 修复引用（仅在文件存在时更新；**`.Knowledge/index.md` 正文不由 init 改写**，见步骤 3b）：
+   - `templates/knowledge/index.md`
+   - `templates/knowledge/manifest-routing.json`
+   - `.Knowledge/index.md`（按需人工或技能侧改路径/段落）
+   - `.Knowledge/manifest-routing.json`
+3. 引用更新目标：
+   - `.Knowledge/topics/f2s-flow2spec-architecture.md`
+   - `.Knowledge/topics/f2s-implement-tech-design.md`
+   - `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md`
+
+> 口径：只清理“旧命名主题文件”，不删除带 `f2s-` 前缀的新主题文件。
+
+### 步骤 3b：`index.md` 融合与 `template/index.template.md`（必须执行）
+
+> **范围**：本条「融合」**仅在本技能内由 Agent 落盘 `.Knowledge/index.md`**；**不要求、也不假设**修改 Flow2Spec 包内 **`cli.js` / `lib/init.js`** 等 JS。`init` 行为仍以仓库现行为准（仅复制快照等）。
+
+**`flow2spec init` 在本流程中的角色**：把包内 **`templates/knowledge/index.md` 原样复制**到 **`.Knowledge/template/index.template.md`**，作为**包版外壳对照**；**不**替代本步骤对 **`index.md`** 的融合书写。
+
+#### 融合规则（必须遵守）
+
+0. **写权归属**：本步骤的 `.Knowledge/index.md` 融合恒由主 agent 执行并落盘；子 agent 不得直接写入（写权硬约束）。
+1. **对照源**  
+   - **包版全文**：**`.Knowledge/template/index.template.md`**（与当前包 `templates/knowledge/index.md` 一致）。  
+   - **项目现状**：**`.Knowledge/index.md`**。
+
+2. **项目自身维护区（锚点：包模板 `index.md` 约第 18–19 行）**  
+   - 以包模板行号为参照：**从二级标题 `## 主题一览` 起**（对应模板中紧接上一段 `---` 之后的 **`## 主题一览`** 与节首空行，即常见 **第 18–19 行**），**直至本节结束**：即到 **紧挨在 `## 命中与执行`（含括号说明）之前的那个 `---` 之前**的整块内容（含「主题一览」下的表格、节内说明段落等）。  
+   - 该整块 **必须保留来自当前项目 `.Knowledge/index.md` 的正文**（由业务与 **f2s-*** 维护）；**禁止**用包模板同一段落**整体替换**覆盖（避免丢失业务主题行与摘要列）。  
+   - **允许**在该块内做**最小必要修补**：例如为包新增的 `topicPaths` 主题**补行**、按 **`manifest-routing.json` 的 `topicPaths`** 改正「路径」列、与快照对比后补上包模板里**新增**的表格列说明——仍以保留项目已有行为主。
+
+3. **必须与包模板一致的部分**  
+   - **上述维护区之外**的所有内容（含 **`## 主题一览` 之前**从文件开头到该节前、以及 **`## 命中与执行` 及之后**直到文件结尾）：须与 **`.Knowledge/template/index.template.md`** 中对应段落 **一致**（以包版为准；diff 后以模板覆盖项目侧旧文）。
+
+4. **产出**  
+   - 将融合后的完整 **`index.md`** 写回 **`.Knowledge/index.md`**。  
+   - **diff** 结论与是否改动写入步骤 5 摘要。
+
+5. **与 `--reset-knowledge` 的关系**  
+   - 若用户已 `reset`，`.Knowledge/index.md` 可能被模板整文件覆盖，仍须按本条 **2** 从备份或版本控制恢复「主题一览」块后再与包外壳做 **3** 的合并（若仓库无备份，则按 `topicPaths` + 快照**重建**主题表并让用户确认）。
+
+### 步骤 4：校验本技能执行结果（必须）
+
+至少校验：
+
+1. 步骤 2 的 `flow2spec init` 是否成功退出（exit code = 0）。
+2. init 输出是否包含 **路由清单与 `.Knowledge` 的结论**（已对齐/已最新/reset 覆盖等），以及 **`index.template.md` 已复制** 一行（若包内缺 `index.md` 则无此行）。
+3. `manifest-routing` 与各 `matcherPath` 分片是否可解析，且 `topicPaths` / `matcherId` 引用均有效。
+4. 存在 **`.Knowledge/template/index.template.md`**；已按步骤 **3b** 完成 **`index.md` 融合**（维护区保留 + 其余与包版一致）或写明待用户处理原因。
+5. 配置根产物是否存在：
+   - Cursor/Claude：`rules/`、`skills/`
+   - Codex：`.codex/AGENTS.md`、`skills/`
+
+### 步骤 5：输出结果摘要（必须）
+
+输出以下信息：
+
+- 执行命令（含 agent 与是否 reset）
+- 是否成功
+- 旧主题模板清理结论（删了哪些 / 哪些本就不存在）
+- `index/manifest` 引用修复结论
+- **index**：`index.template.md` 是否已生成；**`index.md` 融合**是否完成（锚点 **18–19「主题一览」节**保留、其余与包版一致）及 `topicPaths` / diff 结论（步骤 3b）
+- **SKILL 自更新**：`init` 后是否重读 `f2s-kb-upgrade/SKILL.md`；是否因文件变化 **整技能重跑**及轮次（见「init 与技能自更新」）
+- manifest / matchers 对齐结论（随 init 输出）
+- 关键文件校验结论
+- 如失败，给出下一步可执行修复建议
+
+## 输出摘要模板（建议）
+
+```markdown
+## f2s-kb-upgrade 执行结果
+
+- 本技能内代跑命令：`<实际执行的 flow2spec init ...>`
+- init 模式：`增量` / `覆盖重置（--reset-knowledge）`
+- 执行结果：`成功` / `失败`
+
+### 核心校验
+- 旧主题文件：`已清理` / `无需清理`
+- 引用修复：`已更新` / `已一致`
+- **index（快照 + 融合）**：`快照已复制` / `index.md 已融合` / `待处理（见备注）`
+- **f2s-kb-upgrade SKILL**：`init 后无变化` / `已按新版重跑 N 轮` / `待确认`
+- manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖`
+- topics.path：`全部存在` / `存在缺失（见下）`
+- agent 产物：`通过` / `异常（见下）`
+
+### 备注
+- <失败原因或后续建议>
+```
+
+## 约束
+
+- 不把“请用户自行运行命令”作为默认方案；优先由 Agent 直接执行。
+- 未经明确同意，不执行 `--reset-knowledge`。
+- 不修改业务代码；仅按 **本技能 `f2s-kb-upgrade`** 流程与结果做校验。
+- 步骤 3b `.Knowledge/index.md` 融合与 `manifest-routing.json` 均恒由主 agent 落盘（写权硬约束）；子 agent 仅可代跑 shell 命令。
+
+## 完成后自检
+
+1. 是否已做 **步骤 0**：V1 未跳过 migrate、**现行库（V2+）** 未误跑 migrate。
+2. 是否在 **步骤 2 的 `init` 之后**重读过 **`f2s-kb-upgrade/SKILL.md`**，并在有变化时 **整技能重跑**（见「init 与技能自更新」）。
+3. 是否已实际执行 shell 命令（而非只给建议）。
+4. 是否明确标注增量 or reset 模式。
+5. 是否已处理旧主题文件清理与 `index/manifest` 引用修复。
+6. 是否已执行 **步骤 3b**：**融合** `index.md`（**主题一览**节起至命中与执行前为项目维护区，其余同包版），并核对 `topicPaths`。
+7. 是否输出了 manifest 与关键路径校验结果。
+8. 若失败，是否给出下一步具体命令建议。
+9. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。

package/templates/skills/f2s-req-backend/SKILL.md

@@ -2,21 +2,29 @@
 name: f2s-req-backend
 description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成后端技术文档；触发：生成后端技术文档、后端技术方案
 ---
-> **「配置根」**：当前 agent 对应的 AI 工具配置目录（`flow2spec init` 写入，常见 **`.cursor/`**、**`.claude/`**、**`.codex/`**）。下文 **`配置根/...`** 指该目录下的相对路径。
+> 执行口径：业务文档统一在 `/.Knowledge/`，本技能只产出 `.Knowledge/req-docs` 方案文档并参考 `.Knowledge` 内知识，不修改配置根 `rules/skills`。
+
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
+- **拆子前提（硬约束）**：当 `subAgent=true` 时，主 agent **必须先**抽取一份「项目约定摘要」作为子 agent 的强制上下文，覆盖：对外契约规范、错误与返回约定、异步/集成规范、数据与存储约定、工程结构、模块边界，合计 **< 80 行**。若未做该前置，**不拆子**——验收返工成本 > 拆子收益，强行拆子得不偿失。
+- **子职责**：多源只读（`.Knowledge/topics`、`stock-docs`、澄清后的 `req-docs`、模版）+ 按 `.Knowledge/template/后端技术模版.md` 写 `req-docs` 方案初稿。
+- **主职责**：契约定稿、对照模版与澄清文档验收、处理接口/流程一致性。
+- **校验**：默认落盘侧自验；本技能不绑定交叉校验。
 
 # 根据需求生成后端技术文档
 
-用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、优先级等）。你需要**基于当前项目的知识库、配置根/skills、配置根/rules** 理解项目约定与能力，针对该需求输出一份**后端技术文档**。
+用户在对话中提供**已澄清的需求**（或需求摘要、PRD 路径），并可选择附带**需求条件**（如范围限定、必须/禁止使用的技术、优先级等）。你需要基于业务知识文档（`.Knowledge/`）和当前 agent 已加载的 rules/skills，输出一份可直接用于实现的后端技术文档。
 
 **用途**：本技能产出的技术方案**供后续代码实现使用**，开发按该文档实现功能。不用于生成 Rules/Skills。
 
-**结构范本**：技术方案按 `配置根/template/后端技术模版.md` 的章节顺序与书写要求输出。**接口与处理流程写在同一处**：每个接口小节内同时给出契约（请求/返回）与**处理流程**（分步说明、分支与错误码引用），**不要**再单独拆「接口及流程说明」「关联接口调用流程」「流程说明」等大章重复描述同一接口。
+**结构范本**：技术方案按 `.Knowledge/template/后端技术模版.md` 的章节顺序与书写要求输出。**接口与处理流程写在同一处**：每个接口小节内同时给出契约（请求/返回）与**处理流程**（分步说明、分支与错误码引用），**不要**再单独拆「接口及流程说明」「关联接口调用流程」「流程说明」等大章重复描述同一接口。
 
 ---
 
 ## 输入
 
-- **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 **`.cursor/req-docs/xxx.md`**、`配置根/stock-docs/需求_终稿.md`）。
+- **第一参数（必填）**：澄清后的需求描述，或**需求/PRD 文档路径**（如 `.Knowledge/req-docs/xxx.md`、`.Knowledge/stock-docs/需求_终稿.md`）。
 - **后续参数或用户补充（可选）**：需求条件与约束，例如：
   - 范围（只做某模块、某端）
   - 必须/禁止使用的中间件、接口风格
@@ -27,7 +35,22 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 ## 输出结构
 
-生成文档时，**按 `配置根/template/后端技术模版.md` 中的章节顺序与书写要求**输出；与需求无关的整节可省略。执行本技能时请**先读取该模版**作为结构与表述参考。
+生成文档时，**按 `.Knowledge/template/后端技术模版.md` 中的章节顺序与书写要求**输出；与需求无关的整节可省略。执行本技能时请**先读取该模版**作为结构与表述参考。
+
+---
+
+## 拆子前置（可选，仅当 `subAgent=true`）
+
+主 agent 在拆子前，必须产出「项目约定摘要」作为子 agent 的**强制输入**，否则**不拆子**。摘要篇幅上限 **< 80 行**，必须包含以下 6 类条款（技术栈无关，按项目实际填具体值）：
+
+1. **对外契约规范**：接口 / 事件 / 消息 / 脚本入口的命名、版本、鉴权、分页、通用返回字段等契约约定。
+2. **错误与返回约定**：错误码体系来源、前缀 / 分段规则、必选字段（如 code / message / data）、状态分层。
+3. **异步 / 集成规范**：消息队列 / 定时任务 / 外部服务调用的命名、消费者组织、重试与幂等约定。
+4. **数据与存储约定**：库 / 表 / 字段 / 缓存 / 文件 / 搜索等命名规范、主键 / 索引 / 时间字段约定、分库分表策略（若有）。
+5. **工程结构**:  后端模块分层（如 controller / service / dao / domain，或等价命名）与包路径 / 目录约定。
+6. **模块边界**：本方案涉及的既有模块与其他模块的调用 / 数据边界。
+
+未完成该前置即拆子，视为违反硬约束；摘要完成后方可将子任务交付子 agent。
 
 ---
 
@@ -35,18 +58,18 @@ description: 根据澄清后的需求基于项目知识库/Skills/Rules 生成
 
 1. **读取需求**：从用户提供的路径或正文获取需求内容；若有需求条件，一并纳入。
 2. **加载项目上下文**：主动读取并运用：
-   - `配置根/rules/` 下与接口、配置、MQ、数据等相关的规则；
-   - `配置根/skills/` 下与公共模块、接口约定、QMQ、配置、工具等相关的 Skill；
-   - 项目内已有技术方案；**结构对照 `配置根/template/后端技术模版.md`**。
+   - `.Knowledge/topics/` 下与接口、配置、MQ、数据相关的主题规则/流程；
+   - `.Knowledge/stock-docs/` 下的背景文档与历史技术方案；
+   - **结构对照 `.Knowledge/template/后端技术模版.md`**。
 3. **对齐项目约定**：接口命名、目录结构、配置中心、QMQ、错误码、表命名等与现有项目一致。
-4. **撰写文档**：按 `配置根/template/后端技术模版.md` 书写；**每个接口下写全处理流程**，避免接口与流程两张皮。
-5. **输出位置**：默认 **`配置根/req-docs/<方案名>_技术方案.md`**（如 `.cursor/req-docs/...`；方案名由需求主题推断）；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。
+4. **撰写文档**：按 `.Knowledge/template/后端技术模版.md` 书写；**每个接口下写全处理流程**，避免接口与流程两张皮。若启用拆子，子 agent 以「项目约定摘要」+ 澄清文档为强制输入，禁止自行扩展读取范围。
+5. **输出位置**：默认 `.Knowledge/req-docs/<方案名>_技术方案.md`；若用户指定路径则用该路径。完成后提示：技术方案已就绪，可据此进行代码实现。
 
 ---
 
 ## 约束
 
-- 所有路径相对于**配置根的父目录**。
+- 所有路径相对于项目根目录（与 `.Knowledge` 同级）。
 - 生成的是**后端技术文档**，不写前端 UI 细节（接口契约与入参出参除外）。
 - 不臆造与项目不符的约定；不确定时标注「待与项目约定确认」。
-- **原则**：接口小节 = 契约 + 处理流程，二者不拆章重复；结构以 `配置根/template/后端技术模版.md` 为准。
+- **原则**：接口小节 = 契约 + 处理流程，二者不拆章重复；结构以 `.Knowledge/template/后端技术模版.md` 为准。

package/templates/skills/f2s-req-clarify/SKILL.md

@@ -3,10 +3,18 @@ name: f2s-req-clarify
 description: 针对 PRD/需求反问直到清楚，再可用 f2s-req-backend 出技术方案；触发：需求澄清、PRD 澄清
 ---
 
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 两字段语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。本技能不复述。
+- 本技能默认**不拆子**：无论 `subAgent` 真值，澄清流程全程在主会话进行（追问与用户对齐强依赖连续同会话，拆子必断上下文）。
+- 校验口径为**落盘侧自验**，本技能不绑定交叉校验。
+
 # 需求澄清
 
-**入参**：可选。PRD 全文、需求描述或文档路径（如 **`.cursor/req-docs/xxx.md`**）；不传则按当前对话内容澄清。后续回复可补需求条件。
+> 执行口径：澄清文档统一落盘到 `.Knowledge/req-docs/`。
+
+**入参**：可选。PRD 全文、需求描述或文档路径（如 `.Knowledge/req-docs/xxx.md`）；不传则按当前对话内容澄清。后续回复可补需求条件。
 
 **行为**：找出需求中的模糊表述、未定义概念、缺失信息、矛盾、与实现相关但未说明的点 → 分组、具体可答地反问 → 根据回答迭代追问，直到流程、边界、异常、关键概念无歧义。不替用户做业务假设，不清楚就问。
 
-**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 **`.cursor/req-docs/`**。输出完文档后，再提示使用 **f2s-req-backend 技能**（可附带需求条件）生成技术方案，供后续代码实现。不在此阶段输出技术方案或接口设计。
+**结束**：当信息已足够清晰时，必须输出一份可直接落盘的「需求澄清文档」（Markdown）。文档至少包含：背景与目标、范围（包含/不包含）、关键流程、边界与异常、关键概念定义、验收标准、未决问题（如有）。建议保存到 `.Knowledge/req-docs/`。输出完文档后，再提示使用 `f2s-req-backend` 生成技术方案，供后续代码实现。

package/templates/skills/f2s-req-plan/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: f2s-req-plan
+description: 根据技术方案/需求描述/变更描述规划并实现任务；始终创建任务清单，支持子 agent 并行实现代码；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单
+---
+
+# 需求任务规划与实现（f2s-req-plan）
+
+从需求/技术方案出发，完整覆盖「规划 → 实现」链路。不依赖 `changeTracking` 配置，始终创建任务清单。知识库同步由用户后续按需调用 `f2s-kb-feat` / `f2s-kb-sync` 完成。
+
+## 编排（主 / 子 agent）
+
+- `subAgent` / `switchAgentVerification` 语义以统一入口为唯一事实源：**Cursor/Claude** 读 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`。
+- **步骤 1（解析）**：`subAgent=true` 时可拆子 agent 并行读多份文档/模块，仅只读，不落盘。
+- **步骤 2（草稿确认）**：必须主 agent，确认权不可下放。
+- **步骤 3（落盘任务清单）**：`task.md` / `context.md` / `user-todos.md` 可交子 agent 写初稿；**`user-todos.md` 中「执行中识别的用户代办」追加**优先主 agent 合并写盘，避免并发覆盖；`todo.json` 恒由主 agent 单点写入。
+- **步骤 4（实现代码）**：`subAgent=true` 时可按任务清单拆子 agent 并行实现各模块；**合并子 agent 结果后**，主 agent 须按 **`f2s-flow2spec-unified-entry`**「Git worktree 与子任务工作目录卫生」清理仅为子任务创建的 worktree / 隔离目录，并 `git worktree list` 自检。
+- **步骤 5（归档）**：主 agent 完成。
+- **步骤 6（摘要）**：主 agent 完成。
+- 落盘侧自验；`switchAgentVerification=true` 且技能正文明确标注时才启用交叉校验。
+
+## 输入（任选其一）
+
+- 技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）
+- 需求描述 / 变更描述（自由文本）
+
+## 步骤
+
+### 步骤 1：解析输入
+
+`subAgent=true` 时，可拆子 agent 并行执行（只读，不落盘）：
+
+- 读取技术方案 / 需求文档全文，提取目标、范围、主要工作项、涉及文件路径
+- 读取项目现有约定（`.Knowledge/stock-docs/`、架构说明）对齐实现上下文
+- 若输入为 PDF，先执行 `f2s-doc-pdf` 转为 MD，再继续
+
+子 agent 只输出「解析结果摘要」（目标、工作项列表、涉及文件）交主 agent 汇总；`subAgent=false` 时主 agent 直接完成。
+
+### 步骤 2：输出草稿并确认（必须主 agent）
+
+主 agent 基于步骤 1 汇总，输出规划草稿：
+
+1. **任务名称建议**（snake_case，如 `alipay_refund_feat`）
+2. **实现任务清单草稿**（每步独立可 checkbox）
+3. **涉及文件列表**
+4. **等待用户确认**
+
+> 未确认前禁止创建任何文件或写任何代码。
+
+### 步骤 3：落盘任务清单
+
+确认后：
+
+- **主 agent**：在 `todo.json` 新增条目（`linkedSkill: "f2s-req-plan"`）
+- **主 agent（`subAgent=false`）/ 子 agent（`subAgent=true`）**：
+  - 创建 `.task/active/<task-name>/task.md`
+  - 创建 `.task/active/<task-name>/context.md`
+  - 创建 `.task/active/<task-name>/user-todos.md`（见 `f2s-task`：固定文件名；尚无用户代办时写入简短占位说明即可）
+
+### 步骤 4：实现代码
+
+`subAgent=true` 时，按任务清单将各模块拆子 agent 并行实现：
+
+- 子 agent 只写实现代码
+- 子 agent 完成后向主 agent 汇报改动摘要（文件路径 + 改动说明）
+- `subAgent=false` 时主 agent 按清单逐项实现
+
+实现原则：
+
+- 复用现有依赖与封装，不引入不必要抽象
+- 与项目命名 / 目录 / 风格一致
+- 未实现或部分实现的能力补齐，不重做
+
+每完成清单中一步，立即用 `Edit` / `Write` 将 `task.md` 对应 checkbox 由 `[ ]` 改为 `[x]`，禁止批量勾选，禁止口头完成代替写盘（长记忆以磁盘 `task.md` 为准；见 `f2s-task`）。
+
+凡产生**须用户执行**的项（改库、配环境、审批等），**同会话内**追加写入 `user-todos.md`（见 `f2s-task`「user-todos.md」）；子 agent 若回报此类项，由主 agent 合并追加，禁止仅写在对话中。
+
+### 步骤 5：归档任务
+
+**仅当** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后：将 `.task/active/<task-name>/` 整体移至 `.task/completed/<YYYYMMDD>-<task-name>/`，从 `todo.json` 删除对应条目。若仍有 `[ ]`，禁止归档，应先补打钩或修订清单（与 `f2s-task` 归档门禁一致）。
+
+### 步骤 6：输出摘要
+
+```markdown
+## f2s-req-plan 完成：<任务名>
+
+### 实现
+- <文件路径>：<改动说明>
+
+### 待办（如需同步知识库）
+- 可后续调用 f2s-kb-sync 补充知识库
+
+### 用户代办（须用户在本机/平台完成）
+- 详见 `.task/active/<task-name>/user-todos.md`（归档后在 `completed/.../` 同路径）
+```
+
+## 约束
+
+- 不依赖 `changeTracking` 配置，始终创建任务清单
+- 步骤 2（草稿确认）必须主 agent，未确认前禁止落盘
+- `todo.json` 恒主 agent 单点写入
+- 禁止批量勾选 checkbox，逐步执行
+- 用户代办必须追加到 `user-todos.md`，禁止仅对话交付（见 `f2s-task`）
+
+## 完成后自检
+
+1. 任务清单步骤是否全部勾选（且已为磁盘上的 `[x]`，非仅对话宣称）。
+2. 实现代码是否覆盖草稿确认的范围。
+3. 满足归档门禁后：`.task/active/<task-name>/` 已移至 `completed/`（含 `user-todos.md`），`todo.json` 条目已删除。
+4. 凡有用户代办意图的，磁盘上 `user-todos.md` 已创建且与会话结论一致（无代办则可为占位说明）。
+5. 若曾拆子 agent / 并行实现且环境可能创建 **`git worktree`**：已按 **`f2s-flow2spec-unified-entry`** 清理或已交接删除命令；未使用 worktree 则标 N/A。

package/templates/skills/stock-docs-vs-req-docs/SKILL.md

@@ -3,24 +3,30 @@ name: stock-docs-vs-req-docs
 description: 文档目录 stock-docs 与 req-docs 分工；触发词：stock-docs、req-docs、f2s-ctx-build、f2s-doc-arch、f2s-doc-add、已落地能力、技术方案放哪、PDF 终稿
 ---
 
+## 编排（主 / 子 agent）
+
+- 两字段（`subAgent` / `switchAgentVerification`）语义以统一入口为唯一事实源：**Cursor/Claude** 读配置根 `rules/f2s-flow2spec-unified-entry.*`；**Codex** 读 `.codex/topics/f2s-flow2spec-unified-entry.md`（与上同源，`flow2spec init` 镜像）。
+- 本技能为**说明型**，**不拆子**（无拆子收益），主 agent 短答即可。
+- 落盘侧自验（本技能通常不产生落盘）。
+
 # stock-docs 与 req-docs（技能）
 
 ## 何时使用
 
 - 用户问「文档放哪」「PDF 转完放哪」「生成 Rules 用哪个目录」「技术方案目录」等。
-- 实现或命令执行时需要选择 **`配置根/stock-docs/`** 还是 **`配置根/req-docs/`**。
+- 实现或命令执行时需要选择 `.Knowledge/stock-docs/` 还是 `.Knowledge/req-docs/`。
 - 区分 **f2s-doc-arch**（架构说明**初稿**）与 **f2s-doc-add**（**工作中**把**已落地能力**从多文件解析进上下文）：二者产物都落在 **stock-docs/**，与 **req-docs** 无关；分工见 **`skills/f2s-doc-arch/SKILL.md`**、**`skills/f2s-doc-add/SKILL.md`**。
 
 ## 核心对照
 
 | 目录 | 位置 | 用途 |
 |------|------|------|
-| **stock-docs** | 配置根下 | **存量上下文源** → **f2s-ctx-build** 入参；**f2s-doc-final** 的初稿/终稿；**f2s-doc-arch** 的架构初稿；**f2s-doc-add** 聚合读源后的初稿与终稿（与 f2s-doc-arch 分工不同，见该 SKILL「使用时机」） |
-| **req-docs** | 配置根下（如 `.cursor/req-docs/`） | 需求与技术方案 → 按 `implement-tech-design` **写代码**、**f2s-doc-pdf** 输出 |
+| **stock-docs** | `.Knowledge/stock-docs/` | **存量上下文源** -> `f2s-ctx-build` 入参；`f2s-doc-final` 初稿/终稿；`f2s-doc-arch` 架构初稿；`f2s-doc-add` 聚合读源后的初稿与终稿 |
+| **req-docs** | `.Knowledge/req-docs/` | 需求与技术方案 -> 按 `implement-tech-design` 写代码、`f2s-doc-pdf` 输出 |
 
 ## 常见错误
 
-- 把 **仅用于实现代码** 的 **`配置根/req-docs/xxx.md`** 当作 **f2s-ctx-build** 技能的入参（应先把符合终稿范式的内容放到 **stock-docs** 再生成上下文）。
+- 把 **仅用于实现代码** 的 `.Knowledge/req-docs/xxx.md` 当作 `f2s-ctx-build` 入参（应先把符合终稿范式的内容放到 `.Knowledge/stock-docs/` 再生成上下文）。
 - 在 Rule 内链到 **`req-docs/`**（应链到 **stock-docs** 中的源文档）。
 - 把 **f2s-doc-add** / **f2s-doc-arch** 产出的初稿、终稿误存到 **req-docs**（应始终在 **stock-docs/**）。