🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@double-codeing/flow2spec

Package Overview
Dependencies
Maintainers
1
Versions
34
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@double-codeing/flow2spec - npm Package Compare versions

Comparing version
3.0.9
 to
3.0.11
+36
-1
cli.js

@@ -15,2 +15,4 @@ #!/usr/bin/env node

const { execSync } = require("child_process");
const args = process.argv.slice(2);

@@ -23,4 +25,6 @@ const sub = args[0];

const pkg = require("./package.json");
const help = `
Flow2Spec - 统一知识库工作流（AI 配置入口）
Flow2Spec - 统一知识库工作流（AI 配置入口） v${pkg.version}

@@ -30,2 +34,4 @@ 用法:

flow2spec config 打印项目根 ${CONFIG_FILENAME} 的解析结果（缺省值合并后）
flow2spec version 显示当前 flow2spec 版本
flow2spec update 更新 flow2spec 到最新版本
flow2spec --help 显示本说明

@@ -66,2 +72,31 @@

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") {

@@ -68,0 +103,0 @@ const cwd = process.cwd();

+47
-1
docs/commands-reference.en.md

@@ -11,2 +11,4 @@ [中文](./README-命令说明.md) | [English](./commands-reference.en.md)

**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**:

@@ -38,2 +40,4 @@ - A new project needs architecture documentation

**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**:

@@ -65,2 +69,4 @@ - PDF technical proposals need conversion to Markdown

**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**:

@@ -98,2 +104,4 @@ - After a final draft is complete, the knowledge base needs to "know about" these documents

**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**:

@@ -130,2 +138,4 @@ - Existing code needs knowledge base documentation

**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**:

@@ -151,2 +161,4 @@ - A document is deprecated and needs removal from the knowledge routing

**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**:

@@ -182,2 +194,4 @@ - A PDF technical proposal needs to be implemented

**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**:

@@ -201,2 +215,4 @@ - First step after receiving a PRD, ensuring correct understanding

**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**:

@@ -231,2 +247,4 @@ - After `f2s-req-clarify` completes, output a proposal based on clarification results

**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**:

@@ -261,2 +279,4 @@ - A technical proposal document exists and needs to be broken down into a task list before implementation

**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**:

@@ -296,2 +316,4 @@ - Committing code after each feature implementation or bug fix

**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**:

@@ -331,2 +353,4 @@ - Code implementation does not match the technical proposal

**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**:

@@ -396,2 +420,4 @@ - New feature development

**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**:

@@ -423,2 +449,4 @@ - Context conflicts arise after a Git merge/rebase

**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**:

@@ -458,2 +486,4 @@ - Upgrading an old project to the new Flow2Spec version

**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**:

@@ -490,2 +520,12 @@ - After a `flow2spec` package version upgrade, upgrade the project knowledge base template

### `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`

@@ -497,2 +537,4 @@

**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**:

@@ -518,2 +560,4 @@

**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**:

@@ -538,2 +582,4 @@

**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.

@@ -570,3 +616,3 @@

`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).

@@ -573,0 +619,0 @@ ### `subAgent` Field

+227
-71
docs/README-命令说明.md

@@ -9,3 +9,6 @@ # 工作流与技能说明

**工作原理**：以「inventory 驱动扫描」为核心——先由主 agent 产出模块清单（inventory）与扫描契约（读哪些入口、关注哪些维度），再按 inventory 执行只读代码扫描，最后将扫描结果聚合为人可读的架构初稿落盘 `stock-docs/`。整个流程不改代码，仅做「代码→文档」的单向提取。
**使用场景**：
- 新项目需要架构文档

@@ -16,2 +19,3 @@ - 存量项目需要补充架构说明

**关联关系**：
- **前置**：无

@@ -22,2 +26,3 @@ - **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内扫描代码并生成

@@ -27,7 +32,10 @@ - `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`），不得自行裁剪范围 |
---

@@ -39,3 +47,6 @@

**工作原理**：将非结构化或格式各异的文档（PDF/初稿）对照内置终稿模版进行格式归一化：提取核心概念表、业务规则、关键流程、配置与错误处理等标准章节，补齐缺失段落标记，最终输出格式统一的 `_终稿.md`。终稿是 `f2s-ctx-build` 的标准输入物，确保知识库入口的结构一致性。
**使用场景**：
- PDF 技术方案需要转为 Markdown

