@double-codeing/flow2spec 3.0.8 → 3.0.11

package/docs/usage-guide.en.md

@@ -0,0 +1,165 @@
+[中文](./Flow2Spec使用说明.md) | [English](./usage-guide.en.md)
+
+# Flow2Spec Usage Guide
+
+## 1. What `init` Does
+
+Execute in the project root:
+
+```bash
+flow2spec init [cursor|claude|codex ...]
+# To force reset .Knowledge from template:
+flow2spec init [cursor|claude|codex ...] --reset-knowledge
+```
+
+| What `init` does | What `init` does NOT do |
+|---------|----------|
+| Fills in missing directories and template files | Write or update business document content |
+| Writes agent config root `rules/` `skills/` | Update `includeAny` business terms |
+| Aligns `manifest-routing` + `matchers/` package-level structure | Replace `f2s-*` skills for writing business semantics |
+| Overwrites `.Knowledge` template files with `--reset-knowledge` | Override existing `.Knowledge` content (without this flag) |
+
+> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-doc-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-ctx-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**
+
+### `f2s-*` and `flow2spec.config.json`: Multi-Client, Multi-Layered Reminders (Authority Remains the Disk JSON)
+
+Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual values of **`subAgent` / `switchAgentVerification` / `changeTracking`**, etc. Flow2Spec enforces this via **different mechanisms** on **different clients**; they **complement** each other and do **not** replace one another. **Authority always** resides in the project root **`flow2spec.config.json`** (call **Read** to verify against disk before proceeding into skill body).
+
+| Client | `init` Output & Behavior | Description |
+| --- | --- | --- |
+| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Rule requires: **Read(`flow2spec.config.json`)** before entering skill body. |
+| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` (PreToolUse, `Skill` matching) | Injects a config summary when invoking **`f2s-*` Skill**; when **file is missing, JSON is invalid, or hook throws an unexpected exception**, it also injects a **notice + default semantics consistent with "file not found"** to avoid silent failure; it is still recommended to **Read** for confirmation when in doubt or after config changes. |
+| **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
+| **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
+
+For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.en.md).
+
+---
+
+## 2. Directory Conventions
+
+Core distinction: `stock-docs/` holds solidified documents (driving knowledge routing), `req-docs/` holds technical designs (driving coding implementation); they are not interchangeable.
+
+See [Directory Conventions](./directory-conventions.en.md) for the full directory description.
+
+---
+
+## 3. Typical Workflows
+
+### Requirements Planning and Implementation
+
+```
+f2s-req-plan
+```
+
+Provide a path to the technical design document or a requirements description. A draft task checklist is produced first and awaits confirmation. After confirmation, implementation proceeds according to the checklist. A `.task/` task checklist is always created — no `changeTracking` configuration is needed. Suitable for scenarios where you want to see the full picture before starting, or need cross-session progress tracking.
+
+### Change Tracking and Cross-Session Continuation
+
+```
+# Automatic mode: enabled by config (independent per skill)
+flow2spec.config.json → changeTracking.feat / fix / implement: true
+
+# Explicit mode: call f2s-req-plan (planning + implementation, no config dependency)
+f2s-req-plan
+```
+
+**Automatic mode**: When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a task checklist under `.task/active/`, check off steps progressively, and archive upon completion. In subsequent sessions, when describing related content, the `f2s-task` rule automatically matches and loads the remaining checklist — no need to re-explain the context.
+
+**Explicit mode**: Call `f2s-req-plan` directly — regardless of the `changeTracking` configuration, a task checklist is always created and code is implemented against it. Suitable for scenarios where you want to confirm the full picture before taking action.
+
+### New Feature Development
+
+```
+f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+```
+
+When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
+
+### Document Ingestion
+
+```
+New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
+PDF document ingestion:          f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
+```
+
+Integrate architecture descriptions or PDF technical designs into the knowledge routing (generates topics/matchers/manifest-routing).
+
+### PDF-Based Implementation
+
+```
+f2s-doc-pdf → implement-tech-design
+```
+
+Convert a PDF technical design to Markdown and place it in `req-docs/`, then let the `implement-tech-design` rule drive coding.
+
+### Backfilling Existing Capabilities
+
+```
+f2s-doc-add      # Aggregate multiple files, extract from source code / documents
+f2s-kb-sync      # Infer already-implemented capabilities from current session
+```
+
+Use these when code has already been shipped but the knowledge base has no record. `f2s-doc-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.
+
+### Routine Maintenance
+
+```
+f2s-kb-fix       # Fix implementation or rule errors, auto-sync knowledge base
+f2s-kb-feat      # Add new capabilities, auto-sync knowledge base
+f2s-kb-sync      # Periodic sync or backfill
+f2s-kb-merge     # Resolve context conflicts after Git merges
+```
+
+### Cross-Version Knowledge Base Upgrade
+
+```
+f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade
+f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0)
+```
+
+---
+
+## 4. Agent Execution Configuration
+
+Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
+
+**When to enable `subAgent: true`**: When the task is large (multi-module parallel implementation, batch document ingestion, large-scale migration). When enabled, each skill decides whether to actually split based on its own size threshold; tasks below the threshold are still completed within the main agent.
+
+**When to enable `switchAgentVerification: true`**: When higher write consistency is needed (large-scale migration, critical design implementation). The trade-off is increased execution rounds; for routine maintenance, the default `false` is sufficient. Requires `subAgent: true` to trigger the "main-writes, sub-verifies" cross-check direction.
+
+**When to enable `changeTracking.*`**: When you want each skill execution to automatically leave a resumable task checklist. Each skill sub-item is independently configurable without mutual interference:
+
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": false,
+    "implement": true
+  }
+}
+```
+
+If you prefer not to rely on configuration and want to explicitly plan tasks on demand, use `f2s-req-plan` directly.
+
+---
+
+## 5. Customization Suggestions
+
+- When customizing the "implement from technical design" logic for your project, prioritize adjusting **`f2s-implement-tech-design`**: Cursor `.cursor/rules/f2s-implement-tech-design.mdc`, Claude `.claude/rules/f2s-implement-tech-design.md`; Codex uses `.codex/AGENTS.md` and associated `skills/` as the source of truth.
+- Running `init` again by default only fills in missing templates and performs package-level structural alignment — it does **not** replace `f2s-*` skills for maintaining business content. To reset `.Knowledge` from the template, add `--reset-knowledge`.
+
+---
+
+## 6. Skill Identification
+
+Skills are triggered by matching `name` and `description`. Files are located under `config-root/skills/*/SKILL.md`.
+
+---
+
+## 7. Related Documents
+
+- [Commands Reference](./commands-reference.en.md)
+- [Directory Conventions](./directory-conventions.en.md)
+- [Architecture](./architecture.en.md)
+- [Usage Scenarios](./usage-scenarios.en.md)

package/docs/usage-scenarios.en.md

@@ -0,0 +1,222 @@
+[中文](./Flow2Spec-使用案例-模拟对话.md) | [English](./usage-scenarios.en.md)
+
+# Flow2Spec Usage Scenarios (Simulated Dialogues)
+
+The following examples revolve around the same e-commerce project, covering the full pipeline from requirements clarification through post-launch maintenance.
+
+**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
+
+---
+
+## Scenario 1: New Requirement -> Clarification -> Technical Design
+
+**You**
+
+> /f2s-req-clarify The product team provided a refund requirement doc, but it does not specify whether partial refunds and full refunds go through the same API, or whether points should be reversed after a successful refund. The document is at `.Knowledge/req-docs/refund-requirements-v1.md`.
+
+**Agent**
+
+> I have read the requirements document. There are a few points that need clarification:
+>
+> 1. Do partial refunds and full refunds reuse the same endpoint, differentiated by the `amount` field, or should they be two separate endpoints?
+> 2. Should points be reversed after a successful refund? If the reversal fails, should it block the refund flow?
+> 3. Is the refund processed synchronously or asynchronously (T+1)?
+> 4. Is there a seller-side review step?
+
+**You**
+
+> 1. Same endpoint, differentiated by amount; 2. Points are reversed; failure does not block the flow, retry asynchronously; 3. Asynchronous T+1; 4. No review needed.
+
+**Agent**
+
+> Clarification complete. Run `/f2s-req-backend` to produce the technical design.
+
+**You**
+
+> /f2s-req-backend
+
+**Agent**
+
+> Generated `.Knowledge/req-docs/refund-tech-design.md`, which includes:
+> - API design: `POST /refunds`, `amount` field distinguishes full / partial refunds
+> - State machine: `PENDING -> SUCCESS / FAILED`
+> - Points reversal: asynchronous queue, failures go to dead letter queue, alert for manual handling
+> - Error code list
+>
+> Next step: say "implement according to `.Knowledge/req-docs/refund-tech-design.md`" to trigger coding.
+
+---
+
+## Scenario 2: Architectural Documentation into Knowledge Base
+
+**You**
+
+> /f2s-doc-arch Help me draft an order service architecture document, focusing on the creation flow, payment callback, idempotency, and message delivery. The code is in `src/order` and `src/payment`.
+
+**Agent**
+
+> Scanned the relevant directories. Generated `.Knowledge/stock-docs/order-service-architecture-draft.md`, which includes:
+> - Module boundaries and dependencies
+> - Creation flow sequence diagram
+> - Payment callback idempotency mechanism (based on the `payment_callback_log` table)
+> - Message delivery retry strategy
+>
+> Confirm it looks good, then run `/f2s-doc-final` to normalize the format.
+
+**You**
+
+> /f2s-doc-final .Knowledge/stock-docs/order-service-architecture-draft.md
+
+**Agent**
+
+> Generated `.Knowledge/stock-docs/order-service-architecture-final.md`, formatted according to the final-draft template, with placeholders for items still to be filled in.
+
+**You**
+
+> f2s-ctx-build .Knowledge/stock-docs/order-service-architecture-final.md
+
+**Agent**
+
+> Knowledge base sync complete:
+> - Added `.Knowledge/topics/order-service.md`
+> - Updated `.Knowledge/manifest-routing.json` (added routing rule)
+> - Generated `.Knowledge/matchers/order-service.json` (keywords: order creation, payment callback, idempotency, message delivery)
+> - Updated `.Knowledge/index.md`
+>
+> Future tasks related to the order service will automatically hit this topic.
+
+---
+
+## Scenario 3: Implementation from Technical Design
+
+**You**
+
+> Implement according to `.Knowledge/req-docs/refund-tech-design.md`. Only modify `src/refund/`; do not touch the payment module.
+
+**Agent**
+
+> I have read the design document. Task list for implementation:
+>
+> 1. Create `RefundController` with `POST /refunds`
+> 2. Create `RefundService` with state machine transition logic
+> 3. Create `RefundRepository` for the `refund` table
+> 4. Create `PointRollbackProducer` to send rollback messages to the points queue
+> 5. Unit tests covering state machine transitions
+>
+> Before proceeding, I need to confirm:
+> - Does the `refund` table already exist, or do I need to generate a migration?
+> - What is the points queue topic name?
+
+**You**
+
+> The table already exists; no migration needed. The topic is `point-rollback-events`.
+
+**Agent**
+
+> Completed all 5 tasks above, all within `src/refund/`. Did not touch `src/payment/`.
+>
+> **Requires manual action**:
+> - Consumer side for `point-rollback-events` (on the points service side)
+> - Dead letter monitoring and alerting rule configuration
+>
+> Recommend running `/f2s-kb-feat` to sync this new capability into the knowledge base.
+
+---
+
+## Scenario 4: PDF Design -> Implementation
+
+**You**
+
+> /f2s-doc-pdf /Users/me/Downloads/marketing-coupon-v2.pdf
+
+**Agent**
+
+> Converted and saved as `.Knowledge/req-docs/marketing-coupon-v2.md`. Filled in the idempotency handling flow description and error code explanations that were missing in the PDF.
+
+**You**
+
+> Implement according to `.Knowledge/req-docs/marketing-coupon-v2.md`
+
+**Agent**
+
+> I have read the design document. Task list for implementation:
+>
+> 1. Create `CouponController` (coupon claim, redemption, and return endpoints)
+> 2. Create `CouponService` with inventory deduction and idempotency checks
+> 3. ...
+>
+> Before proceeding, I need to confirm: is the coupon inventory managed via Redis or database row locks?
+
+---
+
+## Scenario 5: Post-Implementation Knowledge Base Recording
+
+**You**
+
+> /f2s-kb-sync The refund feature has gone live. Help me record the payment failure retry queue naming, dead letter table fields, and monitoring alerting criteria into the knowledge base. Give me an outline first so I can confirm before you write.
+
+**Agent**
+
+> Knowledge base update outline (pending confirmation):
+>
+> **Update topic**: `order-service` (already exists)
+>
+> - Add "Payment Failure Retry Mechanism": queue name `payment-retry-queue`, max retries 3, intervals 30s / 120s / 300s
+> - Add "Dead Letter Table": table name `payment_dead_letter`, fields `order_id / error_code / retry_count / created_at`
+> - Add "Monitoring Criteria": alert threshold `retry_count >= 3`, notification channel DingTalk
+>
+> Confirm to write, or let me know what needs to be changed.
+
+**You**
+
+> Confirm, go ahead and write.
+
+**Agent**
+
+> Updated `.Knowledge/topics/order-service.md`. `manifest-routing` unchanged (topic already exists).
+
+---
+
+## Scenario 6: Non-compliant Implementation Found, Fix and Sync Knowledge Base
+
+**You**
+
+> /f2s-kb-fix `RefundService` directly calls `new RestTemplate()`, which violates the Spring Bean injection convention.
+
+**Agent**
+
+> Fixed: Line 34 of `RefundService.java` changed to constructor injection; `RefundConfig` supplemented with `@Bean` declaration.
+>
+> Knowledge base synced: the "HTTP Client Conventions" section in `.Knowledge/stock-docs/` has been updated, noting that `RestTemplate` must be injected as a Bean, and direct instantiation is prohibited.
+
+---
+
+## Scenario 7: Knowledge Base Conflicts After Git Merge
+
+**You**
+
+> /f2s-kb-merge `.Knowledge/index.md` and `.Knowledge/stock-docs/order-service-architecture-final.md` have conflict markers after the merge. I have already resolved the conflicts in the business code manually.
+
+**Agent**
+
+> Scanned the conflict markers in both files:
+>
+> - `index.md`: 2 conflicts, both in topic description fields. Took the HEAD version (newer content). Resolved automatically.
+> - `order-service-architecture-final.md`: 1 conflict. The "monitoring alert threshold" differs between branches (3 vs. 5). Please confirm which one to keep.
+
+**You**
+
+> Use 3.
+
+**Agent**
+
+> All conflict markers have been cleaned up per your confirmation. The files are ready to commit.
+
+---
+
+## Related Documentation
+
+- [Usage Guide](./usage-guide.en.md)
+- [Commands Reference](./commands-reference.en.md)
+- [Directory Conventions](./directory-conventions.en.md)
+- [Architecture](./architecture.en.md)

package/package.json

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

package/templates/knowledge/manifest-routing.json

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

package/templates/rules/f2s-task.mdc

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

package/templates/skills/f2s-ctx-build/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: f2s-ctx-build
 description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
+---
 
 > 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。
 

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 则注明）。