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

English ·

flow-comet

一个自动化执行引擎，将 AI 编码纪律转化为可验证的状态机——面向 flow-kit 9 阶段工作流，专为 Claude Code、Codex 和 DeepSeek Harness 打造。

面向 AI 编码工作流——确定性状态机 · 协议驱动 · 守卫校验 · 子代理隔离

为什么

如果你使用像 superpowers、OpenSpec 或 GSD 这样基于技能的纪律，你就知道这种痛苦：纪律依赖于模型的遵从，而进度存在于聊天记录中。flow-comet 将 flow-kit 9 阶段流程（CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE）从依赖纪律的手动流程转变为可验证的确定性状态机：

- 自动化路由——脚本管理阶段转换、守卫校验和基于钩子的写入拦截
- 协议驱动——内置的 8 节点协议是默认工作流；由任何已安装技能组合而成的自定义协议在同一引擎上运行（参见自定义协议）
- 三层防御——物理写入拦截（钩子）、协调器禁止和退出接管检测
- 子代理隔离执行 — 实现工作被委派给具有可验证返回契约的全新上下文子代理
- 以文件为真相的恢复 — 状态派生自 .specs/ 产物，因此恢复从不依赖对话历史

快速开始

需要在目标项目中安装 Claude Code、Codex 或 DeepSeek Harness（dsh）以及 flow-kit（参见安装）。

1. 全局安装 CLI（Node.js 18+）
npm install -g flow-comet

2. 从项目目录将 flow-comet 安装到你的项目中
cd
fcomet init

该包提供两个指向同一安装器的命令名 — fcomet（主命令）和 flow-comet（别名）。init 标记是可选的（单独的 fcomet 等效），--target  也是可选的（默认：当前工作目录）。重新运行同一命令会更新现有安装，并且是幂等的。

在交互式终端上，首次运行会通过方向键多选提示选择平台（方向键 + 空格切换，回车确认；默认为 Claude Code）— @clack/prompts 是主要路径，当依赖未安装、离线或 stdin 没有原始模式时，会自动回退到 readline 数字/逗号多选（FLOW_COMET_FORCE_READLINE=1 强制使用回退以进行测试）；对于非交互式选择，添加 --platform codex / --platform dsh / --platform claude-code,dsh（逗号分隔）/ --platform all。

更新：全局包升级不会影响已安装的项目 — 在每个项目中重新运行 fcomet init 以获取新文件。并且由于 npm 安装没有 git 历史来派生开发标记，它写入的版本标记（Claude Code 为 /.claude/skills/flow-comet/INSTALLED_VERSION，Codex 为 .agents/skills/…，dsh 为 .dsh/skills/…）是包内附带的发布版本；--g 形式仅出现在从具有 git 和标签的仓库克隆运行的安装中。
默认情况下，安装器以 Claude Code 为目标（行为不变）。对于 Codex：fcomet init --platform codex —— 技能安装到 .agents/skills/（自动发现），编排规则注入到 AGENTS.md 的受管块中，写入防护钩子通过 Codex 的 PreToolUse 拦截 Bash 写入命令（首次使用时信任该钩子：/hooks）。对于 DeepSeek Harness：fcomet init --platform dsh —— 技能安装到 .dsh/skills/flow-comet（以 rank 100 自动发现，无需重启），编排规则注入到 AGENTS.md 的受管块中，并且一个轻量桥接加载器被全局挂载到 $DSH_HOME（参见安装 → 选项 D）。在交互式终端（TTY）上运行时若未指定 --platform，安装器会通过多选提示目标平台（根据现有痕迹预勾选——默认为 Claude Code——按 Enter 接受）；在没有 TTY 的情况下（CI/脚本），会检测目标项目中现有的 .claude/ / .codex/ / .dsh/，并回退到 Claude Code。

安装器还会确保目标项目中有 flow-kit：当缺失时，它会克隆上游并检出锁定的快照 9b5dda7；已存在的上游克隆只会被检查（报告当前 HEAD 与锁定快照的对比，只读）；同名但非克隆的目录会被跳过并给出指引；网络失败会发出警告并继续；清除操作绝不会触碰它。

同一个安装器也可以直接从仓库克隆运行，无需全局包——这正是本仓库自身工作流及其向其他项目分发所使用的路径（安装指南中的选项 B）：

cd
node scripts/prepare-env.mjs --target

对于 DeepSeek Harness（dsh），通过同一个安装器安装——一个专用的 dsh 平台描述符，没有单独的插件包：