@@ -46,2 +57,3 @@ - 初稿需要规范化以便沉淀

**关联关系**：
- **前置**：PDF 文档或初稿文档

@@ -52,2 +64,3 @@ - **后续**：`f2s-ctx-build`（终稿入库）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成全流程

@@ -57,7 +70,10 @@ - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做套模版与排版草稿；子不追问用户、不补写流程说明、不宣称终稿合规；主 agent 识别格式缺口并定稿验收

**职责划分**：
| 角色 | 职责 |
|------|------|
| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿 |
| 角色 | 职责 |
| ------- | --------------------- |
| 主 agent | 识别格式缺口、对照模版与澄清文档验收定稿 |
| 子 agent | 套模版与排版草稿，不追问用户、不写流程说明 |
---

@@ -69,3 +85,6 @@

**工作原理**：以终稿文档为输入，执行「文档→路由」的三步映射：① 从终稿中提取能力主题与关键词；② 生成 `topics/<topic>.md`（路由摘要，含执行边界与下一步指针）和 `matchers/<id>.json`（机读匹配词 `includeAny`）；③ 在 `manifest-routing.json` 注册 task→topic 映射规则，并更新 `index.md` 人读导航。完成后，任务路由引擎即可通过关键词命中该主题。
**使用场景**：
- 终稿文档完成后，需要让知识库"知道"这些文档

@@ -76,2 +95,3 @@ - 新增业务领域，需要建立路由映射

**关联关系**：
- **前置**：`f2s-doc-arch`、`f2s-doc-final` 或直接编写的终稿

@@ -87,2 +107,3 @@ - **后续**：无（入库完成后可直接使用）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内顺序处理各文档

@@ -92,8 +113,11 @@ - `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 |
---

@@ -105,3 +129,6 @@

**工作原理**：从多个分散的源文件（代码、配置、散落文档）中聚合提取能力描述，走完整的「初稿→终稿→topics/index/manifest」沉淀链路。与 `f2s-ctx-build` 的区别在于输入：`ctx-build` 从已有的单份终稿驱动，`doc-add` 从多个散落源聚合后再走同一管线。本质是补齐「有实现无文档」的缺口。
**使用场景**：
- 存量代码需要补录知识库

@@ -112,2 +139,3 @@ - 多份相关文档需要聚合入库

**关联关系**：
- **前置**：无（可直接触发）

@@ -118,2 +146,3 @@ - **后续**：无（入库完成即结束）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内顺序处理

@@ -124,8 +153,12 @@ - `subAgent: true`：满足以下任一阈值时启用，默认走 **B 模式**（主产出 inventory → 子并行只读按 schema 填表 → 主合并落盘）；多 workspace / monorepo、首轮子表矛盾或空洞、多源叙述冲突严重时升级 **C 模式**（多轮纠偏）

**职责划分**：
| 角色 | 职责 |
|------|------|
| 主 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 校验路由映射完整性与关键词覆盖

@@ -140,3 +173,6 @@ - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

**工作原理**：`f2s-ctx-build` 的逆操作——给定一份 `stock-docs` 文档路径，定位其在 `manifest-routing.json` 中的 task→topic 规则、对应的 `matchers/<id>.json` 分片、`topics/<topic>.md` 文件以及 `index.md` 中的行项，逐一清除引用。若删除后某 topic 无任何 task 引用，则移除该 topic 文件。源文档本身保留不动，用户可自行决定是否物理删除。
**使用场景**：
- 文档已废弃，需要从知识路由中移除

@@ -147,2 +183,3 @@ - 误入库的文档需要撤销路由映射

**关联关系**：
- **前置**：已入库的 stock-docs 文档

@@ -153,2 +190,3 @@ - **后续**：无

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内全流程执行（单点删除拆子收益低）

@@ -163,3 +201,6 @@ - `subAgent: true`：仅当**批量删除 ≥ 5 个主题**时才拆子执行删除与清引用；主 agent 必控范围确认与 fallbackTopic 重指；manifest-routing.json 与 index.md 恒由主落盘

**工作原理**：面向「按方案实现代码」的前置环节——将 PDF 中的接口定义、数据模型、时序流程等结构化内容提取为 Markdown 格式并落盘 `req-docs/`。与 `f2s-doc-final` 的区别在于目标路径和用途：`doc-pdf` 输出到 `req-docs/` 供 `implement-tech-design` 规则消费驱动编码，`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。
**使用场景**：
- 收到 PDF 格式技术方案需要实现

