Flow-Spec 文档交付技能包

本目录是一套与业务领域解耦的文档工作流技能：头脑风暴 → 原型与功能清单 → 需求文档（PRD）→ 流程图（draw.io 泳道等）→ 可选技术说明文档。技能正文以 Superpowers 开源库中的同名能力为蓝本翻译并改写为中文；唯一例外是 requirement-doc-writing/SKILL.md：该文件为作者已实战验证的 PRD 写法，未按本仓库泛化改写，正文可能仍含原项目术语与模板引用。

本包不包含编码、TDD、开发实现计划或分批写代码类技能；若需扩展商务文档（如报价单），见 workflows/default.md 文末「扩展位」。

技能一览

| 技能目录 | 作用 | 来源说明 | |----------|------|----------| | using-flow-spec | 总章程：如何发现、加载、组合技能 | 对齐 Superpowers using-superpowers 理念 | | flow-spec-routing | 主编排：触发词与路线 A～D | 自研编排 | | requirement-brainstorming | 设计前头脑风暴与方案 | Superpowers brainstorming | | prototype-design | 基于 brainstorm 结论生成静态 HTML 原型，含人工确认检查点 | 自研，write-doc 链路 | | feature-list | 原型确认后输出 CSV 功能清单（系统/角色/模块/功能/前后端描述），PRD 的前置 | 自研，write-doc 链路 | | requirement-doc-writing | 需求文档（PRD） | 保留原文，未泛化 | | swimlane-diagram | PRD 第二章跨职能泳道图（draw.io XML） | 自研，与 requirement-doc-writing 联用 | | technical-doc-writing | 技术说明/设计类文档（纯文档） | 泛化 + 模板引用 |

这套工作流怎么用

1. 会话开始时

让智能体先阅读并遵循 skills/using-flow-spec/SKILL.md。

2. 两种用法

（1）只做某一环 — 只加载对应技能（例如仅 PRD 则 requirement-doc-writing）。

（2）端到端 — 阅读 workflows/default.md 与 skills/flow-spec-routing/SKILL.md，按路线 A/B/C/D 执行；产物默认在 flow-spec/temp/（见 references/rules/storage.md）。

3. 快捷命令（若环境支持 commands/）

| 文件 | 作用 | |------|------| | write-doc.md | 文档写作完整链路（brainstorm → 原型 → 功能点 → PRD） | | brainstorm.md | 头脑风暴技能 | | write-requirement.md | 需求文档技能 | | route-delivery.md | 主编排 |

实际技能标识以当前编辑器为准（如带 flow-spec: 前缀）。

4. 参考与脚本

• references/：模板、规则、索引。其中部分模板文件名或示例仍可能来自历史项目，可按需替换为当前业务的术语表与场景示例。
• scripts/：文档辅助脚本（模板填充、校验、索引同步等）。

5. OpenSpec

若业务仓库启用 OpenSpec，变更与校验方式遵循该仓库约定；见 using-flow-spec 与 flow-spec-routing 中的可选说明。

在本机接入与验证（建议流程）

| 步骤 | 说明 | |------|------| | 1. 建仓库 | 包含本 flow-spec/ 目录结构。 | | 2. 克隆 | git clone <仓库地址> | | 3. 打开 | 用 Cursor 打开项目根目录。 | | 4. 规则 | 在 .cursor/rules/ 或 AGENTS.md 中约定：会话开始阅读 flow-spec/skills/using-flow-spec/SKILL.md；技能根目录为 <项目根>/flow-spec/skills/。 | | 5. 验证 | 新开会话，用自然语言触发某技能，确认会加载对应 SKILL.md。 |

用 npm CLI 初始化到任意业务项目（推荐）

本仓库根目录已配置 @yuzijun/create-flow-spec 包（与 OpenSpec 类似：npm create 会执行同名工具）。发布后在业务仓库根目录执行：

npm create @yuzijun/flow-spec@latest

等价：

npx @yuzijun/create-flow-spec@latest

默认（推荐轻量）：不会在仓库里再拷一份 flow-spec/ 大目录，只会在项目根生成：

• .cursor/commands/fsx-*.md（斜杠命令入口）
• .cursor/rules/flow-spec.mdc
• flow-spec-output/（对应 SKILL 里 temp/ 的产出映射）
• 若存在 package.json：自动 npm install -D @yuzijun/create-flow-spec@<版本>

