@double-codeing/flow2spec 3.0.8 → 3.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.en.md +114 -0
  2. package/README.md +78 -80
  3. package/docs/architecture.en.md +122 -0
  4. package/docs/commands-reference.en.md +605 -0
  5. package/docs/design-principles.en.md +592 -0
  6. package/docs/directory-conventions.en.md +49 -0
  7. package/docs/usage-guide.en.md +165 -0
  8. package/docs/usage-scenarios.en.md +222 -0
  9. package/package.json +1 -1
  10. package/templates/skills/f2s-ctx-build/SKILL.md +1 -0
package/README.en.md ADDED
@@ -0,0 +1,114 @@
1
+ # Flow2Spec — Let AI Always Know What You're Doing
2
+
3
+ > Cures the "amnesia" of Cursor / Claude Code — with one `init` command, AI
4
+ > remembers project context across sessions. No more re-explaining every time.
5
+ >
6
+ > 🌐 **[中文](./README.md)** · 中 / EN
7
+
8
+ 🎬 **[Live Demo (English)](https://lands-1203.github.io/Flow2Spec/en/)** | **[中文演示](https://lands-1203.github.io/Flow2Spec/)** (13-slide HTML PPT, `←` `→` to navigate, `S` for presenter mode)
9
+
10
+ 🔧 **Quick start**:
11
+
12
+ ```bash
13
+ npx @double-codeing/flow2spec@latest init
14
+ ```
15
+
16
+ ---
17
+
18
+ ## Before / After
19
+
20
+ The exact same request, two conversations:
21
+
22
+ ```
23
+ > Update the batch re-scoring of the review template library
24
+ ```
25
+
26
+ **Without Flow2Spec**:
27
+
28
+ ```
29
+ AI: Which module has this table?
30
+ AI: Is batchReScore sync or async?
31
+ AI: Is there a lock? What's the idempotency key?
32
+ AI: What's the response format? What's the error code?
33
+ AI: (Digging through 416 APIs, 796 files, 4.7 MB of source code…)
34
+ ```
35
+
36
+ Repeated introductions · Repeated code searches · Repeated mistakes
37
+
38
+ **With Flow2Spec**:
39
+
40
+ ```
41
+ [matcher hit] m-product-review-template-library
42
+ [loading deps] 4 topics · ~300 lines
43
+ AI: Known — fire-and-forget
44
+ Redis lock smp:product-review:template-library:batch-rescore:lock (TTL 10 min)
45
+ Max 100 items per batch · error code 101
46
+ AI: Starting implementation, 3 files affected.
47
+ ```
48
+
49
+ 4.7 MB → 300 lines · Pinpoint accuracy in seconds
50
+
51
+ ---
52
+
53
+ ## What Flow2Spec Does (3 Things)
54
+
55
+ **① Remembers project context across devices and sessions**
56
+ `.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant.
57
+
58
+ **② Routing manifest means AI doesn't dig through your repo**
59
+ Each task hits 1–4 topics, ~300 lines. Business constraints — Redis lock keys, error codes, batch limits — are all in the topics. AI doesn't have to guess from source code.
60
+
61
+ **③ f2s-* skills update knowledge as you code**
62
+ `/f2s-kb-feat` writes topics while writing features, `/f2s-kb-fix` corrects topics while fixing bugs, `/f2s-git-commit` checks topic coverage before committing. Changing code == updating knowledge. No separate "documentation maintenance."
63
+
64
+ ---
65
+
66
+ ## Getting Started
67
+
68
+ **Minimum viable setup is an empty skeleton.**
69
+
70
+ ```bash
71
+ npx @double-codeing/flow2spec@latest init
72
+ ```
73
+
74
+ 1 minute generates the directory structure + routing config. Empty, ready to use. **Next requirement hits whichever area → you document that area.** No upfront investment needed.
75
+
76
+ Real data from a production repo running for 3 months:
77
+
78
+ | Metric | Value |
79
+ |---|---|
80
+ | Public APIs | 416 |
81
+ | Source code | 796 files / 4.7 MB / ~100K lines |
82
+ | Flow2Spec per-task load | **≈ 300 lines** (99% noise removed) |
83
+
84
+ ---
85
+
86
+ ## When NOT to Use
87
+
88
+ - **One-off scripts** — throwaway code is faster with a few Markdown files for AI context
89
+ - **Solo small projects** — a single CLAUDE.md is enough; routing overhead > benefits
90
+ - **Team won't maintain .Knowledge/** — tools can't replace discipline
91
+
92
+ ---
93
+
94
+ ## Documentation
95
+
96
+ ### English
97
+ - [Usage Guide](./docs/usage-guide.en.md) — skill chains, config details
98
+ - [Commands Reference](./docs/commands-reference.en.md) — all f2s-* command reference
99
+ - [Directory Conventions](./docs/directory-conventions.en.md)
100
+ - [Architecture & Principles](./docs/architecture.en.md)
101
+ - [Usage Scenarios](./docs/usage-scenarios.en.md)
102
+ - [Design Principles](./docs/design-principles.en.md)
103
+
104
+ ### 中文
105
+ - [使用说明](./docs/Flow2Spec使用说明.md)
106
+ - [命令说明](./docs/README-命令说明.md)
107
+ - [目录与路径约定](./docs/README-目录与路径约定.md)
108
+ - [体系与原理](./docs/README-体系与原理.md)
109
+ - [使用案例·模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
110
+ - [设计说明](./docs/Flow2Spec-设计说明.md)
111
+
112
+ ## License
113
+
114
+ MIT. Copyright © 2026 兰涛
package/README.md CHANGED
@@ -1,117 +1,115 @@
1
- # Flow2Spec
1
+ # Flow2Spec — 让 AI 一直知道你在做什么
2
2
 
3
- Flow2Spec 用于在业务仓库初始化一套可持续的 AI 协作结构：
4
-
5
- - **业务知识文档**统一在 `.Knowledge/`
6
- - **规则与技能能力**保留在各 agent 配置根（`.cursor/`、`.claude/`、`.codex/`）
7
-
8
- 集中管理项目知识，同时不破坏各工具原生的 rules/skills 加载机制。
9
-
10
- > 🎬 **在线演示**：组内分享用的 13 页 HTML PPT（脱敏版）——**<https://lands-1203.github.io/Flow2Spec/>**
11
- > `←` `→` 翻页，`S` 打开演讲者模式。源文件见 [presentations/flow2spec-intro-public/](./presentations/flow2spec-intro-public/)。
3
+ > 解决 Cursor / Claude Code 的「失忆症」——用一个命令初始化，让 AI
4
+ > 跨会话记住项目上下文，不用每轮重新交代。
5
+ >
6
+ > 🌐 **[English](./README.en.md)** · 中 / EN
12
7
 
13
- ---
8
+ 🎬 **[在线演示(中文)](https://lands-1203.github.io/Flow2Spec/)** | **[English Demo](https://lands-1203.github.io/Flow2Spec/en/)**（13 页 HTML PPT，`←` `→` 翻页，`S` 演讲者模式）
14
9
 
15
- ## 快速开始
10
+ 🔧 **快速体验**：
16
11
 
17
12
  ```bash
18
13
  npx @double-codeing/flow2spec@latest init
19
- npx @double-codeing/flow2spec@latest init cursor claude codex
20
14
  ```
21
15
 
22
- 可选：全局安装 CLI 后，可在仓库根直接使用 `flow2spec init …`（与上文等价）：
16
+ ---
23
17
 
24
- ```bash
25
- npm install -g @double-codeing/flow2spec@latest
26
- ```
18
+ ## Before / After
27
19
 
28
- `init` 完成后的目录结构：
20
+ 同样一句话，两段对话：
29
21
 
30
- | 路径 | 用途 |
31
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
32
- | `.Knowledge/stock-docs/` | 架构说明、终稿等沉淀文档 |
33
- | `.Knowledge/req-docs/` | 需求澄清与技术方案 |
34
- | `.Knowledge/topics/` | 主题路由摘要 |
35
- | `.Knowledge/template/` | 终稿与技术方案模板 |
36
- | `.Knowledge/manifest-routing.json` + `matchers/` | 机器可读路由与关键词索引 |
37
- | `配置根/rules/` + `配置根/skills/` | 各工具规则与技能入口 |
38
- | `flow2spec.config.json` | 控制 `subAgent`、`switchAgentVerification`、`changeTracking`（各技能独立子项），默认均为 `false` |
22
+ ```
23
+ > 改一下评价模板文案库的批量重评分
24
+ ```
39
25
 
40
- > `init` 只做结构与模板补齐，业务文档内容由 `f2s-*` 技能维护。详见 [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)。
26
+ **没有 Flow2Spec**：
41
27
 
42
- 包升级后可在业务仓库用 **`/f2s-kb-upgrade`** 对齐知识库模板与路由；细则见 [使用说明](./docs/Flow2Spec使用说明.md)。
28
+ ```
29
+ AI: 这个模块的表在哪？
30
+ AI: batchReScore 是同步还是异步？
31
+ AI: 有没有锁？幂等键是什么？
32
+ AI: 返回格式是什么？错误码是多少？
33
+ AI: （翻遍 416 个接口、796 份文件、4.7 MB 源码…）
34
+ ```
35
+ 反复介绍 · 反复翻代码 · 反复踩坑
43
36
 
44
- ---
37
+ **有 Flow2Spec**：
45
38
 
46
- ## 工作流全景
39
+ ```
40
+ [matcher 命中] m-product-review-template-library
41
+ [加载依赖] 4 个 topic · 约 300 行
42
+ AI: 已知 — fire-and-forget
43
+ Redis 锁 smp:product-review:template-library:batch-rescore:lock（TTL 10 分钟）
44
+ 单次最多 100 条 · 错误码 101
45
+ AI: 开始改，预计 3 处文件。
46
+ ```
47
+ 4.7 MB → 300 行 · 秒级定位到硬约束
47
48
 
48
- 所有技能均以 `f2s-*` 前缀或主题名在 Agent 内触发。以下按**业务场景**分组，标明推荐执行链路与前置条件。
49
+ ---
49
50
 
50
- > **前置要求**：涉及「旧库迁移」或「包模板对齐」时，需先在本地安装最新 CLI：
51
- >
52
- > ```bash
53
- > npm install -g @double-codeing/flow2spec@latest
54
- > ```
55
- >
56
- > 其余场景以仓库内已初始化的规则与技能为准。
51
+ ## Flow2Spec 做三件事
57
52
 
58
- ### 一、需求交付链路
53
+ **① 跨设备会话记住项目上下文**
54
+ `.Knowledge/` 结构化知识库：路由清单（manifest-routing.json）+ 关键词索引（matchers）+ 主题分片（topics）。AI
55
+ 启动时只读该读的。
59
56
 
60
- 从 PRD 到代码落地的完整路径。
57
+ **② 路由清单让 AI 不翻仓库，只拿该拿的**
58
+ 每次需求命中 1~4 个 topic，约 300 行。业务的硬约束——锁的 key、错误码、上限——都在
59
+ topic 里，AI 不用从源码猜。
61
60
 
62
- > **任务清单控制**：`f2s-req-plan` **强制**创建任务清单；`f2s-implement-tech-design` 是否使用任务清单取决于 `changeTracking.implement` 配置。
61
+ **③ f2s-* 技能改代码顺手更新知识**
62
+ `/f2s-kb-feat` 写功能时同步写 topic，`/f2s-kb-fix` 修 bug 时更正 topic，
63
+ `/f2s-git-commit` 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。
63
64
 
64
- | 场景 | 执行链 | 产出 |
65
- | ------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------- |
66
- | 有 PRD，需澄清后出方案并落地 | `f2s-req-clarify` → `f2s-req-backend` → `f2s-implement-tech-design` → `f2s-kb-feat` | 澄清纪要 → 技术方案 → 实现+知识库 |
67
- | 已有方案，需强制任务清单后实现 | `f2s-req-plan`
68
- | 可确认任务清单与实现编排 |
65
+ ---
69
66
 
70
- ### 二、知识沉淀链路
67
+ ## 上手成本
71
68
 
72
- 将非结构化信息（口述、草稿、外部文档、代码）转化为可检索的知识资产。
69
+ **最小可用集是一个空骨架。**
73
70
 
74
- | 场景 | 执行链 | 产出 |
75
- | ----------------- | -------------------------------------------------- | ------------------------------ |
76
- | 从口述/草稿到终稿 | `f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build` | 架构初稿 → 规范终稿 → 主题路由 |
77
- | 外部文档转知识库 | `f2s-doc-final` → `f2s-ctx-build` | 可检索 Markdown + 路由索引 |
78
- | 存量代码/散稿补录 | `f2s-doc-add` 或 `f2s-kb-sync` | 自动提取能力 → 主题索引 |
71
+ ```bash
72
+ npx @double-codeing/flow2spec@latest init
73
+ ```
79
74
 
80
- ### 三、日常协作
75
+ 1 分钟生成目录结构 + 路由配置，空的，直接跑。**下次需求命中哪块，写哪块**，不提前建设。
81
76
 
82
- 缺陷修复、迭代与上下文同步。
77
+ 真实仓库跑了三个月的数据：
83
78
 
84
- | 场景 | 技能 |
85
- | -------------- | -------------- |
86
- | 修复缺陷 | `f2s-kb-fix` |
87
- | 新增功能 | `f2s-kb-feat` |
88
- | 同步已实现能力 | `f2s-kb-sync` |
89
- | 解决合并冲突 | `f2s-kb-merge` |
79
+ | 指标 | 数值 |
80
+ |---|---|
81
+ | 对外接口数 | 416 |
82
+ | 源码体积 | 796 文件 / 4.7 MB / ~10 万行 |
83
+ | Flow2Spec 每次加载 | **≈ 300 行**（噪声切掉 99%） |
90
84
 
91
- ### 四、仓库治理
85
+ ---
92
86
 
93
- 一次性或周期性的结构化维护。
87
+ ## 什么时候别用
94
88
 
95
- | 场景 | 技能 | 注意事项 |
96
- | -------------------------------------------- | ---------------- | ------------------ |
97
- | 旧版迁移（rules/skills 散稿 → `.Knowledge`） | `f2s-kb-migrate` | 一次性；执行前备份 |
98
- | 模板对齐（包升级后同步） | `f2s-kb-upgrade` | 可重复执行 |
89
+ - **一次性脚本** — 写完就删的东西，直接丢几个 Markdown 给 AI 更快
90
+ - **单人小项目** — 一份 CLAUDE.md 就够，路由和分片的开销大于收益
91
+ - **团队不愿同步 .Knowledge/** — 工具不能替代纪律
99
92
 
100
93
  ---
101
94
 
102
- ## 关键原则
95
+ ## 详细文档
103
96
 
104
- 1. `.Knowledge/` 只放业务文档与索引，不放规则执行文件。
105
- 2. `rules/` `skills/` 始终在配置根，保证 Claude/Cursor/Codex 按各自方式加载。
106
- 3. Codex 不读取 `rules/` 目录，通过 `.codex/AGENTS.md` + `skills/ + .codex/topics/*.md`承载约束入口。
97
+ ### 中文
98
+ - [使用说明](./docs/Flow2Spec使用说明.md) — 技能链、配置详解
99
+ - [命令说明](./docs/README-命令说明.md) — 所有 f2s-* 命令速查
100
+ - [目录与路径约定](./docs/README-目录与路径约定.md)
101
+ - [体系与原理](./docs/README-体系与原理.md)
102
+ - [使用案例·模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
103
+ - [设计说明](./docs/Flow2Spec-设计说明.md)
107
104
 
108
- ---
105
+ ### English
106
+ - [Usage Guide](./docs/usage-guide.en.md)
107
+ - [Commands Reference](./docs/commands-reference.en.md)
108
+ - [Directory Conventions](./docs/directory-conventions.en.md)
109
+ - [Architecture & Principles](./docs/architecture.en.md)
110
+ - [Usage Scenarios](./docs/usage-scenarios.en.md)
111
+ - [Design Principles](./docs/design-principles.en.md)
109
112
 
110
- ## 文档导航
113
+ ## 协议
111
114
 
112
- - [Flow2Spec使用说明](./docs/Flow2Spec使用说明.md)
113
- - [README-命令说明](./docs/README-命令说明.md)
114
- - [README-目录与路径约定](./docs/README-目录与路径约定.md)
115
- - [README-体系与原理](./docs/README-体系与原理.md)
116
- - [Flow2Spec-使用案例-模拟对话](./docs/Flow2Spec-使用案例-模拟对话.md)
117
- - [Flow2Spec-设计说明](./docs/Flow2Spec-设计说明.md)
115
+ MIT. Copyright © 2026 兰涛
package/docs/architecture.en.md ADDED
@@ -0,0 +1,122 @@
1
+ [中文](./README-体系与原理.md) | [English](./architecture.en.md)
2
+
3
+ # Architecture & Principles
4
+
5
+ Flow2Spec's goal is to separate "business knowledge curation" from "Agent capability loading":
6
+
7
+ - **Knowledge layer**: `.Knowledge` (documents and index)
8
+ - **Execution layer**: config root `rules/skills` (natively loaded by each tool)
9
+
10
+ ---
11
+
12
+ ## 1. Two-Layer Structure
13
+
14
+ | Layer | Location | Role |
15
+ | --- | --- | --- |
16
+ | Knowledge layer | `.Knowledge/` | Stores business documents, index, routing |
17
+ | Execution layer | `.cursor/.claude/.codex` | Stores rules and skill entry points |
18
+
19
+ ---
20
+
21
+ ## 2. Progressive Reading
22
+
23
+ The recommended unified order:
24
+
25
+ 1. `.Knowledge/manifest-routing.json`
26
+ 2. `.Knowledge/matchers/<matcher>.json` (on demand: directly located by `manifest-routing.taskToTopicRules[].matcherPath`)
27
+ 3. `.Knowledge/index.md`
28
+ 4. The matched `stock-docs` / `req-docs` documents
29
+ 5. Source code drill-down when necessary
30
+
31
+ After reading, execute the four-step pipeline `match -> expand -> verify -> act`: expand dependency topics after hitting the primary candidate, perform gap analysis, execute only when confidence is sufficient; clarify first when confidence is low.
32
+
33
+ Simultaneously, loading behavior is governed by the config root entry points (Flow2Spec package rules: `f2s-flow2spec-unified-entry.mdc` / `f2s-flow2spec-unified-entry.md`; legacy business repos commonly use `main.md(c)`; and `AGENTS.md`).
34
+ Codex does not read the `rules/` directory; execution constraints are carried through `.codex/AGENTS.md` + `skills/`.
35
+
36
+ ---
37
+
38
+ ## 3. Key Chains
39
+
40
+ - Documentation curation chain: `f2s-doc-arch` -> `f2s-doc-final` -> `f2s-ctx-build`
41
+ - Implementation chain: `.Knowledge/req-docs/*.md` -> `implement-tech-design` -> code
42
+ - Maintenance chain: `f2s-kb-fix` / `f2s-kb-feat` / `f2s-kb-sync` / `f2s-kb-merge`
43
+ - Requirements planning chain: `f2s-req-plan` (planning + implementation, always creates task checklist)
44
+ - Change tracking chain: `changeTracking.*` config -> `f2s-task` rules (automatic) -> `.task/` task checklist -> cross-session continuation
45
+ - Package template/routing shape alignment with config root: `f2s-kb-upgrade` (**do not** equate running `flow2spec init` alone with "knowledge base upgrade"); migrate legacy repo structure into `.Knowledge`: `f2s-kb-migrate`
46
+
47
+ ---
48
+
49
+ ## 4. Agent Execution Model
50
+
51
+ Flow2Spec controls execution behavior through two fields in the project root `flow2spec.config.json`: `subAgent` and `switchAgentVerification`.
52
+
53
+ **How the Agent reads the above truth values**: multi-end prompts + **Read** as authority, see [usage-guide.en.md § 1 (the only detailed table)](./usage-guide.en.md); design summary see [design-principles.en.md § 4, 5.1](./design-principles.en.md).
54
+
55
+ ### 4.1 Primary/Sub Agent Responsibility Division Principle
56
+
57
+ **`subAgent: false` (default)**: All `f2s-*` skills execute sequentially within the primary agent, no parallel decomposition.
58
+
59
+ **`subAgent: true`**: When the scale threshold agreed upon in the skill body is reached, sub-agents may be spawned for parallel processing. Responsibility boundaries are as follows:
60
+
61
+ | Role | Responsibility Boundary |
62
+ |------|----------|
63
+ | Primary agent | Overall planning, determining task granularity and allocation strategy, aggregating sub-agent output, verifying cross-unit consistency, final write-to-disk |
64
+ | Sub agent | Processes the assigned unit (module/document/topic), outputs results in the agreed format, does not make cross-unit decisions |
65
+
66
+ The decomposition boundaries for sub-agents are progressively defined by each `f2s-*` skill body (e.g., thresholds for module count, document count, code line count). **There is currently no unified stage table at the template layer**; the skill body takes precedence.
67
+
68
+ ### 4.2 Verification Ownership Principle
69
+
70
+ **Default (whoever writes to disk verifies)**: Verification after write-to-disk or changes is performed within the agent that wrote to disk. If a sub-agent wrote, the sub-agent self-verifies; if the primary agent wrote, the primary agent self-verifies.
71
+
72
+ **Cross-verification (`switchAgentVerification: true`)**: The counterpart agent bears the verification responsibility, suitable for scenarios requiring higher confidence. The enabling conditions must be **satisfied simultaneously**:
73
+
74
+ 1. Configuration `switchAgentVerification: true`
75
+ 2. The currently executing `f2s-*` skill body **explicitly states** that the step depends on this field
76
+
77
+ Cross-verification rules:
78
+
79
+ | Writer | Verifier | Prerequisite |
80
+ |--------|--------|----------|
81
+ | Sub-agent writes | Primary agent verifies | No additional conditions |
82
+ | Primary agent writes | Sub-agent verifies | Requires `subAgent: true` and that sub-tasks have actually been decomposed; otherwise, the primary agent self-verifies |
83
+
84
+ Design intent: Cross-verification introduces an external perspective, reducing the blind spots in the writer's self-verification, but increases execution overhead. It is therefore an explicit opt-in rather than the default behavior.
85
+
86
+ ### 4.3 Change Tracking (changeTracking)
87
+
88
+ `changeTracking` is a third dimension independent of `subAgent` / `switchAgentVerification`. It controls whether the skill automatically creates a task checklist that can be continued across sessions during execution.
89
+
90
+ ```json
91
+ {
92
+ "changeTracking": {
93
+ "feat": false,
94
+ "fix": false,
95
+ "implement": false
96
+ }
97
+ }
98
+ ```
99
+
100
+ - Each skill sub-item is independently controlled and does not affect each other
101
+ - When enabled: automatically checks `.task/todo.json` before skill execution, creates or resumes tasks; automatically archives upon completion
102
+ - Cross-session: when a new session describes related content, the `f2s-task` rule (`alwaysApply`) loads the remaining checklist and corresponding skill context after keyword matching
103
+ - `f2s-req-plan` is not constrained by this configuration and always creates a task checklist
104
+
105
+ ---
106
+
107
+ ## 5. Design Benefits
108
+
109
+ 1. Share the same business knowledge source across tools
110
+ 2. Does not break the rule loading conventions of Claude/Cursor/Codex
111
+ 3. Controls task routing and dependencies via `manifest-routing` + `matcherPath` shards (`matchers/*.json`), reducing misreading and full scans
112
+ 4. Clear primary/sub-agent responsibility boundaries: the primary agent always holds the global view, sub-agents focus on unit processing, consistency is ensured by the primary agent
113
+ 5. Configurable verification ownership: default self-verification by the writer keeps overhead low; cross-verification can be enabled on demand to boost confidence in critical scenarios
114
+
115
+ ---
116
+
117
+ ## 6. Related Documents
118
+
119
+ - [Usage Guide](./usage-guide.en.md)
120
+ - [Commands Reference](./commands-reference.en.md)
121
+ - [Directory Conventions](./directory-conventions.en.md)
122
+ - [Usage Scenarios](./usage-scenarios.en.md)