@@ -170,2 +211,3 @@ - 历史 PDF 文档需要纳入管理

**关联关系**：
- **前置**：PDF 文档

@@ -175,5 +217,6 @@ - **输出**：`.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 内完成全流程

@@ -183,7 +226,10 @@ - `subAgent: true`：PDF > 50 页或 > 5MB 时，可拆子做 PDF→MD 首稿落盘 req-docs；子不追问用户、不补写流程说明章节；主 agent 接手追问与流程说明补写

**职责划分**：
| 角色 | 职责 |
|------|------|
| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收 |
| 角色 | 职责 |
| ------- | ------------------------------- |
| 主 agent | 追问用户补充流程说明、完成 req-docs 落盘验收 |
| 子 agent | 仅做 PDF→MD 首稿并落盘 req-docs，不向用户追问 |
---

@@ -197,3 +243,6 @@

**工作原理**：采用「结构化追问」策略——将需求文档按「角色/场景/流程/边界/异常/非目标」六维拆解，逐维检查是否存在模糊表述、未定义概念或矛盾点，对每个缺口生成针对性追问。多轮对话直到所有维度无歧义后，输出需求澄清记录作为 `f2s-req-backend` 的输入。本质是将非结构化 PRD 转为可落地的结构化需求约束。
**使用场景**：
- 收到 PRD 后首步骤，确保理解正确

@@ -204,2 +253,3 @@ - 需求边界模糊、缺少验收标准时

**关联关系**：
- **前置**：无（可直接触发）

@@ -217,3 +267,6 @@ - **后续**：`f2s-req-backend`（澄清后生成技术方案）

**工作原理**：以「知识库约束 + 模版驱动」为核心——先从 `topics/stock-docs` 中抽取当前项目的架构约定、接口风格、数据模型规范等约束摘要，再将澄清后的需求对照后端技术方案模版（接口/模型/流程/异常/配置/迁移）逐章填写，确保方案与现有架构一致。输出落盘 `req-docs/`，即为 `implement-tech-design` 的编码依据。
**使用场景**：
- `f2s-req-clarify` 完成后，基于澄清结果输出方案

@@ -223,2 +276,3 @@ - 已有明确需求文档，直接生成技术方案

**关联关系**：
- **前置**：`f2s-req-clarify`（推荐）或明确的需求文档

@@ -229,2 +283,3 @@ - **输出**：`.Knowledge/req-docs/<技术方案>.md`

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成方案编写

@@ -234,8 +289,12 @@ - `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 校验跨章节一致性（接口签名与数据模型对齐、流程与异常处理覆盖）

@@ -250,3 +309,6 @@ - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

**工作原理**：执行「解析→规划→确认→实现→归档」五阶段闭环。① 解析技术方案文档提取实现要点；② 按模块/功能粒度拆分为可执行任务清单并写入 `.task/`；③ 展示草稿给用户确认后锁定清单；④ 按清单逐项实现代码，每完成一项立即打钩 `task.md`；⑤ 全部完成后归档。与 `implement-tech-design` 规则的区别：`req-plan` 始终带任务追踪且支持并行子 agent 实现，适合大型需求；后者是轻量规则驱动的单线程编码。
**使用场景**：
- 有技术方案文档，需要拆解为任务清单后再实现

@@ -257,2 +319,3 @@ - 需求描述较复杂，希望先确认清单再动手

**关联关系**：
- **前置**：技术方案文档路径（`.Knowledge/req-docs/*.md` 或 PDF）或需求/变更描述

@@ -263,2 +326,3 @@ - **输出**：`.task/active/<task-name>/task.md` + `context.md`；实现代码

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成解析、确认、实现全流程

@@ -268,8 +332,11 @@ - `subAgent: true`：步骤 1（解析文档）可拆子并行只读；步骤 2（草稿确认）必须主 agent；步骤 4（实现代码）可按模块拆子并行；`todo.json` 恒由主 agent 写