cd
fcomet init --platform dsh
将技能树项目本地安装在 /.dsh/skills/flow-comet（dsh 会在该位置以 rank 100 自动发现技能，无需重启——没有该目录的项目无法看到该技能，这使得激活天然处于项目级别），将编排规则注入到 AGENTS.md 的托管块中（非破坏性合并），并在 $DSH_HOME/plugins/dsh-flow-comet-bridge.mjs 全局挂载一个轻量桥接加载器，同时在 $DSH_HOME/cordis.patch.yml 中放置一个托管块（读取-合并-写入，保留诸如 dsh-skin 等现有块，对所有 profile 生效）。该桥接通过 dsh 的 tools/pre-execute 事件拦截写入工具。拦截仅在流程运行期间生效——在空闲会话中，项目根目录之外的写入不会被中断。每次安装都会通过比较嵌入的版本戳与先前安装的加载器，报告 dsh 加载器版本变化（升级 / 降级 / 一致），而 workflow-state.mjs bridge-check 是一个只读健康检查，具有六种状态（healthy / file missing / not mounted / version skew / duplicate registration / not applicable）。最低 dsh 版本为 0.1.0-rc.6。完整的 dsh 平台部分见 Installation → Option D。

3. Open your project in a new Claude Code session and run:
/flow-comet
(Codex: invoke the skill in a Codex session — /use flow-comet or natural language;
same workflow, see Installation → "Using flow-comet on Codex")

首次调用会确认范围，然后自动创建 change/ 分支、初始化状态、进入 open 节点，并生成 CHANGE.md / REQUIREMENT.md。之后的每个阶段都会自动路由——你只需回答决策点（范围、技术栈、破坏性变更、审查发现、归档确认）。

在项目中首次使用时，工作流会自动检测是否存在项目上下文（CONTEXT.md），并在缺失时提示初始化——现有的 AI 上下文文档（例如 CLAUDE.md / AGENTS.md）会被读取并整合，并注明来源，且现有文件绝不会被修改。具有全新上下文的项目会静默运行。无需记住单独的命令。

Usage

- 8-node workflow — 逐节点职责、分支模式、执行模式、决策点
- Custom protocols — 通过 /flow-comet-compose 将任意已安装技能组合成自定义工作流
- Core mechanisms — 状态机、三层防御、守卫验证、执行模型
- Troubleshooting — BLOCKED/WARN 消息及其修复方法

入口点是 /flow-comet 命令；状态从命令行检查和推进（以下路径假定为 Claude Code 安装的 .claude/skills/；Codex 安装到 .agents/skills/，dsh 安装到 .dsh/skills/——见 Installation）：

node .claude/skills/flow-comet/scripts/workflow-state.mjs status   # 当前变更 + 节点
node .claude/skills/flow-comet/scripts/workflow-state.mjs next     # 下一个节点 + 技能

架构
mermaid
graph LR
O[open] --> D[design] --> P[plan] --> E[execute]
E  SE[subagent-execute]
E --> R[review] --> V[verify] --> A[archive]
style O fill:#e8f5e9
style D fill:#e3f2fd
style P fill:#fff3e0
style E fill:#fce4ec
style SE fill:#f3e5f5
style R fill:#e8eaf6
style V fill:#e0f7fa
style A fill:#f1f8e9

引擎通过从 .specs/ 产物中推导状态（determineNode）在节点之间进行路由，并由守卫退出校验进行门控。

什么是 flow-kit

flow-kit 是一种纯 Markdown 开发方法论，它融合了主流 AI 编码工作流——superpowers、OpenSpec、spec-kit、GSD、gstack、claude-task-master——形成其自身的 9 阶段流程（CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE），并配有 .specs/ 产物模板和 R1-R8 行为规则。无运行时，无 CLI——将其克隆到项目中，它便定义了要产出什么以及要遵循什么规则，但进度依赖于人（和 AI）的纪律。

为什么选择 flow-comet

横向对比

