@double-codeing/flow2spec 3.0.14 → 3.0.16

package/docs/{usage-guide.en.md → en/usage-guide.md}

@@ -1,4 +1,4 @@
-[中文](./Flow2Spec使用说明.md) | [English](./usage-guide.en.md)
+[中文](../使用说明.md) | [English](./usage-guide.md)
 
 # Flow2Spec Usage Guide
 
@@ -32,7 +32,7 @@ Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual val
 | **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
 | **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
 
-For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.en.md).
+For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.md).
 
 ---
 
@@ -40,38 +40,38 @@ For field semantics and default value rules, see [Commands Reference § 6) Sub-A
 
 Core distinction: `stock-docs/` holds solidified documents (driving knowledge routing), `req-docs/` holds technical designs (driving coding implementation); they are not interchangeable.
 
-See [Directory Conventions](./directory-conventions.en.md) for the full directory description.
+See [Directory Conventions](./directory-conventions.md) for the full directory description.
 
 ---
 
 ## 3. Typical Workflows
 
-### Requirements Planning and Implementation
+### Change Tracking and Cross-Session Continuation (Recommended)
 
-```
-f2s-req-plan
-```
-
-Provide a path to the technical design document or a requirements description. A draft task checklist is produced first and awaits confirmation. After confirmation, implementation proceeds according to the checklist. A `.task/` task checklist is always created — no `changeTracking` configuration is needed. Suitable for scenarios where you want to see the full picture before starting, or need cross-session progress tracking.
+Enable `changeTracking` per skill in `flow2spec.config.json` (each sub-field is independent):
 
-### Change Tracking and Cross-Session Continuation
-
-```
-# Automatic mode: enabled by config (independent per skill)
-flow2spec.config.json → changeTracking.feat / fix / implement: true
-
-# Explicit mode: call f2s-req-plan (planning + implementation, no config dependency)
-f2s-req-plan
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": true,
+    "implement": true
+  }
+}
 ```
 
-**Automatic mode**: When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a task checklist under `.task/active/`, check off steps progressively, and archive upon completion. In subsequent sessions, when describing related content, the `f2s-task` rule automatically matches and loads the remaining checklist — no need to re-explain the context.
+When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a checklist under `.task/active/`, check off steps, and archive on completion. In later sessions, the `f2s-task` rule matches related wording and resumes the remaining steps — no need to re-explain context.
 
-**Explicit mode**: Call `f2s-req-plan` directly — regardless of the `changeTracking` configuration, a task checklist is always created and code is implemented against it. Suitable for scenarios where you want to confirm the full picture before taking action.
+If **`changeTracking` is off** but you still need a `.task/` checklist temporarily, call `f2s-req-plan` explicitly (always creates a checklist, ignores config) — a **fallback**, not the default path. See [Commands Reference § f2s-req-plan](./commands-reference.md).
 
 ### New Feature Development
 
 ```
-f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+f2s-req-clarify (one-line requirement or doc) → f2s-req-backend → implement <technical design> (strictly follows implement-tech-design rule)
+After implementation, new capability → f2s-kb-feat
+After implementation, bug fix → f2s-kb-fix
+After debugging → f2s-kb-sync
+Finally → f2s-git-commit
 ```
 
 When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
@@ -80,18 +80,10 @@ When requirements are already clear, `f2s-req-clarify` can be skipped, starting
 
 ```
 New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
-PDF document ingestion:          f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
-```
-
-Integrate architecture descriptions or PDF technical designs into the knowledge routing (generates topics/matchers/manifest-routing).
-
-### PDF-Based Implementation
-
-```
-f2s-doc-pdf → implement-tech-design
+PDF/draft ingestion:               f2s-doc-final → f2s-ctx-build
 ```
 
-Convert a PDF technical design to Markdown and place it in `req-docs/`, then let the `implement-tech-design` rule drive coding.
+Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-ctx-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."
 
 ### Backfilling Existing Capabilities
 
@@ -122,7 +114,7 @@ f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects,
 
 ## 4. Agent Execution Configuration
 
-Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
+Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
 
 **When to enable `subAgent: true`**: When the task is large (multi-module parallel implementation, batch document ingestion, large-scale migration). When enabled, each skill decides whether to actually split based on its own size threshold; tasks below the threshold are still completed within the main agent.
 
@@ -140,7 +132,7 @@ Controlled via the project root `flow2spec.config.json`. For complete field rule
 }
 ```
 
-If you prefer not to rely on configuration and want to explicitly plan tasks on demand, use `f2s-req-plan` directly.
+Use `f2s-req-plan` only when all `changeTracking` sub-fields are off and you still need a checklist (see § 3 footnote).
 
 ---
 
@@ -159,7 +151,7 @@ Skills are triggered by matching `name` and `description`. Files are located und
 
 ## 7. Related Documents
 
-- [Commands Reference](./commands-reference.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Architecture](./architecture.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Commands Reference](./commands-reference.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Architecture](./architecture.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/{usage-scenarios.en.md → en/usage-scenarios.md}

@@ -1,4 +1,4 @@
-[中文](./Flow2Spec-使用案例-模拟对话.md) | [English](./usage-scenarios.en.md)
+[中文](../使用案例-模拟对话.md) | [English](./usage-scenarios.md)
 
 # Flow2Spec Usage Scenarios (Simulated Dialogues)
 
@@ -123,33 +123,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 4: PDF Design -> Implementation
-
-**You**
-
-> /f2s-doc-pdf /Users/me/Downloads/marketing-coupon-v2.pdf
-
-**Agent**
-
-> Converted and saved as `.Knowledge/req-docs/marketing-coupon-v2.md`. Filled in the idempotency handling flow description and error code explanations that were missing in the PDF.
-
-**You**
-
-> Implement according to `.Knowledge/req-docs/marketing-coupon-v2.md`
-
-**Agent**
-
-> I have read the design document. Task list for implementation:
->
-> 1. Create `CouponController` (coupon claim, redemption, and return endpoints)
-> 2. Create `CouponService` with inventory deduction and idempotency checks
-> 3. ...
->
-> Before proceeding, I need to confirm: is the coupon inventory managed via Redis or database row locks?
-
----
-
-## Scenario 5: Post-Implementation Knowledge Base Recording
+## Scenario 4: Post-Implementation Knowledge Base Recording
 
 **You**
 
@@ -177,7 +151,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 6: Non-compliant Implementation Found, Fix and Sync Knowledge Base
+## Scenario 5: Non-compliant Implementation Found, Fix and Sync Knowledge Base
 
 **You**
 
@@ -191,7 +165,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 7: Knowledge Base Conflicts After Git Merge
+## Scenario 6: Knowledge Base Conflicts After Git Merge
 
 **You**
 
@@ -216,7 +190,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ## Related Documentation
 
-- [Usage Guide](./usage-guide.en.md)
-- [Commands Reference](./commands-reference.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Architecture](./architecture.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Commands Reference](./commands-reference.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Architecture](./architecture.md)

package/docs/{README- → }/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -1,22 +1,63 @@
 # 体系与原理
 
-Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
+[English](./en/architecture.md)
 
-- **知识层**：`.Knowledge`（文档与索引）
-- **执行层**：配置根 `rules/skills`（供各工具原生加载）
+Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并在仓库里用 **Memory Coding（记忆编码）** 把「要记住的东西」落盘为可 diff、可评审的 Git 资产。
+
+- **知识环**（`.Knowledge/`）：业务文档与机读路由（见下文多层结构）
+- **任务环**（`.task/`）：跨会话续作清单
+- **规则环**（各工具 `rules` / `AGENTS.md`）：规定 Agent **怎么读、怎么做**
+- **技能环**（`f2s-*`）：维护知识、触发流程
+
+> Flow2Spec ≠ 只有知识库；上述四环同属 Memory Coding，下文「两层结构」描述的是**知识环 vs 工具侧执行落点**的生命周期分工。
+
+---
+
+## 1. Memory Coding 与仓内四环
+
+**Memory Coding**：把必须长期记住的上下文**编码进可提交仓库**——不押在模型私有 Memory、不只在聊天里重复，也不靠全仓向量概率猜。
+
+仓内拆成 **四环**（勿说成「三环」把规则与技能合并）：
+
+| 环 | 落点 | 记什么 |
+| --- | --- | --- |
+| **知识环** | `.Knowledge/` | 路由、主题、存量/需求文档（见 §2 多层） |
+| **任务环** | `.task/` | `todo.json`、checklist、用户代办 |
+| **规则环** | `.cursor/.claude/.codex` 下 rules、`AGENTS.md` | 读取顺序、缺口闸门、实现约束 |
+| **技能环** | 配置根 `skills/*/SKILL.md` | `f2s-kb-feat/fix/sync` 等维护与触发 |
+
+与「两层结构」的关系：**知识环**对应「随项目走」的知识层；**规则环 + 技能环**落在各工具配置根，随工具升级迭代；**任务环**与 `.Knowledge/` 并列于仓内，不属于 `.Knowledge/` 目录。
+
+---
+
+## 2. 知识环内的多层记忆结构
+
+`.Knowledge/` 不是扁平「一堆 Markdown」，而是 **横读（渐进式路由）+ 纵链（主题依赖）** 的多层记忆：
+
+| 层级 | 路径 / 机制 | 记什么 | 典型读法 |
+| --- | --- | --- | --- |
+| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths` | 会话首读（机读事实源） |
+| **L1 关键词分片** | `matchers/<id>.json` | `includeAny` 触发词 | **match**：只打开命中的一个分片 |
+| **L2 主题摘要** | `topics/<topic>.md` | 硬约束摘要、边界、下一步指针 | **expand**：拉齐依赖主题 |
+| **L3 长文档** | `stock-docs/`、`req-docs/` | 架构终稿、技术方案全文 | 按需下钻背景 |
+| **纵链（横切）** | `topicDependencies` | 通用约定 → 子域 → 白名单 → 本域细则 | **expand** 时按依赖顺序叠层 |
+
+**渐进式读取**（`match → expand → verify → act`）作用在 L0–L2（必要时再到 L3）：先收窄入口，再展开依赖与缺口检查，最后才改代码。主题级依赖挂一次、所有任务共享，避免每个任务重复声明前置约束。
+
+人读导航：`index.md` 仅作语义边界校验，**不**替代 `manifest-routing` 机读链。
 
 ---
 
-## 1. 两层结构
+## 3. 知识层与执行层（两层结构）
 
 | 层 | 位置 | 作用 |
 | --- | --- | --- |
-| 知识层 | `.Knowledge/` | 保存业务文档、索引、路由 |
-| 执行层 | `.cursor/.claude/.codex` | 保存规则与技能入口 |
+| 知识层（知识环） | `.Knowledge/` | 保存业务文档、索引、路由（§2 多层） |
+| 执行层（规则环 + 技能环） | `.cursor/.claude/.codex` | 保存规则与技能入口 |
 
 ---
 
-## 2. 渐进式读取
+## 4. 渐进式读取
 
 统一建议顺序：
 
@@ -33,7 +74,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
 
 ---
 
-## 3. 关键链路
+## 5. 关键链路
 
 - 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build`
 - 实现链：`.Knowledge/req-docs/*.md` → `implement-tech-design` → 代码
@@ -44,13 +85,13 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
 
 ---
 
-## 4. Agent 执行模型
+## 6. Agent 执行模型
 
 Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentVerification` 两个字段控制执行行为。
 
-**Agent 如何读到上述真值**：多端提示 + **Read** 权威，见 [Flow2Spec使用说明 § 一（唯一详表）](./Flow2Spec使用说明.md)；设计归纳见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)。
+**Agent 如何读到上述真值**：多端提示 + **Read** 权威，见 [使用说明 § 一（唯一详表）](./使用说明.md)；设计归纳见 [设计说明 § 四、5.1](./设计说明.md)。
 
-### 4.1 主/子 Agent 职责划分原则
+### 6.1 主/子 Agent 职责划分原则
 
 **`subAgent: false`（默认）**：全部 `f2s-*` 技能在主 agent 内顺序完成，无并行拆分。
 
@@ -63,7 +104,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 子 agent 的拆分边界由各 `f2s-*` 技能正文逐步约定（如模块数、文档数、代码行数等门槛），**当前尚未在模板层给出统一阶段表**，以技能正文为准。
 
-### 4.2 验证归属原则
+### 6.2 验证归属原则
 
 **默认（谁落盘谁验）**：落盘或变更后的验证在落盘侧 agent 内完成。子 agent 落盘则子 agent 自验，主 agent 落盘则主 agent 自验。
 
@@ -81,7 +122,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 设计意图：交叉验证引入外部视角，降低落盘侧的自验盲区，但增加执行开销，因此设为显式 opt-in 而非默认行为。
 
-### 4.3 变更追踪（changeTracking）
+### 6.3 变更追踪（changeTracking）
 
 `changeTracking` 是独立于 `subAgent` / `switchAgentVerification` 的第三个维度，控制技能执行时是否自动创建可跨会话续作的任务清单。
 
@@ -102,7 +143,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 ---
 
-## 5. 设计收益
+## 7. 设计收益
 
 1. 跨工具共享同一业务知识源
 2. 不破坏 Claude/Cursor/Codex 的规则加载习惯
@@ -112,9 +153,9 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 ---
 
-## 6. 相关文档
+## 8. 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)

package/docs/{Flow2Spec- → }/344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md

@@ -1,5 +1,7 @@
 # Flow2Spec 使用案例（模拟对话）
 
+[English](./en/usage-scenarios.md)
+
 以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。
 
 **前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
@@ -121,33 +123,7 @@
 
 ---
 
-## 场景四：PDF 方案 → 实现
-
-**你**
-
-> /f2s-doc-pdf /Users/me/Downloads/营销优惠券_v2.pdf
-
-**Agent**
-
-> 已转换并保存为 `.Knowledge/req-docs/营销优惠券_v2.md`，补全了 PDF 中缺失的幂等处理流程描述和错误码说明。
-
-**你**
-
-> 按方案实现：`.Knowledge/req-docs/营销优惠券_v2.md`
-
-**Agent**
-
-> 已读取方案，输出实现任务列表：
->
-> 1. 新建 `CouponController`（领券、核销、退券接口）
-> 2. 新建 `CouponService`，含库存扣减与幂等校验
-> 3. …
->
-> 实现前确认：优惠券库存是用 Redis 还是数据库行锁？
-
----
-
-## 场景五：实现后补录知识库
+## 场景四：实现后补录知识库
 
 **你**
 
@@ -175,7 +151,7 @@
 
 ---
 
-## 场景六：发现违规实现，修复并同步知识库
+## 场景五：发现违规实现，修复并同步知识库
 
 **你**
 
@@ -189,7 +165,7 @@
 
 ---
 
-## 场景七：Git 合并后知识库冲突
+## 场景六：Git 合并后知识库冲突
 
 **你**
 
@@ -214,7 +190,7 @@
 
 ## 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [README-体系与原理](./README-体系与原理.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,162 @@
+# Flow2Spec 使用说明
+
+[English](./en/usage-guide.md)
+
+## 一、init 做了什么
+
+在业务仓库根执行：
+
+```bash
+flow2spec init [cursor|claude|codex ...]
+# 需要强制重置 .Knowledge 到模板时：
+flow2spec init [cursor|claude|codex ...] --reset-knowledge
+```
+
+
+| init 做                                      | init 不做                      |
+| ------------------------------------------- | ---------------------------- |
+| 补齐缺失的目录与模板文件                                | 撰写或更新业务文档内容                  |
+| 落盘各 agent 配置根 `rules/` `skills/`            | 更新 `includeAny` 业务词条         |
+| `manifest-routing` + `matchers/` 包级结构对齐     | 替代 `f2s-*` 技能对业务语义的书写        |
+| `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |
+
+
+> **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
+
+### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）
+
+执行任意 **`f2s-*` 技能**前，需要让 Agent 拿到 **`subAgent` / `switchAgentVerification` / `changeTracking`** 等实际值。Flow2Spec 在 **不同客户端** 用 **不同机制** 强化这一点；它们彼此**补充**，**不**互相替代，**权威始终**是项目根 **`flow2spec.config.json`**（须用 **Read** 与磁盘一致后再进技能正文）。
+
+
+| 端               | `init` 落盘与行为                                                                          | 说明                                                                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Cursor**      | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`）                                   | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。                                                                                                                                         |
+| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。                                                                |
+| **Codex**       | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表                        | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
+| **知识库（可选）**     | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时                              | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。                                                                      |
+
+
+字段语义与默认值规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。设计视角见 [设计说明 § 四、5.1](./设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
+
+---
+
+## 二、目录约定
+
+核心区分：`stock-docs/` 放沉淀文档（驱动知识路由），`req-docs/` 放技术方案（驱动编码实现），两者不互换。
+
+完整目录说明见 [目录与路径约定](./目录与路径约定.md)。
+
+---
+
+## 三、典型工作场景
+
+### 变更追踪与跨会话续作（推荐）
+
+在 `flow2spec.config.json` 按技能开启 `changeTracking`（各子项独立）：
+
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": true,
+    "implement": true
+  }
+}
+```
+
+开启后，`f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` 执行时会在 `.task/active/` 自动创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容时，`f2s-task` 规则会匹配并加载剩余步骤，无需重复交代上下文。
+
+若你**关闭了** `changeTracking` 但仍临时需要 `.task/` 清单，可显式调用 `f2s-req-plan`（不读配置、始终建清单）——这是兜底用法，非常规主路径；详见 [命令说明 § f2s-req-plan](./命令说明.md)。
+
+### 新需求开发
+
+```
+f2s-req-clarify 一句话需求或文档 → f2s-req-backend → 实现xx技术方案 （会严格按照implement-tech-design规则走）
+实现完成后需新增能力→ f2s-kb-feat
+实现完成后需修bug→ f2s-kb-fix
+调试完成后-> f2s-kb-sync
+最后->f2s-git-commit
+```
+
+需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-backend` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
+
+### 文档沉淀
+
+```
+新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
+PDF/初稿沉淀：     f2s-doc-final → f2s-ctx-build
+```
+
+把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-ctx-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。
+
+### 存量能力补录
+
+```
+f2s-doc-add      # 多文件聚合，从源码/文档提取
+f2s-kb-sync      # 从当前会话推断已实现能力
+```
+
+代码已落地但知识库没有记录时使用。`f2s-doc-add` 适合批量导入，`f2s-kb-sync` 适合会话结束时的即时沉淀。
+
+### 日常维护
+
+```
+f2s-kb-fix       # 修复实现或规则错误，自动同步知识库
+f2s-kb-feat      # 新增能力，自动同步知识库
+f2s-kb-sync      # 定期同步或补录
+f2s-kb-merge     # Git 合并后解决上下文冲突
+```
+
+### 知识库跨版本升级
+
+```
+f2s-kb-migrate（流程 V1：旧库）→ f2s-kb-upgrade
+f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，见技能步骤 0）
+```
+
+---
+
+## 四、Agent 执行配置
+
+通过项目根 `flow2spec.config.json` 控制，字段完整规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。**各端如何被提示读到配置、为何仍以 Read 为权威**见 **§ 一**（本 § 仅说明**何时**打开各开关）。
+
+**何时开启 `subAgent: true`**：任务规模较大时（多模块并行实现、批量文档入库、大规模迁移）。开启后各技能按自身规模门槛决定是否实际拆分，未达门槛的仍在主 agent 内完成。
+
+**何时开启 `switchAgentVerification: true`**：需要更高落盘一致性时（大规模迁移、重要方案实现）。代价是增加执行轮次；常规维护场景默认 `false` 足够。须搭配 `subAgent: true` 才能触发"主落子验"方向的交叉。
+
+**何时开启 `changeTracking.*`**：希望每次技能执行自动留下可续作的任务清单时。各技能子项独立配置，互不影响：
+
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": false,
+    "implement": true
+  }
+}
+```
+
+`changeTracking` 全关且仍要任务清单时，再考虑 `f2s-req-plan`（见 § 三「变更追踪」脚注）。
+
+---
+
+## 五、规则改造建议
+
+- 项目特化「按技术方案实现」逻辑时，优先调整 **`f2s-implement-tech-design`**：Cursor `.cursor/rules/f2s-implement-tech-design.mdc`，Claude `.claude/rules/f2s-implement-tech-design.md`；Codex 以 `.codex/AGENTS.md` 与相关 `skills/` 为准
+- 再次 `init` 默认仅补齐缺失模板并做包级结构对齐，**不**替代 `f2s-*` 对业务内容的维护；需用模板重置 `.Knowledge` 时加 `--reset-knowledge`
+
+---
+
+## 六、技能标识
+
+技能以 `name` 与 `description` 匹配触发，文件位于 `配置根/skills/*/SKILL.md`。
+
+---
+
+## 七、相关文档
+
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)
+

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

@@ -1,5 +1,7 @@
 # 工作流与技能说明
 
+[English](./en/commands-reference.md)
+
 ## 1) 文档沉淀（stock-docs 链路）
 
 ### `f2s-doc-arch`
@@ -17,7 +19,7 @@
 **关联关系**：
 
 - **前置**：无
-- **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`
+- **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-ctx-build`（**须终稿入参**；初稿不可直驱 build）
 - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
 
 **子 agent 调用**：
@@ -179,21 +181,19 @@
 
 **作用**：将 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 中的接口定义、数据模型、时序流程等提取为 Markdown 并落盘 `req-docs/`，便于后续编辑或与 `f2s-req-clarify` / `f2s-req-backend` 衔接。与 `f2s-doc-final` 的区别：`doc-pdf` 输出到 `req-docs/`（实现侧文档目录），`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。**不推荐**把「PDF 转 MD」当作跳过澄清与后端技术方案的直驱编码路径。
 
 **使用场景**：
 
