the-flow

/the-flow — SDD 流水线调度

整个 SDD 流水线的唯一公开技能，遵循 flow-architecture 模式构建（docs/skills-pipeline/flow-architecture.md）：子技能（受契约约束的动词，每个阶段一个）位于 references/stages/，引导模式引擎位于 references/00-routing.md，辅导语气位于 references/coach.md。刚接触此流程？请查看 references/getting-started.md。

渐进式披露是契约：当前步骤只加载一个子技能——绝不预先读取所有子技能。

两种加载路径

引导模式 — /the-flow（无参数，或 <slug> / <ord>-<slug>）：

1. 读取 references/00-routing.md（入口路径、状态契约、Graph）以及 references/coach.md（轨道、旁白、先展示再提供选项）。
2. 根据 00-routing.md 处理新建／恢复／接管；仅在接受某个步骤时加载当前阶段的子技能，并辅导阶段衔接。
3. 引导模式拥有所有 the-flow 状态，并通过 harness flow nav 调用驱动全部状态——包括位置和会话数据袋：飞行计划（the-flow.json → the-flow.md）是唯一的状态基础（计划 024 — CLI 是生成器；不得手写；先运行能力预检，见 § 前置条件）。在会话中首次修改飞行计划之前，还要加载 references/flight-plan-ops.md——导航模型、主干与偏离规则，以及动词标志和注意事项（按需加载，不预先加载；子技能永远不会加载它）。

直接跳转 — /the-flow <id> <verb> [flags]：

1. 通过下方的注册表解析阶段。Id 和 verb 各自都能解析到阶段（输入 6 ≡ 输入 implement）；如果两者都给出，则必须指向同一阶段——若不一致，显示注册表并询问用户想要哪个（绝不猜测）。
2. 只读取该子技能，并按照给定标志执行（与该动词原本接受的标志相同）。
3. 不使用辅导、轨道或状态写入——也没有 harness 衔接点（harness 编排属于引导引擎的工作；直接跳转按设计直接运行基础动词，不使用 harness）。产物仍写入原有位置；下一次引导模式运行会根据产物是否存在发现它们，并补齐状态。

子技能在引用 references/00-routing.md § 共享约定时，可以按需加载该内容——这仍属于渐进式披露（该模式认可的例外 1）。读取当前未执行阶段的子技能则不允许。

注册表

此表为主表（Graph 主表位于 00-routing.md § Graph；references/getting-started.md 是其渲染视图）。它分配工作流的 id，将动词绑定到模块，并说明每项契约。

