flow-comet 1.6.0 → 1.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.flow-comet/skills/flow-comet/GUIDANCE.md +22 -3
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +20 -1
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
- package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +2513 -295
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +3 -3
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +422 -10
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +140 -226
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +362 -4
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-design/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
- package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
- package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
- package/README.md +45 -119
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
|
@@ -23,6 +23,8 @@ This node performs a structured multi-round review of the implemented change, ch
|
|
|
23
23
|
|
|
24
24
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
25
|
|
|
26
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
27
|
+
|
|
26
28
|
### 必查清单(review 逐项核对 · 执行者交付纪律)
|
|
27
29
|
|
|
28
30
|
- [ ] **工件模板保真**:每份交付工件(`*-SUMMARY.md` / TASK / CHANGE / REQUIREMENT / DESIGN)的**标题 / 首部字段 / 段序**与对应模板一致——SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写并含 `## 自检方法` 段;执行者按 `flow-kit/prompts/4-dev.md` 协议交付。
|
|
@@ -91,7 +93,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
91
93
|
- Major (should fix: design issues, significant regression)
|
|
92
94
|
- Minor (optional: naming, style, small refactor)
|
|
93
95
|
|
|
94
|
-
8. **Generate fix tasks**: For all Critical and decided-to-fix Major findings, append to `.specs/<change-id>/TASK.md` as numbered fix tasks with full 7 fields — 追加到 TASK.md 的 `## Fix 任务` 段内(**禁止文件尾追加**), then follow the
|
|
96
|
+
8. **Generate fix tasks**: For all Critical and decided-to-fix Major findings, append to `.specs/<change-id>/TASK.md` as numbered fix tasks with full 7 fields — 追加到 TASK.md 的 `## Fix 任务` 段内(**禁止文件尾追加**), then follow the「修复回路状态机路径」section below: home back to execute and run its four exit gates before review can be closed.
|
|
95
97
|
|
|
96
98
|
9. **Disposition markers (problem-handling principle)**: Every finding entry in the `## 发现` section of REVIEW.md — including Minor — must carry a **disposition marker** so findings never silently disappear after being recorded:
|
|
97
99
|
- `[已修]` — fixed via a fix task (linked in the entry)
|
|
@@ -124,7 +126,7 @@ This node is truly done when:
|
|
|
124
126
|
- **Agent thought**: "I'll record this Minor and move on." **Actual risk**: Findings (especially Minor) that are recorded without a disposition marker silently disappear — the exit guard warns on missing markers; every finding must be `[已修]`, `[升级]` (user decision), or `[转待办]` (tracked for archive).
|
|
125
127
|
- **Agent thought**: "This Major is not for this batch, I'll defer it to backlog myself." **Actual risk**: Major 延期属用户决策点——reviewer 自行 `[转待办]` 会被退出守卫拦截(新 change BLOCKED / 旧 change WARN);须先 `[升级]` 等用户裁决,用户接受延期后才可记录裁决并转待办。
|
|
126
128
|
|
|
127
|
-
##
|
|
129
|
+
## 修复回路状态机路径
|
|
128
130
|
|
|
129
131
|
review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
|
|
130
132
|
|
|
@@ -132,10 +134,10 @@ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周
|
|
|
132
134
|
2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
|
|
133
135
|
3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
|
|
134
136
|
4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
|
|
135
|
-
- **guard exit 回源审计行语义(Fix vs RETURN
|
|
137
|
+
- **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
|
|
136
138
|
5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
|
|
137
139
|
- **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
|
|
138
|
-
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED
|
|
140
|
+
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
139
141
|
|
|
140
142
|
**由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
|
|
141
143
|
|
|
@@ -218,5 +220,5 @@ If the script prints `SKILL: flow-comet-verify`, load that Skill next.
|
|
|
218
220
|
2. Read `.specs/<change-id>/REVIEW.md` — if exists with all rounds completed and Critical resolved, review is done.
|
|
219
221
|
3. If REVIEW.md exists but incomplete, check which rounds are missing and resume from there.
|
|
220
222
|
4. If Critical items were found but fix tasks not yet generated, generate them now.
|
|
221
|
-
5. If fix tasks were generated but not executed, follow the
|
|
223
|
+
5. If fix tasks were generated but not executed, follow the「修复回路状态机路径」section below to home back to execute and run its four exit gates; return here only after execute exit passes, then run review's own exit.
|
|
222
224
|
6. Do not repeat completed review rounds.
|
|
@@ -15,11 +15,12 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
|
|
|
15
15
|
|
|
16
16
|
职责分工(趟次协作):本节点负责**并行委托**(`parallel="true"` 且依赖已满足的任务,同一趟内同时发出)——委托节点可多次往返:每趟委托当时全部依赖已满足的并行任务,趟间由 execute 节点串行消化,直至不存在依赖已满足的可并行 pending 且无串行残留。execute 节点负责**串行委托**(非 parallel 任务,一次一个)。两者共用同一委托证据库(handoff 记录在 subagent-execute evidence)。序列形态不是本节点的关注点:全并行、全串行、串→并、并→串及任意混排均合法(合法性只取决于 `depends_on` 无环且引用存在;依赖环与缺失依赖已在 plan 出口拦截并附恢复指引),到达本节点的任务序列由多趟路由按依赖拓扑自动分趟消化。
|
|
17
17
|
|
|
18
|
-
> **Codex
|
|
19
|
-
>
|
|
20
|
-
>
|
|
21
|
-
>
|
|
22
|
-
>
|
|
18
|
+
> **Codex 平台事实与 flow-comet 当前支持面(2026-09-30 记录)**:**平台事实**——Codex 的常规用法是交互式 CLI(`codex` 无子命令)与会话内 agent,`codex exec` 只是 headless 子面;原生多代理 `multi_agent` 为 stable、默认启用(`codex features list` 可查),本机真实交互式会话日志中记录到 `spawn_agent` / `wait_agent` / `close_agent` 的实际调用——因此「Codex 不能委派 / 不使用并行委托」**不是平台事实**。**flow-comet 当前支持面(机制缺口)**——现有守卫 / 白名单 / 隔离模型未覆盖 Codex 原生子代理形态;在后续契约(须先由覆盖交互式会话与原生子代理的探针得出结论,再据此决定是否修改引擎)落地前,本节点在 Codex 上**不派遣并行子代理**,任务逐个走 `execute` 节点串行交付——这是 flow-comet 现阶段的**支持面限制,不是平台能力边界**;headless 子面实测见下(仅 `codex exec`,不得外推)。
|
|
19
|
+
> **dsh 平台委托方式(实测核对)**:dsh 的子代理是平台**进程内子代理**(不创建独立工作区)——写入守卫按**会话身份分派**:子代理 `delegationDepth` 大于 0 直接放行、**项目内任意路径可写(含 gitignored)**,因此**无需隔离区**;直接委托即可,不需要 worktree 隔离。**通用边界**:同一工作区内的并行子代理会看到彼此未提交的中间态——任务的 `write_files` 边界与提交时点即相互隔离纪律(本节点第 1 步的 write_files 互斥检查因此仍是硬前置)。
|
|
20
|
+
> **旧结论(实测 2026-08-13;证据已不可复核,未纳入 2026-09-30 重测矩阵——不得作为现行结论)**:worktree 的 `.git` 是主仓共享——`workspace-write`/`git-write-access` 沙箱均被 Codex 硬拦截(index.lock / objects / COMMIT_EDITMSG Permission denied);子代理必须用 `sandbox_mode="danger-full-access"` 才能完成 git 提交(worktree 隔离已限定写范围,full-access 仅用于让 git 提交可行)。**信任边界**:`danger-full-access` 是宿主级信任边界(不隔离凭据/网络访问)——仅委托可信子代理,并移除委托环境中的不必要凭据。以上仅作历史留档;现行结论以探针结论与后续契约为准。
|
|
21
|
+
> **headless 子面实测与 hook 会话 root 订正(依据 2026-09-30 真机重测;codex-cli 0.146.0 / Windows;仅 `codex exec --json --ephemeral` headless 子面;不得外推为平台结论)**:旧结论「手工 worktree 内的写入会被协调者白名单拦住、会话 root 仍是主仓库」被**推翻并收窄**——实测 hook 进程 cwd == 载荷 `cwd` == 会话工作根(cwd=项目 / `-C` / 手工 worktree 三形态);**Codex 原生子代理(`spawn_agent`)形态未覆盖,不得外推**。手工 worktree 形态下相对路径写入**不会**被拦:worktree 通常缺 gitignored 运行态 state → 守卫走「无活跃 workflow」放行;若 hook 命令仍指向主仓安装副本(runRoot 外),守卫因「workflow protocol file must stay inside the project root」报错退出,Codex 将 hook 失败降级为非阻塞 → 写入照常落地。**静态喂测(独立复现)**:守卫白名单只覆盖**解析后仍在 runRoot 内**的目标;`Write/Edit` 的 `file_path` 解析为 runRoot 外时跳过判定(**fail-open**,已知缺口、未闭合),而 Bash 写命令同目标仍 `decision:block`(两分支不对称)。**`apply_patch`**:会触发 PreToolUse,但 `tool_name="Bash"`、补丁正文在 `tool_input.command`(heredoc)、**无 `file_path`**;守卫不解析补丁体 → 目标不被提取、放行(独立复验复现了载荷与守卫盲区;「文件确实落盘」子项在复验环境因 apply_patch shim 失败未复现,首次真机重测环境曾落盘——按此差异如实理解)。**hook 触发条件**:隔离 `CODEX_HOME` 无持久信任时默认 headless **不执行**项目 hook;`hooks` 特性默认 enabled、可被项目配置/开关覆盖;`codex_hooks` 是 deprecated 别名;per-invocation 信任是必要因素之一,但独立复验显示 trust-only 触发**不稳定**(3/21;补 `--dangerously-bypass-approvals-and-sandbox` 后 5/5)——**不得写成稳定/确定性保证**;持久信任与交互式 TUI 形态未覆盖。**CC 的判据不同**:CC 的守卫按路径前缀识别隔离区(写入落在 `.claude/worktrees/**` 内即放行,`file_path` 与 Bash 命令两条判定路径同语义)。
|
|
22
|
+
> **出路(受支持路径,三平台各一条)**:① **CC 平台**——用 `Agent` 工具的 `isolation: "worktree"` 委托(守卫已覆盖该区,见步骤 3);② **dsh 平台**——直接委托平台进程内子代理(写入守卫按会话身份分派放行,**无需隔离区**;保持 `write_files` 边界与提交时点纪律);③ **Codex 平台**——**本节点暂不派遣并行子代理**:任务逐个走 `execute` 节点串行交付。依据是 flow-comet 当前支持面(原生子代理形态未被守卫 / 白名单 / 隔离模型覆盖,属机制缺口;待探针结论决定后续契约),**不是「Codex 不能委派 / 不使用并行委托」的平台边界**;headless 子面实测见上(仅 `codex exec`,不得外推)。
|
|
23
|
+
> **不提供/不使用规避通道**:绕开守卫命令级检测的写法(如用 Python `open()` 等 File API 直写)**不是受支持路径**——它绕过的是写入防线本身(防线失效时无拦截、无记录),与三层防御的设计相反。需要越出边界时一律走上面的出路,或如实上报 BLOCKED,**不得以更换工具形态绕过**。handoff 记录(workflow-handoff request/result)与 Return Contract 校验机制不变。
|
|
23
24
|
|
|
24
25
|
## Guidance
|
|
25
26
|
|
|
@@ -37,11 +38,13 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
|
|
|
37
38
|
|
|
38
39
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
39
40
|
|
|
41
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
42
|
+
|
|
40
43
|
# Subagent Execute
|
|
41
44
|
|
|
42
45
|
## Node Goal
|
|
43
46
|
|
|
44
|
-
This node parallelizes execution by delegating independent tasks (marked `parallel="true"` in TASK.md) to separate subagents. Each subagent loads the full `flow-comet-dev` protocol and operates within its task's `read_files`/`write_files` boundaries. This node produces handoff evidence for each delegated task and marks them done in TASK.md after all subagents complete. It exists to exploit parallelism when tasks have no file conflicts.
|
|
47
|
+
This node parallelizes execution by delegating independent tasks (marked `parallel="true"` in TASK.md) to separate subagents. Each subagent loads the full `flow-comet-dev` protocol and operates within its task's `read_files`/`write_files` boundaries. This node produces handoff evidence for each delegated task and marks them done in TASK.md after all subagents complete. It exists to exploit parallelism when tasks have no file conflicts. On Codex, whose native subagent shape the guard model does not yet cover, this node's current support surface delivers serially through the `execute` node instead (see the platform notes above).
|
|
45
48
|
|
|
46
49
|
Division of labor (pass-based collaboration): this node handles parallel delegation (`parallel="true"` tasks whose dependencies are satisfied — all of them dispatched concurrently within a pass) and may be entered multiple times across passes: each pass delegates every currently eligible parallel task, serial tasks are digested by the `execute` node between passes, and the node counts as complete only when no dependency-satisfied parallel task and no serial task remains. The `execute` node handles serial delegation (non-parallel tasks, one at a time). Both share the same delegation evidence library (handoff recorded under subagent-execute evidence). Sequence shape is not this node's concern: all-parallel, all-serial, serial→parallel, parallel→serial, and any mixed interleaving are all legal (legality depends only on an acyclic `depends_on` graph whose references all exist; cycles and missing dependencies are already intercepted at the plan exit with recovery guidance), and any sequence reaching this node is digested pass by pass by multi-pass routing along the dependency topology.
|
|
47
50
|
|
|
@@ -49,7 +52,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
49
52
|
|
|
50
53
|
### 协调者禁令(最高优先级)
|
|
51
54
|
|
|
52
|
-
|
|
55
|
+
主会话是协调者,不是执行者。禁止在主会话直接修改源码或执行实现。源码只能委托子代理完成,**委托形态按平台**:**CC = 用 `Agent` 工具的 `isolation: "worktree"` 委托**;**dsh = 直接委托平台进程内子代理(无需隔离区)**;**Codex = 本节点当前支持面下不派遣并行子代理,任务逐个走 `execute` 节点串行交付**(原生多代理为平台已启用能力,未覆盖属机制缺口而非平台边界,见上方「Codex 平台事实与 flow-comet 当前支持面」段)。子代理派发失败时,主会话**不得接管实现**——记录当前任务为 BLOCKED 并走 Recovery。协调者只允许更新:TASK.md(标记 done)、`<task>-SUMMARY.md`、handoff evidence(workflow-handoff.mjs result)。
|
|
53
56
|
|
|
54
57
|
### 受控重入打开的修复场景(archive 源)
|
|
55
58
|
|
|
@@ -60,7 +63,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
60
63
|
- `.specs/<change-id>/TASK.md` must exist with at least one task marked `parallel="true"` and `status="pending"`.
|
|
61
64
|
- `.specs/<change-id>/DESIGN.md` or `DESIGN-lite.md` must exist.
|
|
62
65
|
- `.specs/LESSONS.md` must exist (or be created).
|
|
63
|
-
-
|
|
66
|
+
- Delegation capability, split by platform: **Claude Code** requires the `Agent` tool (the platform creates the worktree automatically, and subagents are delegated with `isolation: "worktree"`); **dsh** requires the platform's in-process delegation capability (subagents carry `delegationDepth > 0`, share the workspace, and need no isolation directory); **Codex** has a real, default-enabled native multi-agent capability — its regular usage is the interactive CLI — but flow-comet's guard/whitelist/isolation model does not yet cover that native subagent shape. Until the contract that follows a probe covering interactive sessions and native subagents is settled, this node does not dispatch parallel subagents on Codex and delivers serially through the `execute` node — a current support-surface limit, not a platform boundary. A manually created `git worktree` is not a supported path (see the "出路" section above).
|
|
64
67
|
|
|
65
68
|
### Steps
|
|
66
69
|
|
|
@@ -88,7 +91,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
88
91
|
- Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
|
|
89
92
|
- **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
90
93
|
|
|
91
|
-
3. **Delegate to subagents**(平台相关——强制隔离的要求只对 CC 成立,见下): **Claude Code 平台**:所有并行子代理**必须**使用 `Agent` 工具的 `isolation: "worktree"`,**禁止共享 cwd 直接委托**——hook 白名单依赖 worktree 隔离:守卫对归一化后位于 `.claude/worktrees/**`(worktree 隔离区)的写入直接放行(`file_path` 与 Bash 命令两条判定路径同语义),共享 cwd 的子代理写入落在该区之外,会被 subagent-execute 协调者白名单误拦。**Codex
|
|
94
|
+
3. **Delegate to subagents**(平台相关——强制隔离的要求只对 CC 成立,见下): **Claude Code 平台**:所有并行子代理**必须**使用 `Agent` 工具的 `isolation: "worktree"`,**禁止共享 cwd 直接委托**——hook 白名单依赖 worktree 隔离:守卫对归一化后位于 `.claude/worktrees/**`(worktree 隔离区)的写入直接放行(`file_path` 与 Bash 命令两条判定路径同语义),共享 cwd 的子代理写入落在该区之外,会被 subagent-execute 协调者白名单误拦。**dsh 平台**:直接委托平台进程内子代理——写入守卫按会话身份分派(子代理 `delegationDepth > 0` 直接放行、项目内任意路径可写(含 gitignored)),**无需隔离区**;同一工作区的并行子代理会看到彼此未提交中间态,靠 `write_files` 边界互斥与提交时点作相互隔离纪律。**Codex 平台**:原生多代理(`multi_agent`,默认启用)不在本节点当前委托面内——现有守卫 / 白名单 / 隔离模型未覆盖该原生子代理形态(机制缺口,非平台边界);在探针结论决定的后续契约落地前,本节点在 Codex 上**不派遣并行子代理**:任务逐个走 `execute` 节点串行交付。`isolation: "worktree"` 是 CC 的 `Agent` 工具能力,手工 `git worktree add <任意路径>` **不是受支持路径**、不得作为绕过手段;**不得用 File API 直写等规避通道代替**(绕过写入防线不是受支持路径)。Each subagent (CC / dsh):
|
|
92
95
|
- Reads TASK.md for its specific task block.
|
|
93
96
|
- Executes the full TDD protocol (RED/GREEN/REFACTOR). **纯文档/纯配置任务无生产代码可测时,`redEvidence` 与 `greenEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态**(guard W1-D 接受此形状;不得伪造测试输出)。
|
|
94
97
|
- Greps existing abstractions (R6.4).
|
|
@@ -7,6 +7,8 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 plan 节点提供 flow-kit 的 TASK 拆解流程。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/3-task.md` 并按其执行。关键步骤:
|
|
@@ -15,12 +17,14 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
15
17
|
2. **拆解原则**:
|
|
16
18
|
- 大小:fresh context 2~10 分钟可完成
|
|
17
19
|
- 粒度:按文件冲突切(垂直切片),不按层切
|
|
18
|
-
- 并行标记 `[P]
|
|
19
|
-
-
|
|
20
|
+
- 并行标记 `[P]`:只给本波确有并发同伴、且 write_files 互不重叠的任务;孤立任务一律串行——「互不冲突」只是必要条件,不等于应标 `[P]`
|
|
21
|
+
- **同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务
|
|
22
|
+
- **[P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行串行任务的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口;共享工作区以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为相互隔离纪律
|
|
23
|
+
- 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;唯一硬性拦截是依赖环(如 A→B→A,规划出口 BLOCKED 并附恢复指引——调整涉环任务的 depends_on 后重新 exit 即可通过),跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
|
|
20
24
|
- 依赖:`depends_on: <task-id>`
|
|
21
25
|
3. **每任务 7 字段**:id / name / read_files / write_files / action / verify / done
|
|
22
26
|
- **write_files 必须包含关联测试文件**:若任务修改组件/函数,且有关联测试直接 import 其本地导出(如 `src/**/__tests__/*.test.ts` 从组件文件 import),该测试文件**必须纳入该任务 write_files**。否则组件删除本地导出/改 import 后,关联测试会编译失败或断言失效(实测:改组件时破坏了关联测试文件)。
|
|
23
|
-
4.
|
|
27
|
+
4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P],孤立任务一律串行;flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
|
|
24
28
|
5. **XML 格式**:便于 AI 解析与执行
|
|
25
29
|
|
|
26
30
|
## 产物
|
|
@@ -7,6 +7,8 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 review 节点提供 flow-kit 的 5 轮测试金字塔。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/5-test.md` 并按其执行。
|
|
@@ -26,6 +26,8 @@ This node performs the final integration verification: running all automated tes
|
|
|
26
26
|
|
|
27
27
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
28
28
|
|
|
29
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
30
|
+
|
|
29
31
|
### Prerequisites
|
|
30
32
|
|
|
31
33
|
- `.specs/<change-id>/REVIEW.md` must exist (from review node).
|
|
@@ -50,7 +52,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
50
52
|
3. **Failure diagnosis**: For any failure (automated test or UAT):
|
|
51
53
|
- Switch to "Diagnose sub-role" — identify root cause, not symptom.
|
|
52
54
|
- Produce fix-plan: append to TASK.md 的 `## Fix 任务` 段 as numbered fix tasks with full 7 fields and verify command — 禁止文件尾追加.
|
|
53
|
-
- Follow the
|
|
55
|
+
- Follow the「修复回路状态机路径」section below: home back to execute, run its four exit gates, then return to verify.
|
|
54
56
|
- Re-run verification after fix, then run verify's own exit gates.
|
|
55
57
|
|
|
56
58
|
4. **Auto-retry limit (R2.6)**: verify 失败自动重试 ≤ 3 次(机器计数 verifyFailures);第 4 次失败必须暂停问用户「继续修 / 停止」。Do not auto-retry beyond 3 times.
|
|
@@ -83,7 +85,7 @@ This node is truly done when:
|
|
|
83
85
|
- **Agent thought**: "Auto-retry 4th time, maybe it'll work now." **Actual risk**: On the 4th failure (R2.6 violation), the problem is likely systematic, not transient. Must pause and ask the user「继续修 / 停止」.
|
|
84
86
|
- **Agent thought**: "Fix the failure directly, no need for a fix task." **Actual risk**: Bypassing the fix-task -> execute -> re-verify cycle means the fix is not properly tracked or tested. Must go through the proper loop.
|
|
85
87
|
|
|
86
|
-
##
|
|
88
|
+
## 修复回路状态机路径
|
|
87
89
|
|
|
88
90
|
review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
|
|
89
91
|
|
|
@@ -91,10 +93,10 @@ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周
|
|
|
91
93
|
2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
|
|
92
94
|
3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
|
|
93
95
|
4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
|
|
94
|
-
- **guard exit 回源审计行语义(Fix vs RETURN
|
|
96
|
+
- **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
|
|
95
97
|
5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
|
|
96
98
|
- **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
|
|
97
|
-
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED
|
|
99
|
+
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
98
100
|
|
|
99
101
|
**由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
|
|
100
102
|
|
|
@@ -174,6 +176,6 @@ If the script prints `SKILL: flow-comet-archive`, load that Skill next.
|
|
|
174
176
|
2. Read `.specs/<change-id>/UAT.md` — check which items have results.
|
|
175
177
|
3. If UAT.md exists with all items passing, verification is done.
|
|
176
178
|
4. If UAT.md has failures, check if fix tasks were generated in TASK.md.
|
|
177
|
-
5. If fix tasks exist but have not gone through the execute lifecycle, follow the
|
|
179
|
+
5. If fix tasks exist but have not gone through the execute lifecycle, follow the「修复回路状态机路径」section below: home back to execute, run its four exit gates, then return to verify and run verify's exit gates.
|
|
178
180
|
6. Count previous auto-retries (from UAT.md / machine-counted verifyFailures) to enforce R2.6 limit.
|
|
179
181
|
7. Resume from the first incomplete verification step.
|
package/README.md
CHANGED
|
@@ -28,111 +28,70 @@
|
|
|
28
28
|
<p align="center">
|
|
29
29
|
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
30
30
|
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
|
|
31
|
-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.
|
|
32
|
-
</p>
|
|
33
|
-
|
|
34
|
-
<p align="center">
|
|
35
|
-
<em>The <code>comet</code> badge links to the Comet project — flow-comet itself no longer reads any Comet files (see ADR-009).</em>
|
|
31
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.1-blue.svg" alt="Version" /></a>
|
|
36
32
|
</p>
|
|
37
33
|
|
|
38
34
|
---
|
|
39
35
|
|
|
40
|
-
## Why
|
|
41
|
-
|
|
42
|
-
If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a **verifiable deterministic state machine**:
|
|
43
|
-
|
|
44
|
-
- **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
|
|
45
|
-
- **Protocol-driven** — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see [Custom Protocols](docs/PROTOCOL.md))
|
|
46
|
-
- **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
|
|
47
|
-
- **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
|
|
48
|
-
- **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
|
|
49
|
-
|
|
50
36
|
## Quick Start
|
|
51
37
|
|
|
52
|
-
|
|
38
|
+
Three steps, run from your project directory:
|
|
53
39
|
|
|
54
40
|
```bash
|
|
55
41
|
# 1. Install the CLI globally (Node.js 18+)
|
|
56
42
|
npm install -g flow-comet
|
|
57
43
|
|
|
58
|
-
# 2.
|
|
44
|
+
# 2. Go to your project
|
|
59
45
|
cd <your project>
|
|
46
|
+
|
|
47
|
+
# 3. Install flow-comet into it
|
|
60
48
|
fcomet init
|
|
61
49
|
```
|
|
62
50
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
On an interactive terminal, the first run prompts for the platform with a direction-key multi-select (arrow keys + space to toggle, Enter to confirm; the default is Claude Code) — `@clack/prompts` is the primary path, with an automatic readline number/comma multi-select fallback when the dependency is not installed, offline, or stdin has no raw mode (`FLOW_COMET_FORCE_READLINE=1` forces the fallback for testing); for a non-interactive pick, add `--platform codex` / `--platform dsh` / `--platform claude-code,dsh` (comma-separated) / `--platform all`.
|
|
66
|
-
|
|
67
|
-
**Updating**: a global package upgrade does not touch projects that are already installed — re-run `fcomet init` in each project to pick up the new files. And because an npm install has no git history to derive a development marker from, the version marker it writes (`<project>/.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/…` for Codex, `.dsh/skills/…` for dsh) is the release version shipped inside the package; the `<release>-<n>-g<hash>` form appears only for installs run from a repository clone that has git and tags.
|
|
51
|
+
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal the first run asks which platform to set up; for a non-interactive pick use `--platform claude-code`, `--platform codex`, `--platform dsh`, a comma-separated combination such as `--platform claude-code,dsh`, or `--platform all`. Re-running the same command updates an existing install and is idempotent. Upgrading the global package only replaces the CLI — run `fcomet init` in a project again to refresh that project's copy.
|
|
68
52
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
The installer also ensures `flow-kit` in the target project: when missing it clones the upstream and checks out the locked snapshot `9b5dda7`; an existing upstream clone is only inspected (current HEAD vs the locked snapshot is reported, read-only); a same-name non-clone directory is skipped with guidance; a network failure warns and continues; purge never touches it.
|
|
72
|
-
|
|
73
|
-
The same installer also runs straight from a repository clone, with no global package — that is the path this repository's own workflow and its distribution to other projects use (Option B in the installation guide):
|
|
53
|
+
**Verify**:
|
|
74
54
|
|
|
75
55
|
```bash
|
|
76
|
-
|
|
77
|
-
|
|
56
|
+
fcomet --version # the installed CLI version
|
|
57
|
+
cat .claude/skills/flow-comet/INSTALLED_VERSION # the version written into this project
|
|
78
58
|
```
|
|
79
59
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
cd <your project>
|
|
84
|
-
fcomet init --platform dsh
|
|
85
|
-
```
|
|
60
|
+
The installer writes the marker to `.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/...` for Codex and `.dsh/skills/...` for dsh. It records the version the copy came from: the package's release version for an npm install, or the repository's `git describe` value for an install run from a clone (that form carries a `-<n>-g<hash>` suffix when the clone is ahead of its tag).
|
|
86
61
|
|
|
87
|
-
|
|
62
|
+
## Use it
|
|
88
63
|
|
|
89
|
-
|
|
90
|
-
# 3. Open your project in a new Claude Code session and run:
|
|
91
|
-
/flow-comet
|
|
92
|
-
# (Codex: invoke the skill in a Codex session — `/use flow-comet` or natural language;
|
|
93
|
-
# same workflow, see Installation → "Using flow-comet on Codex")
|
|
94
|
-
```
|
|
64
|
+
Open a session in your project and invoke the workflow:
|
|
95
65
|
|
|
96
|
-
|
|
66
|
+
- **Claude Code** — `/flow-comet`
|
|
67
|
+
- **Codex** — invoke the skill (`/use flow-comet`, or simply ask for the flow-comet workflow in natural language)
|
|
68
|
+
- **DeepSeek Harness** — invoke the `flow-comet` skill
|
|
97
69
|
|
|
98
|
-
|
|
70
|
+
The first call confirms scope, then creates the branch for the change, initializes the state and enters the first node, producing that change's `CHANGE.md` / `REQUIREMENT.md` under `.specs/`. Every later stage is routed automatically — you only answer the decision points (scope, tech stack, destructive changes, review findings, archive confirmation). On first use in a project it detects a missing project context and offers to build one from your existing documents before starting.
|
|
99
71
|
|
|
100
|
-
|
|
72
|
+
To see where it is, just ask it — or inspect it from the command line with `status` and `next` in the project (the per-platform paths are in [Installation](docs/INSTALLATION.md)).
|
|
101
73
|
|
|
102
|
-
-
|
|
103
|
-
- **[Custom protocols](docs/PROTOCOL.md)** — compose any installed skill into a custom workflow via `/flow-comet-compose`
|
|
104
|
-
- **[Core mechanisms](docs/MECHANISM.md)** — state machine, three defense layers, guard validation, execution model
|
|
105
|
-
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** — BLOCKED/WARN messages and their fixes
|
|
74
|
+
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is added to `.specs/CHANGELOG.md`. The node-by-node walkthrough — including what the workflow runs underneath, and how to drive a node by hand when you need to — is in [Usage](docs/USAGE.md).
|
|
106
75
|
|
|
107
|
-
|
|
76
|
+
## Pick a platform
|
|
108
77
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
78
|
+
| Platform | Skills install to | Hook / bridge | First use |
|
|
79
|
+
|---|---|---|---|
|
|
80
|
+
| Claude Code (default) | `.claude/skills/` | `settings.local.json` → `hooks.PreToolUse` | the workspace must be trusted; headless sessions need that trust pre-accepted |
|
|
81
|
+
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs — see [Installation](docs/INSTALLATION.md) |
|
|
82
|
+
| DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
|
|
113
83
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
```mermaid
|
|
117
|
-
graph LR
|
|
118
|
-
O[open] --> D[design] --> P[plan] --> E[execute]
|
|
119
|
-
E <--> SE[subagent-execute]
|
|
120
|
-
E --> R[review] --> V[verify] --> A[archive]
|
|
121
|
-
style O fill:#e8f5e9
|
|
122
|
-
style D fill:#e3f2fd
|
|
123
|
-
style P fill:#fff3e0
|
|
124
|
-
style E fill:#fce4ec
|
|
125
|
-
style SE fill:#f3e5f5
|
|
126
|
-
style R fill:#e8eaf6
|
|
127
|
-
style V fill:#e0f7fa
|
|
128
|
-
style A fill:#f1f8e9
|
|
129
|
-
```
|
|
84
|
+
Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
|
|
130
85
|
|
|
131
|
-
|
|
86
|
+
## Why
|
|
132
87
|
|
|
133
|
-
|
|
88
|
+
If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a **verifiable deterministic state machine**:
|
|
134
89
|
|
|
135
|
-
|
|
90
|
+
- **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
|
|
91
|
+
- **Protocol-driven** — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see [Custom Protocols](docs/MECHANISM.md#custom-protocols))
|
|
92
|
+
- **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
|
|
93
|
+
- **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
|
|
94
|
+
- **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
|
|
136
95
|
|
|
137
96
|
## Why flow-comet
|
|
138
97
|
|
|
@@ -191,55 +150,22 @@ processor-pipeline/ (archived change, full artifact set)
|
|
|
191
150
|
|
|
192
151
|

|
|
193
152
|
|
|
194
|
-
##
|
|
195
|
-
|
|
196
|
-
| Project | Role | Relationship to flow-comet |
|
|
197
|
-
|---------|------|---------------------------|
|
|
198
|
-
| [flow-kit](https://github.com/rihebty/flow-kit) | Methodology & artifact system (9-stage flow, `.specs/` templates, R1-R8 rules) | **Dependency** — flow-comet is its automation layer; artifacts and rules come from flow-kit |
|
|
199
|
-
| [Comet](https://github.com/rpamis/comet) | Skill Creator ecosystem (bundle authoring, hook-guard pattern, state machine) | **Mechanism source** — flow-comet borrows Comet's mechanism patterns extensively (workflow-protocol as source of truth, script-owned state, guard gates, hook interception); **runtime optional** (copy install needs no Comet CLI). Details in [Ecosystem](docs/ECOSYSTEM.md) |
|
|
200
|
-
| **Comet Classic** | Comet's classic workflow (OpenSpec + Superpowers) | **Not a dependency** — flow-comet is an independent workflow-kernel; state does not interoperate with classic (own `.flow-comet/flow-comet-state.json` + file-derived routing) |
|
|
201
|
-
|
|
202
|
-
## Directory Structure
|
|
203
|
-
|
|
204
|
-
```
|
|
205
|
-
flow-comet/
|
|
206
|
-
├── .flow-comet/ ★ authoritative source (skills/ + rules/)
|
|
207
|
-
├── scripts/ prepare-env installer (npm bin: fcomet / flow-comet)
|
|
208
|
-
├── docs/
|
|
209
|
-
│ ├── examples/ workflow artifact examples
|
|
210
|
-
│ ├── ECOSYSTEM.md roles of flow-kit & Comet, borrowing boundaries
|
|
211
|
-
│ ├── INSTALLATION.md installation guide
|
|
212
|
-
│ ├── USAGE.md usage guide
|
|
213
|
-
│ ├── PROTOCOL.md custom protocol guide
|
|
214
|
-
│ ├── MECHANISM.md core mechanisms (behavior layer)
|
|
215
|
-
│ ├── TROUBLESHOOTING.md failure diagnosis
|
|
216
|
-
│ └── VERSIONS.md versioning & compatibility
|
|
217
|
-
└── CHANGELOG.md Keep a Changelog style
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
## Tech Stack
|
|
153
|
+
## Relationship to the upstream project
|
|
221
154
|
|
|
222
|
-
|
|
223
|
-
|-------|------------|
|
|
224
|
-
| Runtime | Node.js ≥ 18 (ESM); third-party dependency: `@clack/prompts` (pinned exact version, installer TTY multi-select only — automatic readline fallback when unavailable) |
|
|
225
|
-
| Platform | Claude Code (default — skills, `.claude/` installation, hooks); Codex (`.agents/skills/`, AGENTS.md managed rules, PreToolUse write interception); DeepSeek Harness (`.dsh/skills/flow-comet` project-level skill, AGENTS.md managed rules, bridge loader + `tools/pre-execute` interception) |
|
|
226
|
-
| Methodology | [flow-kit](https://github.com/rihebty/flow-kit) (artifacts, rules, templates) |
|
|
155
|
+
flow-comet automates the methodology of [flow-kit](https://github.com/rihebty/flow-kit) — its stages, artifacts, rules and templates are inherited rather than reinvented. The two projects do not share files: flow-kit is consumed as a read-only, pinned dependency, and this repository vendors a copy only as a format baseline. What may be borrowed, and how divergences are declared, is written down in [CONTRIBUTING.md](CONTRIBUTING.md#borrowing-boundary).
|
|
227
156
|
|
|
228
157
|
## Documentation
|
|
229
158
|
|
|
230
|
-
| Document |
|
|
231
|
-
|
|
232
|
-
| [
|
|
233
|
-
| [
|
|
234
|
-
| [
|
|
235
|
-
| [
|
|
236
|
-
| [
|
|
237
|
-
| [
|
|
238
|
-
| [
|
|
239
|
-
| [
|
|
240
|
-
| [Changelog](CHANGELOG.md) | Version history (Keep a Changelog) |
|
|
241
|
-
| [Security](SECURITY.md) | How to report vulnerabilities |
|
|
242
|
-
| [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines |
|
|
159
|
+
| Document | What it is the single place for |
|
|
160
|
+
|---|---|
|
|
161
|
+
| [Installation](docs/INSTALLATION.md) | Prerequisites, the four install options, platform choice, verification, and reset (purge is delete-and-rebuild, not uninstall) |
|
|
162
|
+
| [Usage](docs/USAGE.md) | The 8-node workflow, the per-node lifecycle and its commands, artifacts, branch mode, execution modes, user entry points |
|
|
163
|
+
| [Core Mechanisms](docs/MECHANISM.md) | The behaviour contract, the three defense layers, guard validation, and custom protocols |
|
|
164
|
+
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Symptoms grouped by where they bite: installation, first run, a stuck node, platform |
|
|
165
|
+
| [Versions](docs/VERSIONS.md) | Version semantics, the nine version surfaces, and the release checklist |
|
|
166
|
+
| [CHANGELOG](CHANGELOG.md) | Per-version history |
|
|
167
|
+
| [Contributing](CONTRIBUTING.md) | Contribution flow and the borrowing boundary |
|
|
168
|
+
| [Security](SECURITY.md) | Reporting a vulnerability |
|
|
243
169
|
|
|
244
170
|
## Contributing
|
|
245
171
|
|
|
@@ -247,7 +173,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
247
173
|
|
|
248
174
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
249
175
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
250
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
176
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 275 SCENARIOS PASSED`
|
|
251
177
|
4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
|
|
252
178
|
|
|
253
179
|
CI enforces the repository conventions automatically on every PR and push (regression, PR discipline, version consistency, dead links). Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-comet",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.1",
|
|
4
4
|
"description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
package/scripts/dsh-bridge.mjs
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
// 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
|
|
29
29
|
// ESM 模块导出 { name, apply },ctx 由 dsh 注入。
|
|
30
30
|
//
|
|
31
|
-
// BRIDGE_VERSION: 1.6.
|
|
31
|
+
// BRIDGE_VERSION: 1.6.1
|
|
32
32
|
|
|
33
33
|
import { spawn } from 'node:child_process';
|
|
34
34
|
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
@@ -40,7 +40,7 @@ import path from 'node:path';
|
|
|
40
40
|
// 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
|
|
41
41
|
// bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
|
|
42
42
|
export const name = 'dsh-flow-comet-bridge';
|
|
43
|
-
export const version = '1.6.
|
|
43
|
+
export const version = '1.6.1';
|
|
44
44
|
|
|
45
45
|
// guard 在项目内的相对路径常量(随 skill 包分发)。
|
|
46
46
|
const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
|