stage 流水线
Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro|------------------ 规划（flow/ 下的文件） ------------------| |------- 交付（cards/ 里） -------|流水线不是待产出的文档清单。每个 stage 存在，是因为构建走到那一步，人容易陷入某种特定的自我欺骗，gate 就瞄着那种欺骗。
规划：六个带 gate 的文件
Section titled “规划：六个带 gate 的文件”规划产物在 flow/ 下，编号写死，顺序没得商量。
00 — Idea。 三句话 pitch：谁有这个痛，他们今天怎么凑合，你打算换什么做法。gate 要找的是问题，不是穿着问题衣服的方案。这是整个项目里毙掉东西最便宜的地方。
01 — Research。 已经有什么：竞品、线上系统、真实价格。规则是先看，证据不凭感觉。这个 stage 造假最诱人也最贵，因为建在编造竞品上的计划，会自信地错好几个星期。脚本识破不了编的引用，语义 gate 是唯一防线。
02 — Scope。 给功能评级，砍。这一关的典型失败是注水——C 级功能因为你想做，被写成了 B 级。Scope 是大多数项目得救或完蛋的地方，所以 work 模式只在这里、也仅在这里，停下来等操作者明确签字。
03 — PRD。 活下来的 scope 变成编号功能需求。每个 FRn 日后必须被 card 认领、被 contract 接口服务。这条 trace 机械可审计，需求在规划和构建之间悄悄蒸发不了。
04 — ADR。 架构决策，包括否掉了什么、为什么。被否的选项是值钱的部分：半年后，没人会为 settled 的问题重新开庭。
05 — Contract。 接口，代码一行没写先写好。web 项目：方法、路径、auth、请求响应 shape；CLI：命令、flag、输出 shape、exit code；库：导出的 API 面；skill：agent 读的命令/文件。
为什么 contract 永远不能跳过
Section titled “为什么 contract 永远不能跳过”其他规划 stage 都能靠诚实记录的 debt 跳过。stage 05 不行，永远不行。
contract 是接缝。生产方照着它 build，消费方从它出发 build，两边能独立推进，恰恰因为中间的 shape 是定的。跳过它省不了时间，只是把成本搬到联调——两边各建一半，发现对不上，有人得重写一边。
接下来的纪律很严：永远别临场发挥 shape。shape 错了，先改 contract，再改代码。shape 的真值晚点才发，这会儿先拿 null 或 stub 顶着。
contract 跟你的项目类型不合，改它——把 “endpoint” 读成“接口”或“命令”——别跳过它。
交付：card
Section titled “交付：card”stage 05 通过之后，/flow card 切构建 card。每张 card 是一次 scoped 构建会话：allowed-files 清单、它实现的需求、verify 块、独立测试、开头空着的证据区。
构建，敌对评审，部署，然后像用户一样上线验证。card 完成的标志是世间证据贴进来、check gate 通过，不是测试绿了。
Brownfield：stage 00-inspect
Section titled “Brownfield：stage 00-inspect”已有代码库不从 Idea 开始。/flow assess 脚手架并设 gate 于 flow/00-inspect.md，一张现状图：技术栈、产品今天实际做什么 vs 应该做什么、风险、测试基线。操作者评审，存在是为了让已有系统的规划扎在实际有的东西上，而不是 README 声称的东西上。
每次运行一行老实话，操作者写，永远不是 agent 写。它喂给持久层，所以下个项目的 recall 能翻出这个项目的痛。
毙掉是有效出口
Section titled “毙掉是有效出口”每个 gate 有三个结果，不是两个：通过、拦下、毙掉。只会说“通过”的 harness 是挂着合规仪式的传送带。在 Scope 毙掉一个弱想法，是构建里最便宜的好决策。
用 /flow next 前进
Section titled “用 /flow next 前进”/flow next 检查你所在的 stage 的 gate，通过了才解锁下一个。runner 把 flow/ 里编号最高且连续的 stage 文件当作当前——stage 文件只有它之前每个 stage 都存在才算数（孤零零一个 05，没有 00–04，不算当前）。六个 stage gate 全干净，规划才算完成；那时 /flow card 才解锁。
机械层挂了会精确打印错在哪、带行号——没打勾的 gate 框、残留的 [FILL] 占位符——然后停下。FAIL 永远不往前走。清单就是完整诊断：打开点名的文件，修那几行，再跑 /flow next。别猜哪个框空着。
脚本通过之后，先施加刚完成的 stage 的语义挑战，你才能往前走，所以机械干净但空洞的产物照样会被点名虚。在 teach 模式，agent 永远不替你打勾、不替你写产物，只告诉你哪挂了。
毙掉是有效的终点。在任何 gate 停下，尤其 Scope，是值得尊敬的结果，不是 flow 的失败。通过、拦下、毙掉是三个答案；只会说“通过”的 harness 是传送带。
flow 生来是 web 形的。老实支持别的软件形态，不是把 gate 泛化成模糊，而是点名到底哪三样东西变。用 /flow project-type web|cli|library|skill 在 stage 05 之前设好。值存在 PROJECT_TYPE 文件，默认 web。不带参数跑这条命令，打印当前值和它蕴含的完成证据规则。
类型适配 stage 05 的 contract 接缝、标准 card 序列、完成证据长什么样。其余——每个 gate 的精神、“contract 先于代码”、“完成是世间的证据”——原封不动。晚点再改类型等于重访 contract，所以现在改便宜，以后改贵。
- web。 Contract：HTTP endpoint（方法、路径、auth、请求、响应）； served OpenAPI。完成：上线的部署 URL 加真实
curl输出。 - cli。 Contract：命令、flag、输出 shape、exit code。完成：工具装得上，一次真实调用返回预期输出和 exit code。CLI 构建的第一步：
/flow project-type cli。 - library。 Contract：公开 API 面——导出的函数和类型及其 shape。完成：公开 API 导得进来，示例跑得起来，覆盖率达标。
- skill。 Contract：agent 读的命令和文件。完成：装进 skill 家目录，一次真实运行达到自定完成定义。skill 构建的第一步：
/flow project-type skill。
CLI 构建不是稀释版 web 构建：它要产出的证据一样具体，只是长成装好的工具和真实 exit code 的样子，而不是部署 URL。gate 本人没变——只动证据的形状。
stage-05 有些 gate措辞还写着 “endpoint”、要 auth 列，那是 web 味。对别的类型，把 “endpoint” 读成“接口”或“命令”，拿写和副作用代替 auth——stage 前言明确授权这种适配，对等的无漂移检查就是按类型的完成证据真通过。
项目类型矩阵
Section titled “项目类型矩阵”用 /flow project-type <web|cli|library|skill> 设置，存在 PROJECT_TYPE，默认 web。
| 类型 | Contract 接缝（stage 05） | 完成证据 | card 序列 |
|---|---|---|---|
web |
HTTP endpoint——方法、路径、auth、请求、响应；served OpenAPI | 上线的部署 URL 加真实 curl 输出 |
脚手架加 /healthz、垂直切片、后端、contract 测试、UI mock、前端、e2e |
cli |
命令、flag、输出 shape、exit code | 工具装得上，一次真实调用返回预期输出和 exit code | 脚手架加一条真实命令、子命令组、测试、干净目录安装冒烟 |
library |
公开 API 面——导出的函数和类型及其 shape | 公开 API 导得进来，示例跑得起来，覆盖率达标 | 脚手架加核心 API、多轮 API、测试、可跑的示例、发布 dry-run |
skill |
agent 读的命令和文件 | 装进 skill 家目录，一次真实运行达到自定完成定义 | 脚手架加一条可跑命令、reference 和 law、安装、一次 dogfood 运行 |
四种类型恒定不变：每个需求映射到接口，每个接口先写 shape 再写代码，contract 是接缝，“tests pass” 或 “merged” 永远不算完成。
模式与运行策略
Section titled “模式与运行策略”flow 有四个模式轴，真的互相独立，每个项目各设各的，随便组合。
起草模式决定谁写 gate 产物：teach（默认）是你写、agent 只守门；work 是 agent 先采访你一次，起草 stage 00 到 05，只在 scope 签字处停下。
项目类型决定完成长什么样——web 要上线 URL，CLI 要真实调用和 exit code，库要可导入 API，skill 要装好的运行。
运行模式决定 card 怎么 build：手动，你 drive card、构建、check；或 auto，自治运行，分 tier 处理，碰 security-class 就 halt。
Greenfield 对 brownfield决定从哪开始：新东西从 stage 00-idea，已有代码库先做一次带 gate 的现状评估。
哪个轴都不动 bar。gate 和完成规则在所有组合下都一样；模式只动起草权、证据形状、驱动方式，永远不动 gate 的高度。
澄清 open decision
Section titled “澄清 open decision”没定下来的产品决策，以 - [ ] bullet 挂在 Scope、PRD、Contract 产物的 ## Open decisions 标题下。数它们的是 gate 已经在用的同一个框扫描器，所以没定的决策是真拦 stage，不是躺在没人看的注释里。
/flow clarify 打印这些残留 bullet，按节过滤，永远 exit 0——它是建议性质的打印机，不是第二个 gate。定下来是收敛的、自愿的写回仪式：一条一条过，把决策记进产物，打勾。clarify 的任何东西都不是 /flow next 的前置；gate 扫描器本来就在数这些框了。
stage 产物
Section titled “stage 产物”runner 随每个 stage 解锁把模板拷进你的项目。规划产物在 flow/ 下，交付单元在 cards/ 下，台账在项目根。下面是文件，不是标题。
| 路径 | stage | 内容 |
|---|---|---|
flow/00-idea.md |
00 | 三句话 pitch：谁有这个痛，他们今天怎么凑合，你打算换什么做法 |
flow/00-inspect.md |
brownfield | 现状评估：技术栈、功能对照产品目标、风险、测试基线 |
flow/01-research.md |
01 | 已经有什么——竞品、线上系统、真实证据 |
flow/02-scope.md |
02 | 评级的功能、砍掉的、scope 签字 |
flow/03-prd.md |
03 | 编号功能需求（FRn） |
flow/04-adr.md |
04 | 架构决策，包括否掉的选项 |
flow/05-contract.md |
05 | 接口，先于代码写好。接缝。永远不能跳过 |
flow/constitution.md |
可选 | 操作者写的项目内不变量，建议性质 |
cards/C-NNN.md |
构建 | 一次 scoped 构建会话：allowed files、实现项、verify、独立测试、证据、风险 |
MODE、PROJECT_TYPE |
— | 起草模式和项目类型 |
DEBT.md、RETRO.md、AUTO-LOG.md |
— | 故意的跳过、retro 行、自治运行日志 |
.flow/harness.db |
— | 持久记录 |
每个规划产物自带 [FILL] 占位符和 gate 框；两个都是机械扫描，哪个没清掉 stage 就挂。没定的决策归 ## Open decisions 标题下，同一个扫描器数它们。
维护者文件（不在公开页）：skills/flow/references/stage-state-machine.md、skills/flow/references/project-types.md、skills/flow/references/mode-work.md、skills/flow/references/clarify.md。