@double-codeing/flow2spec 3.0.9 → 3.0.11

package/cli.js

@@ -12,6 +12,8 @@ const {
   getMissingConfigFields,
 } = require("./lib/flow2specConfig");
 
+const { execSync } = require("child_process");
+
 const args = process.argv.slice(2);
 const sub = args[0];
 
@@ -19,12 +21,16 @@ const agentList = Object.entries(AGENTS)
   .map(([id, { label }]) => `${id}(${label})`)
   .join(", ");
 
+const pkg = require("./package.json");
+
 const help = `
-Flow2Spec - 统一知识库工作流（AI 配置入口）
+Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
 
 用法:
   flow2spec init [agent ...] [--reset-knowledge] [--yes]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
   flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
+  flow2spec version             显示当前 flow2spec 版本
+  flow2spec update              更新 flow2spec 到最新版本
   flow2spec --help              显示本说明
 
 agent（可多个，空格分隔；省略时交互选择）：
@@ -60,6 +66,35 @@ if (sub === "--help" || sub === "-h" || !sub) {
   process.exit(0);
 }
 
+if (sub === "version" || sub === "--version" || sub === "-v") {
+  console.log(`flow2spec v${pkg.version}`);
+  process.exit(0);
+}
+
+if (sub === "update") {
+  console.log(`当前版本: v${pkg.version}`);
+  console.log("正在检查最新版本...");
+  try {
+    const latest = execSync(`npm view ${pkg.name} version`, {
+      encoding: "utf8",
+    }).trim();
+    if (latest === pkg.version) {
+      console.log(`已是最新版本 v${latest}`);
+      process.exit(0);
+    }
+    console.log(`发现新版本: v${latest}`);
+    console.log("正在更新...");
+    execSync(`npm install -g ${pkg.name}@latest`, {
+      stdio: "inherit",
+    });
+    console.log(`\n✓ 已更新到 v${latest}`);
+  } catch (e) {
+    console.error("更新失败:", e.message || e);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (sub === "config") {
   const cwd = process.cwd();
   const abs = path.join(cwd, CONFIG_FILENAME);

package/docs/README-/345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -6,64 +6,84 @@
 
 **作用**：根据用户说明或扫描代码，生成项目架构说明初稿。无固定格式要求，描述清楚系统结构、模块关系、关键决策即可。
 
+**工作原理**：以「inventory 驱动扫描」为核心——先由主 agent 产出模块清单（inventory）与扫描契约（读哪些入口、关注哪些维度），再按 inventory 执行只读代码扫描，最后将扫描结果聚合为人可读的架构初稿落盘 `stock-docs/`。整个流程不改代码，仅做「代码→文档」的单向提取。
+
 **使用场景**：
+
 - 新项目需要架构文档
 - 存量项目需要补充架构说明
 - 系统重构后更新架构描述
 
 **关联关系**：
+
 - **前置**：无
 - **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`
 - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内扫描代码并生成
 - `subAgent: true`：默认走 **B 模式**（主产出 inventory + 扫描契约 → 子 agent 并行只读扫表 → 主合并落盘）；满足以下任一条件时升级为 **C 模式**（多轮纠偏）：多 workspace / monorepo、源路径 > 20 条、首轮子表有矛盾或空洞、多源叙述冲突严重
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 产出 inventory（入口 + 核心模块名）与扫描契约，汇总子 agent 交付，落盘 stock-docs 初稿 |
+
+
+| 角色              | 职责                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| 主 agent         | 产出 inventory（入口 + 核心模块名）与扫描契约，汇总子 agent 交付，落盘 stock-docs 初稿                                |
 | 子 agent（B/C 模式） | 按主手写 inventory 并行只读扫描，按统一 YAML schema 交付（`source / scope / cross_refs / pending`），不得自行裁剪范围 |
 
+
 ---
 
 ### `f2s-doc-final`
 
 **作用**：将 PDF 技术方案或初稿文档转为《终稿模版》规范格式，统一文档结构，便于后续进入知识库。
 
