🎩 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
2
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.2.8-beta.1
 to
3.2.8
+91
assets/readme/hero-zh.svg
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="420" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
<title id="title">Flow2Spec 在修改代码前加载正确项目事实</title>
<desc id="desc">静态产品首屏图，展示 Flow2Spec 把自然语言需求路由到 AI 修改代码前需要读取的少量项目事实。</desc>
<defs>
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#05070B"/>
<stop offset="0.52" stop-color="#08111D"/>
<stop offset="1" stop-color="#111827"/>
</linearGradient>
<linearGradient id="card" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#111C2D"/>
<stop offset="1" stop-color="#07111C"/>
</linearGradient>
<linearGradient id="line" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#22D3EE"/>
<stop offset="0.62" stop-color="#67E8F9"/>
<stop offset="1" stop-color="#F59E0B"/>
</linearGradient>
<radialGradient id="halo" cx="42%" cy="38%" r="62%">
<stop offset="0" stop-color="#22D3EE" stop-opacity="0.22"/>
<stop offset="1" stop-color="#22D3EE" stop-opacity="0"/>
</radialGradient>
<pattern id="dots" width="28" height="28" patternUnits="userSpaceOnUse">
<circle cx="1" cy="1" r="1" fill="#233247" opacity="0.55"/>
</pattern>
<clipPath id="clip">
<rect width="1200" height="420" rx="34"/>
</clipPath>
</defs>
<g clip-path="url(#clip)">
<rect width="1200" height="420" fill="url(#bg)"/>
<rect x="30" y="30" width="1140" height="360" rx="30" fill="url(#dots)" opacity="0.58"/>
<circle cx="250" cy="126" r="230" fill="url(#halo)"/>
<path d="M78 300C244 238 378 258 522 210C676 158 764 82 1088 96" fill="none" stroke="#38BDF8" stroke-width="2" opacity="0.14"/>
<path d="M616 296C746 248 860 260 1088 210" fill="none" stroke="#F59E0B" stroke-width="2" opacity="0.12"/>
</g>
<g id="title-block" transform="translate(76 70)">
<text x="0" y="0" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17" letter-spacing="2.8">AI CODING CONTEXT ENGINE</text>
<text x="0" y="76" fill="#F8FAFC" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="76" font-weight="860">Flow2Spec</text>
<text x="2" y="123" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="29" font-weight="720">让 AI 动手前先读到正确事实。</text>
<text x="2" y="162" fill="#9FB3C8" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="21">把自然语言需求转换成 AI 应该先读的事实，</text>
<text x="2" y="192" fill="#9FB3C8" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="21">再进入代码修改。</text>
<g id="install-chip" transform="translate(0 236)">
<rect width="408" height="52" rx="18" fill="#08111D" stroke="#26364C"/>
<circle cx="26" cy="26" r="6" fill="#22D3EE"/>
<text x="46" y="32" fill="#D8E2EE" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">npx @double-codeing/flow2spec init</text>
</g>
</g>
<g id="context-receipt" transform="translate(658 58)">
<rect width="470" height="288" rx="28" fill="url(#card)" stroke="#2A3B55"/>
<rect x="18" y="18" width="434" height="252" rx="20" fill="#060D18" stroke="#1F2F46"/>
<circle cx="44" cy="42" r="6" fill="#F87171"/>
<circle cx="66" cy="42" r="6" fill="#FBBF24"/>
<circle cx="88" cy="42" r="6" fill="#34D399"/>
<text x="116" y="49" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, Microsoft YaHei, sans-serif" font-size="22" font-weight="760">改代码前，先加载事实</text>
<g id="receipt-lines" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17">
<text x="42" y="92" fill="#64748B">用户需求</text>
<text x="174" y="92" fill="#F8FAFC">"修复批量重评分"</text>
<text x="42" y="128" fill="#64748B">Flow2Spec</text>
<text x="174" y="128" fill="#67E8F9">命中对应 matcher</text>
<text x="42" y="164" fill="#64748B">AI 读取</text>
<text x="174" y="164" fill="#F8FAFC">4 topics · ~300 lines</text>
<text x="42" y="200" fill="#64748B">硬事实</text>
<text x="174" y="200" fill="#FDBA74">Redis lock · TTL 10 min</text>
</g>
<g id="context-pills" transform="translate(42 226)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14" font-weight="700">
<rect width="112" height="30" rx="15" fill="#082F49" stroke="#0EA5E9"/>
<text x="18" y="20" fill="#BAE6FD">.Knowledge</text>
<g transform="translate(130 0)">
<rect width="92" height="30" rx="15" fill="#0B1828" stroke="#38BDF8"/>
<text x="18" y="20" fill="#BAE6FD">topics</text>
</g>
<g transform="translate(240 0)">
<rect width="110" height="30" rx="15" fill="#1A1410" stroke="#F59E0B"/>
<text x="18" y="20" fill="#FEF3C7">f2s skills</text>
</g>
</g>
</g>
<g id="compression-bar" transform="translate(650 365)">
<text x="0" y="0" fill="#94A3B8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">4.7 MB project source</text>
<path d="M206 -5H350" stroke="url(#line)" stroke-width="5" stroke-linecap="round"/>
<text x="372" y="0" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16" font-weight="700">~300 lines loaded</text>
</g>
</svg> 
+91
assets/readme/hero.svg
<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="420" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
<title id="title">Flow2Spec loads the right project facts before code edits</title>
<desc id="desc">A static product hero showing Flow2Spec routing a natural language request to the few project facts an agent needs before editing code.</desc>
<defs>
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#05070B"/>
<stop offset="0.52" stop-color="#08111D"/>
<stop offset="1" stop-color="#111827"/>
</linearGradient>
<linearGradient id="card" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#111C2D"/>
<stop offset="1" stop-color="#07111C"/>
</linearGradient>
<linearGradient id="line" x1="0" y1="0" x2="1" y2="0">
<stop offset="0" stop-color="#22D3EE"/>
<stop offset="0.62" stop-color="#67E8F9"/>
<stop offset="1" stop-color="#F59E0B"/>
</linearGradient>
<radialGradient id="halo" cx="42%" cy="38%" r="62%">
<stop offset="0" stop-color="#22D3EE" stop-opacity="0.22"/>
<stop offset="1" stop-color="#22D3EE" stop-opacity="0"/>
</radialGradient>
<pattern id="dots" width="28" height="28" patternUnits="userSpaceOnUse">
<circle cx="1" cy="1" r="1" fill="#233247" opacity="0.55"/>
</pattern>
<clipPath id="clip">
<rect width="1200" height="420" rx="34"/>
</clipPath>
</defs>
<g clip-path="url(#clip)">
<rect width="1200" height="420" fill="url(#bg)"/>
<rect x="30" y="30" width="1140" height="360" rx="30" fill="url(#dots)" opacity="0.58"/>
<circle cx="250" cy="126" r="230" fill="url(#halo)"/>
<path d="M78 300C244 238 378 258 522 210C676 158 764 82 1088 96" fill="none" stroke="#38BDF8" stroke-width="2" opacity="0.14"/>
<path d="M616 296C746 248 860 260 1088 210" fill="none" stroke="#F59E0B" stroke-width="2" opacity="0.12"/>
</g>
<g id="title-block" transform="translate(76 70)">
<text x="0" y="0" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17" letter-spacing="2.8">AI CODING CONTEXT ENGINE</text>
<text x="0" y="76" fill="#F8FAFC" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="76" font-weight="860">Flow2Spec</text>
<text x="2" y="123" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="29" font-weight="720">Project facts before code edits.</text>
<text x="2" y="162" fill="#9FB3C8" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="21">Turn a natural-language request into the facts</text>
<text x="2" y="192" fill="#9FB3C8" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="21">the agent should read before it edits.</text>
<g id="install-chip" transform="translate(0 236)">
<rect width="408" height="52" rx="18" fill="#08111D" stroke="#26364C"/>
<circle cx="26" cy="26" r="6" fill="#22D3EE"/>
<text x="46" y="32" fill="#D8E2EE" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">npx @double-codeing/flow2spec init</text>
</g>
</g>
<g id="context-receipt" transform="translate(658 58)">
<rect width="470" height="288" rx="28" fill="url(#card)" stroke="#2A3B55"/>
<rect x="18" y="18" width="434" height="252" rx="20" fill="#060D18" stroke="#1F2F46"/>
<circle cx="44" cy="42" r="6" fill="#F87171"/>
<circle cx="66" cy="42" r="6" fill="#FBBF24"/>
<circle cx="88" cy="42" r="6" fill="#34D399"/>
<text x="116" y="49" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="760">Before editing, load facts</text>
<g id="receipt-lines" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="17">
<text x="42" y="92" fill="#64748B">user asks</text>
<text x="174" y="92" fill="#F8FAFC">"fix batch re-score"</text>
<text x="42" y="128" fill="#64748B">Flow2Spec</text>
<text x="174" y="128" fill="#67E8F9">routes to the right matcher</text>
<text x="42" y="164" fill="#64748B">agent reads</text>
<text x="174" y="164" fill="#F8FAFC">4 topics · ~300 lines</text>
<text x="42" y="200" fill="#64748B">hard facts</text>
<text x="174" y="200" fill="#FDBA74">Redis lock · TTL 10 min</text>
</g>
<g id="context-pills" transform="translate(42 226)" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14" font-weight="700">
<rect width="112" height="30" rx="15" fill="#082F49" stroke="#0EA5E9"/>
<text x="18" y="20" fill="#BAE6FD">.Knowledge</text>
<g transform="translate(130 0)">
<rect width="92" height="30" rx="15" fill="#0B1828" stroke="#38BDF8"/>
<text x="18" y="20" fill="#BAE6FD">topics</text>
</g>
<g transform="translate(240 0)">
<rect width="110" height="30" rx="15" fill="#1A1410" stroke="#F59E0B"/>
<text x="18" y="20" fill="#FEF3C7">f2s skills</text>
</g>
</g>
</g>
<g id="compression-bar" transform="translate(650 365)">
<text x="0" y="0" fill="#94A3B8" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">4.7 MB project source</text>
<path d="M206 -5H350" stroke="url(#line)" stroke-width="5" stroke-linecap="round"/>
<text x="372" y="0" fill="#67E8F9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16" font-weight="700">~300 lines loaded</text>
</g>
</svg> 
+107
-22
lib/developerId.js

