@double-codeing/flow2spec 3.0.9 → 3.0.12

package/docs/commands-reference.en.md

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

package/package.json

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

package/templates/knowledge/index.md

@@ -26,9 +26,11 @@
 | stock-docs-vs-req-docs | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock：[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)（可选） |
 | fallback-triage | `.Knowledge/topics/f2s-fallback-triage.md` | 未命中或低置信度：分诊与澄清 | stock：[路由分诊说明](.Knowledge/stock-docs/<分诊说明>.md)（可选） |
 | config-precheck | `.Knowledge/topics/f2s-config-precheck.md` | 执行 `f2s-*` 前读 `flow2spec.config.json` / 编排开关 | Codex 长文：仓库根 `.codex/topics/f2s-config-check.md`；[路由摘要](topics/f2s-config-precheck.md) |
+| f2s-task | `.Knowledge/topics/f2s-task.md` | 变更追踪、`.task/` 任务清单与跨会话续作 | 长文：配置根 `rules/f2s-task.*`；Codex：`.codex/topics/f2s-task.md` |
+| f2s-req-plan | `.Knowledge/topics/f2s-req-plan.md` | 需求/方案规划与实现；始终维护 `.task/` | 技能：`skills/f2s-req-plan/SKILL.md`；依赖 `f2s-task` |
 
 每主题保留 **1–3 条** 可点击摘要链接；全量路径对照写入 `.Knowledge/migration-report.md`（迁移场景）。  
-其中 **`implement-tech-design`**、**`stock-docs-vs-req-docs`**、**`config-precheck`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。
+其中 **`implement-tech-design`**、**`stock-docs-vs-req-docs`**、**`config-precheck`**、**`f2s-task`** 在 `topics/` 内为**路由摘要**；执行长文见配置根 **`rules/f2s-*.md(c)`**；使用 Codex 时见 **`.codex/AGENTS.md`**、**`.codex/topics/f2s-*.md`**（`f2s-config-check` 与 `AGENTS` 前置同源，按需打开）。
 
 ---
 

package/templates/knowledge/manifest-matchers.json

@@ -30,6 +30,36 @@
         "f2s-config-inject",
         "changeTracking"
       ]
+    },
+    "m-change-tracking": {
+      "includeAny": [
+        "changeTracking",
+        "变更追踪",
+        "任务追踪",
+        "任务清单",
+        ".task",
+        "续作",
+        "继续上次任务",
+        "todo.json",
+        "task.md",
+        "f2s-task",
+        "任务清单归档",
+        "跨会话"
+      ]
+    },
+    "m-req-plan": {
+      "includeAny": [
+        "f2s-req-plan",
+        "任务规划",
+        "任务清单设计",
+        "需求规划",
+        "创建任务清单",
+        "规划需求",
+        "req-plan",
+        "需求实现",
+        "按需求实现",
+        "按方案规划"
+      ]
     }
   }
 }

package/templates/knowledge/manifest-routing.json

@@ -7,13 +7,18 @@
   "topicDependencies": {
     "implement-tech-design": [
       "stock-docs-vs-req-docs"
+    ],
+    "f2s-req-plan": [
+      "f2s-task"
     ]
   },
   "topicPaths": {
     "implement-tech-design": ".Knowledge/topics/f2s-implement-tech-design.md",
     "stock-docs-vs-req-docs": ".Knowledge/topics/f2s-stock-docs-vs-req-docs.md",
     "fallback-triage": ".Knowledge/topics/f2s-fallback-triage.md",
-    "config-precheck": ".Knowledge/topics/f2s-config-precheck.md"
+    "config-precheck": ".Knowledge/topics/f2s-config-precheck.md",
+    "f2s-task": ".Knowledge/topics/f2s-task.md",
+    "f2s-req-plan": ".Knowledge/topics/f2s-req-plan.md"
   },
   "taskToTopicRules": [
     {
@@ -40,6 +45,22 @@
       "topics": [
         "stock-docs-vs-req-docs"
       ]
+    },
+    {
+      "task": "change-tracking",
+      "matcherId": "m-change-tracking",
+      "matcherPath": ".Knowledge/matchers/m-change-tracking.json",
+      "topics": [
+        "f2s-task"
+      ]
+    },
+    {
+      "task": "req-plan",
+      "matcherId": "m-req-plan",
+      "matcherPath": ".Knowledge/matchers/m-req-plan.json",
+      "topics": [
+        "f2s-req-plan"
+      ]
     }
   ]
 }

package/templates/knowledge/matchers/m-change-tracking.json