+**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-ctx-build` 的标准输入物，确保知识库入口的结构一致性。
+
 **使用场景**：
+
 - PDF 技术方案需要转为 Markdown
 - 初稿需要规范化以便沉淀
 - 外部文档需要纳入 Flow2Spec 管理
 
 **关联关系**：
+
 - **前置**：PDF 文档或初稿文档
 - **后续**：`f2s-ctx-build`（终稿入库）
 - **输出**：`.Knowledge/stock-docs/<文档>_终稿.md`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成全流程
 - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做套模版与排版草稿；子不追问用户、不补写流程说明、不宣称终稿合规；主 agent 识别格式缺口并定稿验收
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿 |
+
+
+| 角色      | 职责                    |
+| ------- | --------------------- |
+| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿  |
 | 子 agent | 套模版与排版草稿，不追问用户、不写流程说明 |
 
+
 ---
 
 ### `f2s-ctx-build`
 
 **作用**：将 `stock-docs/` 中的沉淀文档（架构、终稿）同步到知识库路由系统，生成/更新主题文件、索引、manifest-routing、matchers。
 
+**工作原理**：以终稿文档为输入，执行「文档→路由」的三步映射：① 从终稿中提取能力主题与关键词；② 生成 `topics/<topic>.md`（路由摘要，含执行边界与下一步指针）和 `matchers/<id>.json`（机读匹配词 `includeAny`）；③ 在 `manifest-routing.json` 注册 task→topic 映射规则，并更新 `index.md` 人读导航。完成后，任务路由引擎即可通过关键词命中该主题。
+
 **使用场景**：
+
 - 终稿文档完成后，需要让知识库"知道"这些文档
 - 新增业务领域，需要建立路由映射
 - 文档内容更新后，同步更新知识库索引
 
 **关联关系**：
+
 - **前置**：`f2s-doc-arch`、`f2s-doc-final` 或直接编写的终稿
 - **后续**：无（入库完成后可直接使用）
 - **输入**：`.Knowledge/stock-docs/*.md`
@@ -74,44 +94,57 @@
   - `.Knowledge/matchers/*.json`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内顺序处理各文档
 - `subAgent: true`：改动超过阈值（新增/修改主题 > 2 个 OR 新增 matcher > 1 个 OR 涉及跨主题批量引用调整）时拆子；子A 只写 topics/、子B 只写 matchers/；主 agent 单点编辑 manifest-routing.json 和 index.md，子 agent 不跨边界落盘
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 单点落盘 manifest-routing.json 和 index.md，整体验收 |
-| 子 agent（topics） | 仅写 topics/ 目录下的主题文件，不触碰 manifest 和 index |
+
+
+| 角色                | 职责                                         |
+| ----------------- | ------------------------------------------ |
+| 主 agent           | 单点落盘 manifest-routing.json 和 index.md，整体验收 |
+| 子 agent（topics）   | 仅写 topics/ 目录下的主题文件，不触碰 manifest 和 index   |
 | 子 agent（matchers） | 仅写 matchers/ 目录下的分片文件，不触碰 manifest 和 index |
 
+
 ---
 
 ### `f2s-doc-add`
 
 **作用**：将已落地能力（多文件聚合）解析进知识库。适用于代码已实现但缺少文档，或已有多个文档需要统一入库的场景。
 
+**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-ctx-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。
+
 **使用场景**：
+
 - 存量代码需要补录知识库
 - 多份相关文档需要聚合入库
 - 第三方文档批量导入
 
 **关联关系**：
+
 - **前置**：无（可直接触发）
 - **后续**：无（入库完成即结束）
 - **流程**：初稿 → 终稿 → topics/index/manifest
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内顺序处理
 - `subAgent: true`：满足以下任一阈值时启用，默认走 **B 模式**（主产出 inventory → 子并行只读按 schema 填表 → 主合并落盘）；多 workspace / monorepo、首轮子表矛盾或空洞、多源叙述冲突严重时升级 **C 模式**（多轮纠偏）
   - 阈值：输入路径 ≥ 5 条 OR 单源 > 3000 行 OR 多路径总量 > 10000 行
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 产出 inventory 与扫描契约，汇总子表，落盘 topics/index/manifest |
+
+
+| 角色              | 职责                                                                                                                                |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| 主 agent         | 产出 inventory 与扫描契约，汇总子表，落盘 topics/index/manifest                                                                                  |
 | 子 agent（B/C 模式） | 按主手写 inventory 执行只读扫描，按 schema 交表（`source / scope / capabilities / cross_refs / pending`）；不得自行裁剪范围、不写 manifest 和 index、不宣布"已进知识库" |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 落盘的 topic 文件 → 主 agent 校验路由映射完整性与关键词覆盖
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -121,17 +154,22 @@
 
 **作用**：按 stock-docs 文档删除对应的知识主题与索引映射。仅删除知识库中的引用关系，不删除源文档本身。
 
+**工作原理**：`f2s-ctx-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。
+
 **使用场景**：
+
 - 文档已废弃，需要从知识路由中移除
 - 误入库的文档需要撤销路由映射
 - 文档合并后清理旧映射
 
 **关联关系**：
+
 - **前置**：已入库的 stock-docs 文档
 - **后续**：无
 - **注意**：只删路由映射，不删源文档
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内全流程执行（单点删除拆子收益低）
 - `subAgent: true`：仅当**批量删除 ≥ 5 个主题**时才拆子执行删除与清引用；主 agent 必控范围确认与 fallbackTopic 重指；manifest-routing.json 与 index.md 恒由主落盘
 
@@ -141,28 +179,36 @@
 
 **作用**：将 PDF 技术方案转为 Markdown 格式，保存到 `req-docs/`，可补全流程说明。
 
+**工作原理**：面向「按方案实现代码」的前置环节——将 PDF 中的接口定义、数据模型、时序流程等结构化内容提取为 Markdown 格式并落盘 `req-docs/`。与 `f2s-doc-final` 的区别在于目标路径和用途：`doc-pdf` 输出到 `req-docs/` 供 `implement-tech-design` 规则消费驱动编码，`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。
+
 **使用场景**：
+
 - 收到 PDF 格式技术方案需要实现
 - 历史 PDF 文档需要纳入管理
 - 跨团队交付物为 PDF 时需要转换
 
 **关联关系**：
+
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
 - **下一步**：
   - 1. 如果是需求实现：提供转换后的方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码
-  - 2. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
+  - 1. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成全流程
 - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做 PDF→MD 首稿落盘 req-docs；子不追问用户、不补写流程说明章节；主 agent 接手追问与流程说明补写
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收 |
+
+
+| 角色      | 职责                              |
+| ------- | ------------------------------- |
+| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收     |
 | 子 agent | 仅做 PDF→MD 首稿并落盘 req-docs，不向用户追问 |
 
+
 ---
 
 ## 2) 需求与方案
@@ -171,12 +217,16 @@
 
 **作用**：针对 PRD/需求文档进行反问澄清，通过多轮问答明确需求边界、非目标、关键流程，直至需求足够清晰可供技术方案编写。
 
+**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-backend` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。
+
 **使用场景**：
+
 - 收到 PRD 后首步骤，确保理解正确
 - 需求边界模糊、缺少验收标准时
 - 跨团队协作需求，需明确接口契约
 
 **关联关系**：
+
 - **前置**：无（可直接触发）
 - **后续**：`f2s-req-backend`（澄清后生成技术方案）
 - **输出**：需求澄清记录（可选保存至 `.Knowledge/req-docs/`）
@@ -189,26 +239,35 @@
 
 **作用**：基于已澄清的需求和项目知识库，生成后端技术方案文档，包含接口设计、数据模型、流程说明、错误码等。
 
+**工作原理**：以「知识库约束 + 模版驱动」为核心——先从 `topics/stock-docs` 中抽取当前项目的架构约定、接口风格、数据模型规范等约束摘要，再将澄清后的需求对照后端技术方案模版（接口/模型/流程/异常/配置/迁移）逐章填写，确保方案与现有架构一致。输出落盘 `req-docs/`，即为 `implement-tech-design` 的编码依据。
+
 **使用场景**：
+
 - `f2s-req-clarify` 完成后，基于澄清结果输出方案
 - 已有明确需求文档，直接生成技术方案
 
 **关联关系**：
+
 - **前置**：`f2s-req-clarify`（推荐）或明确的需求文档
 - **输出**：`.Knowledge/req-docs/<技术方案>.md`
 - **下一步**：提供技术方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成方案编写
 - `subAgent: true`：主 agent 必须先从 topics/stock-docs 抽取 < 80 行项目约定摘要（含架构约定、接口风格、数据模型规范等 6 类条款）作为子强制上下文，再拆子并行写 req-docs 初稿；主 agent 做契约定稿与验收
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 抽取项目约定摘要、分配写作任务、对照模版做定稿验收并写入 req-docs |
+
+
+| 角色      | 职责                                                                      |
+| ------- | ----------------------------------------------------------------------- |
+| 主 agent | 抽取项目约定摘要、分配写作任务、对照模版做定稿验收并写入 req-docs                                   |
 | 子 agent | 只读多源（topics / stock-docs / 澄清 req-docs / 模版），按模版写 req-docs 初稿；不自行扩展读取范围 |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 落盘的接口/模型/流程文档 → 主 agent 校验跨章节一致性（接口签名与数据模型对齐、流程与异常处理覆盖）
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -218,27 +277,35 @@
 
 **作用**：从技术方案或需求描述出发，**始终创建任务清单**，然后按清单实现代码。不依赖 `changeTracking` 配置，代表用户明确需要可追溯的任务管理。
 
+**工作原理**：执行「解析→规划→确认→实现→归档」五阶段闭环。① 解析技术方案文档提取实现要点；② 按模块/功能粒度拆分为可执行任务清单并写入 `.task/`；③ 展示草稿给用户确认后锁定清单；④ 按清单逐项实现代码，每完成一项立即打钩 `task.md`；⑤ 全部完成后归档。与 `implement-tech-design` 规则的区别：`req-plan` 始终带任务追踪且支持并行子 agent 实现，适合大型需求；后者是轻量规则驱动的单线程编码。
+
 **使用场景**：
+
 - 有技术方案文档，需要拆解为任务清单后再实现
 - 需求描述较复杂，希望先确认清单再动手
 - 希望跨会话追踪实现进度
 
 **关联关系**：
+
 - **前置**：技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）或需求/变更描述
 - **输出**：`.task/active/<task-name>/task.md` + `context.md`；实现代码
 - **后续**：可按需调用 `f2s-kb-sync` 补充知识库
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成解析、确认、实现全流程
 - `subAgent: true`：步骤 1（解析文档）可拆子并行只读；步骤 2（草稿确认）必须主 agent；步骤 4（实现代码）可按模块拆子并行；`todo.json` 恒由主 agent 写
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要 |
-| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘 |
+
+
+| 角色          | 职责                                   |
+| ----------- | ------------------------------------ |
+| 主 agent     | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要       |
+| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘                    |
 | 子 agent（实现） | 按模块实现代码，不触碰 `.task/` 和 `.Knowledge/` |
 
+
 ---
 
 ## 3) Git 提交
@@ -247,17 +314,22 @@
 
 **作用**：代码写完后执行 Git 提交。自动检查变更文件、比对知识库覆盖情况，未入库的能力会提示用户处理，确认提交信息后执行 commit。
 
+**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
+
 **使用场景**：
+
 - 每次功能实现或 Bug 修复后提交代码
 - 希望在提交时得到知识库覆盖情况的提醒
 - 需要 AI 帮助生成有意义的提交信息
 
 **关联关系**：
+
 - **前置**：代码已写完（`implement-tech-design`、`f2s-kb-fix`、`f2s-kb-feat` 等执行后）
 - **后续**：无（commit 完成即结束，不自动 push）
 - **可衔接**：若知识库未覆盖，可先运行 `f2s-kb-sync` 或 `f2s-kb-feat` 补录后继续提交
 
 **执行流程**：
+
 1. `git status --short` + `git diff HEAD` 区分 staged / unstaged / untracked 三类文件；发现 merge conflict 标记立即终止
 2. 对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示
 3. 未覆盖时提示用户选择：A) 先补录再提交 / B) 先提交稍后补录 / C) 取消
@@ -266,6 +338,7 @@
 6. 输出 commit hash；若选 B 则附带未补录能力提醒
 
 **约束**：
+
 - 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件
 - 禁止 `--no-verify`，hook 失败须修复后重试
 - 禁止自动 push
@@ -281,7 +354,10 @@
 
 **作用**：根据用户指出的实现或规则错误修正代码，并**默认自动同步**知识库相关文档与索引。
 
+**工作原理**：执行「定位→修复→同步」三步——先根据用户描述在知识库路由（manifest→topic→stock-docs）中定位相关上下文与代码位置，确认问题根因；修复代码后，自动检查 `topics/stock-docs/matchers` 中与该能力相关的描述是否因修复而需要更新，若有则原位修订（现行真值覆盖，不追加历史否定句）。「修代码必同步文档」是核心原则，避免知识库与实现漂移。
+
 **使用场景**：
+
 - 代码实现与技术方案不符
 - 规则理解有误需要修正
 - Bug 修复后需要同步文档
@@ -289,22 +365,28 @@
 **变更追踪**：若 `changeTracking.fix: true`，执行前自动检查 `.task/todo.json` 并创建任务清单，完成后自动归档；跨会话可通过关键词续作（见 `f2s-task` 规则）。
 
 **关联关系**：
+
 - **前置**：问题发现（代码实现错误或规则偏差）
 - **后续**：无（修复并同步完成即结束）
 - **特点**：无需用户额外要求"请同步知识库"，自动完成
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成修复和知识库同步
 - `subAgent: true`：代码子包（bug 修复）可外包给子 agent；文档子包（rules/skills/topics 文风类）默认主 agent 直接写，如拆则子 agent 仅输出 before/after diff 片段，不整文件重写；manifest 和 index 恒由主落盘
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 定位问题根因、制定修复方案、落盘文风合规内容、校验知识库一致性 |
-| 子 agent（代码） | 负责指定模块的代码 bug 修复，输出变更并报告影响范围 |
+
+
+| 角色             | 职责                                                   |
+| -------------- | ---------------------------------------------------- |
+| 主 agent        | 定位问题根因、制定修复方案、落盘文风合规内容、校验知识库一致性                      |
+| 子 agent（代码）    | 负责指定模块的代码 bug 修复，输出变更并报告影响范围                         |
 | 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 落盘的代码变更 → 主 agent 校验修复正确性与知识库一致性
 - 主 agent 落盘的知识库同步 → 子 agent 复核 topic/manifest 一致性（须 `subAgent: true` 且已拆出子任务，否则主 agent 内自验）
 - 复核方与落盘方必须为不同 agent 实例
@@ -315,29 +397,38 @@
 
 **作用**：新增能力时补全实现与知识库；若能力已实现，则仅同步知识库。
 
+**工作原理**：执行「判断→实现→入库」三阶段——先判断用户描述的能力在代码中处于「未实现/部分实现/已实现」哪种状态；未实现或部分实现时先补齐代码；最后走知识库同步：写 `stock-docs` 能力说明、生成或更新 `topics` 主题摘要、在 `manifest-routing` 和 `matchers` 注册路由映射。与 `f2s-kb-fix` 的区别：`kb-feat` 面向「新增」，`kb-fix` 面向「修正已有」。
+
 **使用场景**：
+
 - 新功能开发
 - 存量功能需要补录知识库
 
 **变更追踪**：若 `changeTracking.feat: true`，执行前自动检查 `.task/todo.json` 并创建任务清单，完成后自动归档；跨会话可通过关键词续作（见 `f2s-task` 规则）。
 
 **关联关系**：
+
 - **前置**：无（可直接触发）
 - **后续**：无（实现+同步完成即结束）
 - **特点**：自动同步知识库，无需用户额外要求
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成
 - `subAgent: true`：代码子包（新增实现）可外包给子 agent；文档子包（rules/skills/topics 文风类）默认主 agent 直接写，如拆则子 agent 仅输出 before/after diff 片段；manifest 和 index 恒由主落盘
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 确定能力边界与实现范围、落盘文风合规内容、最终校验知识库一致性 |
-| 子 agent（代码） | 负责代码实现（接口、逻辑、数据层），输出实现清单 |
+
+
+| 角色             | 职责                                                   |
+| -------------- | ---------------------------------------------------- |
+| 主 agent        | 确定能力边界与实现范围、落盘文风合规内容、最终校验知识库一致性                      |
+| 子 agent（代码）    | 负责代码实现（接口、逻辑、数据层），输出实现清单                             |
 | 子 agent（文档，可选） | 仅输出 before/after diff 片段，不整文件重写，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 文档子 agent 落盘的 topic → 主 agent 校验与实现代码的能力描述一致性
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -348,28 +439,35 @@
 **作用**：将会话中的已实现能力沉淀回知识库。可显式给出能力或零输入推断。
 
 **使用场景**：
+
 - 会话中已完成实现，需要补录知识库
 - 从代码反向沉淀知识
 - 定期知识库整理
 
 **关联关系**：
+
 - **前置**：无（可直接触发，或零输入推断）
 - **后续**：无
 - **特点**：先输出知识库更新大纲，用户确认后才写入
 - **与 `f2s-ctx-build` 区别**：`ctx-build` 从 `stock-docs` 驱动，`kb-sync` 从会话/代码推断
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成推断和同步
 - `subAgent: true`：分步骤拆子——**步骤 1**（汇总推断）可拆子并行只读会话历史；**步骤 2**（用户确认大纲）必须在主 agent 完成；**步骤 3**（落盘同步）可拆子写 topic/matcher，但子落盘前须读近邻 2–3 个主题摘要做风格对齐；manifest 和 index 恒由主落盘
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 输出大纲并确认、单点落盘 manifest 和 index、最终验收 |
-| 子 agent（汇总） | 只读会话历史、推断能力点、生成结构化更新大纲片段 |
+
+
+| 角色          | 职责                                                      |
+| ----------- | ------------------------------------------------------- |
+| 主 agent     | 输出大纲并确认、单点落盘 manifest 和 index、最终验收                      |
+| 子 agent（汇总） | 只读会话历史、推断能力点、生成结构化更新大纲片段                                |
 | 子 agent（同步） | 按大纲写 topic/matcher，落盘前加载近邻主题摘要对齐风格，不触碰 manifest 和 index |
 
+
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 同步子 agent 落盘的 topic/matcher → 主 agent 校验跨 topic 路由完整性与 `includeAny` 关键词覆盖
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -379,57 +477,74 @@
 
 **作用**：解决 Git 合并后的编辑器上下文冲突。可选传入冲突文件路径。
 
+**工作原理**：按文件类别分层处理冲突——将冲突文件分为「可安全自动合并」（index、manifest、matchers 等结构化文件，取并集或最新版本）和「须用户确认」（实现代码、业务规则等语义文件）两类。对前者自动 resolve，对后者生成分类对照表（ours/theirs 摘要 + 建议）并罗列差异，等待用户逐项裁决。核心设计思想：知识库元数据可自动化，业务语义不可擅自裁定。
+
 **使用场景**：
+
 - Git merge/rebase 后出现上下文冲突
 - 多人协作导致知识库文件冲突
 - 分支合并后需要统一知识库状态
 
 **关联关系**：
+
 - **前置**：Git 合并产生的冲突
 - **后续**：无（冲突解决即结束）
 - **特点**：实现侧冲突仅罗列待用户确认
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内分析与解决冲突
 - `subAgent: true`：可拆子做冲突扫描与分类对照表（`file / category / ours_summary / theirs_summary / recommendation` 五字段）；子不得自行合并文件；主 agent 按策略落盘、处理实现侧决策、完成验收
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
-| 主 agent | 按策略落盘合并结果、处理实现侧冲突决策、验收 |
+
+
+| 角色      | 职责                                  |
+| ------- | ----------------------------------- |
+| 主 agent | 按策略落盘合并结果、处理实现侧冲突决策、验收              |
 | 子 agent | 仅做冲突扫描与分类，按五字段 schema 交付对照表，不自行合并文件 |
 
+
 ---
 
 ### `f2s-kb-migrate`
 
 **作用**：将旧版知识库（`docs-index.md` + `rules/` 模式）按主题迁移到 `.Knowledge/` 结构。
 
+**工作原理**：以旧版 `docs-index.md` 和 `rules/main.md(c)` 为「索引线索」，递归识别所有被引用的业务规则和技能文件，按主题粒度重新组织到 `.Knowledge/` 的 `topics/stock-docs/req-docs` 三层结构中。迁移完成后落盘 `migration-report.md`（对照表 + 拟删路径），待用户确认后清理旧文件。本质是一次性的结构重组，将分散的规则/文档归并为统一知识库。
+
 **使用场景**：
+
 - 旧项目升级到 Flow2Spec 新版
 - 存量知识库需要结构化整理
 
 **关联关系**：
+
 - **前置**：旧版知识库（`docs-index.md`、`rules/`、`skills/`）
 - **后续**：`f2s-kb-upgrade`（**流程 V1** 旧库须先 migrate 再 upgrade；**现行库 V2+**（含 npm v3.x）见 upgrade 技能步骤 0）
 - **流程**：
   1. 以 `docs-index.md` + `rules/main.md(c)` 为主索引
-  2. 全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-*` 包技能）
+  2. 全量处理业务 `rules/` 与业务 `skills/`（排除 `f2s-`* 包技能）
   3. 全量迁移 `stock-docs`/`req-docs`
   4. 落盘 `.Knowledge/migration-report.md`
   5. 用户确认后删除已迁旧的文件
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内逐主题迁移
 - `subAgent: true`：子只做搬运 + migration-report 草案片段（以 patch 形式交付）；状态文件（migration-report.md、删除执行记录）由主 agent 唯一落盘；主 agent 主导删除清单确认与删除闭环
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
+
+
+| 角色      | 职责                                            |
+| ------- | --------------------------------------------- |
 | 主 agent | 制定迁移规划、合并迁移结果、落盘 migration-report、主导删除确认与执行闭环 |
-| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录 |
+| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录    |
+
 
 **交叉验证（`switchAgentVerification: true` 时）**：
+
 - 子 agent 迁移落盘的主题 → 主 agent 校验迁移完整性（旧路径是否全量覆盖、主题边界是否重叠）
 - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证
 
@@ -439,28 +554,37 @@
 
 **作用**：知识库模板升级。对齐 manifest-routing + matchers 分片。
 
+**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构，需先 migrate）还是 V2+（已有 `.Knowledge`），V1 走 migrate 后再 init，V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐。
+
 **使用场景**：
+
 - flow2spec 包版本升级后，升级项目知识库模板
 - 旧项目升级到最新结构
 
 **关联关系**：
+
 - **前置**：`f2s-kb-migrate`（V1 流程）或已存在的 `.Knowledge/`
 - **包含**：内部会调用 `flow2spec init` 进行结构对齐
 - **注意**：单独的 `flow2spec init` **不是**升级命令
 
 **流程差异**（技能内分流代号，**不等于** npm 包主版本号）：
+
 - **V1**：先 `f2s-kb-migrate` 再代跑 `flow2spec init`
 - **现行库（V2+）**：已稳定 `.Knowledge` + `manifest-routing` 时，代跑 `flow2spec init` 以对齐 manifest-routing + matchers 分片（**含 Flow2Spec npm v3.x 等**，详见 `skills/f2s-kb-upgrade/SKILL.md` 步骤 0）
 
 **子 agent 调用**：
+
 - `subAgent: false`（默认）：主 agent 内完成升级
 - `subAgent: true`：子 agent 仅承接 shell 命令执行（代跑 `flow2spec init`），不承担知识库正文落盘；以下步骤主 agent 不可下放：版本分流（V1 / 现行库 V2+）、init 后重读 SKILL.md 并判断是否整技能重跑、步骤 3b index.md 融合、校验摘要输出
 
 **职责划分**：
-| 角色 | 职责 |
-|------|------|
+
+
+| 角色      | 职责                                                                            |
+| ------- | ----------------------------------------------------------------------------- |
 | 主 agent | 版本分流、init 后重读并判断重跑、步骤 3b index.md 融合、校验摘要；落盘 manifest-routing.json 和 index.md |
-| 子 agent | 仅代跑 `flow2spec init` 等 shell 命令，不落盘知识库内容 |
+| 子 agent | 仅代跑 `flow2spec init` 等 shell 命令，不落盘知识库内容                                      |
+
 
 **交叉验证**：本技能不绑定交叉校验，落盘侧自验。
 
@@ -470,23 +594,37 @@
 
 以下不是技能命令，而是通过触发词激活的规则，用于辅助指导 Agent 的行为。
 
+### `f2s-karpathy-guidelines`
+
+**触发词**：`alwaysApply`（始终生效，无需显式触发）
+
+**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
+
+**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
+
+---
+
 ### `f2s-task`
 
 **触发词**：changeTracking、变更追踪、任务追踪、续作、继续上次任务
 
-**作用**：变更追踪规则（`alwaysApply`）。当对应技能的 `changeTracking.*` 为 `true` 时，在技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。
+**作用**：变更追踪规则（`alwaysApply`）。当对应技能的 `changeTracking.`* 为 `true` 时，在技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。
+
+**工作原理**：基于「磁盘 checkpoint + 关键词匹配」实现跨会话状态持久化——每个活跃任务在 `.task/active/<name>/task.md` 中以 checkbox 记录进度（`[ ]`/`[x]`），`todo.json` 作为活跃任务索引。新会话开始时，规则自动将用户首条消息与各任务的 `keywords` 做模糊匹配：命中则加载 `task.md` 剩余步骤和 `linkedSkill` 对应的技能文件，恢复完整执行上下文。任务完成后移入 `completed/` 归档。核心设计：以文件系统而非对话记忆作为状态真值，对话中断不丢进度。
 
 **生效范围**：
 
-| 配置项 | 对应技能 |
-|--------|---------|
-| `changeTracking.feat` | `f2s-kb-feat` |
-| `changeTracking.fix` | `f2s-kb-fix` |
+
+| 配置项                        | 对应技能                        |
+| -------------------------- | --------------------------- |
+| `changeTracking.feat`      | `f2s-kb-feat`               |
+| `changeTracking.fix`       | `f2s-kb-fix`                |
 | `changeTracking.implement` | `f2s-implement-tech-design` |
 
+
 **跨会话续作**：新会话开始时若存在 `.task/todo.json`，自动将用户首条消息与各任务 `keywords` 匹配；命中则加载对应 `task.md` 及 `linkedSkill` 技能文件，展示剩余清单，提示是否继续；无命中则不打扰。
 
-**规则位置**：`配置根/rules/f2s-task.*`
+**规则位置**：`配置根/rules/f2s-task.`*
 
 ---
 
@@ -496,14 +634,19 @@
 
 **作用**：区分知识沉淀目录与需求实现目录的边界。
 
+**工作原理**：通过「用途隔离」避免文档混放——`stock-docs/` 存放已沉淀的存量知识（架构、终稿），由 `ctx-build` 消费入库，禁止直接用于编码；`req-docs/` 存放面向实现的需求与技术方案，由 `implement-tech-design` 规则消费驱动编码。两目录的写入者和消费者完全隔离，防止「存量描述被当编码依据」或「实现方案被当能力沉淀」的混淆。
+
 **目录分工**：
 
-| 目录 | 用途 | 写入时机 |
-|------|------|----------|
-| `stock-docs/` | 存量沉淀（架构、终稿） | `f2s-doc-arch`、`f2s-doc-final`、`f2s-ctx-build` |
-| `req-docs/` | 需求与技术方案（驱动实现） | `f2s-req-backend`、`f2s-doc-pdf`、手动放置 |
+
+| 目录            | 用途            | 写入时机                                           |
+| ------------- | ------------- | ---------------------------------------------- |
+| `stock-docs/` | 存量沉淀（架构、终稿）   | `f2s-doc-arch`、`f2s-doc-final`、`f2s-ctx-build` |
+| `req-docs/`   | 需求与技术方案（驱动实现） | `f2s-req-backend`、`f2s-doc-pdf`、手动放置           |
+
 
 **使用场景**：
+
 - 不确定文档应该放哪里
 - 需要明确 stock-docs 与 req-docs 的分工
 
@@ -515,13 +658,17 @@
 
 **作用**：根据 `req-docs/` 中的技术方案文档实现可运行代码。
 
+**工作原理**：以「方案即合约」为核心约束——Agent 以 `req-docs/` 中的技术方案为唯一编码依据，按「理解方案→输出任务列表→提问确认→逐步实现→输出待完成列表」的强制六步流水线执行。任务列表和实现前提问是不可跳过的门禁，确保不会在理解偏差的情况下动手编码。与 `f2s-req-plan` 的区别：本规则是轻量单线程编码驱动，不强制创建 `.task/` 追踪（除非 `changeTracking.implement: true`）。
+
 **变更追踪**：若 `changeTracking.implement: true`，在步骤 2.5 输出任务列表后同步写入 `.task/active/<task-name>/task.md`；步骤 5 收尾时归档任务。
 
 **使用场景**：
+
 - 技术方案已就绪，需要按方案编码
 - 方案变更后需要同步更新代码
 
 **关联关系**：
+
 - **前置**：`.Knowledge/req-docs/<技术方案>.md`（通过 `f2s-req-backend` 或手动放置）
 - **规则位置**：
   - Cursor：`.cursor/rules/f2s-implement-tech-design.mdc`
@@ -529,6 +676,7 @@
   - Codex：`.codex/AGENTS.md` + `.codex/topics/f2s-implement-tech-design.md`
 
 **执行流程**（规则强制）：
+
 1. 输入标准化
 2. 理解方案与上下文
 3. **输出实现任务列表**（必做，不可跳过）
@@ -546,21 +694,25 @@
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[Flow2Spec使用说明 § 一、`f2s-*` 与 `flow2spec.config.json`](./Flow2Spec使用说明.md)。
+`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[Flow2Spec使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./Flow2Spec使用说明.md)`。
 
 ### `subAgent` 字段
 
-| 取值 | 行为 |
-|------|------|
-| `false`（默认） | 所有 `f2s-*` 技能在主 agent 内完成 |
-| `true` | 部分技能可按正文约定使用子 agent（大规模并行处理场景） |
+
+| 取值          | 行为                             |
+| ----------- | ------------------------------ |
+| `false`（默认） | 所有 `f2s-*` 技能在主 agent 内完成      |
+| `true`      | 部分技能可按正文约定使用子 agent（大规模并行处理场景） |
+
 
 ### `switchAgentVerification` 字段
 
-| 取值 | 行为 |
-|------|------|
-| `false`（默认） | 落盘侧自验：谁落盘谁验 |
-| `true` | 技能正文明确写出该步骤时，启用交叉校验：子 agent 落盘 → 主 agent 验；主 agent 落盘 → 子 agent 验（须 `subAgent: true` 且已拆出子任务） |
+
+| 取值          | 行为                                                                                            |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| `false`（默认） | 落盘侧自验：谁落盘谁验                                                                                   |
+| `true`      | 技能正文明确写出该步骤时，启用交叉校验：子 agent 落盘 → 主 agent 验；主 agent 落盘 → 子 agent 验（须 `subAgent: true` 且已拆出子任务） |
+
 
 ### `changeTracking` 字段
 
@@ -576,11 +728,13 @@
 }
 ```
 
-| 子项 | 对应技能 | 效果 |
-|------|---------|------|
-| `feat` | `f2s-kb-feat` | 执行前创建任务清单，完成后归档，支持跨会话续作 |
-| `fix` | `f2s-kb-fix` | 同上 |
-| `implement` | `f2s-implement-tech-design` | 同上 |
+
+| 子项          | 对应技能                        | 效果                      |
+| ----------- | --------------------------- | ----------------------- |
+| `feat`      | `f2s-kb-feat`               | 执行前创建任务清单，完成后归档，支持跨会话续作 |
+| `fix`       | `f2s-kb-fix`                | 同上                      |
+| `implement` | `f2s-implement-tech-design` | 同上                      |
+
 
 > `f2s-req-plan` 不受此配置约束，始终创建任务清单。旧版布尔值（`"changeTracking": true/false`）向下兼容，自动展开为三项全开/全关。
 
@@ -597,7 +751,9 @@
 ---
 
 相关文档：
+
 - [Flow2Spec使用说明](./Flow2Spec使用说明.md)
 - [README-目录与路径约定](./README-目录与路径约定.md)
 - [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+

package/docs/commands-reference.en.md

@@ -8,6 +8,8 @@
 
 **Purpose**: Generates an architecture overview draft based on user descriptions or code scanning. No fixed format required; it should clearly describe the system structure, module relationships, and key decisions.
 
+**How It Works**: Centered on inventory-driven scanning: the main agent first produces a module inventory and a scan contract (which entry points to read, which dimensions to focus on), then performs read-only code scanning according to that inventory, and finally aggregates the results into a human-readable architecture draft persisted under `stock-docs/`. The flow does not change code; it is one-way "code → document" extraction only.
+
 **Use Cases**:
 - A new project needs architecture documentation
 - An existing project needs architecture descriptions supplemented
@@ -34,6 +36,8 @@
 
 **Purpose**: Converts PDF technical proposals or draft documents into the standardized "Final Draft Template" format, unifying the document structure for subsequent knowledge base ingestion.
 
+**How It Works**: Unstructured or heterogeneous documents (PDF/drafts) are normalized against the built-in final-draft template: core concept tables, business rules, key flows, configuration, error handling, and other standard sections are extracted; missing section markers are filled in; the output is a consistently structured `_final.md`. The final draft is the standard input for `f2s-ctx-build`, keeping knowledge-base entry structure uniform.
+
 **Use Cases**:
 - PDF technical proposals need conversion to Markdown
 - Draft documents need normalization for long-term storage
@@ -60,6 +64,8 @@
 
 **Purpose**: Synchronizes documents from `stock-docs/` (architecture, final drafts) into the knowledge base routing system, generating/updating topic files, the index, manifest-routing, and matchers.
 
+**How It Works**: Starting from a final-draft document, it runs a three-step "document → routing" mapping: (1) extract capability topics and keywords from the draft; (2) generate `topics/<topic>.md` (routing summary with execution boundaries and next-step pointers) and `matchers/<id>.json` (machine-readable `includeAny` terms); (3) register task→topic rules in `manifest-routing.json` and update the human-readable `index.md`. After that, the task routing engine can hit the topic via keywords.
+
 **Use Cases**:
 - After a final draft is complete, the knowledge base needs to "know about" these documents
 - A new business domain needs routing mappings established
@@ -92,6 +98,8 @@
 
 **Purpose**: Parses already-implemented capabilities (aggregated from multiple files) into the knowledge base. Suitable when code already exists but lacks documentation, or when multiple documents need to be imported into the knowledge base in a unified manner.
 
+**How It Works**: Aggregates capability descriptions from multiple scattered sources (code, config, loose docs) and runs the full "draft → final draft → topics/index/manifest" pipeline. Unlike `f2s-ctx-build`, the input differs: `ctx-build` is driven from a single existing final draft; `doc-add` aggregates many scattered sources first, then follows the same pipeline. It closes the gap of "implementation exists but documentation does not."
+
 **Use Cases**:
 - Existing code needs knowledge base documentation
 - Multiple related documents need aggregated import
@@ -123,6 +131,8 @@
 
 **Purpose**: Deletes corresponding knowledge topics and index mappings based on `stock-docs` documents. Only removes reference relationships in the knowledge base, not the source documents themselves.
 
+**How It Works**: The inverse of `f2s-ctx-build` — given a `stock-docs` document path, locate its task→topic rules in `manifest-routing.json`, the corresponding `matchers/<id>.json` shard, `topics/<topic>.md`, and entries in `index.md`, and remove those references one by one. If a topic has no remaining task references after deletion, remove that topic file. Source documents are left in place; the user may delete them physically if desired.
+
 **Use Cases**:
 - A document is deprecated and needs removal from the knowledge routing
 - A document was imported by mistake and its routing mapping needs revocation
@@ -143,6 +153,8 @@
 
 **Purpose**: Converts PDF technical proposals to Markdown format, saves to `req-docs/`, and can supplement the process description.
 
+**How It Works**: Targets the step before "implement from a proposal" — extracts structured content from the PDF (API definitions, data models, sequence flows, etc.) into Markdown under `req-docs/`. Unlike `f2s-doc-final`, the destination and use differ: `doc-pdf` writes to `req-docs/` for consumption by the `implement-tech-design` rule to drive coding; `doc-final` writes to `stock-docs/` for ingestion via `ctx-build`.
+
 **Use Cases**:
 - A PDF technical proposal needs to be implemented
 - Historical PDF documents need to be managed
@@ -173,6 +185,8 @@
 
 **Purpose**: Asks clarifying questions against PRDs/requirement documents, using multi-round Q&A to define requirement boundaries, non-goals, and key flows, until the requirements are clear enough for a technical proposal.
 
+**How It Works**: Uses a "structured questioning" strategy — decomposes the requirement document along six dimensions (roles, scenarios, flows, boundaries, exceptions, non-goals), checks each for vague wording, undefined concepts, or contradictions, and generates targeted questions for each gap. Dialogue continues until all dimensions are unambiguous, then outputs a clarification record as input for `f2s-req-backend`. It turns unstructured PRDs into structured, actionable requirement constraints.
+
 **Use Cases**:
 - First step after receiving a PRD, ensuring correct understanding
 - When requirement boundaries are fuzzy or acceptance criteria are missing
@@ -191,6 +205,8 @@
 
 **Purpose**: Based on clarified requirements and the project knowledge base, generates a backend technical proposal document including API design, data models, flow descriptions, error codes, etc.
 
+**How It Works**: Centered on "knowledge base constraints + template-driven" authoring — first pull a constraint summary for the current project from `topics/stock-docs` (architecture conventions, API style, data model norms, etc.), then fill the backend technical proposal template (APIs / models / flows / errors / config / migrations) chapter by chapter against the clarified requirements so the proposal matches the existing architecture. Output is persisted under `req-docs/` as the coding contract for `implement-tech-design`.
+
 **Use Cases**:
 - After `f2s-req-clarify` completes, output a proposal based on clarification results
 - When clear requirement documents already exist, directly generate a technical proposal
@@ -220,6 +236,8 @@
 
 **Purpose**: Starting from a technical proposal or requirement description, **always creates a task checklist**, then implements the code accordingly. Does not depend on the `changeTracking` configuration; represents the user's explicit need for traceable task management.
 
+**How It Works**: Runs a five-phase closed loop: parse → plan → confirm → implement → archive. (1) Parse the technical proposal for implementation points; (2) split into executable tasks at module/feature granularity and write to `.task/`; (3) show the draft to the user, lock the checklist after confirmation; (4) implement item by item, checking off `task.md` immediately when each item completes; (5) archive when all are done. Unlike the `implement-tech-design` rule, `req-plan` always carries task tracking and can parallelize implementation with sub-agents for large work; the rule path is lightweight, single-threaded coding.
+
 **Use Cases**:
 - A technical proposal document exists and needs to be broken down into a task list before implementation
 - The requirement description is complex and the user wants to confirm the checklist before starting work
@@ -249,6 +267,8 @@
 
 **Purpose**: Executes a Git commit after code is written. Automatically checks changed files, compares knowledge base coverage, prompts the user about capabilities not yet imported, and performs the commit after the commit message is confirmed.
 
+**How It Works**: Layers a "knowledge base coverage gate" on top of `git commit` — infer touched capability areas from `git diff`, cross-check against `.Knowledge/topics/` and `stock-docs/`, and decide whether changed capabilities are documented in the knowledge base. If not covered, block and offer three choices (document first / skip / cancel) to avoid silent drift where "code exists but the knowledge base does not know." Commit messages use emoji + Conventional Commits for consistent, machine-friendly `git log`.
+
 **Use Cases**:
 - Committing code after each feature implementation or bug fix
 - Wanting reminders about knowledge base coverage at commit time
@@ -283,6 +303,8 @@
 
 **Purpose**: Fixes code based on implementation or rule errors reported by the user, and **by default automatically syncs** the knowledge base documents and index.
 
+**How It Works**: Three steps: locate → fix → sync. From the user's description, locate context and code via the knowledge routing path (manifest → topic → stock-docs) and confirm root cause; after fixing code, automatically check whether related descriptions in `topics/stock-docs/matchers` need updates and revise in place if so (current truth only, no stacked historical negation). "Fix code, sync docs" is the core principle to prevent knowledge drift.
+
 **Use Cases**:
 - Code implementation does not match the technical proposal
 - Rule understanding errors need correction
@@ -317,6 +339,8 @@
 
 **Purpose**: When adding a new capability, completes both the implementation and the knowledge base; if the capability is already implemented, only syncs the knowledge base.
 
+**How It Works**: Three phases: assess → implement → ingest. First assess whether the described capability is not implemented, partially implemented, or already implemented in code; if not or partial, complete the code first; then sync the knowledge base: write a capability description in `stock-docs`, generate or update `topics` summaries, register routing in `manifest-routing` and `matchers`. Unlike `f2s-kb-fix`, `kb-feat` targets **new** work; `kb-fix` targets **correcting existing** work.
+
 **Use Cases**:
 - New feature development
 - Adding knowledge base documentation for an existing feature
@@ -381,6 +405,8 @@
 
 **Purpose**: Resolves editor context conflicts after Git merges. An optional conflict file path can be provided.
 
+**How It Works**: Layered by file kind — split conflict files into "safe to auto-merge" (structured files such as index, manifest, matchers, using union or latest) vs "needs user judgment" (implementation code, business rules, and other semantic files). Auto-resolve the former; for the latter, produce a comparison table (ours/theirs summary + recommendation) and list differences for the user to decide item by item. Design idea: knowledge-base metadata can be automated; business semantics must not be decided unilaterally.
+
 **Use Cases**:
 - Context conflicts arise after a Git merge/rebase
 - Knowledge base file conflicts caused by multi-person collaboration
@@ -407,6 +433,8 @@
 
 **Purpose**: Migrates an old-format knowledge base (`docs-index.md` + `rules/` pattern) into the `.Knowledge/` structure organized by topic.
 
+**How It Works**: Uses the legacy `docs-index.md` and `rules/main.md(c)` as index clues, recursively finds all referenced business rules and skill files, and reorganizes by topic into `.Knowledge/` (`topics` / `stock-docs` / `req-docs`). After migration, persist `migration-report.md` (mapping table + proposed deletion paths), then clean up old files after user confirmation. A one-time structural merge of scattered rules/docs into one knowledge base.
+
 **Use Cases**:
 - Upgrading an old project to the new Flow2Spec version
 - An existing knowledge base needs structured reorganization
@@ -441,6 +469,8 @@
 
 **Purpose**: Knowledge base template upgrade. Aligns manifest-routing and matchers shards.
 
+**How It Works**: Uses "version branching + delegated init" — detect whether the current knowledge base is V1 (legacy structure, migrate first) or V2+ (already has `.Knowledge`): V1 runs migrate then init; V2+ runs `flow2spec init` directly for incremental package alignment (new templates, manifest schema upgrades, matcher shard format alignment). After upgrade, re-read SKILL.md to see if certain steps must be re-run. Unlike a standalone `init`, `kb-upgrade` includes version routing and re-run logic; `init` alone is a one-shot structural fill-in.
+
 **Use Cases**:
 - After a `flow2spec` package version upgrade, upgrade the project knowledge base template
 - Upgrade an old project to the latest structure
@@ -472,12 +502,24 @@
 
 The following are not skill commands but rules activated by trigger words to guide Agent behavior.
 
+### `f2s-karpathy-guidelines`
+
+**Trigger Words**: `alwaysApply` (always on; no explicit trigger needed)
+
+**Purpose**: Flow2Spec's built-in Karpathy-style coding discipline to improve the quality of agent coding decisions.
+
+**How It Works**: Four behavioral constraints distilled from Andrej Karpathy's observations on common LLM coding mistakes, applied as an `alwaysApply` rule that implicitly governs all `f2s-*` skill runs: (1) think before coding (state assumptions; ask when unsure); (2) simplicity first (minimum code to solve the problem); (3) surgical edits (touch only what must change; match existing style); (4) goal-driven execution (define verifiable success criteria, then iterate). When these guidelines conflict with mandatory `f2s-*` steps, the `f2s-*` steps win.
+
+---
+
 ### `f2s-task`
 
 **Trigger Words**: changeTracking, change tracking, task tracking, continuation, continue last task
 
 **Purpose**: Change tracking rules (`alwaysApply`). When the corresponding skill's `changeTracking.*` is set to `true`, automatically creates, progressively updates, and finally archives task checklists under `.task/` before and after skill execution, supporting cross-session continuation.
 
+**How It Works**: Cross-session persistence via "disk checkpoints + keyword matching" — each active task records progress with checkboxes (`[ ]` / `[x]`) in `.task/active/<name>/task.md`, with `todo.json` as the active-task index. At the start of a new session, the rule fuzzy-matches the user's first message to each task's `keywords`; on a match, it loads the remaining steps in `task.md` and the skill file for `linkedSkill`, restoring full execution context. Completed tasks move to `completed/`. Design: the file system, not chat memory, is the source of truth so interrupted sessions do not lose progress.
+
 **Scope**:
 
 | Config Item | Corresponding Skill |
@@ -498,6 +540,8 @@ The following are not skill commands but rules activated by trigger words to gui
 
 **Purpose**: Distinguishes the boundary between the knowledge archival directory and the requirements implementation directory.
 
+**How It Works**: "Purpose isolation" to avoid mixing folders — `stock-docs/` holds archived existing knowledge (architecture, final drafts), consumed by `ctx-build` for ingestion into the knowledge base and **must not** be used directly as coding input; `req-docs/` holds implementation-facing requirements and technical proposals, consumed by the `implement-tech-design` rule to drive coding. Writers and readers are fully separated so "stock descriptions are not mistaken for coding contracts" and "implementation proposals are not mistaken for capability archival."
+
 **Directory Division**:
 
 | Directory | Purpose | When It Is Written |
@@ -517,6 +561,8 @@ The following are not skill commands but rules activated by trigger words to gui
 
 **Purpose**: Implements runnable code based on technical proposal documents in `req-docs/`.
 
+**How It Works**: "Proposal as contract" — the agent treats the technical proposal in `req-docs/` as the sole coding contract and must follow the mandatory six-step pipeline: understand proposal → output task list → ask clarifying questions before coding → implement step by step → output remaining work and post-implementation reminders. The task list and pre-implementation Q&A are non-skippable gates so coding does not start on a misunderstood spec. Unlike `f2s-req-plan`, this rule is lightweight single-threaded coding and does not force `.task/` tracking unless `changeTracking.implement: true`.
+
 **Change Tracking**: If `changeTracking.implement: true`, after outputting the task list in Step 2.5, synchronously writes to `.task/active/<task-name>/task.md`; archives the task in Step 5 during wrap-up.
 
 **Use Cases**:
@@ -548,7 +594,7 @@ Controlled via `flow2spec.config.json` at the project root (all fields default t
 
 ### How Different Products "See" the Configuration (use with the field table below)
 
-`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude hooks / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale at [design-principles.en.md Sec. 4.5.1](./design-principles.en.md)). **The full path and table are maintained in one place**: [usage-guide.en.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.en.md).
+`subAgent` and similar fields are written to the **on-disk JSON**; products do not guarantee automatic file opening. Therefore, multi-layered hints are provided via **Cursor rules / Claude hooks / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.en.md — Agent Orchestration § 5.1](./design-principles.en.md); talk / deck pacing in [intro deck HTML](../presentations/flow2spec-intro-public-en/index.html), config section). **The full path and table are maintained in one place**: [usage-guide.en.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.en.md).
 
 ### `subAgent` Field
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.0.9",
+  "version": "3.0.11",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

package/templates/knowledge/manifest-routing.json

@@ -7,6 +7,9 @@
   "topicDependencies": {
     "implement-tech-design": [
       "stock-docs-vs-req-docs"
+    ],
+    "f2s-req-plan": [
+      "f2s-task"
     ]
   },
   "topicPaths": {

package/templates/rules/f2s-task.mdc

@@ -21,6 +21,14 @@ alwaysApply: true
 
 > `f2s-req-plan` 命令不受此条件约束，始终执行（见 `skills/f2s-req-plan/SKILL.md`）。
 
+## f2s-req-plan 调用时的绑定
+
+执行 **`f2s-req-plan`**（或续作命中 `linkedSkill: "f2s-req-plan"`）时：
+
+- **不受** `changeTracking.feat` / `fix` / `implement` 限制，但 **必须** 按本规则「任务开始 / 执行中 / 中断与会话结束 / 任务完成 / 新会话续作」维护 `.task/`；
+- 技能 **步骤 0** 须 `Read` 本规则全文（**Cursor/Claude**：`rules/f2s-task.*`；**Codex**：`.codex/topics/f2s-task.md`）；
+- 落盘、打钩、归档、`user-todos.md` 格式 **以本规则为准**；技能正文不得省略 `todo.json` 或 `user-todos.md`，不得改写归档目录命名（`<YYYYMMDD>-<task-name>`）。
+
 ## 目录结构
 
 ```

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

@@ -1,82 +1,121 @@
 ---
 name: f2s-req-plan
-description: 根据技术方案/需求描述/变更描述规划并实现任务；始终创建任务清单，支持子 agent 并行实现代码；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单
+description: 根据技术方案/需求描述/变更描述规划并实现任务；始终按 f2s-task 维护 .task/；支持子 agent 并行实现；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单
 ---
 
 # 需求任务规划与实现（f2s-req-plan）
 
-从需求/技术方案出发，完整覆盖「规划 → 实现」链路。不依赖 `changeTracking` 配置，始终创建任务清单。知识库同步由用户后续按需调用 `f2s-kb-feat` / `f2s-kb-sync` 完成。
+从需求/技术方案出发，完整覆盖「规划 → 实现」链路。**不依赖** `changeTracking.*`，但 **`.task/` 全生命周期必须以 `f2s-task` 为唯一真值源**（目录、格式、续作、打钩、归档、user-todos）。知识库同步由用户后续按需调用 `f2s-kb-feat` / `f2s-kb-sync`。
+
+## 与 f2s-task 的关系（硬约束）
+
+| 项 | 说明 |
+| --- | --- |
+| **真值源** | 配置根 **`rules/f2s-task.*`**（`alwaysApply: true`）；Codex 读 **`.codex/topics/f2s-task.md`**（init 镜像，与 rules 同源） |
+| **本技能职责** | 规划草稿、实现代码、子 agent 编排；**不得**自定 `.task/` 结构或弱化打钩/归档 |
+| **与 changeTracking** | `f2s-req-plan` **不受** `changeTracking.feat/fix/implement` 约束，**始终**走任务清单；见 `f2s-task`「生效条件」 |
+
+**三端读取 `f2s-task` 全文（步骤 0 必做，先于下文任何步骤）**：
+
+| 端 | 路径 |
+| --- | --- |
+| **Cursor** | 配置根 `rules/f2s-task.mdc`；或已 init 的 `.cursor/rules/f2s-task.mdc` |
+| **Claude Code** | `.claude/rules/f2s-task.md` |
+| **Codex** | `.codex/topics/f2s-task.md` |
 
 ## 编排（主 / 子 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` 且技能正文明确标注时才启用交叉校验。
+- `subAgent` / `switchAgentVerification` 以统一入口为唯一事实源：**Cursor/Claude** → `rules/f2s-flow2spec-unified-entry.*`；**Codex** → `.codex/topics/f2s-flow2spec-unified-entry.md`。
+- **步骤 1（续作分诊 + 解析）**：主 agent 必做 `f2s-task`「任务开始」1–2；解析文档可拆子 agent（只读）。
+- **步骤 2（草稿确认）**：必须主 agent；未确认前禁止创建 `.task/` 或写业务代码。
+- **步骤 3（落盘）**：按 `f2s-task`「任务开始」3.a–3.f；`todo.json` **仅主 agent**；`task.md` / `context.md` / `user-todos.md` 初稿可子 agent，`user-todos.md` 执行中追加由主 agent 合并。
+- **步骤 4（实现）**：子 agent 只写业务代码；**禁止**子 agent 写 `todo.json`、改 `task.md` checkbox；打钩由主 agent 在合并后当步完成。
+- **步骤 5（归档）**：主 agent；**仅**满足 `f2s-task`「任务完成」归档门禁后执行。
+- worktree 卫生见 `f2s-flow2spec-unified-entry`；中断/结束见 `f2s-task`「中断与会话结束」。
 
 ## 输入（任选其一）
 
-- 技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）
-- 需求描述 / 变更描述（自由文本）
+- 技术方案路径（`.Knowledge/req-docs/*.md` 或 PDF）
+- 需求 / 变更描述（自由文本）
 
 ## 步骤
 
-### 步骤 1：解析输入
+### 步骤 0：前置（强制，任何步骤之前）
+
+1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。
+2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。
+3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。
+
+### 步骤 1：续作分诊 + 解析输入
 
-`subAgent=true` 时，可拆子 agent 并行执行（只读，不落盘）：
+#### 1a. 续作分诊（`f2s-task`「任务开始」1–2，主 agent）
 
-- 读取技术方案 / 需求文档全文，提取目标、范围、主要工作项、涉及文件路径
-- 读取项目现有约定（`.Knowledge/stock-docs/`、架构说明）对齐实现上下文
-- 若输入为 PDF，先执行 `f2s-doc-pdf` 转为 MD，再继续
+1. 若存在 **`.task/todo.json`**，`Read` 并将**用户本条输入**与各条目 **`keywords`** 匹配。
+2. **命中 1 个** → `Read` 对应 `task.md`、`context.md`；若存在则 `Read` **`user-todos.md`**；向用户展示剩余 checklist 与未勾用户代办；询问是否**续作**该任务。
+   - 用户确认续作 → **加载本 SKILL 全文**（`linkedSkill` 应为 `f2s-req-plan`），从 `task.md` 首个 `[ ]` 继续；**禁止**新建重复 `active/` 目录；**跳至步骤 4**（若仍需补充规划，先在「## 备注」记录后再实现）。
+   - 用户明确要**新任务** → 进入 1b。
+3. **命中多个** → 列出候选，让用户选择续作哪一个或新建。
+4. **无命中** → 检查**孤儿 `active/`**（`f2s-task`）：若有未归档且含 `[ ]` 的 `task.md`，提示是否续作或恢复 `todo.json`；否则进入 1b。
+5. **无 `todo.json`** → 进入 1b。
 
-子 agent 只输出「解析结果摘要」（目标、工作项列表、涉及文件）交主 agent 汇总；`subAgent=false` 时主 agent 直接完成。
+#### 1b. 解析输入（新任务或待草稿）
+
+`subAgent=true` 时可拆子 agent 并行只读：
+
+- 读取方案/需求全文，提取目标、范围、工作项、涉及文件
+- 读取 `.Knowledge/stock-docs/` 等对齐上下文
+- PDF 先 `f2s-doc-pdf` 转 MD
+
+子 agent 只交「解析摘要」；`subAgent=false` 时主 agent 完成。→ **步骤 2**。
 
 ### 步骤 2：输出草稿并确认（必须主 agent）
 
-主 agent 基于步骤 1 汇总，输出规划草稿：
+主 agent 输出：
 
-1. **任务名称建议**（snake_case，如 `alipay_refund_feat`）
-2. **实现任务清单草稿**（每步独立可 checkbox）
-3. **涉及文件列表**
-4. **等待用户确认**
+1. **任务名称**（snake_case）
+2. **实现清单草稿**（每步可 checkbox，将写入 `task.md` 的「## 步骤」）
+3. **涉及文件列表**（将写入 `context.md`）
+4. **建议 `keywords`**（2–5 个，供 `todo.json` 续作匹配）
+5. **等待用户确认**
 
-> 未确认前禁止创建任何文件或写任何代码。
+> **未确认前**禁止：创建 `.task/`、写 `todo.json`、写业务代码。
 
-### 步骤 3：落盘任务清单
+### 步骤 3：落盘任务清单（`f2s-task`「任务开始」3.a–3.f）
 
-确认后：
+用户确认后，**严格按 `f2s-task` 执行**（格式以该规则正文为准，不得省略文件）：
 
-- **主 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`：固定文件名；尚无用户代办时写入简短占位说明即可）
+| 子步 | 动作 | 写权 |
+| --- | --- | --- |
+| 3.a | 确认 `<task-name>`（snake_case） | 主 |
+| 3.b | 创建 `.task/active/<task-name>/` | 主或子（初稿） |
+| 3.c | 写入 **`task.md`**：`# 任务名` + `## 步骤` + `- [ ]` 列表 + 空 `## 备注` | 主或子 |
+| 3.d | 写入 **`context.md`**：涉及文件、`.Knowledge` 资料链接；用户代办指向 `user-todos.md` | 主或子 |
+| 3.e | 创建 **`user-todos.md`**（固定文件名；无代办时写占位说明） | 主或子 |
+| 3.f | **`todo.json` 新增条目**：`name`、`folder`、`keywords`（含步骤 2 建议词）、`linkedSkill: "f2s-req-plan"`、`createdAt` | **仅主 agent** |
 
-### 步骤 4：实现代码
+**禁止**：只建 `task.md` 不写 `todo.json`；省略 `user-todos.md`；使用 `completed/<task-name>-<date>` 旧式归档名。
 
-`subAgent=true` 时，按任务清单将各模块拆子 agent 并行实现：
+### 步骤 4：实现代码
 
-- 子 agent 只写实现代码
-- 子 agent 完成后向主 agent 汇报改动摘要（文件路径 + 改动说明）
-- `subAgent=false` 时主 agent 按清单逐项实现
+遵守 `f2s-task`「**执行中**」「**中断与会话结束**」：
 
-实现原则：
+- 按 `task.md` 顺序实现；**每真实完成一步**，主 agent **立即** `Edit` 该步 `[ ]` → `[x]`（禁止批量勾选、禁止仅口头完成）。
+- 凡须用户改库/配环境/审批等，**同会话**追加 **`user-todos.md`**（按日期分节）；禁止只写在对话或 `task.md` 正文。
+- `subAgent=true`：子 agent 只改业务源码；回报后由主 agent 打钩与写 `user-todos.md`。
+- 合并子 agent 后清理 **git worktree**（见统一入口）。
 
-- 复用现有依赖与封装，不引入不必要抽象
-- 与项目命名 / 目录 / 风格一致
-- 未实现或部分实现的能力补齐，不重做
+### 步骤 5：归档任务（`f2s-task`「任务完成」）
 
-每完成清单中一步，立即用 `Edit` / `Write` 将 `task.md` 对应 checkbox 由 `[ ]` 改为 `[x]`，禁止批量勾选，禁止口头完成代替写盘（长记忆以磁盘 `task.md` 为准；见 `f2s-task`）。
+**归档门禁**（自检通过后才移动目录）：
 
-凡产生**须用户执行**的项（改库、配环境、审批等），**同会话内**追加写入 `user-todos.md`（见 `f2s-task`「user-todos.md」）；子 agent 若回报此类项，由主 agent 合并追加，禁止仅写在对话中。
+- `task.md`「## 步骤」中与本次交付相关项 **全部为 `[x]`**（取消项已在「## 备注」说明）。
+- 仍有 `[ ]` → **禁止**移入 `completed/`、**禁止**删 `todo.json` 条目。
 
-### 步骤 5：归档任务
+通过后：
 
-**仅当** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后：将 `.task/active/<task-name>/` 整体移至 `.task/completed/<YYYYMMDD>-<task-name>/`，从 `todo.json` 删除对应条目。若仍有 `[ ]`，禁止归档，应先补打钩或修订清单（与 `f2s-task` 归档门禁一致）。
+1. `.task/active/<task-name>/` → `.task/completed/<YYYYMMDD>-<task-name>/`（**日期 8 位在前**）
+2. 从 `todo.json` 删除该条；空数组则删文件
+3. `user-todos.md` 随目录一并归档
 
 ### 步骤 6：输出摘要
 
@@ -86,25 +125,29 @@ description: 根据技术方案/需求描述/变更描述规划并实现任务
 ### 实现
 - <文件路径>：<改动说明>
 
-### 待办（如需同步知识库）
-- 可后续调用 f2s-kb-sync 补充知识库
+### 任务清单
+- 已归档：`.task/completed/<YYYYMMDD>-<task-name>/`（或仍 active 时写明路径与剩余 `[ ]`）
+
+### 待办（知识库）
+- 可后续调用 f2s-kb-sync / f2s-kb-feat
 
-### 用户代办（须用户在本机/平台完成）
-- 详见 `.task/active/<task-name>/user-todos.md`（归档后在 `completed/.../` 同路径）
+### 用户代办
+- 见 `user-todos.md`（归档后在 completed 同路径）
 ```
 
 ## 约束
 
-- 不依赖 `changeTracking` 配置，始终创建任务清单
-- 步骤 2（草稿确认）必须主 agent，未确认前禁止落盘
-- `todo.json` 恒主 agent 单点写入
-- 禁止批量勾选 checkbox，逐步执行
-- 用户代办必须追加到 `user-todos.md`，禁止仅对话交付（见 `f2s-task`）
+- **步骤 0**：必须先 `Read` `flow2spec.config.json` + **`f2s-task` 全文**（三端路径见上表）
+- **`.task/`**：一律服从 `f2s-task`；本 SKILL 不得与之冲突
+- 不依赖 `changeTracking`，但**始终**创建并维护任务清单（除非续作已有 active 任务）
+- 步骤 2 必须主 agent；未确认禁止落盘
+- `todo.json` 仅主 agent；子 agent 禁止写入
+- 禁止批量勾选；禁止跳过 `user-todos.md`
 
 ## 完成后自检
 
-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。
+1. 是否已读 **`f2s-task` 全文** 且落盘格式与其一致。
+2. `task.md` 步骤是否均已磁盘 `[x]`（非口头）。
+3. 归档门禁满足时目录在 `completed/<YYYYMMDD>-<task-name>/`，`todo.json` 已更新。
+4. `user-todos.md` 与会话中用户代办一致（无则占位）。
+5. worktree 已清理或已交接删除命令（N/A 则注明）。