@@ -6,12 +6,23 @@ /**

* 1. flow2spec.config.json → collaboration.developerId
* - 非空但 sanitize 后为空（如纯中文、纯符号）：抛错，让用户显式修正配置。
* - 显式配置视为「用户明确表达了隔离意图」，不做静默降级。
* 2. git user.email（@ 前）或 user.name，规范化
* - 若规范化失败（如纯中文邮箱前缀 / 用户名），走 hash 兜底：
* 基于原始字符串 sha256 前 8 位生成 `dev-xxxxxxxx`，同时在 warnings 中提示。
* 这样避免中文用户被静默塞回 legacy 单根。
* 3. 都没有 → null（调用方使用 legacy `.task/` 根）
*
* collaboration.enabled === false 时强制 legacy（返回 null）。
*
* 需要「是否隔离 / 是否 legacy」语义的调用方**请用 resolveDeveloperContext**；
* taskRootFor 只做拼路径，不看 enabled 开关，仅供内部/外部工具在已确定 id 的
* 情形下拼路径。
*/
const { execFileSync } = require("child_process");
const crypto = require("crypto");
const path = require("path");
const TASK_DIR = ".task";
const HASH_FALLBACK_PREFIX = "dev-";

@@ -35,3 +46,2 @@ /**

if (s.length < 1 || s.length > 64) return null;
// 禁止纯数字或易混通用名作为「看起来像配置」的默认（仍允许 git 推出的合法 id）
return s;

@@ -41,2 +51,17 @@ }

/**
* 基于原始字符串生成稳定的 hash 兜底 id，例如 `dev-a1b2c3d4`。
* 用于 git identity 存在但 sanitize 失败（如纯中文）的情况，
* 保证隔离仍然按人生效、跨机器一致。
* @param {string} raw
* @returns {string|null}
*/
function hashDeveloperId(raw) {
if (raw == null) return null;
const trimmed = String(raw).trim();
if (!trimmed) return null;
const digest = crypto.createHash("sha256").update(trimmed).digest("hex");
return `${HASH_FALLBACK_PREFIX}${digest.slice(0, 8)}`;
}
/**
* @param {string} [cwd]

@@ -72,9 +97,12 @@ * @returns {{ email: string|null, name: string|null }}

* @param {{ email?: string|null, name?: string|null }} [options.gitIdentity] 测试注入
* @param {boolean} [options.skipGit]
* @returns {{
* developerId: string|null,
* source: 'config'|'git-email'|'git-name'|'legacy',
* source: 'config'|'git-email'|'git-name'|'git-email-hash'|'git-name-hash'|'legacy',
* legacy: boolean,
* taskRoot: string,
* enabled: boolean,
* warnings: string[],
* }}
* @throws {Error} 当 collaboration.developerId 非空但 sanitize 后为空时。
*/

@@ -96,7 +124,19 @@ function resolveDeveloperContext(config, options = {}) {

enabled: false,
warnings: [],
};
}
const fromConfig = sanitizeDeveloperId(collab.developerId);
if (fromConfig) {
const warnings = [];
// 1) 显式 config：非空但非法 → 抛错，防止静默降级
const rawConfigId =
typeof collab.developerId === "string" ? collab.developerId.trim() : "";
if (rawConfigId) {
const fromConfig = sanitizeDeveloperId(rawConfigId);
if (!fromConfig) {
throw new Error(
`flow2spec.config.json → collaboration.developerId "${rawConfigId}" 无法规范化为 [a-z0-9-]。` +
`请改用英文/数字标识（如 "alice"），或留空让 Flow2Spec 从 git 身份推断。`,
);
}
return {

@@ -108,27 +148,67 @@ developerId: fromConfig,

enabled: true,
warnings,
};
}
// 2) git identity：先直接 sanitize，失败则 hash 兜底并 warn
const git =
options.gitIdentity ||
(options.skipGit ? { email: null, name: null } : readGitIdentity(cwd));
const fromEmail = sanitizeDeveloperId(git.email);
if (fromEmail) {
return {
developerId: fromEmail,
source: "git-email",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, fromEmail),
enabled: true,
};
if (git.email) {
const fromEmail = sanitizeDeveloperId(git.email);
if (fromEmail) {
return {
developerId: fromEmail,
source: "git-email",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, fromEmail),
enabled: true,
warnings,
};
}
const hashed = hashDeveloperId(git.email);
if (hashed) {
warnings.push(
`git user.email "${git.email}" 无法直接规范化，已回退到 hash id "${hashed}"。` +
`建议在 flow2spec.config.json 显式配置 collaboration.developerId 以获得可读的目录名。`,
);
return {
developerId: hashed,
source: "git-email-hash",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, hashed),
enabled: true,
warnings,
};
}
}
const fromName = sanitizeDeveloperId(git.name);
if (fromName) {
return {
developerId: fromName,
source: "git-name",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, fromName),
enabled: true,
};
if (git.name) {
const fromName = sanitizeDeveloperId(git.name);
if (fromName) {
return {
developerId: fromName,
source: "git-name",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, fromName),
enabled: true,
warnings,
};
}
const hashed = hashDeveloperId(git.name);
if (hashed) {
warnings.push(
`git user.name "${git.name}" 无法直接规范化，已回退到 hash id "${hashed}"。` +
`建议在 flow2spec.config.json 显式配置 collaboration.developerId 以获得可读的目录名。`,
);
return {
developerId: hashed,
source: "git-name-hash",
legacy: false,
taskRoot: path.posix.join(TASK_DIR, hashed),
enabled: true,
warnings,
};
}
}

