编码流程状态机 baobaolaodie/flow-comet

English ·

快速开始

三步搞定，都在你的项目目录里执行：

1. Install the CLI globally (Node.js 18+)
npm install -g flow-comet

2. Go to your project
cd <your project>

3. Install flow-comet into it
fcomet init

fcomet 和 flow-comet 是同一个安装器的两个名字。只要其他参数已经表达了意图，init 这个词就可以省略（fcomet --target <dir>）；--target 本身默认指向当前目录。完全不带参数调用时，命令会打印用法并以非零状态退出，不会执行安装。在终端里运行时，如果没给 --platform，会先问你要配置哪个平台——方向键选择器会预选它检测到的平台，回退提示则以检测到的平台为默认值（同时存在多个平台痕迹时选 Claude Code）；想非交互式指定，可以用 --platform claude-code、--platform codex、--platform dsh，也可以用逗号组合，比如 --platform claude-code,dsh，或者 --platform all。重复执行同一条命令会更新已有安装，是幂等的。升级全局包只会替换命令行，要在项目里再跑一次 fcomet init，才能刷新该项目里的那份副本。

验证：

fcomet --version # the installed CLI version
cat .claude/skills/flow-comet/INSTALLED_VERSION # the version written into this project
安装器会把标记写入 .claude/skills/flow-comet/INSTALLED_VERSION（Claude Code）、.agents/skills/...（Codex）和 .dsh/skills/...（dsh）。标记记录这份副本来自哪个版本：npm 安装时记包的发布版本，从克隆仓库安装时记仓库的 git describe 值（克隆领先于 tag 时，这种形式会带 -<n>-g<hash> 后缀）。

使用

在项目里打开会话，调用工作流：

- Claude Code —— /flow-comet
- Codex —— 调用技能（/use flow-comet，或直接用自然语言要求走 flow-comet 工作流）
- DeepSeek Harness —— 调用 flow-comet 技能

首次调用会确认范围，然后为这次变更创建分支、初始化状态并进入第一个节点，在 .specs/ 下生成该变更的 CHANGE.md / REQUIREMENT.md。之后每个阶段自动流转——你只需在决策点作答（范围、技术栈、破坏性变更、评审发现、归档确认）。在项目里首次使用时，它会检测到缺少项目上下文，并在开始前提议从你现有的文档中构建一份。

想知道走到哪了，直接问它就行——或者在项目里用命令行 status 和 next 查看（各平台路径见 Installation）。

产物放在 .specs/<change-id>/；归档时移到 .specs/archive/<date>-<change-id>/，并在 .specs/CHANGELOG.md 顶部追加一行。逐节点走查——包括工作流底层跑了什么、需要时如何手动驱动某个节点——见 Usage。

选择平台

| 平台 | 技能安装到 | 钩子 / 桥接 | 首次使用 |
| Claude Code（默认） | .claude/skills/ | settings.local.json → hooks.PreToolUse | 工作区必须受信任；无头会话需要预先接受该信任 |
| Codex | .agents/skills/ | .codex/hooks.json，外加 AGENTS.md 中的托管块 | 交互式信任一次项目钩子，或为脚本化运行传入自动化标志 |
| DeepSeek Harness (dsh) | .dsh/skills/ | $DSH_HOME 下的全局桥接加载器，外加 AGENTS.md 中的托管块 | 无需钩子信任步骤 |

前置条件、全部四种安装方式、各平台验证步骤以及卸载/重置行为：Installation。

真实运行产物

一次完整的 8 节点运行会留下下面的产物轨迹——一个真实归档的变更，来自端到端测试项目（2026-08-13），保留在本仓库作为质量参照：CHANGE / REQUIREMENT / DESIGN / TASK / 六段式总结 / 带处置标记的 REVIEW / TEST / UAT / KNOWN-ISSUES / 技能加载声明标记。

processor-pipeline/ (archived change, full artifact set)
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
├── T01~T06-SUMMARY.md (six-section summaries)
├── REVIEW.md （带处置标记的发现） ├── TEST.md / UAT.md （验证确实会执行测试命令） ├── KNOWN-ISSUES.md └── .skill-loads/ （11 个技能加载声明标记）