| 项目 | 定位 | 机制 | 与 flow-comet 的关系 |
|---------|-------------|-----------|---------------------------|
| flow-kit | 纯 Markdown 方法论包：9 阶段流程 + .specs/ 模板 + R1-R8 规则，零运行时 | 人类逐阶段加载提示文件；状态通过 .md 产物流转 | 依赖 / 基础——flow-comet 是其自动化层；产物和规则完全继承 |
| OpenSpec (Fission-AI) | 规范驱动开发框架：编码前的轻量级规范层 | openspec/ 目录，每次变更一个 proposal/specs/design/tasks，propose→apply→verify→archive | 理念来源 + 更轻量的替代方案——规范优先思维融入 flow-kit；独立使用更轻量（无状态机，无阶段门控） |
| Superpowers (obra) | Claude Code 技能集 + 完整开发方法论 | 可组合技能（brainstorm/plan/TDD/debug/review），由上下文触发，由指令强制执行 | 理念来源 + 部分重叠——基于技能的纪律依赖模型遵从；flow-comet 用脚本对同样的纪律进行机器验证 |
| comet (rpamis) | 可恢复的长任务工作流 + 技能平台：协议状态机、守卫门、钩子拦截 | /comet 按配置路由；Classic = OpenSpec + Superpowers 五阶段状态机 | 机制来源 —— flow-comet 借鉴其机制形态（协议即真相、脚本持有状态、守卫门、钩子白名单），并舍弃其平台设施（评估/发布）；状态不与 Comet Classic 互通 |
| GSD | 规范驱动开发的元提示词 / 上下文工程工作流 | 里程碑 → 切片 → 任务；每个阶段使用全新上下文并预内联上下文；工作树隔离 + UAT | 理念来源（同一路线） —— 全新上下文执行与阶段门一致；无脚本状态机路由，依赖提示词纪律 |
| spec-kit (GitHub) | SDD 工具包：Spec → Plan → Tasks → Implement | 每个阶段将 markdown 产物馈入下一阶段；任务格式包含顺序 ID、并行 [P] 标记、文件路径 | 理念来源（同一路线） —— 带文件路径/并行标记的任务形态与 flow-kit TASK 同源；无阶段转换强制 |
| claude-task-master | AI 驱动的任务管理（MCP + CLI） | PRD 解析 → 任务分解 → 依赖图 → 下一任务编排 | 互补 —— 仅管理任务层（分解/排序/依赖），不涉及阶段门、产物验证或写入权限 |

纵向对比：手动 flow-kit → flow-comet

| 维度 | 手动 flow-kit（纪律） | flow-comet（自动化） |
|-----------|------------------------------|------------------------|
| 阶段路由 | 人类记住流程并手动加载提示词；跳过阶段由你负责 | 脚本从 .specs/ 产物推导当前节点并自动路由；违反顺序会被阻止 |
| 验证 | 人类对照规则目视检查产物；TEST.md 命令“应该”运行 | 守卫在每个节点进入/退出时强制要求必需的产物/章节；verify 实际执行 TEST.md 命令并统计失败 |
| 纪律强制 | 规则是模型可能忽略的 markdown 文本 | 三层防御：写入白名单物理阻止越界写入 / 协调者禁止 / 退出接管检测 |
| 恢复 | 依赖对话记忆；跨会话进度丢失 | 文件即真相：从 .specs/ 重新推导节点并自动纠正状态；任何会话都能正确恢复 |
| 并行实现 | 人类协调多个窗口，容易越界 | 子代理在隔离的工作树中实现（协调者不能写入源代码），并且必须返回经过验证的契约（提交哈希 + 证据） |
| 决策负担 | 每个阶段都有确认点，人类回答一切 | 决策被分类（用户决定 / 自动处理 / 停止条件 / 手动移交）；人类仅在关键点介入（范围、技术栈、破坏性变更、审查发现、归档） |

为什么选择 flow-comet
1. 纪律从“自律”变为“机器校验” —— 每个阶段的进入/退出都有脚本验证：产物完整、章节已填写、验证命令确实运行、任务不越界。
2. 跨会话不丢失进度 —— 你所在的位置始终从 .specs/ 产物推导，绝不来自对话记忆；重新打开后从正确的节点继续。
3. 实现与协调在物理上分离 —— 实现在隔离 worktree 中的全新上下文子代理内运行，并且必须返回经过验证的契约；协调者被禁止编写源代码，写入白名单在物理层阻止违规。
4. flow-kit 的原生自动化层 —— 不是重新发明：产物格式、规则和阶段与 flow-kit 完全相同；flow-kit 项目通过安装 flow-comet 升级为机器驱动的流程，无需迁移。
5. 协议驱动、最小依赖、安装即运行 —— 内置的 8 节点流程开箱即用；任何已安装的 skill 都可以在同一引擎上组合成自定义协议；Node.js 18+；唯一的第三方依赖是 @clack/prompts，仅由安装器的 TTY 多选使用（否则自动回退到 readline）；一条命令即可安装。

适用场景：flow-comet 专为 Claude Code 上长时间运行、多会话的开发变更而构建——当一项变更跨越数小时和多个会话时，它所自动化的纪律会带来回报。它不是通用的 CI/CD 或项目管理工具；支持 Codex 和 DeepSeek Harness（见安装），其他平台（Gemini / Cursor）不做保证。

真实运行产物

一次完整的 8 节点运行会生成 docs/examples/processor-pipeline 中所示的完整产物轨迹——一个真实归档的变更（端到端测试项目，2026-08-13）：CHANGE / REQUIREMENT / DESIGN / TASK / 六段式摘要 / 带处置标记的 REVIEW / TEST / UAT / KNOWN-ISSUES / skill 加载声明标记。