@@ -142,2 +222,3 @@

enabled: true,
warnings,
};

@@ -147,2 +228,4 @@ }

/**
* 仅用于「已确定 id」时的路径拼接。**不检查 collaboration.enabled**；
* 需要开关语义的调用方请用 resolveDeveloperContext。
* @param {string|null|undefined} developerId

@@ -176,3 +259,5 @@ * @returns {string} posix 风格相对路径，如 `.task` 或 `.task/alice`

TASK_DIR,
HASH_FALLBACK_PREFIX,
sanitizeDeveloperId,
hashDeveloperId,
readGitIdentity,

@@ -179,0 +264,0 @@ resolveDeveloperContext,

+18
-0
lib/knowledgeEngine.js

@@ -119,2 +119,9 @@ const fs = require("fs");

// NOTE(frontmatter-subset): parse* / stringify* 只支持有限 YAML 子集
// （null/bool/int/float/裸字符串/单层数组）。当前所有 change 类型
// 都会经 normalizeTopicFrontmatter / normalizeStringArray 归一化，
// 类型是可控的。若未来允许 delta 直接写入任意 frontmatter，需要：
// 1) 显式声明每个字段的期望类型（否则会踩到 "3"↔3 类型漂移）；
// 2) 或者引入一个真正的 YAML 库（如 yaml/js-yaml）替换本节。
// 详情见 review 结论 L2。
function parseFrontmatterScalar(raw) {

@@ -717,2 +724,13 @@ const value = String(raw || "").trim();

}
if (
(normalized.type === "appendBody" || normalized.type === "replaceBody") &&
!String(normalized.content || "").trim()
) {
// 提前到 parse 阶段：kb status/plan 命中此错误时会被
// scanTaskKnowledgeDeltas 的 try/catch 转成结构化 error 字段，
// 而不是让 applyTopicChangeDraft 在 plan 时抛出裸异常炸掉 CLI。
throw new Error(
`kb delta change[${index}] ${normalized.type} 缺少 content（不能为空字符串）`,
);
}
if (normalized.type === "createTopic") {

@@ -719,0 +737,0 @@ if (!TOPIC_ID_RE.test(normalized.targetTopic)) {

+1
-1
LICENSE
MIT License
Copyright (c) 2026 兰涛
Copyright (c) 2026 double-coding-lab

@@ -5,0 +5,0 @@ Permission is hereby granted, free of charge, to any person obtaining a copy

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

@@ -18,2 +18,3 @@ "main": "./cli.js",

"files": [
"assets/readme",
"cli.js",

@@ -29,3 +30,3 @@ "lib",

"scripts": {
"test": "node cli.js --help && node cli.js kb check && node scripts/test-knowledge-engine.js && node scripts/test-template-knowledge.js && node scripts/test-init-gitignore.js",
"test": "node cli.js --help && node cli.js kb check && node scripts/test-knowledge-engine.js && node scripts/test-developer-id.js && node scripts/test-template-knowledge.js && node scripts/test-init-gitignore.js",
"sync:agents": "node cli.js init cursor claude codex",

@@ -32,0 +33,0 @@ "prepublishOnly": "node cli.js --help",

+101
-150
README.en.md

@@ -1,14 +0,28 @@

# Flow2Spec — Let AI Always Know What You're Doing
# Flow2Spec
> Cures the "amnesia" of Cursor / Claude Code — with one `init` command, AI
> remembers project context across sessions. No more re-explaining every time.
>
> 🌐 **[中文](./README.zh-CN.md)** · EN / 中
<p align="center">
<img src="./assets/readme/hero.svg" width="100%" alt="Flow2Spec routes a natural language coding request into compact project facts before code edits">
</p>
🎬 **[Live Demo](https://lands-1203.github.io/Flow2Spec/)** (13-slide HTML PPT, `←` `→` to navigate, `S` for presenter mode)
<p align="center">
<strong>Give Cursor, Claude Code, and Codex the project facts they need before editing.</strong>
</p>
📖 **[Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md)** · **[基础介绍（中文）](./docs/Flow2Spec基础介绍.md)** — long-form article: why Flow2Spec, knowledge graph vs project memory, with diagrams
<p align="center">
<a href="./README.zh-CN.md">中文</a> ·
<a href="https://double-coding-lab.github.io/Flow2Spec">Live demo</a> ·
<a href="./docs/en/Flow2Spec-Introduction.md">Introduction</a> ·
<a href="./docs/en/usage-guide.md">Usage guide</a> ·
<a href="./docs/en/commands-reference.md">Commands</a>
</p>
🔧 **Quick start**:
<p align="center">
<img alt="npm latest" src="https://img.shields.io/npm/v/@double-codeing/flow2spec?label=latest">
<img alt="npm beta" src="https://img.shields.io/npm/v/@double-codeing/flow2spec/beta?label=beta">
<img alt="node version" src="https://img.shields.io/node/v/@double-codeing/flow2spec">
<img alt="license" src="https://img.shields.io/npm/l/@double-codeing/flow2spec">
</p>
Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
```bash

@@ -18,184 +32,121 @@ npx @double-codeing/flow2spec@latest init

---
Try the current beta:
## Before / After
The exact same request, two conversations:
```bash
npx @double-codeing/flow2spec@beta init
```
> Update the batch re-scoring of the review template library
```
**Without Flow2Spec**:
## Why it exists
```
AI: Which module has this table?
AI: Is batchReScore sync or async?
AI: Is there a lock? What's the idempotency key?
AI: What's the response format? What's the error code?
AI: (Digging through 416 APIs, 796 files, 4.7 MB of source code…)
```
Without a maintained, routable project memory, an agent has to rediscover the same constraints on every request. Flow2Spec keeps those facts in compact topic shards and routes each request to the topics it needs.
Repeated introductions · Repeated code searches · Repeated mistakes
| Without Flow2Spec | With Flow2Spec |
| --- | --- |
| “Which module owns this table?” | `[matcher hit] m-product-review-template-library` |
| “Is batchReScore sync or async?” | `[loading deps] 4 topics · ~300 lines` |
| “Is there a lock? What is the idempotency key?” | `Redis lock ... TTL 10 min` |
| Agent searches 416 APIs, 796 files, and 4.7 MB of source before editing. | Agent reads the verified constraints first and opens the relevant files. |
**With Flow2Spec**:
Flow2Spec does not add documentation for its own sake. It keeps a small, machine-readable knowledge layer alongside the code, and lets the same skills update it when verified facts change.
```
[matcher hit] m-product-review-template-library
[loading deps] 4 topics · ~300 lines
AI: Known — fire-and-forget
Redis lock smp:product-review:template-library:batch-rescore:lock (TTL 10 min)
Max 100 items per batch · error code 101
AI: Starting implementation, 3 files affected.
```
## What you get
4.7 MB → 300 lines · Pinpoint accuracy in seconds
| Layer | What it does | Files |
| --- | --- | --- |
| Knowledge routing | Maps a request to the few topics the agent needs to read. | `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` |
| Topic shards | Stores project facts such as APIs, limits, locks, data rules, and workflows. | `.Knowledge/topics/*.md` |
| Agent entrypoints | Installs rules and skills for Cursor, Claude Code, and Codex. | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.md` |
| Skill workflows | Clarifies requirements, writes specs, implements, fixes, syncs knowledge, and commits. | `f2s-*` skills |
| Local task state | Keeps AI steps and user-side todos separate from product knowledge. | `.task/` |
---
## First use
## What Flow2Spec Does
After initialization, you do not need to document the whole project upfront. Start with the change you actually need. The agent reads the relevant code and existing docs while it works, then saves confirmed project facts back into the knowledge base.
**① Remembers project context across sessions**
`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.
For an existing project, you can ask the agent to draft the project structure first:
**② Routing manifest means AI doesn't dig through your repo**
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.
```text
/f2s-doc-arch
```
**③ f2s-* skills update knowledge as you code**
`/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."
This helps the agent understand the main directories, module boundaries, and existing conventions. It is optional. For a small change, you can start directly from the request.
**④ Full pipeline from requirements to code**
`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-tech` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
## Daily development
**⑤ Task checklists track progress across sessions**
When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
Most of the time, describe the task in natural language:
**⑥ Document-driven: PDF / MD straight into the knowledge base**
`/f2s-kb-add` aggregates source files into draft → final → topics. `/f2s-doc-final` converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.
---
## Getting Started
**Minimum viable setup is an empty skeleton.**
```bash
npx @double-codeing/flow2spec@latest init
```text
Add batch recalculation. It should retry failed items and avoid running the same batch twice.
```
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.
The agent should look for relevant project knowledge first. If something is missing, it should explain the gap, then read the necessary code or ask you a follow-up question. Confirmed facts such as APIs, limits, locks, data rules, and workflows can be synced back into `.Knowledge`.
Real data from a production repo running for 3 months:
A larger change usually follows this path:
| Metric | Value |
|---|---|
| Public APIs | 416 |
| Source code | 796 files / 4.7 MB / ~100K lines |
| Flow2Spec per-task load | **≈ 300 lines** (99% noise removed) |
---
## Usage Flow
### Step 1: Initialize (one-time)
```bash
npx @double-codeing/flow2spec@latest init
```text
describe the requirement
→ agent fills in missing details
→ generate or review the technical spec
→ implement / fix
→ sync verified project facts
→ check knowledge coverage before commit
```
Follow the prompts to completion — generates the `.Knowledge/` directory structure and routing config skeleton.
If you already know which workflow you want, use one of the explicit entrypoints below.
---
## How the knowledge base grows
### Step 2: Build the Knowledge Base (one-time)
Flow2Spec's knowledge base is not meant to be finished in one pass. It grows with development:
In your Agent tool (Cursor / Claude Code):
1. `init` creates the base skeleton.
2. The first time a module matters, the agent reads the relevant code and docs.
3. Confirmed facts from the development process become routable topics.
4. Later similar requests can hit those topics directly instead of searching the whole repository again.
1. `/f2s-doc-arch` — Scan your project architecture, generate an architecture draft, and follow the flow until topics are created
The directories can be read this way:
> This step is done once. You won't need to repeat it for daily development.
- `req-docs/`: technical specs and implementation plans for concrete changes.
- `stock-docs/`: stable project background, architecture notes, and imported source material.
- `topics/`: compact facts the agent should actually load.
- `matchers/`: rules that route a user request to the right topics.
2. `/f2s-kb-add <folder path>` — Import any feature modules that haven't been added yet
## Explicit skill entrypoints
> Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.
Natural-language requests can select these workflows automatically when intent recognition is enabled. Use the entrypoints below when you want to choose one directly.
---
### Step 3: Daily Development (every feature or fix)
**Large features:**
```
/f2s-req-clarify one-line description or paste PRD ← clarify requirements
/f2s-req-tech ← generate technical proposal
natural language: implement the proposal above ← AI starts coding (task checklist auto-created when changeTracking is on)
(debug and verify)
/f2s-kb-feat add xxx capability ← if something's missing
/f2s-kb-fix fix xxx ← if there's a bug
/f2s-kb-sync ← sync knowledge base
/f2s-git-commit ← check and commit
```
**Small changes / quick fixes:**
```
/f2s-kb-feat add xxx capability ← missing feature
/f2s-kb-fix fix xxx ← bug fix
```
---
## Quick Command Reference
| Command | Purpose |
|---|---|
| `/f2s-req-clarify` | Clarify requirements |
| `/f2s-req-tech` | Generate technical proposal |
| `/f2s-kb-feat` | Add a new capability |
| `/f2s-kb-fix` | Fix a bug |
| `/f2s-kb-sync` | Sync knowledge base |
| `/f2s-git-commit` | Commit code; "quick commit" skips KB coverage check |
| `/f2s-kb-add <path>` | Import API module into knowledge base |
| --- | --- |
| `/f2s-req-clarify` | Clarify missing requirements until the change is unambiguous. |
| `/f2s-req-tech` | Turn confirmed requirements into an implementation-ready technical proposal. |
| `/f2s-kb-feat` | Add a capability and update project knowledge. |
| `/f2s-kb-fix` | Fix behavior and correct the matching knowledge. |
| `/f2s-kb-sync` | Sync already implemented facts into `.Knowledge/`. |
| `/f2s-kb-add <path>` | Import an existing module or document set. |
| `/f2s-git-commit` | Check changed files and knowledge coverage before committing. |
For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
Full references:
---
- [Usage guide](./docs/en/usage-guide.md)
- [Commands reference](./docs/en/commands-reference.md)
- [Directory conventions](./docs/en/directory-conventions.md)
- [Architecture and principles](./docs/en/architecture.md)
- [Design principles](./docs/en/design-principles.md)
- [Project milestones](./docs/en/milestones.md)
## When NOT to Use
## When not to use it
- **One-off scripts** — throwaway code is faster with a few Markdown files for AI context
- **Solo small projects** — a single CLAUDE.md is enough; routing overhead > benefits
- **Team won't maintain .Knowledge/** — tools can't replace discipline
Flow2Spec is useful when context drift is expensive. It may be unnecessary for:
---
- throwaway one-off scripts;
- tiny solo projects where one `CLAUDE.md` is enough;
- teams that will not keep `.Knowledge/` aligned with the code.
## Documentation
## Learn more
**Start here** — product narrative and diagrams:
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) — product narrative, diagrams, and comparison with ordinary project memory.
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) — Chinese long-form introduction.
- [Live demo](https://double-coding-lab.github.io/Flow2Spec) — 13-slide HTML presentation.
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) (EN)
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) (中文)
**Hands-on guides**
### English
- [Usage Guide](./docs/en/usage-guide.md) — skill chains, config details
- [Commands Reference](./docs/en/commands-reference.md) — all f2s-* command reference
- [Directory Conventions](./docs/en/directory-conventions.md)
- [Architecture & Principles](./docs/en/architecture.md)
- [Usage Scenarios](./docs/en/usage-scenarios.md)
- [Design Principles](./docs/en/design-principles.md)
- [Project Milestones](./docs/en/milestones.md)
### 中文
- [使用说明](./docs/使用说明.md)
- [命令说明](./docs/命令说明.md)
- [目录与路径约定](./docs/目录与路径约定.md)
- [体系与原理](./docs/体系与原理.md)
- [使用案例·模拟对话](./docs/使用案例-模拟对话.md)
- [设计说明](./docs/设计说明.md)
- [项目里程碑](./docs/项目里程碑.md)
## License
MIT. Copyright © 2026 兰涛
[MIT](./LICENSE)
+106
-146
README.md

@@ -1,14 +0,28 @@

# Flow2Spec — Let AI Always Know What You're Doing
# Flow2Spec
> Cures the "amnesia" of Cursor / Claude Code — with one `init` command, AI
> remembers project context across sessions. No more re-explaining every time.
>
> 🌐 **[中文](./README.zh-CN.md)** · EN / 中
<p align="center">
<img src="./assets/readme/hero.svg" width="100%" alt="Flow2Spec routes a natural language coding request into compact project facts before code edits">
</p>
🎬 **[Live Demo](https://lands-1203.github.io/Flow2Spec/)** (13-slide HTML PPT, `←` `→` to navigate, `S` for presenter mode)
<p align="center">
<strong>Give Cursor, Claude Code, and Codex the project facts they need before editing.</strong>
</p>
📖 **[Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md)** · **[基础介绍（中文）](./docs/Flow2Spec基础介绍.md)** — long-form article: why Flow2Spec, knowledge graph vs project memory, with diagrams
<p align="center">
<a href="./README.zh-CN.md">中文</a> ·
<a href="https://double-coding-lab.github.io/Flow2Spec">Live demo</a> ·
<a href="./docs/en/Flow2Spec-Introduction.md">Introduction</a> ·
<a href="./docs/en/usage-guide.md">Usage guide</a> ·
<a href="./docs/en/commands-reference.md">Commands</a>
</p>
🔧 **Quick start**:
<p align="center">
<img alt="npm latest" src="https://img.shields.io/npm/v/@double-codeing/flow2spec?label=latest">
<img alt="npm beta" src="https://img.shields.io/npm/v/@double-codeing/flow2spec/beta?label=beta">
<img alt="node version" src="https://img.shields.io/node/v/@double-codeing/flow2spec">
<img alt="license" src="https://img.shields.io/npm/l/@double-codeing/flow2spec">
</p>
Flow2Spec adds a spec-driven workflow layer to AI coding agents. It creates a small, routable `.Knowledge/` knowledge base, installs agent-specific `f2s-*` skills, and keeps optional local task state separate from product knowledge. A new session can load the facts relevant to a request instead of rediscovering the repository.
```bash

@@ -18,184 +32,130 @@ npx @double-codeing/flow2spec@latest init

---
Try the current beta:
## Before / After
The exact same request, two conversations:
```bash
npx @double-codeing/flow2spec@beta init
```
> Update the batch re-scoring of the review template library
```
**Without Flow2Spec**:
## Why it exists
```
AI: Which module has this table?
AI: Is batchReScore sync or async?
AI: Is there a lock? What's the idempotency key?
AI: What's the response format? What's the error code?
AI: (Digging through 416 APIs, 796 files, 4.7 MB of source code…)
```
Without a maintained, routable project memory, an agent has to rediscover the same constraints on every request. Flow2Spec keeps those facts in compact topic shards and routes each request to the topics it needs.
Repeated introductions · Repeated code searches · Repeated mistakes
| Without Flow2Spec | With Flow2Spec |
| --- | --- |
| “Which module owns this table?” | `[matcher hit] m-product-review-template-library` |
| “Is batchReScore sync or async?” | `[loading deps] 4 topics · ~300 lines` |
| “Is there a lock? What is the idempotency key?” | `Redis lock ... TTL 10 min` |
| Agent searches 416 APIs, 796 files, and 4.7 MB of source before editing. | Agent reads the verified constraints first and opens the relevant files. |
**With Flow2Spec**:
Flow2Spec does not add documentation for its own sake. It keeps a small, machine-readable knowledge layer alongside the code, and lets the same skills update it when verified facts change.
```
[matcher hit] m-product-review-template-library
[loading deps] 4 topics · ~300 lines
AI: Known — fire-and-forget
Redis lock smp:product-review:template-library:batch-rescore:lock (TTL 10 min)
Max 100 items per batch · error code 101
AI: Starting implementation, 3 files affected.
```
## What you get
4.7 MB → 300 lines · Pinpoint accuracy in seconds
| Layer | What it does | Files |
| --- | --- | --- |
| Knowledge routing | Maps a request to the few topics the agent needs to read. | `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` |
| Topic shards | Stores project facts such as APIs, limits, locks, data rules, and workflows. | `.Knowledge/topics/*.md` |
| Agent entrypoints | Installs rules and skills for Cursor, Claude Code, and Codex. | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.md` |
| Skill workflows | Clarifies requirements, writes specs, implements, fixes, syncs knowledge, and commits. | `f2s-*` skills |
| Team collaboration | Keeps each developer's task state local while merging reviewed knowledge through structured deltas and topic revisions. | `.task/<developerId>/`, `.Knowledge/` |
---
## Built for shared repositories
## What Flow2Spec Does
Flow2Spec separates collaboration state by ownership. Checklists, session context, and user todos stay under each developer's local `TASK_ROOT` and do not enter Git. Confirmed project knowledge remains shared in `.Knowledge/`.
**① Remembers project context across sessions**
`.Knowledge/` structured knowledge base: routing manifest (`manifest-routing.json`) + keyword indices (matchers) + topic shards (topics). AI only loads what's relevant — 4.7 MB of source code compressed to ~300 lines of precise context.
Knowledge-producing skills write a structured `kb-delta.json` instead of editing topic files directly. Before apply, the CLI compares the delta's `baseRevisions` with the topic revisions on disk. Different topics can merge independently; concurrent changes to the same topic stop for a semantic review after the latest branch state is pulled.
**② Routing manifest means AI doesn't dig through your repo**
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.
Read the full model in [Team Collaboration](./docs/en/team-collaboration.md).
**③ f2s-* skills update knowledge as you code**
`/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."
## First use
**④ Full pipeline from requirements to code**
`/f2s-req-clarify` asks questions until requirements are unambiguous. `/f2s-req-tech` generates a ready-to-implement technical proposal into `req-docs/`. AI implements from the proposal — no relying on verbal agreements.
After initialization, you do not need to document the whole project upfront. Start with the change you actually need. The agent reads the relevant code and existing docs while it works, then saves confirmed project facts back into the knowledge base.
**⑤ Task checklists track progress across sessions**
When `changeTracking` is enabled, skills like `f2s-kb-feat` / `f2s-kb-fix` automatically create a `task.md` with checkboxes. Each step is checked off immediately to disk. New sessions auto-load the remaining checklist — no relying on memory. User-side todos (run SQL, set env vars, click approvals) go into `user-todos.md`, separate from AI steps.
For an existing project, you can ask the agent to draft the project structure first:
**⑥ Document-driven: PDF / MD straight into the knowledge base**
`/f2s-kb-add` aggregates source files into draft → final → topics. `/f2s-doc-final` converts any PDF or MD into the canonical final-draft format. External docs and legacy proposals all become routable knowledge.
```text
/f2s-doc-arch
```
---
This helps the agent understand the main directories, module boundaries, and existing conventions. It is optional. For a small change, you can start directly from the request.
## Getting Started
## Daily development
**Minimum viable setup is an empty skeleton.**
Most of the time, describe the task in natural language:
```bash
npx @double-codeing/flow2spec@latest init
```text
Add batch recalculation. It should retry failed items and avoid running the same batch twice.
```
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.
The agent should look for relevant project knowledge first. If something is missing, it should explain the gap, then read the necessary code or ask you a follow-up question. Confirmed facts such as APIs, limits, locks, data rules, and workflows can be synced back into `.Knowledge`.
Real data from a production repo running for 3 months:
A larger change usually follows this path:
| Metric | Value |
|---|---|
| Public APIs | 416 |
| Source code | 796 files / 4.7 MB / ~100K lines |
| Flow2Spec per-task load | **≈ 300 lines** (99% noise removed) |
---
## Usage Flow
### Step 1: Initialize (one-time)
```bash
npx @double-codeing/flow2spec@latest init
```text
describe the requirement
→ agent fills in missing details
→ generate or review the technical spec
→ implement / fix
→ sync verified project facts
→ check knowledge coverage before commit
```
Follow the prompts to completion — generates the `.Knowledge/` directory structure and routing config skeleton.
If you already know which workflow you want, use one of the explicit entrypoints below.
---
## How the knowledge base grows
### Step 2: Build the Knowledge Base (one-time)
Flow2Spec's knowledge base is not meant to be finished in one pass. It grows with development:
In your Agent tool (Cursor / Claude Code):
1. `init` creates the base skeleton.
2. The first time a module matters, the agent reads the relevant code and docs.
3. Confirmed facts from the development process become routable topics.
4. Later similar requests can hit those topics directly instead of searching the whole repository again.
1. `/f2s-doc-arch` — Scan your project architecture, generate an architecture draft, and follow the flow until topics are created
The directories can be read this way:
> This step is done once. You won't need to repeat it for daily development.
- `req-docs/`: technical specs and implementation plans for concrete changes.
- `stock-docs/`: stable project background, architecture notes, and imported source material.
- `topics/`: compact facts the agent should actually load.
- `matchers/`: rules that route a user request to the right topics.
2. `/f2s-kb-add <folder path>` — Import any feature modules that haven't been added yet
## Explicit skill entrypoints
> Do this selectively before starting development when you notice a module's knowledge is missing from the knowledge base.
Natural-language requests can select these workflows automatically when intent recognition is enabled. Use the entrypoints below when you want to choose one directly.
---
### Step 3: Daily Development (every feature or fix)
**Large features:**
```
/f2s-req-clarify one-line description or paste PRD ← clarify requirements
/f2s-req-tech ← generate technical proposal
natural language: implement the proposal above ← AI starts coding (task checklist auto-created when changeTracking is on)
(debug and verify)
/f2s-kb-feat add xxx capability ← if something's missing
/f2s-kb-fix fix xxx ← if there's a bug
/f2s-kb-sync ← sync knowledge base
/f2s-git-commit ← check and commit
```
**Small changes / quick fixes:**
```
/f2s-kb-feat add xxx capability ← missing feature
/f2s-kb-fix fix xxx ← bug fix
```
---
## Quick Command Reference
| Command | Purpose |
|---|---|
| `/f2s-req-clarify` | Clarify requirements |
| `/f2s-req-tech` | Generate technical proposal |
| `/f2s-kb-feat` | Add a new capability |
| `/f2s-kb-fix` | Fix a bug |
| `/f2s-kb-sync` | Sync knowledge base |
| `/f2s-git-commit` | Commit code; "quick commit" skips KB coverage check |
| `/f2s-kb-add <path>` | Import API module into knowledge base |
| --- | --- |
| `/f2s-req-clarify` | Clarify missing requirements until the change is unambiguous. |
| `/f2s-req-tech` | Turn confirmed requirements into an implementation-ready technical proposal. |
| `/f2s-kb-feat` | Add a capability and update project knowledge. |
| `/f2s-kb-fix` | Fix behavior and correct the matching knowledge. |
| `/f2s-kb-sync` | Sync already implemented facts into `.Knowledge/`. |
| `/f2s-kb-add <path>` | Import an existing module or document set. |
| `/f2s-git-commit` | Check changed files and knowledge coverage before committing. |
For the full command list, see [Usage Guide](./docs/en/usage-guide.md) · [Commands Reference](./docs/en/commands-reference.md)
Full references:
---
- [Usage guide](./docs/en/usage-guide.md)
- [Commands reference](./docs/en/commands-reference.md)
- [Directory conventions](./docs/en/directory-conventions.md)
- [Architecture and principles](./docs/en/architecture.md)
- [Team collaboration](./docs/en/team-collaboration.md)
- [Design principles](./docs/en/design-principles.md)
- [Project milestones](./docs/en/milestones.md)
## When NOT to Use
## When not to use it
- **One-off scripts** — throwaway code is faster with a few Markdown files for AI context
- **Solo small projects** — a single CLAUDE.md is enough; routing overhead > benefits
- **Team won't maintain .Knowledge/** — tools can't replace discipline
Flow2Spec is useful when context drift is expensive. It may be unnecessary for:
---
- throwaway one-off scripts;
- tiny solo projects where one `CLAUDE.md` is enough;
- teams that will not keep `.Knowledge/` aligned with the code.
## Documentation
## Learn more
**Start here** — product narrative and diagrams:
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) — product narrative, diagrams, and comparison with ordinary project memory.
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) — Chinese long-form introduction.
- [Live demo](https://double-coding-lab.github.io/Flow2Spec) — 13-slide HTML presentation.
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) (EN)
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) (中文)
**Hands-on guides**
### English
- [Usage Guide](./docs/en/usage-guide.md) — skill chains, config details
- [Commands Reference](./docs/en/commands-reference.md) — all f2s-* command reference
- [Directory Conventions](./docs/en/directory-conventions.md)
- [Architecture & Principles](./docs/en/architecture.md)
- [Usage Scenarios](./docs/en/usage-scenarios.md)
- [Design Principles](./docs/en/design-principles.md)
- [Project Milestones](./docs/en/milestones.md)
### 中文
- [使用说明](./docs/使用说明.md)
- [命令说明](./docs/命令说明.md)
- [目录与路径约定](./docs/目录与路径约定.md)
- [体系与原理](./docs/体系与原理.md)
- [使用案例·模拟对话](./docs/使用案例-模拟对话.md)
- [设计说明](./docs/设计说明.md)
- [项目里程碑](./docs/项目里程碑.md)
## License
MIT. Copyright © 2026 兰涛
[MIT](./LICENSE)
+106
-144
README.zh-CN.md

@@ -1,14 +0,28 @@

# Flow2Spec — 让 AI 一直知道你在做什么
# Flow2Spec
> 解决 Cursor / Claude Code 的「失忆症」——用一个命令初始化，让 AI
> 跨会话记住项目上下文，不用每轮重新交代。
>
> 🌐 **[English](./README.md)** · 中 / EN
<p align="center">
<img src="./assets/readme/hero-zh.svg" width="100%" alt="Flow2Spec 将自然语言编码需求路由到紧凑项目事实后再修改代码">
</p>
🎬 **[在线演示](https://lands-1203.github.io/Flow2Spec/)**（13 页 HTML PPT，`←` `→` 翻页，`S` 演讲者模式）
<p align="center">
<strong>让 Cursor、Claude Code、Codex 在动手改代码前，先读到正确的项目事实。</strong>
</p>
📖 **[Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md)** · **[Introduction (EN)](./docs/en/Flow2Spec-Introduction.md)** — 长文：为什么做 Flow2Spec、知识图谱 vs 项目记忆，含配图与流程图
<p align="center">
<a href="./README.md">English</a> ·
<a href="https://double-coding-lab.github.io/Flow2Spec">在线演示</a> ·
<a href="./docs/Flow2Spec基础介绍.md">基础介绍</a> ·
<a href="./docs/使用说明.md">使用说明</a> ·
<a href="./docs/命令说明.md">命令说明</a>
</p>
🔧 **快速体验**：
<p align="center">
<img alt="npm latest" src="https://img.shields.io/npm/v/@double-codeing/flow2spec?label=latest">
<img alt="npm beta" src="https://img.shields.io/npm/v/@double-codeing/flow2spec/beta?label=beta">
<img alt="node version" src="https://img.shields.io/node/v/@double-codeing/flow2spec">
<img alt="license" src="https://img.shields.io/npm/l/@double-codeing/flow2spec">
</p>
Flow2Spec 是给 AI 编码工具使用的 Spec-driven 工作流层。它会在项目里建立小而可路由的 `.Knowledge/` 知识库，安装面向 agent 的 `f2s-*` 技能，并把可选的本地任务状态和产品知识分开保存。新的会话可以按需求加载相关事实，而不是重新翻完整个仓库。
```bash

@@ -18,182 +32,130 @@ npx @double-codeing/flow2spec@latest init

---
尝试当前 beta：
## Before / After
同样一句话，两段对话：
```bash
npx @double-codeing/flow2spec@beta init
```
> 改一下评价模板文案库的批量重评分
```
**没有 Flow2Spec**：
## 为什么需要它
```
AI: 这个模块的表在哪？
AI: batchReScore 是同步还是异步？
AI: 有没有锁？幂等键是什么？
AI: 返回格式是什么？错误码是多少？
AI: （翻遍 416 个接口、796 份文件、4.7 MB 源码…）
```
反复介绍 · 反复翻代码 · 反复踩坑
如果项目记忆不能维护、不能路由，agent 每次处理需求都要重新确认同一批约束。Flow2Spec 把这些事实整理成紧凑的 topic 分片，再把需求路由到需要读取的主题。
**有 Flow2Spec**：
| 没有 Flow2Spec | 有 Flow2Spec |
| --- | --- |
| “这个模块的表在哪？” | `[matcher 命中] m-product-review-template-library` |
| “batchReScore 是同步还是异步？” | `[加载依赖] 4 个 topic · 约 300 行` |
| “有没有锁？幂等键是什么？” | `Redis lock ... TTL 10 min` |
| Agent 在修改前搜索 416 个接口、796 份文件、4.7 MB 源码。 | Agent 先读取已验证约束，再打开相关文件。 |
```
[matcher 命中] m-product-review-template-library
[加载依赖] 4 个 topic · 约 300 行
AI: 已知 — fire-and-forget
Redis 锁 smp:product-review:template-library:batch-rescore:lock（TTL 10 分钟）
单次最多 100 条 · 错误码 101
AI: 开始改，预计 3 处文件。
```
4.7 MB → 300 行 · 秒级定位到硬约束
Flow2Spec 不是为了增加文档数量。它把项目事实保存在一层小而准的机读知识里，并让同一套技能在事实变化后同步更新它。
---
## 它提供什么
## Flow2Spec 做这些事
| 层 | 作用 | 文件 |
| --- | --- | --- |
| 知识路由 | 把一次需求映射到 agent 需要读取的少量 topics。 | `.Knowledge/manifest-routing.json`, `.Knowledge/matchers/*.json` |
| 主题分片 | 保存 API、上限、锁、数据规则、业务流程等项目事实。 | `.Knowledge/topics/*.md` |
| Agent 入口 | 为 Cursor、Claude Code、Codex 安装规则和技能。 | `.cursor/`, `.claude/`, `.codex/`, `AGENTS.md` |
| 技能工作流 | 澄清需求、编写方案、实现、修复、同步知识、提交。 | `f2s-*` skills |
| 团队协作 | 每个人的任务现场留在本地，确认后的知识通过结构化 delta 与 topic revision 合入共享仓库。 | `.task/<developerId>/`, `.Knowledge/` |
**① 跨会话记住项目上下文**
`.Knowledge/` 结构化知识库：路由清单（manifest-routing.json）+ 关键词索引（matchers）+ 主题分片（topics）。AI 启动时只读该读的，4.7 MB 源码压到 300 行精准上下文。
## 多人共用一份知识库
**② 路由清单让 AI 不翻仓库，只拿该拿的**
每次需求命中 1~4 个 topic，约 300 行。业务的硬约束——锁的 key、错误码、上限——都在 topic 里，AI 不用从源码猜。
Flow2Spec 按所有权拆分协作状态。checklist、会话上下文和用户代办保存在每名开发者自己的 `TASK_ROOT`，默认不进 Git；已经确认的项目知识统一进入 `.Knowledge/`。
**③ f2s-* 技能改代码顺手更新知识**
`/f2s-kb-feat` 写功能时同步写 topic，`/f2s-kb-fix` 修 bug 时更正 topic，`/f2s-git-commit` 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。
知识类技能先生成结构化 `kb-delta.json`，不直接改 topic。真正 apply 前，CLI 会比较 delta 的 `baseRevisions` 与磁盘上的 topic revision。修改不同 topic 可以分别合入；两个人同时修改同一 topic 时，后合入的一方需要先拉取最新版本、重读语义，再改写 delta。
**④ 需求到实现全链路：澄清 → 技术方案 → 代码**
`/f2s-req-clarify` 反问到无歧义，`/f2s-req-tech` 生成可直接实现的技术方案文档落到 `req-docs/`，AI 按方案实现，不靠口头约定。
完整流程见 [团队协作](./docs/团队协作.md)。
**⑤ 任务清单跨会话追踪进度**
开启 `changeTracking` 配置后，`f2s-kb-feat` / `f2s-kb-fix` 等技能执行时自动创建带 checkbox 的 `task.md`，每步完成立即打钩落盘。新会话续作时自动加载剩余清单，不靠记忆、不靠口头，任务进度永远在磁盘上。用户侧的代办（执行 SQL、配环境变量、点审批）单独写入 `user-todos.md`，不混在 AI 步骤里。
## 第一次怎么用
**⑥ 文档驱动：PDF / MD 一键入知识库**
`/f2s-kb-add` 把已落地能力的源码聚合成初稿 → 终稿 → topics，`/f2s-doc-final` 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。
初始化以后，不需要先把整个项目文档补齐。更推荐的方式是从当前要处理的需求开始，让 Agent 在开发过程中读取真实代码和已有文档，再把确认过的项目事实沉淀下来。
---
如果这是一个已有项目，可以先让 Agent 整理一次项目结构：
## 上手成本
**最小可用集是一个空骨架。**
```bash
npx @double-codeing/flow2spec@latest init
```text
/f2s-doc-arch
```
1 分钟生成目录结构 + 路由配置，空的，直接跑。**下次需求命中哪块，写哪块**，不提前建设。
这一步会帮助 Agent 理解主要目录、模块边界和已有约定。它不是必选步骤；如果只是处理一个很小的修改，也可以直接从需求开始。
真实仓库跑了三个月的数据：
## 日常开发怎么用
| 指标 | 数值 |
|---|---|
| 对外接口数 | 416 |
| 源码体积 | 796 文件 / 4.7 MB / ~10 万行 |
| Flow2Spec 每次加载 | **≈ 300 行**（噪声切掉 99%） |
大多数时候，直接用自然语言说明要处理的事情即可：
---
```text
帮我新增一个批量重算功能，需要支持失败重试，并且不要重复执行同一批任务。
```
## 使用流程
Agent 会先根据规则查找相关项目知识。如果信息不够，它应该先说明缺口，再读取必要代码或反问你。实现过程中确认下来的接口、限制、锁、数据规则等事实，会在合适的时候同步回 `.Knowledge`。
### 第一步：初始化（一次性）
较大的需求通常按这个顺序推进：
```bash
npx @double-codeing/flow2spec@latest init
```text
说明需求
→ Agent 补齐缺失信息
→ 生成或复核技术方案
→ 实现 / 修复
→ 同步已验证的项目事实
→ 提交前检查知识库覆盖情况
```
跟着提示走完，生成 `.Knowledge/` 目录结构和路由配置骨架。
如果你已经知道要走哪个流程，可以直接输入下面的显式入口。
---
## 知识库会怎么增长
### 第二步：建知识库（一次性）
Flow2Spec 的知识库不是一次性整理完的。它会随着开发逐步变完整：
在 Agent 工具（Cursor / Claude Code）中执行：
1. `init` 先生成基础骨架。
2. 第一次处理某个模块时，Agent 读取相关代码和文档。
3. 开发过程中确认下来的事实，会被整理成可路由的主题。
4. 后续再处理相似需求时，Agent 可以直接命中这些主题，不需要重新翻完整个仓库。
1. `/f2s-doc-arch` — 扫描项目架构，生成架构说明初稿，跟着流程走直到生成主题（topics）
目录可以简单理解为：
> 这一步只做一次，之后日常开发不需要重复。
- `req-docs/`：某次具体变更的技术方案和实现计划。
- `stock-docs/`：稳定的项目背景、架构说明和导入材料。
- `topics/`：Agent 实际会读取的精简事实。
- `matchers/`：把用户需求路由到对应 topics 的匹配规则。
2. `/f2s-kb-add <文件夹路径>` — 把还没入库的功能模块路径补进来
## 显式技能入口
> 这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做
开启意图识别后，自然语言需求可以自动选择这些工作流。下面这些入口适合在你想明确指定流程时使用。
---
### 第三步：日常开发（每次需求）
**大需求：**
```
/f2s-req-clarify 一句话需求或粘贴 PRD ← 需求澄清
/f2s-req-tech ← 生成技术方案
自然语言：实现上面的技术方案 ← AI 开始实现（开启 changeTracking 时自动建任务清单）
（调试验证）
/f2s-kb-feat 新增 xxx 能力 ← 功能缺失时补能力
/f2s-kb-fix 修复 xxx ← 有 BUG 时修复
/f2s-kb-sync ← 同步知识库
/f2s-git-commit ← 检查并提交
```
**小需求 / 日常改动：**
```
/f2s-kb-feat 新增 xxx 能力 ← 功能缺失
/f2s-kb-fix 修复 xxx ← 改 BUG
```
---
## 常用命令速查
| 命令 | 用途 |
|---|---|
| `/f2s-req-clarify` | 需求澄清 |
| `/f2s-req-tech` | 生成技术方案 |
| `/f2s-kb-feat` | 新增小功能 |
| `/f2s-kb-fix` | 改 BUG |
| `/f2s-kb-sync` | 同步知识库 |
| `/f2s-git-commit` | 提交代码；“快捷提交”跳过知识库覆盖检查 |
| `/f2s-kb-add <路径>` | 接口模块入知识库 |
| --- | --- |
| `/f2s-req-clarify` | 补齐缺失信息，直到变更目标没有明显歧义。 |
| `/f2s-req-tech` | 把已确认的需求整理成可实现的技术方案。 |
| `/f2s-kb-feat` | 新增能力，并同步项目知识。 |
| `/f2s-kb-fix` | 修复行为，并更正对应知识。 |
| `/f2s-kb-sync` | 把已实现事实同步进 `.Knowledge/`。 |
| `/f2s-kb-add <path>` | 导入已有模块或文档集。 |
| `/f2s-git-commit` | 提交前检查变更文件和知识覆盖情况。 |
更多命令详见 [使用说明](./docs/使用说明.md) · [命令说明](./docs/命令说明.md)
完整参考：
---
- [使用说明](./docs/使用说明.md)
- [命令说明](./docs/命令说明.md)
- [目录与路径约定](./docs/目录与路径约定.md)
- [体系与原理](./docs/体系与原理.md)
- [团队协作](./docs/团队协作.md)
- [设计说明](./docs/设计说明.md)
- [项目里程碑](./docs/项目里程碑.md)
## 什么时候别用
## 什么时候不适合
- **一次性脚本** — 写完就删的东西，直接丢几个 Markdown 给 AI 更快
- **单人小项目** — 一份 CLAUDE.md 就够，路由和分片的开销大于收益
- **团队不愿同步 .Knowledge/** — 工具不能替代纪律
Flow2Spec 适合上下文漂移成本较高的项目。下面这些场景可能不需要它：
---
- 写完就删的一次性脚本；
- 很小的个人项目，一份 `CLAUDE.md` 已经够用；
- 团队不愿意让 `.Knowledge/` 和代码保持同步。
## 详细文档
## 继续了解
**从这里开始** — 产品叙事与配图：
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md) — 产品叙事、配图、与普通项目记忆的区别。
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md) — 英文长文介绍。
- [在线演示](https://double-coding-lab.github.io/Flow2Spec) — 13 页 HTML PPT。
- [Flow2Spec 基础介绍](./docs/Flow2Spec基础介绍.md)（中文）
- [Flow2Spec Introduction](./docs/en/Flow2Spec-Introduction.md)（EN）
**上手与参考**
### 中文
- [使用说明](./docs/使用说明.md) — 技能链、配置详解
- [命令说明](./docs/命令说明.md) — 所有 f2s-* 命令速查
- [目录与路径约定](./docs/目录与路径约定.md)
- [体系与原理](./docs/体系与原理.md)
- [使用案例·模拟对话](./docs/使用案例-模拟对话.md)
- [设计说明](./docs/设计说明.md)
- [项目里程碑](./docs/项目里程碑.md)
### English
- [Usage Guide](./docs/en/usage-guide.md)
- [Commands Reference](./docs/en/commands-reference.md)
- [Directory Conventions](./docs/en/directory-conventions.md)
- [Architecture & Principles](./docs/en/architecture.md)
- [Usage Scenarios](./docs/en/usage-scenarios.md)
- [Design Principles](./docs/en/design-principles.md)
- [Project Milestones](./docs/en/milestones.md)
## 协议
MIT. Copyright © 2026 兰涛
[MIT](./LICENSE)