@double-codeing/flow2spec 3.0.19 → 3.1.1

package/README.en.md

@@ -50,10 +50,10 @@ AI: Starting implementation, 3 files affected.
 
 ---
 
-## What Flow2Spec Does (3 Things)
+## What Flow2Spec Does
 
-**① Remembers project context across devices and sessions**  
-`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant.
+**① Remembers project context across sessions**  
+`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.
 
 **② Routing manifest means AI doesn't dig through your repo**  
 Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock keys, error codes, batch limits — are all in the topics. AI doesn't have to guess from source code.
@@ -61,6 +61,15 @@ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock key
 **③ f2s-* skills update knowledge as you code**  
 `/f2s-kb-feat` writes topics while writing features, `/f2s-kb-fix` corrects topics while fixing bugs, `/f2s-git-commit` checks topic coverage before committing. Changing code == updating knowledge. No separate "documentation maintenance."
 
+**④ Full pipeline from requirements to code**  
+`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-backend` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
+
+**⑤ Task checklists track progress across sessions**  
+When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
+
+**⑥ Document-driven: PDF / MD straight into the knowledge base**  
+`/f2s-kb-add` aggregates source files into draft → final → topics. `/f2s-doc-final` converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.
+
 ---
 
 ## Getting Started
@@ -103,7 +112,7 @@ In your Agent tool (Cursor / Claude Code):
 
 > This step is done once. You won't need to repeat it for daily development.
 
-2. `/f2s-doc-add <folder path>` — Import any feature modules that haven't been added yet
+2. `/f2s-kb-add <folder path>` — Import any feature modules that haven't been added yet
 
 > Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.
 