**职责划分**：
| 角色 | 职责 |
|------|------|
| 主 agent | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要 |
| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘 |
| 角色 | 职责 |
| ----------- | ------------------------------------ |
| 主 agent | 输出草稿、用户确认、写 `todo.json`、汇总实现摘要 |
| 子 agent（解析） | 只读文档，输出解析结果摘要，不落盘 |
| 子 agent（实现） | 按模块实现代码，不触碰 `.task/` 和 `.Knowledge/` |
---

@@ -283,3 +350,6 @@

**工作原理**：在 `git commit` 之上叠加「知识库覆盖门控」——先通过 `git diff` 推断本次变更涉及的功能模块，再与 `.Knowledge/topics/` 和 `stock-docs/` 交叉比对，判断变更能力是否已有知识库记录。未覆盖时阻断并提示三选（补录/跳过/取消），避免「代码有了但知识库不知道」的静默漂移。提交信息强制 emoji + Conventional Commits 格式，保证 git log 的机读一致性。
**使用场景**：
- 每次功能实现或 Bug 修复后提交代码

@@ -290,2 +360,3 @@ - 希望在提交时得到知识库覆盖情况的提醒

**关联关系**：
- **前置**：代码已写完（`implement-tech-design`、`f2s-kb-fix`、`f2s-kb-feat` 等执行后）

@@ -296,2 +367,3 @@ - **后续**：无（commit 完成即结束，不自动 push）

**执行流程**：
1. `git status --short` + `git diff HEAD` 区分 staged / unstaged / untracked 三类文件；发现 merge conflict 标记立即终止

@@ -305,2 +377,3 @@ 2. 对比 `.Knowledge/topics/` 与 `stock-docs/`，判断本次变更能力是否已入库；`.Knowledge` 不存在时跳过并提示

**约束**：
- 禁止 `git add -A` / `git add .`，只 add 已确认的变更文件

@@ -321,3 +394,6 @@ - 禁止 `--no-verify`，hook 失败须修复后重试

**工作原理**：执行「定位→修复→同步」三步——先根据用户描述在知识库路由（manifest→topic→stock-docs）中定位相关上下文与代码位置，确认问题根因；修复代码后，自动检查 `topics/stock-docs/matchers` 中与该能力相关的描述是否因修复而需要更新，若有则原位修订（现行真值覆盖，不追加历史否定句）。「修代码必同步文档」是核心原则，避免知识库与实现漂移。
**使用场景**：
- 代码实现与技术方案不符

@@ -330,2 +406,3 @@ - 规则理解有误需要修正

**关联关系**：
- **前置**：问题发现（代码实现错误或规则偏差）

@@ -336,2 +413,3 @@ - **后续**：无（修复并同步完成即结束）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成修复和知识库同步

@@ -341,9 +419,13 @@ - `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 校验修复正确性与知识库一致性

@@ -359,3 +441,6 @@ - 主 agent 落盘的知识库同步 → 子 agent 复核 topic/manifest 一致性（须 `subAgent: true` 且已拆出子任务，否则主 agent 内自验）

**工作原理**：执行「判断→实现→入库」三阶段——先判断用户描述的能力在代码中处于「未实现/部分实现/已实现」哪种状态；未实现或部分实现时先补齐代码；最后走知识库同步：写 `stock-docs` 能力说明、生成或更新 `topics` 主题摘要、在 `manifest-routing` 和 `matchers` 注册路由映射。与 `f2s-kb-fix` 的区别：`kb-feat` 面向「新增」，`kb-fix` 面向「修正已有」。
**使用场景**：
- 新功能开发

@@ -367,2 +452,3 @@ - 存量功能需要补录知识库

**关联关系**：
- **前置**：无（可直接触发）

@@ -373,2 +459,3 @@ - **后续**：无（实现+同步完成即结束）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成

@@ -378,9 +465,13 @@ - `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 校验与实现代码的能力描述一致性

@@ -396,2 +487,3 @@ - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

**使用场景**：
- 会话中已完成实现，需要补录知识库

@@ -402,2 +494,3 @@ - 从代码反向沉淀知识

**关联关系**：
- **前置**：无（可直接触发，或零输入推断）

@@ -409,2 +502,3 @@ - **后续**：无

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成推断和同步