processor-pipeline/            (archived change, full artifact set)
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
├── T01~T06-SUMMARY.md          (six-section summaries)
├── REVIEW.md                   (findings with disposition markers)
├── TEST.md / UAT.md            (verify actually executes the test command)
├── KNOWN-ISSUES.md
└── .skill-loads/               (11 skill-load declaration markers)

稳定的 skill 触发 —— 工作流 skill 在 4 小时以上的会话中持续正确加载：

Skill triggering

5 小时验证运行 —— 在 5 小时 14 分会话结束时进行完整验证和 UAT（↓399k tokens）：

Verification run

生态系统

| 项目 | 角色 | 与 flow-comet 的关系 |
|---------|------|---------------------------|
| flow-kit | 方法论与产物系统（9 阶段流程、.specs/ 模板、R1-R8 规则） | 依赖 — flow-comet 是其自动化层；产物和规则来自 flow-kit |
| Comet | Skill Creator 生态（bundle 编写、hook-guard 模式、状态机） | 机制来源 — flow-comet 大量借鉴 Comet 的机制模式（workflow-protocol 作为唯一事实来源、脚本持有状态、guard 门禁、hook 拦截）；运行时可选（复制安装无需 Comet CLI）。详情见 Ecosystem |
| Comet Classic | Comet 的经典工作流（OpenSpec + Superpowers） | 非依赖项 — flow-comet 是独立的工作流内核；状态不与经典版互通（自有 .flow-comet/flow-comet-state.json + 文件派生路由） |

目录结构

flow-comet/
├── .flow-comet/            ★ 权威来源（skills/ + rules/）
├── scripts/                prepare-env 安装器（npm bin：fcomet / flow-comet）
├── docs/
│   ├── examples/           工作流产物示例
│   ├── ECOSYSTEM.md        flow-kit 与 Comet 的角色、借鉴边界
│   ├── INSTALLATION.md     安装指南
│   ├── USAGE.md            使用指南
│   ├── PROTOCOL.md         自定义协议指南
│   ├── MECHANISM.md        核心机制（行为层）
│   ├── TROUBLESHOOTING.md  故障诊断
│   └── VERSIONS.md         版本管理与兼容性
└── CHANGELOG.md            Keep a Changelog 风格

技术栈

| 层级 | 技术 |
|-------|------------|
| 运行时 | Node.js ≥ 18（ESM）；第三方依赖：@clack/prompts（锁定精确版本，仅用于安装器 TTY 多选 — 不可用时自动回退到 readline） |
| 平台 | Claude Code（默认 — skills、.claude/ 安装、hooks）；Codex（.agents/skills/、AGENTS.md 托管规则、PreToolUse 写入拦截）；DeepSeek Harness（.dsh/skills/flow-comet 项目级 skill、AGENTS.md 托管规则、bridge 加载器 + tools/pre-execute 拦截） |
| 方法论 | flow-kit（产物、规则、模板） |

文档

| 文档 | 描述 |
|----------|-------------|
| Ecosystem | flow-kit 与 Comet 的角色、flow-comet 借鉴了什么以及刻意不借鉴什么 |
| Installation | 前置条件、安装选项 A–D（npm / prepare-env / 手动复制 / dsh）、安装验证 |
| Usage | 8 节点工作流、分支模式、执行模式、决策点 |
| Custom Protocols | 将 skills 组合为自定义工作流 |
| Core Mechanisms | 状态机、防御层、guard 校验 |
| Troubleshooting | 常见错误与修复 |
| Versions | SemVer 策略、兼容性 |
| Examples | 完整工作流产物示例 |
| 变更日志 | 版本历史（Keep a Changelog） |
| 安全 | 如何报告漏洞 |
| 行为准则 | 社区准则 |

贡献

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

1. 从 dev 分支创建：git checkout dev && git checkout -b feat/
2. 编辑 .flow-comet/skills/ 下的技能/脚本（权威来源）；先进行 RED 场景的 TDD
3. 运行回归测试：node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs → ALL 243 SCENARIOS PASSED
4. 向 dev 发起 PR（squash —— 一个变更级别的提交）；发布 PR dev → main（merge —— dev 的变更级别提交进入 main，每次发布后 dev 不再领先）

CI 会在每次 PR 和推送时自动强制执行仓库约定（回归测试、PR 规范、版本一致性、死链接）。本地钩子（提交/推送消息检查）通过 node scripts/install-commit-hook.mjs 安装 —— 完整指南见 CONTRIBUTING.md。

许可证

MIT © 2026 baobaolaodie

flow-comet 依赖于 flow-kit（MIT）和 Comet（MIT）。