下面两张截图来自本项目真实会话，未经编辑：一张是工作流技能在会话进行四个多小时后正常加载，另一张是五小时运行结束时，verify 退出已经执行过测试命令。

工作原理

流程是 flow-kit 的九个阶段；引擎把它们跑成八个节点。CHANGE 和 REQUIREMENT 由 open 覆盖，TEST 和 REVIEW 由 review 覆盖，DEV 按执行模式跑成 execute 或 subagent-execute。每个节点的退出都要先通过校验，下一个节点才会打开——verify 退出会真正执行 TEST.md 里的命令——每个节点的产物都落在 .specs/<change-id>/ 下。

手动驱动节点、各节点产出的产物，以及两套命令入口，见 Usage；引擎保证什么、节点退出如何校验，见 Core Mechanisms。

为什么选 flow-comet

1. 纪律从「靠自觉」变成「机器校验」——每个阶段的进入/退出都有脚本校验：产物齐全、章节填好、verify 命令真的跑过、任务不越界。
2. 跨会话不丢进度——你进行到哪一步，永远从 .specs/ 产物推导，不靠对话记忆；重新打开就能从正确的节点继续。
3. 实现与协调分离，而且分离是强制的——实现跑在全新上下文的子代理里，必须返回经过验证的契约；守卫在解析任何路径之前，先按调用方身份做判断，所以隔离 worktree 只是提供写权限的一种方式，并非硬性要求。协调者禁止写源码，超出当前节点范围的写入会被钩子拒绝。各层本身见 Core Mechanisms。

相关项目

| 项目 | 是什么、怎么工作 | 与 flow-comet 的关系 |
| flow-kit | 纯 Markdown 方法论包：9 阶段流程、.specs/ 模板、R1–R8 规则，无运行时。你手动加载各阶段提示词；状态通过 .md 产物传递。安装时会固定到某个具体 commit。 | 依赖——基础层，也是聚合点。 flow-comet 是它的自动化层：模板、规则和产物形态都继承自上游，本仓库只补充上游未定义的增量部分；模板是形态的唯一权威，没有上游模板的文档（UAT、归档的遗留清单）只检查是否存在。下面这些项目都是经由它接入 flow-comet 的。 |
| OpenSpec（Fission-AI） | 规格驱动开发框架：编码前的轻量规格层。每次变更在 openspec/ 下有一组 proposal / specs / design / tasks；默认配置档跑 propose → apply → sync → archive。 | 经由 flow-kit 聚合（想法来源）。单独使用时更轻：没有状态机，没有门禁。 |
| Superpowers（obra） | 智能体技能框架，外加一套完整开发方法论，按 harness 分别安装，覆盖 Claude Code、Codex、Cursor、Gemini CLI 等。技能按上下文触发，靠指令强制执行。 | 经由 flow-kit 聚合（想法来源，部分重叠）。纪律写在技能文本里，依赖模型自觉遵守；flow-comet 对同样的纪律做机器校验。 |
| comet（rpamis） | 可恢复的长任务工作流与技能平台：五阶段状态机、阶段守卫、钩子写入拦截。/comet 按配置路由，默认走 Native 分支。 | 早期机制参考，现已解耦。 钩子注入的形态和脚本持有状态来自这里；命名已解耦，状态不互通。只有它的 Classic 分支带有 OpenSpec + Superpowers 的血统。 |
| GSD | 规格驱动开发的元提示词与上下文工程工作流：里程碑 → 阶段 → 计划，每个智能体一个全新上下文窗口，载荷按范围裁剪，worktree 隔离，外加 UAT 门禁。 | 经由 flow-kit 聚合（想法来源，同一路线）。全新上下文执行和阶段门禁方向一致；路由仍由提示词驱动。 |
| spec-kit（GitHub） | SDD 工具包：Specify → Plan → Tasks → Implement → Converge。每个阶段把 markdown 产物交给下一阶段，任务块里带顺序 id、[P] 并行标记和文件路径。 | 经由 flow-kit 聚合（想法来源，同一路线）。flow-kit 的 TASK 模板继承的就是这种任务块形态；阶段切换不做强制。 |
| claude-task-master | 基于 MCP 和命令行的 AI 驱动任务管理：解析 PRD → 拆解任务 → 依赖图 → 编排下一个任务。以 MIT 加 Commons Clause 分发。 | 经由 flow-kit 聚合（补充）。只覆盖任务层：没有阶段门禁，没有产物校验，没有写入权限。 |
| brooks-lint (hyhmrright) | 第三方审查引擎，以十二本经典工程书为依据：6 类生产风险和 6 类测试腐化风险，每条发现按「症状 → 来源 → 后果 → 补救」引用，给出 0–100 健康分和六种模式。 | 可选集成（MIT，不是依赖）。 装了它，六条命令中的五条为自检和审查轮次提供支撑；没装，工作流沿一条声明好的回退链降级。 |