@@ -414,9 +508,13 @@ - `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` 关键词覆盖

@@ -431,3 +529,6 @@ - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

**工作原理**：按文件类别分层处理冲突——将冲突文件分为「可安全自动合并」（index、manifest、matchers 等结构化文件，取并集或最新版本）和「须用户确认」（实现代码、业务规则等语义文件）两类。对前者自动 resolve，对后者生成分类对照表（ours/theirs 摘要 + 建议）并罗列差异，等待用户逐项裁决。核心设计思想：知识库元数据可自动化，业务语义不可擅自裁定。
**使用场景**：
- Git merge/rebase 后出现上下文冲突

@@ -438,2 +539,3 @@ - 多人协作导致知识库文件冲突

**关联关系**：
- **前置**：Git 合并产生的冲突

@@ -444,2 +546,3 @@ - **后续**：无（冲突解决即结束）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内分析与解决冲突

@@ -449,7 +552,10 @@ - `subAgent: true`：可拆子做冲突扫描与分类对照表（`file / category / ours_summary / theirs_summary / recommendation` 五字段）；子不得自行合并文件；主 agent 按策略落盘、处理实现侧决策、完成验收

**职责划分**：
| 角色 | 职责 |
|------|------|
| 主 agent | 按策略落盘合并结果、处理实现侧冲突决策、验收 |
| 角色 | 职责 |
| ------- | ----------------------------------- |
| 主 agent | 按策略落盘合并结果、处理实现侧冲突决策、验收 |
| 子 agent | 仅做冲突扫描与分类，按五字段 schema 交付对照表，不自行合并文件 |
---

@@ -461,3 +567,6 @@

**工作原理**：以旧版 `docs-index.md` 和 `rules/main.md(c)` 为「索引线索」，递归识别所有被引用的业务规则和技能文件，按主题粒度重新组织到 `.Knowledge/` 的 `topics/stock-docs/req-docs` 三层结构中。迁移完成后落盘 `migration-report.md`（对照表 + 拟删路径），待用户确认后清理旧文件。本质是一次性的结构重组，将分散的规则/文档归并为统一知识库。
**使用场景**：
- 旧项目升级到 Flow2Spec 新版

@@ -467,2 +576,3 @@ - 存量知识库需要结构化整理

**关联关系**：
- **前置**：旧版知识库（`docs-index.md`、`rules/`、`skills/`）

@@ -472,3 +582,3 @@ - **后续**：`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`

@@ -479,2 +589,3 @@ 4. 落盘 `.Knowledge/migration-report.md`

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内逐主题迁移

@@ -484,8 +595,12 @@ - `subAgent: true`：子只做搬运 + migration-report 草案片段（以 patch 形式交付）；状态文件（migration-report.md、删除执行记录）由主 agent 唯一落盘；主 agent 主导删除清单确认与删除闭环

**职责划分**：
| 角色 | 职责 |
|------|------|
| 角色 | 职责 |
| ------- | --------------------------------------------- |
| 主 agent | 制定迁移规划、合并迁移结果、落盘 migration-report、主导删除确认与执行闭环 |
| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录 |
| 子 agent | 负责指定主题的搬运与草案片段生成（patch 形式），不写状态文件、不写删除执行记录 |
**交叉验证（`switchAgentVerification: true` 时）**：
- 子 agent 迁移落盘的主题 → 主 agent 校验迁移完整性（旧路径是否全量覆盖、主题边界是否重叠）

@@ -500,3 +615,6 @@ - 仅当 `subAgent: true` 且实际拆出子任务时生效；否则全部在主 agent 内验证

**工作原理**：通过「版本分流 + init 代跑」实现升级——先检测当前知识库属于 V1（旧结构，需先 migrate）还是 V2+（已有 `.Knowledge`），V1 走 migrate 后再 init，V2+ 直接代跑 `flow2spec init` 进行包级结构增量对齐（补齐新模板、升级 manifest schema、对齐 matchers 分片格式）。升级后重读 SKILL.md 判断是否需要重跑某些步骤。与单独 `init` 的区别：`kb-upgrade` 包含版本判断和重跑逻辑，`init` 仅做一次性结构补齐。
**使用场景**：
- flow2spec 包版本升级后，升级项目知识库模板