-- 收到 PDF 格式技术方案需要实现
-- 历史 PDF 文档需要纳入管理
-- 跨团队交付物为 PDF 时需要转换
+- 跨团队交付物为 PDF，需转为可编辑的 Markdown
+- 历史 PDF 技术方案需纳入 `req-docs/` 管理
+- 为后续 `f2s-req-clarify` / `f2s-req-backend` 提供可读底稿
 
 **关联关系**：
 
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
-- **下一步**：
-  - 1. 如果是需求实现：提供转换后的方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码
-  - 1. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
+- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-ctx-build`
 
 **子 agent 调用**：
 
@@ -694,7 +694,7 @@
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`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`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
 
 ### `subAgent` 字段
 
@@ -738,22 +738,22 @@
 
 > `f2s-req-plan` 不受此配置约束，始终创建任务清单。旧版布尔值（`"changeTracking": true/false`）向下兼容，自动展开为三项全开/全关。
 
-完整原则与设计意图见 [README-体系与原理 § 4. Agent 执行模型](./README-体系与原理.md)。
+完整原则与设计意图见 [体系与原理 § 4. Agent 执行模型](./体系与原理.md)。
 
 ---
 
 ## 7) 快速参考
 
-典型工作场景与完整链路见 [Flow2Spec使用说明 § 三、典型工作场景](./Flow2Spec使用说明.md)。
+典型工作场景与完整链路见 [使用说明 § 三、典型工作场景](./使用说明.md)。
 
-目录完整说明见 [README-目录与路径约定](./README-目录与路径约定.md)。
+目录完整说明见 [目录与路径约定](./目录与路径约定.md)。
 
 ---
 
 相关文档：
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)