@@ -116,7 +125,7 @@ In your Agent tool (Cursor / Claude Code):
 ```
 /f2s-req-clarify  one-line description or paste PRD    ← clarify requirements
 /f2s-req-backend                                       ← generate technical proposal
-natural language: implement the proposal above         ← AI starts coding
+natural language: implement the proposal above         ← AI starts coding (task checklist auto-created when changeTracking is on)
 (debug and verify)
 /f2s-kb-feat  add xxx capability                       ← if something's missing
 /f2s-kb-fix   fix xxx                                  ← if there's a bug
@@ -143,7 +152,7 @@ natural language: implement the proposal above         ← AI starts coding
 | `/f2s-kb-fix` | Fix a bug |
 | `/f2s-kb-sync` | Sync knowledge base |
 | `/f2s-git-commit` | Commit code |
-| `/f2s-doc-add <path>` | Import API module into knowledge base |
+| `/f2s-kb-add <path>` | Import API module into knowledge base |
 
 For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
 

package/README.md

@@ -66,7 +66,7 @@ AI: 开始改，预计 3 处文件。
 开启 `changeTracking` 配置后，`f2s-kb-feat` / `f2s-kb-fix` 等技能执行时自动创建带 checkbox 的 `task.md`，每步完成立即打钩落盘。新会话续作时自动加载剩余清单，不靠记忆、不靠口头，任务进度永远在磁盘上。用户侧的代办（执行 SQL、配环境变量、点审批）单独写入 `user-todos.md`，不混在 AI 步骤里。
 
 **⑥ 文档驱动：PDF / MD 一键入知识库**  
-`/f2s-doc-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。
+`/f2s-kb-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。
 
 ---
 
@@ -110,7 +110,7 @@ npx @double-codeing/flow2spec@latest init
 
 > 这一步只做一次，之后日常开发不需要重复。
 
-2. `/f2s-doc-add <文件夹路径>` — 把还没入库的功能模块路径补进来
+2. `/f2s-kb-add <文件夹路径>` — 把还没入库的功能模块路径补进来
 
 > 这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做
 
@@ -149,8 +149,8 @@ npx @double-codeing/flow2spec@latest init
 | `/f2s-kb-feat` | 新增小功能 |
 | `/f2s-kb-fix` | 改 BUG |
 | `/f2s-kb-sync` | 同步知识库 |
-| `/f2s-git-commit` | 提交代码 |
-| `/f2s-doc-add <路径>` | 接口模块入知识库 |
+| `/f2s-git-commit` | 提交代码；“快捷提交”跳过知识库覆盖检查 |
+| `/f2s-kb-add <路径>` | 接口模块入知识库 |
 
 更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)
 
@@ -184,4 +184,4 @@ npx @double-codeing/flow2spec@latest init
 
 ## 协议
 
-MIT. Copyright © 2026 兰涛
+MIT. Copyright © 2026 兰涛

package/cli.js

@@ -2,6 +2,7 @@
 
 const path = require("path");
 const fs = require("fs");
+const os = require("os");
 const readline = require("readline");
 const runInit = require("./lib/init");
 const { AGENTS } = require("./lib/agents");
@@ -12,7 +13,7 @@ const {
   getMissingConfigFields,
 } = require("./lib/flow2specConfig");
 
-const { execSync } = require("child_process");
+const { execFileSync } = require("child_process");
 
 const args = process.argv.slice(2);
 const sub = args[0];
@@ -23,6 +24,107 @@ const agentList = Object.entries(AGENTS)
 
 const pkg = require("./package.json");
 
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+function parseVersion(version) {
+  return String(version || "")
+    .replace(/^v/, "")
+    .split(/[.-]/)
+    .slice(0, 3)
+    .map((part) => {
+      const n = Number.parseInt(part, 10);
+      return Number.isFinite(n) ? n : 0;
+    });
+}
+
+function compareVersions(a, b) {
+  const av = parseVersion(a);
+  const bv = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (av[i] || 0) - (bv[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function updateCheckCacheFile() {
+  const safeName = String(pkg.name || "flow2spec").replace(/[^a-z0-9_.-]+/gi, "_");
+  return path.join(os.homedir(), ".flow2spec", `${safeName}-update-check.json`);
+}
+
+function readUpdateCheckCache() {
+  const file = updateCheckCacheFile();
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!data || typeof data !== "object") return null;
+    if (Date.now() - Number(data.checkedAt || 0) > UPDATE_CHECK_TTL_MS) {
+      return null;
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCheckCache(latest) {
+  try {
+    const file = updateCheckCacheFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      file,
+      `${JSON.stringify({ latest, checkedAt: Date.now() }, null, 2)}\n`,
+      "utf8",
+    );
+  } catch {
+    // 更新检查不能影响主命令。
+  }
+}
+
+function queryLatestPackageVersion() {
+  const cached = readUpdateCheckCache();
+  if (cached?.latest) return cached.latest;
+  const latest = execFileSync("npm", ["view", pkg.name, "version"], {
+    encoding: "utf8",
+    timeout: 2000,
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+  if (latest) writeUpdateCheckCache(latest);
+  return latest;
+}
+
+function shouldCheckForUpdates() {
+  if (process.env.FLOW2SPEC_SKIP_UPDATE_CHECK === "1") return false;
+  if (process.env.CI) return false;
+  if (!process.stdout.isTTY) return false;
+  return Boolean(pkg.name && pkg.version);
+}
+
+function printKnowledgeUpgradeHint(latest) {
+  console.log(`
+⚠ Flow2Spec 有新版本 v${latest}（当前 v${pkg.version}）
+建议先更新包：
+  flow2spec update
+
+更新后请在 Agent 对话中执行：
+  f2s-kb-upgrade
+
+用于对齐项目知识库模板、manifest/matchers 与配置根产物；不要把单独 flow2spec init 当作知识库升级。
+`);
+}
+
+function maybePrintUpdateNotice() {
+  if (!shouldCheckForUpdates()) return;
+  try {
+    const latest = queryLatestPackageVersion();
+    if (latest && compareVersions(latest, pkg.version) > 0) {
+      printKnowledgeUpgradeHint(latest);
+    }
+  } catch {
+    // 静默跳过，不能因为网络或 npm registry 影响主命令。
+  }
+}
+
 const help = `
 Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
 
@@ -30,7 +132,7 @@ Flow2Spec - 统一知识库工作流（AI 配置入口）  v${pkg.version}
   flow2spec init [agent ...] [--reset-knowledge] [--yes]    在当前项目初始化：写入 .Knowledge 与所选 agent 入口
   flow2spec config              打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
   flow2spec version             显示当前 flow2spec 版本
-  flow2spec update              更新 flow2spec 到最新版本
+  flow2spec update              更新 flow2spec 到最新版本；更新后提示执行 f2s-kb-upgrade
   flow2spec --help              显示本说明
 
 agent（可多个，空格分隔；省略时交互选择）：