技能正文从 node_modules/@yuzijun/create-flow-spec/skills/... 读取（与 OpenSpec 式「只装依赖 + 项目内命令」一致）。

仅当需要把整包放进仓库时（旧行为 / 离线改技能）：

npx @yuzijun/create-flow-spec@latest --full
# 或
flow-spec init --full

| 选项 | 含义 | |------|------| | --full | 将完整 skills/、references/ 等拷入 ./flow-spec（或 --dir / --here） | | --no-install | 轻量模式下不自动执行 npm install -D | | --dir <路径> | 仅配合 --full：子目录名，默认 flow-spec | | --here | 仅配合 --full：直接写入当前目录 | | --force | 覆盖 |

未发布前可在本仓库根本地调试：node bin/create-flow-spec.mjs、node bin/flow-spec.mjs。亦可 npm link 后使用全局命令 flow-spec / create-flow-spec。

全局命令 flow-spec（OpenSpec 式：init + update + 项目内斜杠命令）

安装本包后同时获得 flow-spec 与 create-flow-spec 两个可执行文件：

npm i -g @yuzijun/create-flow-spec@latest

在业务仓库根目录：

| 命令 | 作用 | |------|------| | flow-spec init | 默认轻量：只写 fsx-* 规则 + flow-spec-output/ + 开发依赖；不拷贝整包到 flow-spec/ | | flow-spec init --full | 将完整技能包拷入 flow-spec/（与旧版行为相同） | | flow-spec update | 若存在嵌入的 flow-spec/ 则同步目录；否则刷新轻量命令与 node_modules 依赖 | | flow-spec doctor | 检查 fsx、规则、技能可读性（嵌入或 node_modules） |

与 create-flow-spec / npm create 行为一致，但 推荐使用 flow-spec init 作为日常入口。

Cursor 项目指令（fsx-*）

安装后，在业务项目根（在 Cursor 中打开该仓库）使用命令面板，可触发：

| 指令文件 | 含义 | |----------|------| | fsx-write-brainstorm | 头脑风暴与方案收敛 | | fsx-write-prototype | 静态原型与标注 | | fsx-write-feature | 功能点清单（CSV） | | fsx-write-prd | PRD 八章 | | fsx-write-swimlane | 泳道图 draw.io | | fsx-route-delivery | 主编排（路线 A～D） | | fsx-revise-doc | 增量修订与一致性 | | fsx-archive-doc | 会话日志与归档 | | fsx-write-quote | 报价单/商务文档（扩展技能） |

实际斜杠名以当前 Cursor 版本对 .cursor/commands/*.md 的解析为准；正文会引导加载 flow-spec:* 技能。

本技能包仓库若需生成上述命令，在根目录执行：node bin/flow-spec.mjs update --force。

常见问题：为什么看起来「整包都在」？

1. 轻量模式不会在仓库根创建 flow-spec/ 目录；但若执行了 npm install -D，node_modules/@yuzijun/create-flow-spec/ 里会有完整包内容——这是依赖安装，不是往仓库里拷了一套 skills（勿提交 node_modules）。
2. 只有加了 --full（或用了旧版 CLI）才会在项目里出现 flow-spec/skills/ 那种嵌入拷贝。
3. 请先确认 CLI 版本：flow-spec --version 应为 ≥ 0.3.0。若不是，请升级全局包：
   npm i -g @yuzijun/create-flow-spec@latest

发布到 npm（维护者）

1. 登录 npm 公网：npm login --registry=https://registry.npmjs.org/
2. 在本仓库根发布：npm publish --registry=https://registry.npmjs.org/（package.json 的 files 已限定只打包容器内技能包文件）
3. 包名为 @yuzijun/create-flow-spec；如需组织名发布，可改为 @你的组织/create-flow-spec。

私有仓可使用 Verdaccio / GitHub Packages，用法同为 npm create … / npx …。

目录结构

flow-spec/
├── skills/           # 各技能（每目录 SKILL.md）
├── references/       # 模板、规则、索引
├── workflows/        # 默认路线
├── commands/         # 快捷入口
├── scripts/          # 辅助脚本
└── temp/             # 默认产出根目录