Flow2Spec: Skill for Claude Code

执行口径：本技能只维护 .Knowledge，默认不改配置根 rules/skills。

KB 自动合并协议（必须）

本技能不得把“人工执行命令”作为用户流程。用户确认同步大纲后，由 agent 自己完成知识候选生成、合并、构建与校验：

1. 将已确认的大纲转换为一个或多个 kb-delta 草稿，记录 taskId、developerId、baseRevisions、changes 与证据摘要；没有显式任务目录时可在内存中形成等价对象，不强制为了本技能创建 .task。changes 可使用 appendBody / replaceBody / updateFrontmatter；确需新主题时使用 createTopic，并可携带 taskRule 与 matcher 让路由一并接入。
2. 写入 .Knowledge 前，必须用 flow2spec kb plan <delta> 或等价内部能力预演；若 topic revision 不一致，停止自动写入，转入语义合并说明。
3. 可自动合并时，由 agent 调用 flow2spec kb apply <delta> 或等价内部能力写入 topic，并随后执行 flow2spec kb build 与 flow2spec kb check。
4. 用户只看到“知识库已同步 / 有语义冲突需确认 / 已跳过入库及原因”，不要求用户手动执行 kb plan/apply/build/check。

编排（主 / 子 agent）

• 两字段（subAgent / switchAgentVerification）语义以统一入口为唯一事实源：Cursor/Claude 读配置根 rules/f2s-flow2spec-unified-entry.*；Codex 读 .codex/topics/f2s-flow2spec-unified-entry.md（与上同源，flow2spec init 镜像）。
• 步骤 1（素材汇总）：subAgent=true 时可拆子并行，仅只读汇总，不得落盘。
• 步骤 2（大纲 + 用户确认）：必主 agent 完成，确认权不可下放子 agent。
• 步骤 3（落盘）：subAgent=true 时可按已确认大纲拆子逐项落盘；硬约束：子落盘前必须前置加载近邻 2–3 个主题的开头摘要，做叙事风格对齐。
• 写权硬约束：manifest-routing.json 与 .Knowledge/index.md 恒由主 agent 单点落盘，禁止下放。
• 校验：默认落盘侧 agent 自验；本 SKILL 不绑定交叉校验。

f2s-kb-sync（先大纲后写入）

输入（可选）

1. 用户显式给出“已实现能力列表”
2. 零输入：由 Agent 基于当前上下文推断
3. 辅助材料：@ 文件、需求文档、架构说明等

强制流程（不可颠倒）

步骤 1：收集素材（只读）

• 汇总用户目标、范围、优先级
• 汇总已实现能力（用户指定 + Agent 推断）
• 对照现有知识库：
  • .Knowledge/topics/
  • .Knowledge/index.md
  • .Knowledge/manifest-routing.json
  • .Knowledge/matchers/*.json（与路由中 matcherPath 对应的分片）
  • .Knowledge/stock-docs/
• 主题粒度扫描：对已有 topic 粗扫以下信号，命中时在步骤 2 大纲中列为"建议拆分"（不阻断同步流程）：
  • 对应 stock-doc 超过 300–500 行；
  • includeAny 词数超过 12 个；
  • topic 正文包含超过 3 个不相干职责域的二级标题。

步骤 2：输出《更新大纲》（必须）

大纲采用 3 段主体 + 折叠详情结构，让用户一眼看清"入哪 / 改什么 / 不入哪"，细节按需展开。目标是信号密度高、视觉焦点在决策点（Issue #38）。

输出骨架（Agent 按此结构填充实际内容）：

## 知识库同步大纲

### 📥 入库
- `<topicId>`：<一句话说明改了什么>（→ `.Knowledge/topics/<topic>.md`）
- **新建** `<topicId>`：<能力概述>（→ 新增 topic + matcher + 路由条目）

### 🚫 不入库
- <能力/变更>：<一句话原因>（如"仅代码重构无新语义 / 属于 fix 已在其他 topic 覆盖 / 与既有 topic 重复"）

### 是否继续？(y/n)

<details>
<summary>展开查看详情</summary>

**拟改文件**：
- `.Knowledge/topics/<topic>.md`
- `.Knowledge/index.md`
- `.Knowledge/manifest-routing.json`
- `.Knowledge/matchers/<id>.json`

**主题元数据**（如有）：
- `<topicId>`：primary=`<type>`，tags=`[...]`，confidence=`<manual|inferred>`

**终稿沉淀**（如需）：
- 待生成 `stock-docs/<能力名>_终稿.md`（来源：`req-docs/<方案>.md` + 已实现代码 + 澄清文档）
  依据见 `rules/f2s-topic-authoring.*`「长文背景引用的目录边界（硬约束）」。

**信息来源**：<用户指定 / Agent 推断 / git diff / 目录扫描>

**不改动范围**：<列出本次刻意跳过的项与原因>

</details>