@@ -506,2 +624,3 @@ - 旧项目升级到最新结构

**关联关系**：
- **前置**：`f2s-kb-migrate`（V1 流程）或已存在的 `.Knowledge/`

@@ -512,2 +631,3 @@ - **包含**：内部会调用 `flow2spec init` 进行结构对齐

**流程差异**（技能内分流代号，**不等于** npm 包主版本号）：
- **V1**：先 `f2s-kb-migrate` 再代跑 `flow2spec init`

@@ -517,2 +637,3 @@ - **现行库（V2+）**：已稳定 `.Knowledge` + `manifest-routing` 时，代跑 `flow2spec init` 以对齐 manifest-routing + matchers 分片（**含 Flow2Spec npm v3.x 等**，详见 `skills/f2s-kb-upgrade/SKILL.md` 步骤 0）

**子 agent 调用**：
- `subAgent: false`（默认）：主 agent 内完成升级

@@ -522,7 +643,10 @@ - `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 命令，不落盘知识库内容 |
**交叉验证**：本技能不绑定交叉校验，落盘侧自验。

@@ -536,2 +660,12 @@

### `f2s-karpathy-guidelines`
**触发词**：`alwaysApply`（始终生效，无需显式触发）
**作用**：Flow2Spec 内置的 Karpathy 式编码行为准则，约束 Agent 的编码决策质量。
**工作原理**：从 Andrej Karpathy 对 LLM 写代码常见失误的观察中提炼四条行为约束，作为 `alwaysApply` 规则在所有 `f2s-*` 技能执行时隐式生效：① 先想清楚再写代码（假设要说清楚，不确定就问）；② 简单优先（用最少代码解决问题）；③ 手术式修改（只动该动的，风格对齐现有代码）；④ 目标驱动执行（先定义可验证的成功标准再循环迭代）。当这些准则与 `f2s-*` 强制步骤冲突时，以 `f2s-*` 为准。
---
### `f2s-task`

@@ -541,15 +675,19 @@

**作用**：变更追踪规则（`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.`*

@@ -564,10 +702,15 @@ ---

**工作原理**：通过「用途隔离」避免文档混放——`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`、手动放置 |
**使用场景**：
- 不确定文档应该放哪里

@@ -584,5 +727,8 @@ - 需要明确 stock-docs 与 req-docs 的分工

**工作原理**：以「方案即合约」为核心约束——Agent 以 `req-docs/` 中的技术方案为唯一编码依据，按「理解方案→输出任务列表→提问确认→逐步实现→输出待完成列表」的强制六步流水线执行。任务列表和实现前提问是不可跳过的门禁，确保不会在理解偏差的情况下动手编码。与 `f2s-req-plan` 的区别：本规则是轻量单线程编码驱动，不强制创建 `.task/` 追踪（除非 `changeTracking.implement: true`）。
**变更追踪**：若 `changeTracking.implement: true`，在步骤 2.5 输出任务列表后同步写入 `.task/active/<task-name>/task.md`；步骤 5 收尾时归档任务。
**使用场景**：
- 技术方案已就绪，需要按方案编码

@@ -592,2 +738,3 @@ - 方案变更后需要同步更新代码

**关联关系**：
- **前置**：`.Knowledge/req-docs/<技术方案>.md`（通过 `f2s-req-backend` 或手动放置）

@@ -600,2 +747,3 @@ - **规则位置**：

**执行流程**（规则强制）：
1. 输入标准化

@@ -618,18 +766,22 @@ 2. 理解方案与上下文

`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` 字段

@@ -649,8 +801,10 @@

| 子项 | 对应技能 | 效果 |
|------|---------|------|
| `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`）向下兼容，自动展开为三项全开/全关。

@@ -671,5 +825,7 @@

相关文档：
- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
- [README-目录与路径约定](./README-目录与路径约定.md)
- [README-体系与原理](./README-体系与原理.md)
- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+1
-1
package.json
{
"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-* 技能在对话中维护。",

@@ -5,0 +5,0 @@ "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",

+3
-0
templates/knowledge/manifest-routing.json

@@ -10,2 +10,5 @@ {

"stock-docs-vs-req-docs"
],
"f2s-req-plan": [
"f2s-task"
]

@@ -12,0 +15,0 @@ },

+101
-58
templates/skills/f2s-req-plan/SKILL.md
---
name: f2s-req-plan
description: 根据技术方案/需求描述/变更描述规划并实现任务；始终创建任务清单，支持子 agent 并行实现代码；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单
description: 根据技术方案/需求描述/变更描述规划并实现任务；始终按 f2s-task 维护 .task/；支持子 agent 并行实现；触发：f2s-req-plan、创建任务、任务规划、我需要任务清单
---

@@ -8,75 +8,114 @@

从需求/技术方案出发，完整覆盖「规划 → 实现」链路。不依赖 `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：前置（强制，任何步骤之前）
`subAgent=true` 时，可拆子 agent 并行执行（只读，不落盘）：
1. **`Read("flow2spec.config.json")`**（项目根；缺失字段视为 `false`）。
2. **`Read` 上表三端之一的 `f2s-task` 全文**（不得跳过；不得仅用本 SKILL 摘要代替）。
3. 按读到的 `subAgent` / `switchAgentVerification` 决定下文是否拆子 agent、是否交叉校验。
- 读取技术方案 / 需求文档全文，提取目标、范围、主要工作项、涉及文件路径
- 读取项目现有约定（`.Knowledge/stock-docs/`、架构说明）对齐实现上下文
- 若输入为 PDF，先执行 `f2s-doc-pdf` 转为 MD，再继续
### 步骤 1：续作分诊 + 解析输入
子 agent 只输出「解析结果摘要」（目标、工作项列表、涉及文件）交主 agent 汇总；`subAgent=false` 时主 agent 直接完成。
#### 1a. 续作分诊（`f2s-task`「任务开始」1–2，主 agent）
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。
#### 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** |
**禁止**：只建 `task.md` 不写 `todo.json`；省略 `user-todos.md`；使用 `completed/<task-name>-<date>` 旧式归档名。
### 步骤 4：实现代码
`subAgent=true` 时，按任务清单将各模块拆子 agent 并行实现：
遵守 `f2s-task`「**执行中**」「**中断与会话结束**」：
- 子 agent 只写实现代码
- 子 agent 完成后向主 agent 汇报改动摘要（文件路径 + 改动说明）
- `subAgent=false` 时主 agent 按清单逐项实现
- 按 `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`）。
- `task.md`「## 步骤」中与本次交付相关项 **全部为 `[x]`**（取消项已在「## 备注」说明）。
- 仍有 `[ ]` → **禁止**移入 `completed/`、**禁止**删 `todo.json` 条目。
凡产生**须用户执行**的项（改库、配环境、审批等），**同会话内**追加写入 `user-todos.md`（见 `f2s-task`「user-todos.md」）；子 agent 若回报此类项，由主 agent 合并追加，禁止仅写在对话中。
通过后：
### 步骤 5：归档任务
1. `.task/active/<task-name>/` → `.task/completed/<YYYYMMDD>-<task-name>/`（**日期 8 位在前**）
2. 从 `todo.json` 删除该条；空数组则删文件
3. `user-todos.md` 随目录一并归档
**仅当** `task.md`「步骤」已全部 `[x]`（或备注已记录取消项）后：将 `.task/active/<task-name>/` 整体移至 `.task/completed/<YYYYMMDD>-<task-name>/`，从 `todo.json` 删除对应条目。若仍有 `[ ]`，禁止归档，应先补打钩或修订清单（与 `f2s-task` 归档门禁一致）。
### 步骤 6：输出摘要

@@ -90,7 +129,10 @@

### 待办（如需同步知识库）
- 可后续调用 f2s-kb-sync 补充知识库
### 任务清单
- 已归档：`.task/completed/<YYYYMMDD>-<task-name>/`（或仍 active 时写明路径与剩余 `[ ]`）
### 用户代办（须用户在本机/平台完成）
- 详见 `.task/active/<task-name>/user-todos.md`（归档后在 `completed/.../` 同路径）
### 待办（知识库）
- 可后续调用 f2s-kb-sync / f2s-kb-feat
### 用户代办
- 见 `user-todos.md`（归档后在 completed 同路径）
```

@@ -100,14 +142,15 @@

- 不依赖 `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 则注明）。
templates/rules/f2s-task.mdc

Sorry, the diff of this file is not supported yet