id	动词	模块	输入 → 输出	标志
1a	探索	references/stages/10-explore.md	意图 → research-dossier.md	"<intent>"
1b	规划	references/stages/20-plan.md	意图、档案？、研讨会？、覆盖范围？ → <slug>-plan.md（一份文档：业务规范 + 实施计划，始终在一次原子流程中同时完成两者；关卡 G1–G7；自动运行 /validate-v2；中途澄清见 § Re-entry）	"<intent>" [--simple] [--skip-clarify]
2c	研讨会	references/stages/25-workshop.md	计划/规范？、主题 → workshops/*.md（权威决策）	<plan> "<topic>" [--from-spec] [--list]
3a	ADR	references/stages/35-adr.md	计划/规范上下文 → docs/adr/*.md	"<decision>"
5	任务	references/stages/50-phase-tasks.md	计划 → tasks/<phase>/tasks.md + 上下文简介	--phase "<Phase N: Title>" --plan "<path>"
6	实施	references/stages/60-implement.md	计划、任务？ → 代码 + execution.log.md（恰好一个阶段）	--plan "<path>" [--phase "<Phase N: Title>"] [--subtask "<ORD-slug>"] [--companion] [--companion-slug "<slug>"]
6a	进度	references/stages/62-progress.md	任务结果 → 更新后的任务表 + 执行日志（每项任务完成后由实施动词读取；负责 companion 复盘）	--plan --phase --task --status [--companion-run-id] [--companion-slug]
7	审查	references/stages/70-review.md	计划、代码 → reviews/*.md	--plan "<path>" [--phase "<Phase N: Title>"]
8	发布	references/stages/80-ship.md	计划、审查 → 已推送的分支 + PR（遵循仓库指南）+ 受监控的 CI 检查；推送和创建 PR 均须先确认，合并可选；刷新遥测（无需确认）	--plan "<path>" [--base "<branch>"] [--no-watch] [--draft]
8c	对齐	references/stages/80-merge.md	（条件性分支流程 — 基准分支存在分歧）→ 对齐/合并计划；只有明确输入 PROCEED 才会执行合并	--plan "<path>" [--target "<branch>"]
sync	同步	references/00-routing.md	工作流计划 + 计划制品 → 已对齐的工作流计划：补全当前知识所能推断出的所有过去/当前/未来阶段、研讨会和 harness 接缝节点；幂等（完整的主干不会写入任何内容），仅提供建议，仅 CLI 可用，绝不推进 nav	（无）— 每次进入引导流程时自动触发；也可按需调用

模块在指定路径缺失时 → 明确说明并停止。切勿凭记忆臆造阶段。

8 ship 是主干中的终止阶段；8c reconcile 是条件性分支流程（仅在基准分支出现实质性分歧时触发），不属于主干。输入 merge 和旧版 plan-8-v2-merge 均解析为 8c reconcile（见下方别名表）。 sync 是维护动词，不是流程阶段——它没有序号 id，不产出阶段制品，也绝不移动游标或运行阶段。它是引擎的每次进入时都会执行的主干对齐流程（例程位于 references/00-routing.md § Reconcile the spine），以动词形式提供，便于任何人按需运行（也便于通过直接跳转构建的计划或手动采用的计划通过一次调用完成修复）。它不同于 8c reconcile（后者会合并存在分歧的 git 基准分支，与此无关）。参见不变量 #11。

命令语法

打印出的命令始终采用 /the-flow <id> <verb> [flags] 格式，例如 /the-flow 6 implement --plan "<path>"。 Id 或 verb 各自都可以单独解析；打印出的格式始终同时包含两者，绝不只显示数字；若两者不匹配 → 显示注册表并询问。本节是语法的唯一规定——其他任何位置（叙述、状态文件、视图）呈现的命令，都必须根据本节和注册表中的条目生成，绝不能手写。 维护动词 sync 可单独解析（其 id 和 verb 是同一个 token）：/the-flow sync 会按需运行主干协调流程。它不接受阶段标志；也绝不会推进流程。

旧 slug 转换与别名（读取时）

整合前编写的文档和旧版状态文件可能包含已弃用技能 slug 指定的命令（例如遗留 .the-flow-state.json 中的 pending_command，仅在一次性恢复回填期间读取——§ 状态）。在读取时进行转换——绝不执行已弃用的 slug；待执行命令的当前来源是 nav.next + 命令语法，在读取时生成（绝不存储）。标志保持不变。目标以 id+flag 形式存储（绝不存储完整命令字符串），打印或写入状态时通过命令语法 + 注册表生成。

已弃用的 slug / 输入别名	→ 目标（id + flags）
plan-1a-v2-explore	1a explore
plan-1b-v3-specify-and-clarify	1b plan
plan-1b-v2-specify	1b plan
plan-2-v2-clarify	1b plan（模块 § 重新进入）
plan-2c-v2-workshop	2c workshop
plan-3-v3-architect	1b plan
plan-3-v2-architect	1b plan
输入的 specify	1b plan
输入的 architect 或 id 3	1b plan
plan-3a-v2-adr	3a adr
plan-5-v2-phase-tasks-and-brief	5 tasks
plan-6-v2-implement-phase	6 implement
plan-6-v2-implement-phase-companion	6 implement --companion
plan-6a-v2-update-progress	6a progress
plan-7-v2-code-review	7 review
plan-8-v2-merge	8c reconcile
输入的 merge	8c reconcile
输入的 6c 或 companion	6 implement --companion

未映射的 slug → 打印不带修饰的阶段别名并询问——绝不猜测。（无法识别的 /plan-* 命令：显示注册表中的 id/verb 并询问用户指的是哪个阶段。）

硬性不变量（适用于每个阶段和两种加载路径）

1. 先打印，再询问是否运行。 以可复制的代码块打印准确命令——按照 § 命令语法呈现（必须包含 id 和动词，不能只写数字），让读者无需知道 id 就能看懂命令的作用——然后询问是否运行；每轮只执行一个获准的步骤（引导模式）。一项有意设计的例外：harness 路由器调用（/eng-harness-flow --hook … --json）会在每个接缝处自动触发——它只读、仅提供建议且按位置执行，因此随着上下文增长或压缩，不会被遗忘；它路由到的操作仍遵循先打印再询问（仅调用深度——references/harness-seams.md § 引擎如何呈现接缝）。
2. 未经明确确认，绝不执行不可逆操作。 每项对外操作都必须经过确认：ship 动词的推送和 PR 创建必须分别确认（对推送说“是”不代表同意创建 PR）；只有在用户输入 PROCEED 后，才会执行 reconcile 合并（8c）及任何即时合并——绝不能仅凭笼统的“是”执行。（一项有意设置的例外：ship 会在未经确认的情况下刷新遥测，通过 harness telemetry sync 执行——它只推送计数数据，推送到仓库树之外的 refs/harness-telemetry/*，不会发布任何工作内容，也不会触及任何分支或 PR，而且可撤销，因此不属于需要确认的对外操作。）
3. 绝不运行 /compact——它是由用户输入的 CLI 内置命令。建议用户：“自行输入 /compact，然后重新运行 /the-flow”。
4. 绝不设门槛、评分或阻止操作。 这些内容所呈现的操作——研讨会、反压调查、压缩、companion——都可以跳过；一切尽力而为，不设阈值，也不设合规底线。范围说明：“可以跳过”指的是接缝所路由到的操作，绝不包括接缝的路由器调用——根据 #1/#9，/eng-harness-flow --hook … --json 调用仍会在每个接缝处按位置自动触发；用户拒绝的是操作，不是调用。
5. 绝不捏造洞见。 每个叙述细节都必须以真实产物为依据；如果无法读取，就如实说明，并退回到检查文件是否存在或查看 git 状态。
6. 绝不手动编辑飞行计划，也绝不手动编写状态文件。 the-flow.md 始终由 harness flow render 根据 the-flow.json 重新生成；the-flow.json 只能通过 harness flow 调用进行修改（计划 024——CLI 是生成器）。不存在 .the-flow-state.json——所有 the-flow 状态（位置 + 会话 bag）都保存在 the-flow.json 中，且 CLI 是唯一写入者。引导模式需要具备相应能力的 CLI（§ 前置条件）。
7. 不要运行 minih。 implement 动词的 companion 模式（--companion）负责 companion 协议；你只需说明这一功能。将 Agent 记录到飞行计划中的工作要等到 v2 的 harness flow agent 动词实现后才能进行——在此之前，agents[] 保持未填充状态，且绝不手动编辑（遵守不变量 #6）。
8. 任何地方都不提供时间估算——只使用复杂度评分（CS 1–5）（references/00-routing.md § 通用约定）。
9. Harness = 唯一入口，在每个接缝处自动触发。 每个 harness 接触点都使用 /eng-harness-flow --hook …（永久的 --event 别名）——绝不提及或调用它的子技能。路由器调用会根据持久化的 nav.now 位置，在每个接缝处以机械方式自动触发（因此能经受漫长或经压缩的上下文）；路由到的操作仍遵循先打印再询问（仅调用）。Harness 接缝编排由 flow 负责（references/harness-seams.md）；子技能与 harness 无关。
10. 每个阶段都是需要深入思考的任务——根据阶段要求进行充分推理。
11. 保持主干完整——引导模式下每次进入都要 reconcile。 在每次引导模式进入时（恢复和接管都包括在内），在进行叙述前，引擎都会运行主干 reconcile 流程（references/00-routing.md § Reconcile the spine，通过 sync 动词调用）：它会将计划中的完整阶段/研讨会清单和 harness 接缝节点集合与 the-flow.json 进行差异比较，并补齐当前认知表明应有但飞行计划中缺失的所有内容——所有过去、当前和未来的阶段、每个研讨会，以及——根据 D1 无条件补齐——每个阶段的 harness 接缝节点（配置只会影响这些节点是否运行，绝不影响它们是否存在）。此操作幂等（主干完整时不写入任何内容）、发现结果仅供参考、只能通过 CLI 执行（不变量 #6），且绝不设门槛、绝不推进 nav、绝不运行阶段。机械执行保障是 references/00-routing.md § CLI 驱动的执行节奏中的 Tier-1 立即运行步骤（步骤 3，与 render 并列）——不是依赖文字记忆：它依赖按位置执行的“漫长或经压缩的会话无法跳过此步骤”保障，因此运行是强制且机械的（与 render 同级），而它发现的内容仍仅供参考、不设门槛。用户绝不能被迫要求“确保所有阶段/杂务都已列出”——这项不变量的目的，就是消除这种遗漏。直接跳转不会自动运行 reconcile（这是有意设计的无 harness 模式）；需要时可通过 sync 动词运行该流程。
12. 每轮都要确定方向——读取 nav、运行 orient，并重新回到主干。 在每个引导模式轮次中采取行动前，读取持久化位置（harness flow nav show）并运行 harness flow orient——它会打印路线、nav.now 节点的 label/command/编写好的 instructions[]，以及当前需要处理的杂务。这是按位置执行的机械步骤——属于 Tier-1 执行节奏，与 render 和主干 reconcile（#11）并列——每次进入时都必须无条件运行，绝不是可选步骤；它依赖与接缝自动触发（#9）相同的“漫长或经压缩的会话无法跳过此步骤”保障。这解决了“能力较弱的模型不遵循流程”的问题：“接下来该做什么”变成了读取，而非推断，因此即使是较弱的模型（或刚执行 /compact 后的上下文），也会在每一轮重新回到主干，而不是偏离流程——每轮都会重新读取节点的 instructions[]，绝不依赖记忆。orient 读取是强制且机械的；它呈现的内容（指令、到期杂务）仍仅供参考、不设门槛（杂务绝不设门槛——#4）。（要确保对抗性弱模型也能遵循，最终需要 harness 侧提供每轮钩子——技能本身只能给出指示；这一更大的需求已记录，但不构成阻碍。）

状态

持久状态就是飞行计划——nav（位置 + 自由格式的 bag）+ docs/plans/<ord>-<slug>/the-flow.json 中的节点状态（渲染为 the-flow.md）。没有单独的状态文件——CLI 是唯一的状态写入方。契约、写入权限和 Graph：references/00-routing.md；harness 接缝编排（检测、接缝映射、节点生成、上游契约）：references/harness-seams.md。子技能拥有各自的阶段产物（规范 / 计划 / 任务 / 执行日志 / 评审），绝不写入 the-flow 状态，也不携带任何 harness 知识。

前置条件——功能完备的 harness flow CLI（功能 + 最低版本要求）

引导模式完全通过 harness flow 动词系列驱动飞行计划（the-flow.json → the-flow.md）（plan 024）。这是硬性运行时依赖：

• 功能预检——每次引导会话运行一次，在首次修改飞行计划之前。 检查 harness flow --help（如果有最低版本要求，也检查 harness --version）。如果缺少 harness，或没有 flow 动词系列（CLI 版本较旧），或其功能不足以支持 create/insert-node/nav/rail/render → 报错并停止，并如实提示：“the-flow 需要功能完备的 harness flow CLI（plan 024）。请运行 harness update（或 npm i -g @ai-substrate/engineering-harness），然后重新运行 /the-flow。” 不要退回到手动编辑 JSON——CLI 是唯一的写入方。
• 无需采用流程。 这不是 engineering-harness 循环。the-flow 的飞行计划存放在 docs/plans/<ord>-<slug>/the-flow.json 中，无需配置 .harness/，无需治理文档，也无需采用 harness——只需全局 CLI 位于 $PATH 中（harness 是类似 git 的环境工具）。飞行计划架构随此技能提供（references/flight-plan.schema.json），并通过 --schema 传入；不会将任何内容打包或安装到使用此技能的仓库中。
• 彻底切换（E308）。 024 之前手动编辑的流程（缺少 provenance 块的 the-flow.json）不会迁移——CLI 读取时会返回 E308（旧格式）。这是明确的停止提示，并非错误：请使用 harness flow create flight-plan --schema <skill base>/references/flight-plan.schema.json --agent the-flow 重新创建（<skill base> = 此技能的基础目录，例如 ~/.claude/skills/the-flow；--agent the-flow 会将重建后的轨道标题设为 [the-flow]；已有 .md 会保留为静态记录）。
• 版本不匹配是运行时依赖缺失，不会自动回退。
  • 向前不匹配（技能需要比已安装 CLI 更新的版本）→ 上述功能预检会提示“运行 harness update”并停止。
  • 向后不匹配（旧版 the-flow 仍手动编辑 JSON，却搭配新版 CLI 运行）→ 旧版手动编辑器写入的 the-flow.json 会被新版 CLI 读取为 E308（缺少 provenance）——这是明确停止，不会静默产生不一致。解决方法是更新技能，绝不要为此添加特殊处理。
• 部署顺序——先 CLI，后技能。 始终先部署功能完备的 harness flow（发布 / harness update），再部署此迁移后的技能，确保技能上线时预检能够通过。回滚是可追加且可逆的：还原技能 + harness update --pin <prev>（CLI 是全局 npm 包）。