适用场景：flow-comet 面向长期运行、跨多会话的开发变更。三个平台上的契约一致——写权限、提交隔离、验证隔离和集成纪律——测试深度则因平台而异，各平台覆盖情况见 核心机制。它不是通用的 CI/CD 或项目管理工具；其他平台（Gemini / Cursor）不做保证。

推荐：brooks-lint

质量检查以 brooks-lint 的腐化风险框架为依据。brooks-lint 是第三方（MIT）审查引擎，对照十二本经典工程书诊断代码。装了它，每个任务的自检、审查节点的代码质量轮次和测试质量检查都走它，health 辅助命令把它的结果并入报告；没装，工作流仍沿一条声明好的回退链跑完，并说明这一点。它不是依赖，flow-comet 这边不需要任何配置；它的安装器覆盖的平台比本项目多，各平台验证深度不同——细节见 安装。

与上游项目的关系

flow-comet 把 flow-kit 的方法论自动化——阶段、产物、规则和模板都是继承来的，不是重新发明。两个项目不共享文件：flow-kit 作为只读的固定版本依赖使用，本仓库只在需要格式基线时内置一份副本。哪些可以借用、分歧如何声明，写在 CONTRIBUTING.md 里。

文档

| 文档 | 它唯一负责讲清的内容 |
| 安装 | 前置条件、四种安装方式、平台选择、验证和重置（purge 是删除重建，不是卸载） |
| 使用 | 8 节点工作流、每个节点的生命周期及其命令、产物、分支模式、执行模式、用户入口 |
| 核心机制 | 行为契约、三层防御、守卫校验和自定义协议 |
| 故障排查 | 按出问题的地方分组的症状：安装、首次运行、节点卡住、平台 |
| 版本 | 版本语义、记录版本的位置和发布检查清单 |
| CHANGELOG | 各版本变更记录 |
| Contributing | 贡献流程与借用边界 |
| Security | 报告漏洞 |

贡献

完整指南见 CONTRIBUTING.md —— 分支模型（feature → dev → main）、PR 工作流、合并规则、提交约定。简要说明：

1. 从 dev 拉分支：git checkout dev && git checkout -b feat/<description>
2. 在 .flow-comet/skills/ 下修改技能与脚本（这里是权威来源）；先写 RED 场景，按 TDD 推进
3. 跑回归：node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs → ALL 350 SCENARIOS PASSED
4. 向 dev 提 PR（squash —— 一个变更级提交）；发布 PR 走 dev → main（merge —— dev 的变更级提交进入 main，每次发布后 dev 不再领先）

每次 PR 和 push，CI 都会自动检查仓库约定：回归、安装器可复现性、工作流与双语镜像质量、PR 规范、版本一致性、死链。本地钩子（提交/推送消息检查）用 node scripts/install-commit-hook.mjs 安装 —— 完整指南见 CONTRIBUTING.md。

许可证

MIT © 2026 baobaolaodie

flow-comet 依赖 flow-kit（MIT）。它的机制形态借鉴自 Comet（MIT），但并不依赖 Comet。