@@ -0,0 +1,17 @@
+{
+  "id": "m-change-tracking",
+  "includeAny": [
+    "changeTracking",
+    "变更追踪",
+    "任务追踪",
+    "任务清单",
+    ".task",
+    "续作",
+    "继续上次任务",
+    "todo.json",
+    "task.md",
+    "f2s-task",
+    "任务清单归档",
+    "跨会话"
+  ]
+}

package/templates/knowledge/matchers/m-req-plan.json

@@ -0,0 +1,15 @@
+{
+  "id": "m-req-plan",
+  "includeAny": [
+    "f2s-req-plan",
+    "任务规划",
+    "任务清单设计",
+    "需求规划",
+    "创建任务清单",
+    "规划需求",
+    "req-plan",
+    "需求实现",
+    "按需求实现",
+    "按方案规划"
+  ]
+}

package/templates/knowledge/topics/f2s-req-plan.md

@@ -0,0 +1,27 @@
+# f2s-req-plan（路由摘要）
+
+> 长文见配置根 **`skills/f2s-req-plan/SKILL.md`**。  
+> **`.task/` 真值源**：配置根 **`rules/f2s-task.*`**（Codex：`.codex/topics/f2s-task.md`）。  
+> 设计背景：[Flow2Spec 任务清单与变更追踪](../stock-docs/<任务清单说明>.md)（可选）。
+
+## 依赖
+
+执行本主题前须先读依赖主题 **`f2s-task`**（`manifest-routing.topicDependencies`）。
+
+## 作用
+
+从技术方案或需求描述出发：**续作分诊 → 草稿确认 → 按 f2s-task 落盘 → 实现 → 归档**。
+
+1. 步骤 0：`flow2spec.config.json` + **`f2s-task` 全文**
+2. `f2s-task`「任务开始」：检查 `todo.json` / keywords 续作
+3. 草稿确认（主 agent）
+4. 落盘 `task.md` / `context.md` / `user-todos.md` / `todo.json`（`linkedSkill: f2s-req-plan`）
+5. 实现并按步打钩；用户代办写 `user-todos.md`
+6. 满足归档门禁后移入 `completed/<YYYYMMDD>-<task-name>/`
+
+不依赖 `changeTracking`，但 **始终** 服从 `f2s-task`。
+
+## 下一步
+
+- 技能全文：`skills/f2s-req-plan/SKILL.md`
+- 任务规则：`rules/f2s-task.*` 或 `.codex/topics/f2s-task.md`

package/templates/knowledge/topics/f2s-task.md

@@ -0,0 +1,45 @@
+# f2s-task（路由摘要）
+
+> 长文见配置根 **`rules/f2s-task.*`**。  
+> 体系化设计说明（两种模式、目录、`todo.json`）：[Flow2Spec 任务清单与变更追踪](../stock-docs/Flow2Spec-任务清单与变更追踪.md)。
+
+## 作用
+
+变更追踪规则（`alwaysApply: true`）。当对应技能的 `changeTracking.*` 为 `true` 时，技能执行前后自动创建、逐步更新、最终归档 `.task/` 下的任务清单，支持跨会话续作。
+
+## 生效范围
+
+| 配置项 | 对应技能 |
+| --- | --- |
+| `changeTracking.feat` | `f2s-kb-feat` |
+| `changeTracking.fix` | `f2s-kb-fix` |
+| `changeTracking.implement` | `f2s-implement-tech-design` |
+
+`f2s-req-plan` 不受配置约束，始终创建任务清单。
+
+## 目录结构
+
+```
+.task/
+├── todo.json                    ← 活跃任务索引（仅主 agent 写）
+├── active/<task-name>/
+│   ├── task.md                  ← checklist（执行步骤）
+│   ├── context.md               ← 涉及文件、文档链接
+│   └── user-todos.md            ← 须用户执行的代办（改库、配环境等）
+└── completed/<YYYYMMDD>-<task-name>/
+    ├── task.md
+    ├── context.md
+    └── user-todos.md
+```
+
+用户代办**必须**落在与 `task.md` 同目录的 **`user-todos.md`**，细则见配置根 **`rules/f2s-task.*`**。
+
+## 跨会话续作
+
+新会话开始时若存在 `todo.json`，规则自动将用户首条消息与各条目 `keywords` 匹配：
+- 命中 → 展示剩余 checklist，**摘要 `user-todos.md` 中未完成项（若有）**，加载 `linkedSkill` 对应技能文件作为执行上下文，提示是否继续
+- 无命中 → 不打扰，正常响应
+
+## 下一步
+
+读配置根 `rules/f2s-task.*` 获取完整规则（目录结构、todo.json 格式、任务生命周期、Hook 配置）。

package/templates/rules/f2s-task.mdc

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

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

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