@@ -47,13 +149,14 @@ init 会:
   1. 交互询问要初始化的 AI 工具（cursor / claude / codex，可多选）；已通过参数指定则跳过。
      传 --yes 或非 TTY 环境时跳过问答，使用默认值。
   2. 对 ${CONFIG_FILENAME} 中缺失的配置字段逐项提问（已有字段不覆盖）。
-     传 --yes 时所有缺失字段使用默认值（均为 false）。
+     传 --yes 时所有缺失字段使用各自默认值。
   3. 默认仅补齐 .Knowledge 缺失模板，并对路由清单做包级/结构增量对齐（manifest-routing + matcherPath 分片；关键词仅写在 matchers/*.json）；不替代 f2s-* 对业务文档与路由内容的写入。
      传 --reset-knowledge 时才会强制用模板覆盖 .Knowledge 中模板承载部分。
   4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 在仓库根写入完整 AGENTS.md，.codex/ 写入指针）。
-     Claude 额外写入 .claude/hooks/f2s-config-inject.js 与 .claude/settings.json（PreToolUse hook），
-     在调用 f2s-* Skill 时注入配置摘要；配置缺失、JSON 无效或 hook 异常时也会注入默认语义说明，避免静默。
-     Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件。
+     Claude 额外写入 .claude/hooks/f2s-config-session.js、f2s-config-inject.js 与 .claude/settings.json：
+     SessionStart 注入一次配置摘要；PreToolUse 仅在调用 f2s-* Skill 时提示首步必须 Read 配置。
+     Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件；
+     并写入 .cursor/hooks.json，在 sessionStart 自动检测知识库版本。
      Codex：仓库根 AGENTS.md（CLI 自动发现，完整条令）；.codex/AGENTS.md 为指针。
   5. 每次 init 将包内 templates/knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。）
   6. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。
@@ -68,6 +171,7 @@ if (sub === "--help" || sub === "-h" || !sub) {
 
 if (sub === "version" || sub === "--version" || sub === "-v") {
   console.log(`flow2spec v${pkg.version}`);
+  maybePrintUpdateNotice();
   process.exit(0);
 }
 
@@ -75,19 +179,25 @@ if (sub === "update") {
   console.log(`当前版本: v${pkg.version}`);
   console.log("正在检查最新版本...");
   try {
-    const latest = execSync(`npm view ${pkg.name} version`, {
+    const latest = execFileSync("npm", ["view", pkg.name, "version"], {
       encoding: "utf8",
     }).trim();
-    if (latest === pkg.version) {
-      console.log(`已是最新版本 v${latest}`);
+    if (compareVersions(latest, pkg.version) <= 0) {
+      console.log(`当前版本不低于 npm 最新版本 v${latest}`);
       process.exit(0);
     }
     console.log(`发现新版本: v${latest}`);
     console.log("正在更新...");
-    execSync(`npm install -g ${pkg.name}@latest`, {
+    execFileSync("npm", ["install", "-g", `${pkg.name}@latest`], {
       stdio: "inherit",
     });
     console.log(`\n✓ 已更新到 v${latest}`);
+    console.log(`
+下一步：请在需要升级的项目 Agent 对话中执行：
+  f2s-kb-upgrade
+
+用于对齐项目知识库模板、manifest/matchers 与配置根产物；不要把单独 flow2spec init 当作知识库升级。
+`);
   } catch (e) {
     console.error("更新失败:", e.message || e);
     process.exit(1);
@@ -296,7 +406,7 @@ if (sub === "init") {
           return `  - ${root}/：（${label}）skills/、topics/、AGENTS.md（指针）；仓库根 AGENTS.md（完整）`;
         if (id === "claude") {
           const hookLine = claudeHooksResult?.settingsChanged
-            ? "rules/、skills/、hooks/f2s-config-inject.js、settings.json（已写入 f2s PreToolUse hook）"
+            ? "rules/、skills/、hooks/f2s-config-session.js、hooks/f2s-config-inject.js、settings.json（已写入 f2s SessionStart/PreToolUse hooks）"
             : "rules/、skills/（settings.json 中 f2s hook 已存在，跳过）";
           return `  - ${root}/：（${label}）${hookLine}`;
         }
@@ -326,6 +436,7 @@ ${lines.join("\n")}
 
 建议阅读 README 或 docs/使用说明.md，按「规则在配置根、文档在 .Knowledge」的方式使用。
 `);
+      maybePrintUpdateNotice();
     })
     .catch((e) => {
       console.error(e.message || e);

package/docs/.mermaid-cache.json

@@ -21,7 +21,7 @@
       "marker": "MERMAID_a24148e2b009"
     },
     {
-      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-ctx-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-doc-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
+      "content": "graph LR\n    K[\".Knowledge/\"] --> AI[\"下次会话\\n的 AI\"]\n    AI --> C[\"功能迭代\"]\n\n    C -->|\"修复 Bug\"| FIX[\"f2s-kb-fix\"] --> K\n    C -->|\"新增能力\"| FEAT[\"f2s-kb-feat\"] --> K\n    C -->|\"会话结束\"| SYNC[\"f2s-kb-sync\"] --> K\n    C -->|\"提交代码\"| CMT[\"f2s-git-commit\\n收口检查\"]\n    CMT -->|\"未入库则提醒\\n-> kb-sync/kb-feat\"| K\n\n    D1[\"架构文档\"] -->|f2s-doc-arch| FIN[\"f2s-doc-final\"]\n    D2[\"PDF/初稿\"] -->|f2s-doc-final| FIN\n    FIN --> CTX[\"f2s-kb-build\"] --> K\n\n    OLD[\"存量代码/文档\"] -->|f2s-kb-add| K\n\n    NR[\"新需求\"] --> CL[\"f2s-req-clarify\"] --> BE[\"f2s-req-backend\"]\n    BE --> IMPL[\"实现xxx技术方案\"] -->|自动触发implement-tech-design规则| K\n\n    GIT[\"Git 合并后\"] -->|f2s-kb-merge| K",
       "hash": "6335fa6eda40",
       "marker": "MERMAID_6335fa6eda40"
     },

package/docs/en/architecture.md

@@ -34,7 +34,7 @@ Four rings in the repo (do not collapse rules + skills into a single "third ring
 
 | Layer | Path / mechanism | Stores | Typical read |
 | --- | --- | --- | --- |
-| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths` | First read (machine source of truth) |
+| **L0 routing** | `manifest-routing.json` | task→topic, `topicDependencies`, `topicPaths`, `topicMetadata` | First read (machine source of truth) |
 | **L1 matcher shard** | `matchers/<id>.json` | `includeAny` triggers | **match**: one shard only |
 | **L2 topic summary** | `topics/<topic>.md` | Hard constraints, boundaries, pointers | **expand**: pull dependency topics |
 | **L3 long docs** | `stock-docs/`, `req-docs/` | Architecture finals, tech specs | Drill down on demand |
@@ -74,7 +74,7 @@ Codex does not read the `rules/` directory; execution constraints are carried th
 
 ## 5. Key Chains
 
-- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-ctx-build`
+- Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-kb-build`
 - Implementation chain: `.Knowledge/req-docs/*.md` -> `implement-tech-design` -> code
 - Maintenance chain: `f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`
 - Requirements planning chain: `f2s-req-plan` (planning + implementation, always creates task checklist)
@@ -136,9 +136,9 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```
@@ -165,4 +165,4 @@ Design intent: Cross-verification introduces an external perspective, reducing t
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Directory Conventions](./directory-conventions.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/commands-reference.md

@@ -8,14 +8,14 @@
 |---|---|---|
 | `/f2s-doc-arch` | Scan project, generate architecture draft | Doc Curation |
 | `/f2s-doc-final` | Convert PDF / draft to standardized final-draft format | Doc Curation |
-| `/f2s-ctx-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
-| `/f2s-doc-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
-| `/f2s-ctx-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
+| `/f2s-kb-build` | Sync final drafts into knowledge base routing (topics / matchers / manifest) | Doc Curation |
+| `/f2s-kb-add <path>` | Aggregate multi-file implemented capabilities into knowledge base | Doc Curation |
+| `/f2s-kb-rm` | Remove knowledge topic and index mapping for a stock-docs document | Doc Curation |
 | `/f2s-doc-pdf` | Convert PDF technical proposal to Markdown, save to req-docs | Doc Curation |
 | `/f2s-req-clarify` | Clarify requirements via multi-round Q&A | Requirements |
 | `/f2s-req-backend` | Generate backend technical proposal from clarified requirements | Requirements |
 | `/f2s-req-plan` | Break a technical proposal into a task checklist and implement (always creates tasks, regardless of `changeTracking.*` config) | Requirements |
-| `/f2s-git-commit` | Commit code with automatic knowledge base coverage check | Commit |
+| `/f2s-git-commit` | Commit code; checks knowledge base coverage by default, skips that check in "quick commit" mode | Commit |
 | `/f2s-kb-feat` | Add new capability + sync knowledge base | KB Maintenance |
 | `/f2s-kb-fix` | Fix a bug + auto-sync knowledge base | KB Maintenance |
 | `/f2s-kb-sync` | Sink implemented capabilities from the conversation into the knowledge base | KB Maintenance |
@@ -40,7 +40,7 @@
 
 **Relationships**:
 - **Prerequisite**: None
-- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-ctx-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
+- **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-kb-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
 - **Output**: `.Knowledge/stock-docs/<Architecture Overview>_draft.md`
 
 **Sub-Agent Invocation**:
@@ -59,7 +59,7 @@
 
 **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.
+**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-kb-build`, keeping knowledge-base entry structure uniform.
 
 **Use Cases**:
 - PDF technical proposals need conversion to Markdown
@@ -68,7 +68,7 @@
 
 **Relationships**:
 - **Prerequisite**: PDF document or draft document
-- **Next Step**: `f2s-ctx-build` (final draft imported into the knowledge base)
+- **Next Step**: `f2s-kb-build` (final draft imported into the knowledge base)
 - **Output**: `.Knowledge/stock-docs/<Document>_final.md`
 
 **Sub-Agent Invocation**:
@@ -83,7 +83,7 @@
 
 ---
 
-### `f2s-ctx-build`
+### `f2s-kb-build`
 
 **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.
 
@@ -117,11 +117,11 @@
 
 ---
 
-### `f2s-doc-add`
+### `f2s-kb-add`
 
 **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."
+**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-kb-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
@@ -150,11 +150,11 @@
 
 ---
 
-### `f2s-ctx-rm`
+### `f2s-kb-rm`
 
 **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.
+**How It Works**: The inverse of `f2s-kb-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
@@ -186,7 +186,7 @@
 **Relationships**:
 - **Prerequisite**: PDF document
 - **Output**: `.Knowledge/req-docs/<Proposal>.md`
-- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-ctx-build`
+- **Next Step** (recommended): `f2s-req-clarify` → `f2s-req-backend` → implement from the technical proposal MD via `implement-tech-design`; for knowledge base archival use `f2s-doc-final` → `f2s-kb-build`
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes the full workflow
@@ -288,13 +288,14 @@
 
 ### `f2s-git-commit`
 
-**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.
+**Purpose**: Executes a Git commit after code is written. By default it checks changed files and knowledge base coverage, prompting the user about capabilities not yet imported. If the user explicitly asks for a "quick commit", it skips the knowledge base coverage check. Before committing, it displays the commit message subject and then runs `git commit`.
 
-**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`.
+**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." Quick commit mode only skips this coverage gate; it does not skip conflict checks, message display, precise `git add`, or git hooks. 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
+- Explicitly wanting to skip this commit's coverage check with a quick commit
 - Needing AI help to generate meaningful commit messages
 
 **Relationships**:
@@ -304,7 +305,7 @@
 
 **Execution Flow**:
 1. `git status --short` + `git diff HEAD` to classify files into staged / unstaged / untracked; immediately terminates if merge conflict markers are found
-2. Compare `.Knowledge/topics/` and `stock-docs/` to determine whether the changed capabilities have been imported; skips and notifies if `.Knowledge` does not exist
+2. By default, compare `.Knowledge/topics/` and `stock-docs/` to determine whether the changed capabilities have been imported; skips and notifies if `.Knowledge` does not exist; skips this step when the user asks for a quick commit
 3. If not covered, prompt the user to choose: A) Import first, then commit / B) Commit now, import later / C) Cancel
 4. Generate a commit message draft based on `git diff` content, wait for user confirmation or changes
 5. `git add <specific files>` + `git commit`; if a hook fails, prompt for fix, do not skip
@@ -314,7 +315,7 @@
 - `git add -A` / `git add .` is forbidden; only add confirmed changed files
 - `--no-verify` is forbidden; hook failures must be fixed and retried
 - Auto-push is forbidden
-- The commit message must be confirmed by the user; silent commits are not allowed
+- The commit message subject must be displayed before committing; an extra user confirmation round is not required
 
 **Sub-Agent Invocation**: None (full interactive confirmation, handled within the main agent)
 
@@ -405,7 +406,7 @@
 - **Prerequisite**: None (can be triggered directly, or with zero-input inference)
 - **Next Step**: None
 - **Feature**: First outputs a knowledge base update outline, then writes only after user confirmation
-- **Difference from `f2s-ctx-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code
+- **Difference from `f2s-kb-build`**: `ctx-build` is driven from `stock-docs`; `kb-sync` infers from the conversation/code
 
 **Sub-Agent Invocation**:
 - `subAgent: false` (default): The main agent completes inference and sync
@@ -497,6 +498,9 @@
 **Use Cases**:
 - After a `flow2spec` package version upgrade, upgrade the project knowledge base template
 - Upgrade an old project to the latest structure
+- When interactive `flow2spec version` / `flow2spec init` detects a newer npm version, the CLI prompts you to run `flow2spec update`, then execute this skill in the Agent conversation
+- When Cursor detects an older knowledge-base version through `.cursor/hooks.json` on `sessionStart`, it prompts you to execute this skill
+- When Codex detects an older knowledge-base version through `.codex/hooks.json` on `SessionStart`, it prompts you to execute this skill (new or changed hooks must be trusted through `/hooks` first)
 
 **Relationships**:
 - **Prerequisite**: `f2s-kb-migrate` (V1 flow) or an existing `.Knowledge/`
@@ -525,14 +529,8 @@
 
 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`
@@ -557,25 +555,8 @@ The following are not skill commands but rules activated by trigger words to gui
 
 ---
 
-### `stock-docs-vs-req-docs`
-
-**Trigger Words**: stock-docs, req-docs, implemented capability, where to put the technical proposal, PDF final draft
-
-**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 |
-|-----------|---------|-------------------|
-| `stock-docs/` | Archival of existing knowledge (architecture, final drafts) | `f2s-doc-arch`, `f2s-doc-final`, `f2s-ctx-build` |
-| `req-docs/` | Requirements and technical proposals (driving implementation) | `f2s-req-backend`, `f2s-doc-pdf`, manual placement |
-
-**Use Cases**:
-- Unsure where a document should go
-- Need to clarify the division of labor between stock-docs and req-docs
 
+---
 ---
 
 ### `implement-tech-design`
@@ -613,11 +594,11 @@ The following are not skill commands but rules activated by trigger words to gui
 
 ## 6) Sub-Agent Configuration
 
-Controlled via `flow2spec.config.json` at the project root (all fields default to `false`).
+Controlled via `flow2spec.config.json` at the project root. Defaults: `subAgent=false`, `switchAgentVerification=false`, `changeTracking.feat=true`, `changeTracking.fix=false`, `changeTracking.implement=true`.
 
 ### 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 in [design-principles.md — Agent Orchestration § 5.1](./design-principles.md); talk / deck pacing in [intro deck HTML](../../presentations/flow2spec-intro-public-en/index.html) (internal); Chinese source in `flow2spec-intro-draft`, config section). **The full path and table are maintained in one place**: [usage-guide.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.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 SessionStart summary + PreToolUse guard / Codex AGENTS snapshot table / knowledge base `config-precheck` summary**, but **the authoritative source remains `Read("flow2spec.config.json")`** (design rationale in [design-principles.md — Agent Orchestration § 5.1](./design-principles.md); talk / deck pacing in [intro deck HTML](../../presentations/flow2spec-intro-public-en/index.html) (internal); Chinese source in `flow2spec-intro-draft`, config section). **The full path and table are maintained in one place**: [usage-guide.md Sec. 1, `f2s-*` and `flow2spec.config.json`](./usage-guide.md).
 
 ### `subAgent` Field
 
@@ -640,9 +621,9 @@ A nested object, with each skill independently controlled:
 ```json
 {
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
   }
 }
 ```
@@ -671,4 +652,4 @@ Related Documents:
 - [Usage Guide](./usage-guide.md)
 - [Directory Conventions](./directory-conventions.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/en/design-principles.md

@@ -100,9 +100,9 @@ graph LR
 
     D1["Architecture Docs"] -->|f2s-doc-arch| FIN["f2s-doc-final"]
     D2["PDF/draft"] -->|f2s-doc-final| FIN
-    FIN --> CTX["f2s-ctx-build"] --> K
+    FIN --> CTX["f2s-kb-build"] --> K
 
-    OLD["Existing Code/Docs"] -->|f2s-doc-add| K
+    OLD["Existing Code/Docs"] -->|f2s-kb-add| K
 
     NR["New Requirement"] --> CL["f2s-req-clarify"] --> BE["f2s-req-backend"]
     BE --> IMPL["Implement xxx technical design"] -->|auto-trigger implement-tech-design rule| K
@@ -259,7 +259,7 @@ git log .Knowledge/
 
   a3f1c2  f2s-kb-feat: add refund state machine routing
   b7e9d1  f2s-kb-fix: fix RestTemplate injection conventions
-  c2a8f0  f2s-ctx-build: onboard order service architecture docs
+  c2a8f0  f2s-kb-build: onboard order service architecture docs
   d5b3e9  f2s-kb-sync: consolidate payment retry queue design
 
   Code changes  +  Knowledge changes  →  same commit or adjacent commits
@@ -477,8 +477,10 @@ Session context itself is an information source  ·  no need for users to organi
 
 | Mechanism | Design Intent |
 | --- | --- |
-| **Cursor `f2s-config-check.mdc`** | Rule-layer enforcement: "Read before skill body." |
-| **Claude `f2s-config-inject` PreToolUse** | Injects parsed results when calling **`f2s-*` Skill**; **missing file / broken JSON / hook exception** still outputs a note with default semantics, no silent failure. |
+| **Cursor `f2s-config-check.mdc`** | Rule-layer enforcement: "Read before skill body"; Cursor hooks are used for update checks only, not automatic config reads. |
+| **Claude `f2s-config-session` SessionStart** | Injects one config summary when the conversation starts, reducing the chance that the setting is forgotten. |
+| **Claude `f2s-config-inject` PreToolUse** | Only guards **`f2s-*` Skill** calls by reminding the agent that the first skill-body action must be Read; it no longer repeatedly injects the full config. |
+| **Codex `AGENTS.md` / `.codex/topics/f2s-config-check.md`** | Text-layer enforcement: "Read before skill body"; Codex hooks are used for update checks only, not automatic config reads. |
 | **Codex `AGENTS.md` + `renderProjectConfigBlock`** | Top-level **Read** hard constraint + **init snapshot table** (if inconsistent with disk, Read takes precedence). |
 | **Knowledge base `config-precheck` topic** | When routing hits, provides only **summary** and a pointer to the Codex full text, **not** a substitute for Read JSON. |
 
@@ -521,7 +523,7 @@ The same `.Knowledge/` drives all tools  ·  adding/removing tools does not affe
 ```
 Adding a topic                         Removing a topic
 ─────────────────────               ─────────────────────
-1. Write topics/xxx.md               f2s-ctx-rm stock-docs/xxx.md
+1. Write topics/xxx.md               f2s-kb-rm stock-docs/xxx.md
 2. Write matchers/m-xxx.json                  ↓
 3. Register in manifest-routing       Automatically cleans up topics/ + manifest
                                        + index references
@@ -562,8 +564,9 @@ flow2spec.config.json
   switchAgentVerification: false → writer-side self-verify, daily use
   switchAgentVerification: true  → cross-verification, high-confidence critical scenarios
 
-  changeTracking.feat/fix/implement: false → no task checklist created
-  changeTracking.feat/fix/implement: true  → automatic task checklist creation when corresponding skills run, supporting cross-session continuation
+  changeTracking.feat: true        → f2s-kb-feat creates a task checklist by default
+  changeTracking.fix: false        → f2s-kb-fix does not create a task checklist by default
+  changeTracking.implement: true   → implement-tech-design creates a task checklist by default
 
   Three orthogonal dimensions · each skill can further refine and override global config
 ```
@@ -615,4 +618,4 @@ Best suited when: has scale · long-term iteration · multi-tool or multi-person
 - [Usage Guide](./usage-guide.md)
 - [Commands Reference](./commands-reference.md)
 - [Architecture](./architecture.md)
-- [Usage Scenarios](./usage-scenarios.md)
+- [Usage Scenarios](./usage-scenarios.md)