flow-comet 1.6.2 → 1.6.4
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/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +64 -46
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
- package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +18 -28
- package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
- package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +266 -25
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +6 -6
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +67 -16325
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1030 -0
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
- package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
- package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
- package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +815 -0
- package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
- package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
- package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +614 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +553 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +837 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +404 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +302 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +141 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +700 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +106 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +189 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1441 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1228 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2484 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +73 -1077
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +966 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1388 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1364 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1484 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +14 -1
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +58 -6692
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +151 -2428
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +116 -9
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +29 -2086
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
- package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -3
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -6
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
- package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
- package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
- package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +3 -3
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
- package/README.md +53 -70
- package/package.json +3 -2
- package/scripts/dsh-bridge.mjs +59 -26
- package/scripts/lib/installer-cleanup.mjs +152 -0
- package/scripts/lib/installer-flowkit.mjs +119 -0
- package/scripts/lib/installer-hooks.mjs +363 -0
- package/scripts/lib/installer-loader.mjs +220 -0
- package/scripts/lib/installer-migrate.mjs +236 -0
- package/scripts/lib/installer-platforms.mjs +314 -0
- package/scripts/prepare-env.mjs +36 -1164
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
|
@@ -15,12 +15,23 @@ 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
|
-
>
|
|
19
|
-
>
|
|
20
|
-
>
|
|
21
|
-
>
|
|
22
|
-
>
|
|
23
|
-
>
|
|
18
|
+
> **平台事实与判级口径(证据与过程记录)**:Codex 原生多代理 `multi_agent` 为 stable、默认启用,「Codex 不能委派 / 不使用并行委托」**不是平台事实**——该**机制缺口**已由身份分派(载荷 `agent_id`)关闭(**三平台均可并行委派,差异只在谁建树**);三平台通道对照表、逐平台载荷字段与判级口径(证实 / 推翻 / 未覆盖)、已知边界、旧结论留档、headless 子面实测订正见 `../flow-comet/reference/platform-facts.md`:**要判定某平台的能力边界、或要引用某条平台结论时读它。**
|
|
19
|
+
> **并行安全四属性契约**:契约对象是**四属性**,不是 worktree——`worktree` 只是属性①「写权限」的**实现之一**,不是契约本身;「一律 worktree」的口号已作废(本仓决策:契约对象 = 四属性,worktree 降为实现之一)。三平台在同一判据下平行对等,**唯一差异是「谁建树」**。
|
|
20
|
+
>
|
|
21
|
+
> | # | 属性 | 含义 | 满足形态 |
|
|
22
|
+
> |---|------|------|----------|
|
|
23
|
+
> | ① | **写权限** | 每个写者必须有一条被守卫认可的写入通道 | **身份分派**(CC / Codex 载荷含 `agent_id` ⇒ 子代理语义;dsh 桥接以环境变量 `FLOW_COMET_AGENT_DEPTH` 透传正整数身份深度,**并同时注入桥接通道标记 `FLOW_COMET_AGENT_DEPTH_SOURCE`——守卫要求标记与深度同时在场才接受该通道**)——**worktree 只是本属性的实现之一**,不是必须;**最小保护集除外**:身份在场时 `.flow-comet/flow-comet-state.json` 与 `../flow-comet/reference/workflow-protocol.json` 仍受拦(三平台一致 BLOCKED) |
|
|
24
|
+
> | ② | **提交隔离** | 提交只含自己 `write_files` 的字面路径 | 提交面 pathspec 纪律五要素(见 Guidance 同名小节) |
|
|
25
|
+
> | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 新 change BLOCKED / 旧 change WARN;全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
|
|
26
|
+
> | ④ | **集成纪律** | 机制选择 / 顺序 / 审计 / 冲突处置四项均有明文规则 | 集成纪律四要素(见 Guidance 同名小节) |
|
|
27
|
+
>
|
|
28
|
+
> **写面含 gitignored 面的任务(四属性映射 · 与其他任务同一判据)**:任务 `write_files` 全为 gitignored 字面路径时,四属性的满足方式不变——① **写权限**仍走**身份通道**(载荷 `agent_id` / 环境变量身份深度 ⇒ 子代理语义放行,项目内任意路径可写(含 gitignored);gitignored 只是路径属性,不是通道差异);② **提交隔离**走既有 **`noCommit` 资格**(request 按 `.gitignore` 命中记 `noCommit:true` ⇒ 任务零提交,「提交只含自己 `write_files` 的字面路径」由**无提交**满足,不是放宽校验;资格 fail-closed:glob / `..` 越界 / 非 git 仓 / tracked 文件 / 链接逃逸一律不授予,result 时刻按同一判据重验,失败即撤销资格);③④ 与其他任务同形(同一时刻单写者 + 集成四要素)。**并行 × 零提交**因此合法:任务可标 `parallel="true"` 并被并行委派,出口校验按 request 的 `noCommit` 资格豁免缺 `commitHash`。
|
|
29
|
+
> **留痕的边界(诚实声明 · 与 `directOverride` / `completedChecks` / `reentryAuthorization` 同族)**:留痕记录的是「**发生过委派**」,**不是**对执行者身份的物理证明——`handoffRequests` / `handoffResult` 只证明协调者写下过 request 与 result 两条记录,不证明写入确实由子代理完成;与 `completedChecks` 只能记录声明、`directOverride` 只能记录授权、`reentryAuthorization` 只能记录授权源同理。声明与事实不符属流程违规,验收以 transcript 可见的委派触发为准。
|
|
30
|
+
>
|
|
31
|
+
> **dsh 平台委托方式(实测核对)**:dsh 的子代理是平台**进程内子代理**(不创建独立工作区)——写入守卫按**会话身份分派**:桥接**不再短路**,而是把身份深度以环境变量 `FLOW_COMET_AGENT_DEPTH` **连同通道标记 `FLOW_COMET_AGENT_DEPTH_SOURCE`** 透传给守卫(**身份与最小保护集的整条判定统一由守卫拥有**,单一实现;守卫要求标记与深度同时在场才接受该通道——CC / Codex 生成的 hook 直接调守卫、不走桥接,继承来的深度变量不构成身份);身份深度为正整数 ⇒ 放行(**最小保护集除外**)、**项目内任意路径可写(含 gitignored)**,因此**无需隔离区**;直接委托即可,不需要 worktree(**无需隔离区 ≠ 无需边界**:`write_files` 互斥与提交时点纪律仍是硬前置)。**通用边界**:同一工作区内的并行子代理会看到彼此未提交的中间态——任务的 `write_files` 边界与提交时点即相互隔离纪律(本节点第 1 步的 write_files 互斥检查因此仍是硬前置)。
|
|
32
|
+
>
|
|
33
|
+
> **受支持路径(三平台同一判据,差异只在谁建树)**:① **CC 平台**——直接委托子代理(守卫按身份分派放行);`Agent` 工具的 `isolation: "worktree"` 是属性①的一种实现(**非强制**,见步骤 3);② **dsh 平台**——直接委托平台进程内子代理(守卫按身份分派放行,**无需隔离区**;保持 `write_files` 边界与提交时点纪律);③ **Codex 平台**——直接委托原生子代理(`spawn_agent` 等,守卫按身份分派放行;默认共享工作区,保持 `write_files` 边界与提交时点纪律)。**建树选择的适用面**:协调者显式 `git worktree add <路径>`(手工建树)**是受支持的建树选择**——在委派 prompt 里指定 `workdir`,写入由身份通道放行(原生子代理无自动建树);**以建树绕过边界**不受支持——用独立树规避协调者禁令 / 最小保护集 / `write_files` 互斥与提交时点纪律 / handoff 与 Return Contract 证据,或把 worktree 当作四属性的替代品。headless 子面实测见 `../flow-comet/reference/platform-facts.md`(仅 `codex exec`,不得外推)。
|
|
34
|
+
> **不提供/不使用规避通道**:绕开守卫命令级检测的写法(如用 Python `open()` 等 File API 直写)**不是受支持路径**——它绕过的是写入防线本身(防线失效时无拦截、无记录),与三层防御的设计相反。需要越出边界时一律走上面的受支持路径,或如实上报 BLOCKED,**不得以更换工具形态绕过**。handoff 记录(workflow-handoff request/result)与 Return Contract 校验机制不变。
|
|
24
35
|
|
|
25
36
|
## Guidance
|
|
26
37
|
|
|
@@ -44,7 +55,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
44
55
|
|
|
45
56
|
## Node Goal
|
|
46
57
|
|
|
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.
|
|
58
|
+
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. All three platforms (Claude Code / Codex / dsh) can delegate in parallel under one identity-based criterion; the only difference is who creates the tree (Claude Code may create one via `isolation: "worktree"`; Codex and dsh share the workspace). The contract object is the four parallel-safety attributes — worktree isolation is one optional implementation of attribute ①, not a requirement (see the four-attribute contract and the platform channel table above).
|
|
48
59
|
|
|
49
60
|
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.
|
|
50
61
|
|
|
@@ -52,27 +63,56 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
52
63
|
|
|
53
64
|
### 协调者禁令(最高优先级)
|
|
54
65
|
|
|
55
|
-
|
|
66
|
+
主会话是协调者,不是执行者。禁止在主会话直接修改源码或执行实现。源码只能委托子代理完成,**委托形态按平台(差异只在谁建树)**:**CC = 直接委托子代理**(`isolation: "worktree"` 是属性①的可选实现,非强制);**dsh = 直接委托平台进程内子代理(无需隔离区;无需隔离区 ≠ 无需边界)**;**Codex = 直接委托原生子代理(`spawn_agent` 等,默认共享工作区)**——三平台同一身份判据放行,见上方「并行安全四属性契约」;三平台通道对照表与平台判级口径见 `../flow-comet/reference/platform-facts.md`。子代理派发失败时,主会话**不得接管实现**——记录当前任务为 BLOCKED 并走 Recovery。协调者只允许更新:TASK.md(标记 done)、`<task>-SUMMARY.md`、handoff evidence(workflow-handoff.mjs result)。
|
|
67
|
+
|
|
68
|
+
### 提交面 pathspec 纪律(要点 · 全文见 `../flow-comet/reference/commit-discipline.md`)
|
|
69
|
+
|
|
70
|
+
**适用条件**:并发写者共处一个工作树时(CC 非 worktree 委托 / Codex 共享工作区 / dsh 进程内子代理)本条生效;**各自独立工作区(worktree 等)内的局部 `reset` / `clean` 不在禁令内**——但只要本趟有**任一**共享工作区的写者,本条即覆盖整个并行趟。
|
|
71
|
+
|
|
72
|
+
五要素(缺一不可):
|
|
73
|
+
|
|
74
|
+
1. **`git add -- <自己字面路径>`**:逐条字面路径(取自本任务 `write_files`),禁用 `.` / `-A` / `-u` 等宽泛形态。
|
|
75
|
+
2. **`git commit -- <同一路径>`**:路径集与上一步**逐字一致**——提交只含自己的文件。
|
|
76
|
+
3. **锁失败重试**:并发提交会撞 `index.lock` / `cannot lock ref`,**失败即重试**,不得因此改用宽泛命令。
|
|
77
|
+
4. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:它们作用于整个共享工作区。
|
|
78
|
+
5. **为什么**:并发写者共享**同一索引与工作树**,宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 还会直接破坏同伴的未提交工作。
|
|
79
|
+
|
|
80
|
+
**并行波次另加两条**:禁用 `git commit --amend`(HEAD 会被并行写者推进——确需修正必须**先断言 `git rev-parse HEAD` 等于自己刚提交的哈希**,否则改用**新提交追加**);**误改后的自救通道**是第 4 条的定向例外——先断言 HEAD 即被误改的那次提交,再 `git reset --soft <自己的父提交>`(**只用 `--soft`**),最后以 **pathspec** 重建自己的提交;**无合法修复通道时人会暗改**(见 ADR-013 记录的同型教训)。
|
|
81
|
+
|
|
82
|
+
> **要判定提交边界、撞上锁或误改要收拾时读 `../flow-comet/reference/commit-discipline.md`**:五要素逐条判据、命令完整形态与实测依据在该文件。
|
|
83
|
+
|
|
84
|
+
### 集成纪律(要点 · 全文见 `../flow-comet/reference/commit-discipline.md`)
|
|
85
|
+
|
|
86
|
+
四要素:
|
|
87
|
+
|
|
88
|
+
1. **机制选择**:优先 **`git merge --no-ff`**(保留父子关系、可审计;comet 先例:集成用 `--no-ff`、交付用 `--ff-only`);冲突难解时**降级 `git cherry-pick` 并强制记因**。
|
|
89
|
+
2. **顺序(确定性规则)**:按 `depends_on` 的**拓扑序**(被依赖者先入),同一拓扑层内按 **task id 升序**——**不得依赖书写顺序** / 提交到达顺序 / 完成先后等运行期不确定量。
|
|
90
|
+
3. **审计留痕**:每次集成输出一行 `INTEGRATE: <task-id> <commitHash> → <集成提交>`(降级路径记降级原因),映射记入该趟流程记录;**判级**:审计行是**执行纪律**(review 把关),本节点不声称存在机械门禁校验它。
|
|
91
|
+
4. **冲突处置(两类分别动作)**:**机械冲突**(不改用户可见行为)执行者**可自行解决**,解决后必须跑**合并后验证**并在审计行记因;**语义冲突**(两侧对同一行为 / 契约 / 接口给出不同语义)**必须中止集成并上抛**(记 BLOCKED + 恢复指引,由协调者 / 用户裁决)——**不得**由执行者自行拍板。
|
|
92
|
+
|
|
93
|
+
> **要在集成前定规则、或遇冲突 / 降级要判定时读 `../flow-comet/reference/commit-discipline.md`**:四要素的完整判据与 comet 先例在该文件。
|
|
56
94
|
|
|
57
95
|
### 受控重入打开的修复场景(archive 源)
|
|
58
96
|
|
|
59
|
-
缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `execute` / `review` / `verify
|
|
97
|
+
缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `execute` / `review` / `verify`,再按常规委托与出口流程完成修复。命令:`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:` 行与 `REASON: <text>` 行(与 `FIX-BATCH` / `RETURN` 行三态可区分)。归档移动已发生或 change 已 `completed` ⇒ 重入 BLOCKED(走人工处置或新 change,**不得静默跳过**);重入只改工作归属——不写闭合标记、不跳过本节点入口 / 出口门禁,重入后仍按本节点常规流程校验委托证据与 write_files 边界。
|
|
98
|
+
|
|
99
|
+
> **要核对授权留痕 / 轮次与续轮审计 / 备份指纹 / 归档侧重入边界时读 `../flow-comet/reference/fix-loop.md`**:受控重入的完整规格在该文件。
|
|
60
100
|
|
|
61
101
|
### Prerequisites
|
|
62
102
|
|
|
63
103
|
- `.specs/<change-id>/TASK.md` must exist with at least one task marked `parallel="true"` and `status="pending"`.
|
|
64
104
|
- `.specs/<change-id>/DESIGN.md` or `DESIGN-lite.md` must exist.
|
|
65
105
|
- `.specs/LESSONS.md` must exist (or be created).
|
|
66
|
-
- Delegation capability, split by platform: **Claude Code** requires the `Agent` tool (
|
|
106
|
+
- Delegation capability, split by platform: **Claude Code** requires the `Agent` tool (subagents are delegated with it; `isolation: "worktree"` is one optional implementation of attribute ①, not a requirement); **dsh** requires the platform's in-process delegation capability (subagents carry an identity depth > 0, share the workspace, and need no isolation directory); **Codex** requires the platform's native multi-agent capability (real, stable and default-enabled — its regular usage is the interactive CLI — and its subagents share the workspace by default). All three platforms delegate under the same identity criterion (payload `agent_id` for Claude Code / Codex; the bridge-forwarded identity signal for dsh), so the only difference is who creates the tree. A manually created `git worktree` **is a supported tree-creation choice** (see the "受支持路径" section above): point the delegation prompt at its `workdir` and the write is admitted through the identity channel (native subagents do not create a tree automatically). What is **not** supported is **using a tree to bypass the boundaries** — evading the coordinator prohibition / the minimum protection set / `write_files` mutual exclusion and commit-timing discipline / handoff and Return Contract evidence, or treating the worktree as a substitute for the four attributes.
|
|
67
107
|
|
|
68
108
|
### Steps
|
|
69
109
|
|
|
70
|
-
0.
|
|
71
|
-
- ① `git status --short`:change 工件(`.specs/<change-id>/`)**必须已 commit
|
|
110
|
+
0. **委托前检查清单(必做——走 worktree 隔离形态时,未 commit 的工件不会被 worktree 子代理看到,曾导致子代理空上下文运行)**:
|
|
111
|
+
- ① `git status --short`:change 工件(`.specs/<change-id>/`)**必须已 commit**——**走 worktree 隔离形态时**(CC `isolation: "worktree"`),未 commit 的工件对 worktree 子代理不可见(harness 从已提交 HEAD 创建 worktree);共享工作区形态(CC 非 worktree 委托 / Codex / dsh)无此限制,但**内联上下文仍是推荐做法**
|
|
72
112
|
- ② `git log --oneline -1`:确认 HEAD 位置(change 分支)
|
|
73
|
-
- ③ 委托 prompt **必须内联任务块全文 + 相关 AC**(worktree 基线可能不是 change 分支——harness
|
|
113
|
+
- ③ 委托 prompt **必须内联任务块全文 + 相关 AC**(worktree 基线可能不是 change 分支——harness 行为不可控;共享工作区形态虽可见工件,内联仍是唯一可靠路径)
|
|
74
114
|
- ④ **子代理会话 Skill 工具可用性(委托前探测)**:委托 prompt 必须要求子代理开工前确认本会话是否具备 Skill 工具——具备时用 Skill 工具加载 `flow-comet-dev`;不可用时按 Read 加载节点 SKILL + `flow-kit/prompts/4-dev.md` 协议执行,并在 Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`(SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入)。**禁止把 Read 声称为已注入**;委托 prompt 未写明该口径 = 委托前检查未完成,不得发出委托
|
|
75
|
-
- **Red Flag**:worktree
|
|
115
|
+
- **Red Flag**:worktree 工件不可见 / 基线不确定时**禁止继续委托**——先 commit 或内联上下文
|
|
76
116
|
- 委托后:子代理回报 commitHash 后校验存在性(`git cat-file -e <commitHash>`,workflow-handoff result 已有 W2-D git show 校验兜底)
|
|
77
117
|
|
|
78
118
|
1. **Identify parallel tasks**: Read TASK.md and find all tasks with `parallel="true"` and `status="pending"`. Verify they are genuinely independent (no file conflicts between them — check `write_files` do not overlap).
|
|
@@ -91,7 +131,10 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
91
131
|
- Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
|
|
92
132
|
- **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
93
133
|
|
|
94
|
-
|
|
134
|
+
- **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit -- <同一路径>`,锁失败重试,禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。
|
|
135
|
+
- **集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`;降级 `cherry-pick` 必须记因;集成顺序按 `depends_on` 拓扑序 + 同层 task id 升序;冲突按**机械冲突 / 语义冲突**两类分别处置(后者必须中止并上抛)。
|
|
136
|
+
|
|
137
|
+
3. **Delegate to subagents**(三平台同一判据,差异只在谁建树): **Claude Code 平台**:直接委托子代理——守卫按**身份判据优先于路径判据**放行(载荷含 `agent_id` ⇒ 子代理语义);`Agent` 工具的 `isolation: "worktree"` 是属性①的一种实现(**可选,非强制**,见「并行安全四属性契约」);`.claude/worktrees/**` 路径前缀通道仍为兼容通道。**dsh 平台**:直接委托平台进程内子代理——守卫按会话身份分派(身份深度为正整数 ⇒ 放行(**最小保护集除外**)、项目内任意路径可写(含 gitignored)),**无需隔离区**;同一工作区的并行子代理会看到彼此未提交中间态,靠 `write_files` 边界互斥与提交时点作相互隔离纪律(**无需隔离区 ≠ 无需边界**)。**Codex 平台**:直接委托原生子代理(`spawn_agent` 等)——守卫按身份分派放行(真机实测:载荷含 `agent_id` / `agent_type`);默认**共享工作区**,同样靠 `write_files` 边界互斥与提交时点纪律。**建树选择的适用面**:协调者显式 `git worktree add <路径>`(手工建树)**是受支持的建树选择**——在委派 prompt 里指定 `workdir`,写入由身份通道放行(原生子代理无自动建树);**以建树绕过边界**不受支持——用独立树规避协调者禁令 / 最小保护集 / `write_files` 互斥与提交时点纪律 / handoff 与 Return Contract 证据,或把 worktree 当作四属性的替代品。**不得用 File API 直写等规避通道代替**(绕过写入防线不是受支持路径)。Each subagent (all three platforms):
|
|
95
138
|
- Reads TASK.md for its specific task block.
|
|
96
139
|
- Executes the full TDD protocol (RED/GREEN/REFACTOR). **纯文档/纯配置任务无生产代码可测时,`redEvidence` 与 `greenEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态**(guard W1-D 接受此形状;不得伪造测试输出)。
|
|
97
140
|
- Greps existing abstractions (R6.4).
|
|
@@ -164,7 +207,7 @@ node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry subagent-execute
|
|
|
164
207
|
|
|
165
208
|
## Skill Implementation
|
|
166
209
|
|
|
167
|
-
The subagent-execute node identifies all `parallel="true"` pending tasks in TASK.md, creates handoff requests via `workflow-handoff.mjs`, and delegates each to
|
|
210
|
+
The subagent-execute node identifies all `parallel="true"` pending tasks in TASK.md, creates handoff requests via `workflow-handoff.mjs`, and delegates each to a fresh-context subagent (identity-based write channel on all three platforms; worktree isolation is one optional implementation of attribute ①) with `flow-comet-dev` loaded. Each subagent executes the full dev protocol independently, follows the commit-pathspec discipline (five elements) and the integration discipline (four elements) recorded above, and the orchestrator collects evidence and marks tasks done after all subagents complete.
|
|
168
211
|
|
|
169
212
|
## Required Skill Calls
|
|
170
213
|
|
|
@@ -20,9 +20,10 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
20
20
|
- 并行标记 `[P]`:只给本波确有并发同伴、且 write_files 互不重叠的任务;孤立任务一律串行——「互不冲突」只是必要条件,不等于应标 `[P]`
|
|
21
21
|
- **同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务
|
|
22
22
|
- **[P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行串行任务的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口;共享工作区以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为相互隔离纪律
|
|
23
|
-
-
|
|
23
|
+
- **四属性可满足(并行安全契约)**:标 `[P]` 的任务须确认**并行安全四属性**(① 写权限 · ② 提交隔离 · ③ 验证隔离 · ④ 集成纪律)可满足——worktree 只是「① 写权限」的实现之一,不是前提;四属性的**含义与三平台通道**以入口册「并行委派契约(四属性)· 三平台通道」为单一来源,本册只点名不复述
|
|
24
|
+
- 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;硬性拦截(规划出口 BLOCKED,附恢复指引):任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见第 3 条;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)——任一项不成立即被拦(读写重叠仅 WARN),修正后重新 exit 即可通过;跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
|
|
24
25
|
- 依赖:`depends_on: <task-id>`
|
|
25
|
-
3. **每任务 7 字段**:
|
|
26
|
+
3. **每任务 7 字段**:name / read_files / write_files / action / verify / done / depends_on——与 plan 出口「新格式任务的 7 字段在场」判据同一集合;`id` **不是字段**,它是 `<task>` 元素的属性(`<task id="T01" parallel="true" status="pending">`);`depends_on` 元素必在(无依赖写空元素)
|
|
26
27
|
- **write_files 必须包含关联测试文件**:若任务修改组件/函数,且有关联测试直接 import 其本地导出(如 `src/**/__tests__/*.test.ts` 从组件文件 import),该测试文件**必须纳入该任务 write_files**。否则组件删除本地导出/改 import 后,关联测试会编译失败或断言失效(实测:改组件时破坏了关联测试文件)。
|
|
27
28
|
4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P],孤立任务一律串行;flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
|
|
28
29
|
5. **XML 格式**:便于 AI 解析与执行
|
|
@@ -13,7 +13,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
13
13
|
|
|
14
14
|
## 关键检查
|
|
15
15
|
|
|
16
|
-
- `flow-kit/reference/ui-anti-patterns.md`(
|
|
16
|
+
- `flow-kit/reference/ui-anti-patterns.md`(111 行 · 77 非空行,可全读)
|
|
17
17
|
- `flow-kit/reference/ui-aesthetics.md`(仅查「5 维度」+ 「给 AI 的模板」节)
|
|
18
18
|
- 装了 ui-ux-pro-max / impeccable 时优先用它们
|
|
19
19
|
|
|
@@ -31,7 +31,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
31
31
|
| 段在场,无**结构形态**的「不适用」标记 | 前端 change | 必须加载本技能并产出 `.specs/<change-id>/UI-DESIGN.md` |
|
|
32
32
|
| 段缺席 | 非前端 change | 同上按非前端处理——但缺席不留可读证据,故约定保留段并以结构形态标注「不适用」(见 `flow-comet-change` 的标记约定) |
|
|
33
33
|
|
|
34
|
-
**「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` /
|
|
34
|
+
**「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、行尾,或下列标点之一:`,。;、,;.::!!??…—()()【】「」『』“”"'`——**只有这一组**,组外的标点如 `/`、`-` 不算边界),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
|
|
35
35
|
|
|
36
36
|
上游的语义信号(`flow-kit/prompts/2a-ui-design.md` 与 `4-dev` 的判定):任务触碰 `.css` / `.scss` / `.tsx` / `.vue` / `.jsx` / `.html` / `.svelte` / 设计 token / 用户可见文案,或 `action` 含 button / 颜色 / 字体 / 卡片 / 布局 / 动画 / 主题 等关键词。
|
|
37
37
|
|
|
@@ -39,7 +39,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
39
39
|
|
|
40
40
|
## 强制等级(design 节点 · guarded)
|
|
41
41
|
|
|
42
|
-
`design` 节点对本技能的绑定等级 = **guarded**(见
|
|
42
|
+
`design` 节点对本技能的绑定等级 = **guarded**(见 `../flow-comet/reference/workflow-protocol.json` 的 `requiredSkillCalls`)。前端 change 的完整动作是**先加载、再声明、后干活**:
|
|
43
43
|
|
|
44
44
|
1. 用 Skill 工具加载本技能(只读取 SKILL.md 文件不叫加载);
|
|
45
45
|
2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md`;
|
|
@@ -57,13 +57,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
57
57
|
|
|
58
58
|
4. **Auto-retry limit (R2.6)**: verify 失败自动重试 ≤ 3 次(机器计数 verifyFailures);第 4 次失败必须暂停问用户「继续修 / 停止」。Do not auto-retry beyond 3 times.
|
|
59
59
|
|
|
60
|
-
5. **LESSONS nomination**: Before archiving, scan all `*-SUMMARY.md` "decisions and deviations" sections and any `*-PROGRESS.md` "excluded solutions" sections.
|
|
61
|
-
- Debugging/trial-and-error took > 30 minutes -> nominate.
|
|
62
|
-
- Error is not task-specific, other tasks would hit it too -> nominate.
|
|
63
|
-
- Reasonable probability of retry within 6 months -> nominate.
|
|
64
|
-
- Otherwise do not nominate (avoid pollution).
|
|
65
|
-
- Add qualifying lessons to `.specs/LESSONS.md` with next L-NNN number — 新条目编号 = 当前最大编号 + 1,插入 `## 条目区` 末尾(文件内升序,继续现有编号),**禁止文件尾追加与乱序插入**.
|
|
66
|
-
- Check existing active lessons for superseded/deprecated status.
|
|
60
|
+
5. **LESSONS nomination**: Before archiving, scan all `*-SUMMARY.md` "decisions and deviations" sections and any `*-PROGRESS.md` "excluded solutions" sections. 判据(三条判据 + 不提名兜底 + 编号续接与插入位置 + superseded 状态更新)见 `flow-comet-integration` 册的「LESSONS 提名」段——该段是判据的**单一权威**,本册不复述、以该册为准;提名结果按该册写回 `.specs/LESSONS.md`。
|
|
67
61
|
|
|
68
62
|
The full verification protocol, UAT format, and failure diagnosis are in:
|
|
69
63
|
- `flow-kit/prompts/7-integration.md` (INTEGRATION phase, verification + UAT sections)
|
|
@@ -87,18 +81,15 @@ This node is truly done when:
|
|
|
87
81
|
|
|
88
82
|
## 修复回路状态机路径
|
|
89
83
|
|
|
90
|
-
|
|
84
|
+
verify 失败或发现缺陷后的修复必须回到 `execute` 节点生命周期内完成——**禁止驻留源节点「顺手修完」**(会被 BLOCKED)。要点:
|
|
91
85
|
|
|
92
|
-
1. **追加 Fix
|
|
93
|
-
2. **受控归位 execute
|
|
94
|
-
3.
|
|
95
|
-
4.
|
|
96
|
-
|
|
97
|
-
5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
|
|
98
|
-
- **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
|
|
99
|
-
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
86
|
+
1. **追加 Fix 任务**:把修复任务(完整任务字段)追加到 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内,**禁止文件尾追加**;任务集修订须在 `entry` 之前完成。
|
|
87
|
+
2. **受控归位 execute**:跑 `workflow-state next` 或 `workflow-guard entry execute` 触发受控归位(审计行 `FIX-BATCH: 归位`;`next` 同时输出 `NODE: execute`);用 `status` 确认 `stateCurrentNode` 已是 `execute` 再开工,未归位不得硬开工。
|
|
88
|
+
3. **跑完 execute 四类出口**:`record execute` → `exit execute --apply`——全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致,任一缺失即 BLOCKED;通过后引擎把当前节点推回 verify。
|
|
89
|
+
4. **回源节点跑出口**:回到源节点后跑该节点出口门禁(`entry <源节点>` → `exit <源节点> --apply`),通过后继续 verify → archive 的正常路由,必要时进入下一轮 Fix 闭环。
|
|
90
|
+
5. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
100
91
|
|
|
101
|
-
|
|
92
|
+
**何时读完整规格**:要核对完整判据——Fix 任务与任务集签名的时序、受控归位的完整判定条件、`FIX-BATCH` / `RETURN` 审计行三态语义与回源节点的回程豁免、绕过的失败面与恢复指引——读 `../flow-comet/reference/fix-loop.md`(**当你 verify 失败、要开修复回路把工作退回 execute 生命周期时读它**)。
|
|
102
93
|
|
|
103
94
|
## Entry Check
|
|
104
95
|
|
package/README.md
CHANGED
|
@@ -4,17 +4,15 @@
|
|
|
4
4
|
|
|
5
5
|
</div>
|
|
6
6
|
|
|
7
|
-
<h1 align="center">flow-comet</h1>
|
|
8
|
-
|
|
9
7
|
<p align="center">
|
|
10
|
-
<
|
|
11
|
-
<br />
|
|
12
|
-
<em>For AI coding workflows — deterministic state machine · protocol-driven · guard-validated · subagent-isolated</em>
|
|
8
|
+
<img src="assets/readme/hero.svg" width="100%" alt="flow-comet — the project mark beside the name, and the engine's eight nodes drawn as a rail in which every transition carries a gate" />
|
|
13
9
|
</p>
|
|
14
10
|
|
|
15
11
|
<p align="center">
|
|
16
|
-
<a href="
|
|
17
|
-
<a href="
|
|
12
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat" alt="License: MIT" /></a>
|
|
13
|
+
<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>
|
|
14
|
+
<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 status" /></a>
|
|
15
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.4-blue.svg" alt="Version 1.6.4" /></a>
|
|
18
16
|
</p>
|
|
19
17
|
|
|
20
18
|
<p align="center">
|
|
@@ -22,13 +20,6 @@
|
|
|
22
20
|
<a href="https://github.com/openai/codex"><img src="https://img.shields.io/badge/Codex-10A37F?style=flat&logoColor=white" alt="Codex" /></a>
|
|
23
21
|
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-4D6BFE?style=flat&logoColor=white" alt="DeepSeek Harness" /></a>
|
|
24
22
|
<a href="https://github.com/rihebty/flow-kit"><img src="https://img.shields.io/badge/flow--kit-4CAF50?style=flat" alt="flow-kit" /></a>
|
|
25
|
-
<a href="https://github.com/rpamis/comet"><img src="https://img.shields.io/badge/comet-4CAF50?style=flat" alt="comet" /></a>
|
|
26
|
-
</p>
|
|
27
|
-
|
|
28
|
-
<p align="center">
|
|
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
|
-
<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.2-blue.svg" alt="Version" /></a>
|
|
32
23
|
</p>
|
|
33
24
|
|
|
34
25
|
---
|
|
@@ -48,7 +39,7 @@ cd <your project>
|
|
|
48
39
|
fcomet init
|
|
49
40
|
```
|
|
50
41
|
|
|
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
|
|
42
|
+
`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, a run without `--platform` asks which platform to set up — the arrow-key selector pre-selects the platforms it detects, and the fallback prompt takes the detected platform as its default (Claude Code when several traces are present); 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.
|
|
52
43
|
|
|
53
44
|
**Verify**:
|
|
54
45
|
|
|
@@ -71,84 +62,76 @@ The first call confirms scope, then creates the branch for the change, initializ
|
|
|
71
62
|
|
|
72
63
|
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)).
|
|
73
64
|
|
|
74
|
-
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is
|
|
65
|
+
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is appended at the top of `.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).
|
|
75
66
|
|
|
76
67
|
## Pick a platform
|
|
77
68
|
|
|
78
69
|
| Platform | Skills install to | Hook / bridge | First use |
|
|
79
70
|
|---|---|---|---|
|
|
80
71
|
| 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
|
|
72
|
+
| 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 |
|
|
82
73
|
| DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
|
|
83
74
|
|
|
84
75
|
Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
|
|
85
76
|
|
|
86
|
-
##
|
|
77
|
+
## Real-run artifacts
|
|
87
78
|
|
|
88
|
-
|
|
79
|
+
A complete 8-node run leaves the artifact trail below — [a real archived change](docs/examples/processor-pipeline/) from the end-to-end test project (2026-08-13), kept in this repository as the quality reference: CHANGE / REQUIREMENT / DESIGN / TASK / six-section summaries / REVIEW with disposition markers / TEST / UAT / KNOWN-ISSUES / skill-load declaration markers.
|
|
89
80
|
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
81
|
+
```
|
|
82
|
+
processor-pipeline/ (archived change, full artifact set)
|
|
83
|
+
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
84
|
+
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
85
|
+
├── REVIEW.md (findings with disposition markers)
|
|
86
|
+
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
87
|
+
├── KNOWN-ISSUES.md
|
|
88
|
+
└── .skill-loads/ (11 skill-load declaration markers)
|
|
89
|
+
```
|
|
95
90
|
|
|
96
|
-
|
|
91
|
+
Two captures from real sessions of this project, unedited: a workflow skill loading normally more than four hours in, and the end of a five-hour run whose verify exit had already executed the test commands.
|
|
97
92
|
|
|
98
|
-
|
|
93
|
+
<p align="center">
|
|
94
|
+
<img src="assets/readme/proof-board.png" width="100%" alt="Two terminal captures: a workflow skill loading four hours into a session, and the end of a five-hour run after verification" />
|
|
95
|
+
</p>
|
|
99
96
|
|
|
100
|
-
|
|
101
|
-
|---------|-------------|-----------|---------------------------|
|
|
102
|
-
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process + `.specs/` templates + R1-R8 rules, zero runtime | Humans load prompt files stage by stage; state flows through `.md` artifacts | **Dependency / base** — flow-comet is its automation layer; artifacts and rules fully inherited |
|
|
103
|
-
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding | `openspec/` directory, one proposal/specs/design/tasks per change, propose→apply→verify→archive | **Idea source + lighter alternative** — spec-first thinking fused into flow-kit; standalone use is lighter (no state machine, no stage gates) |
|
|
104
|
-
| **Superpowers** (obra) | Claude Code skill set + full dev methodology | Composable skills (brainstorm/plan/TDD/debug/review), triggered by context, enforced by instructions | **Idea source + partial overlap** — skill-based discipline relies on model compliance; flow-comet scripts and machine-verifies the same discipline |
|
|
105
|
-
| **comet** (rpamis) | Resumable long-task workflows + skill platform: protocol state machine, guard gates, hook interception | `/comet` routes by config; Classic = OpenSpec + Superpowers 5-stage state machine | **Mechanism source** — flow-comet borrows its mechanism shapes (protocol-as-truth, script-owned state, guard gates, hook whitelist) and drops its platform facilities (eval/publish); state does not interoperate with Comet Classic |
|
|
106
|
-
| **GSD** | Spec-driven development meta-prompt / context-engineering workflow | Milestones → slices → tasks; fresh context per stage with pre-inlined context; worktree isolation + UAT | **Idea source (same lane)** — fresh-context execution and stage gates align; no script state-machine routing, relies on prompt discipline |
|
|
107
|
-
| **spec-kit** (GitHub) | SDD toolkit: Spec → Plan → Tasks → Implement | Each stage feeds markdown artifacts to the next; task format with order IDs, parallel `[P]` markers, file paths | **Idea source (same lane)** — task-with-file-paths/parallel-marker shape is same-origin with flow-kit TASK; no stage-transition enforcement |
|
|
108
|
-
| **claude-task-master** | AI-driven task management (MCP + CLI) | PRD parsing → task decomposition → dependency graph → next-task orchestration | **Complement** — manages the task layer only (decomposition/ordering/dependencies), not stage gates, artifact validation, or write permissions |
|
|
97
|
+
## How it works
|
|
109
98
|
|
|
110
|
-
|
|
99
|
+
The process is flow-kit's nine stages; the engine runs them as eight nodes. CHANGE and REQUIREMENT are covered by `open`, TEST and REVIEW by `review`, and DEV runs as `execute` or `subagent-execute` depending on the execution mode. Every node's exit is validated before the next one opens — the `verify` exit really executes the commands in `TEST.md` — and each node's artifacts land under `.specs/<change-id>/`.
|
|
111
100
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| Validation | Humans eyeball artifacts against the rules; TEST.md commands "should" run | Guards enforce required artifacts/sections at every node entry/exit; verify actually executes the TEST.md commands and counts failures |
|
|
116
|
-
| Discipline enforcement | Rules are markdown text the model may ignore | Three defense layers: write whitelist physically blocks out-of-scope writes / coordinator prohibition / exit takeover detection |
|
|
117
|
-
| Recovery | Depends on conversation memory; progress is lost across sessions | File-as-truth: re-derive the node from `.specs/` and auto-correct state; any session resumes correctly |
|
|
118
|
-
| Parallel implementation | Humans coordinate multiple windows, easy to overstep | Subagents implement in isolated worktrees (coordinators cannot write source) and must return a verified contract (commit hash + evidence) |
|
|
119
|
-
| Decision burden | A confirmation point at every stage, humans answer everything | Decisions are classified (user-decided / auto-handled / stop conditions / manual handover); humans only intervene at key points (scope, tech stack, breaking changes, review findings, archive) |
|
|
101
|
+
<p align="center">
|
|
102
|
+
<img src="assets/readme/workflow.gif" width="100%" alt="An animated diagram mapping the nine flow-kit stages onto the engine's eight nodes: CHANGE and REQUIREMENT merge into open, TEST and REVIEW into review, DEV runs as execute or subagent-execute, and every transition carries a gate" />
|
|
103
|
+
</p>
|
|
120
104
|
|
|
121
|
-
|
|
105
|
+
Driving a node by hand, the artifacts each node produces, and the two command surfaces are documented in [Usage](docs/USAGE.md); what the engine guarantees and how a node's exit is validated are in [Core Mechanisms](docs/MECHANISM.md).
|
|
106
|
+
|
|
107
|
+
## Why flow-comet
|
|
122
108
|
|
|
123
109
|
1. **Discipline goes from "self-discipline" to "machine-checked"** — every stage entry/exit has script validation: artifacts complete, sections filled, verify commands actually run, tasks stay in bounds.
|
|
124
110
|
2. **No lost progress across sessions** — where you are is always derived from `.specs/` artifacts, never from conversation memory; reopen and continue from the right node.
|
|
125
|
-
3. **Implementation and coordination are
|
|
126
|
-
4. **The native automation layer for flow-kit** — not a re-invention: artifact formats, rules, and stages are identical to flow-kit; a flow-kit project upgrades to a machine-driven flow by installing flow-comet, no migration needed.
|
|
127
|
-
5. **Protocol-driven, minimal dependency, install-and-run** — the built-in 8-node flow works out of the box; any installed skill can be composed into a custom protocol on the same engine; Node.js 18+; the only third-party dependency is `@clack/prompts`, used exclusively by the installer's TTY multi-select (with an automatic readline fallback otherwise); one command installs it.
|
|
111
|
+
3. **Implementation and coordination are separated, and the separation is enforced** — implementation runs in fresh-context subagents that must return a verified contract; the guard decides by the caller's identity before it resolves any path, so an isolated worktree is one way to provide write permission rather than a requirement. The coordinator is banned from writing source, and writes outside the current node's scope are refused by the hook. The layers themselves are described in [Core Mechanisms](docs/MECHANISM.md).
|
|
128
112
|
|
|
129
|
-
|
|
113
|
+
### Related projects
|
|
130
114
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
processor-pipeline/ (archived change, full artifact set)
|
|
137
|
-
├── CHANGE.md / REQUIREMENT.md / DESIGN.md / TASK.md
|
|
138
|
-
├── T01~T06-SUMMARY.md (six-section summaries)
|
|
139
|
-
├── REVIEW.md (findings with disposition markers)
|
|
140
|
-
├── TEST.md / UAT.md (verify actually executes the test command)
|
|
141
|
-
├── KNOWN-ISSUES.md
|
|
142
|
-
└── .skill-loads/ (11 skill-load declaration markers)
|
|
143
|
-
```
|
|
115
|
+
<p align="center">
|
|
116
|
+
<img src="assets/readme/related-projects.svg" width="100%" alt="How flow-comet relates to the projects it is compared with: five sources aggregated through flow-kit, comet as an early mechanism reference that is now decoupled, and brooks-lint as an optional integration" />
|
|
117
|
+
</p>
|
|
144
118
|
|
|
145
|
-
|
|
119
|
+
| Project | What it is, and how it works | Relationship to flow-comet |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer and inherits its artifacts and rules; the projects below reached flow-comet through it. |
|
|
122
|
+
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding. One `proposal` / `specs` / `design` / `tasks` set per change under `openspec/`; the default profile runs propose → apply → sync → archive. | **Aggregated through flow-kit** (idea source). Standalone it stays lighter: no state machine, no gates. |
|
|
123
|
+
| **Superpowers** (obra) | Agentic skills framework plus a full development methodology, installed per harness across Claude Code, Codex, Cursor, Gemini CLI and more. Skills trigger by context and are enforced by instructions. | **Aggregated through flow-kit** (idea source, partial overlap). Discipline lives in skill text and relies on model compliance; flow-comet machine-checks the same discipline. |
|
|
124
|
+
| **comet** (rpamis) | Resumable long-running task workflow and skill platform: a five-stage state machine, stage guards, hook write-interception. `/comet` routes from config and defaults to its Native branch. | **Early mechanism reference, now decoupled.** The hook-injection shape and script-owned state came from here; the naming was decoupled and state does not interoperate. Only its Classic branch carries the OpenSpec + Superpowers lineage. |
|
|
125
|
+
| **GSD** | Spec-driven development meta-prompt and context-engineering workflow: milestones → phases → plans, a fresh context window per agent with scoped payloads, worktree isolation and a UAT gate. | **Aggregated through flow-kit** (idea source, same lane). Fresh-context execution and stage gates align; routing stays prompt-driven. |
|
|
126
|
+
| **spec-kit** (GitHub) | SDD toolkit: Specify → Plan → Tasks → Implement → Converge. Each stage feeds markdown artifacts to the next, with order ids, `[P]` parallel markers and file paths in the task block. | **Aggregated through flow-kit** (idea source, same lane). That task-block shape is what flow-kit's TASK template inherited; stage transitions are not enforced. |
|
|
127
|
+
| **claude-task-master** | AI-driven task management over MCP and a CLI: PRD parsing → task breakdown → dependency graph → next-task orchestration. Distributed under MIT with Commons Clause. | **Aggregated through flow-kit** (complement). Covers the task layer only: no stage gates, no artifact validation, no write permissions. |
|
|
128
|
+
| **brooks-lint** (hyhmrright) | Third-party review engine grounded in twelve classic engineering books: 6 production and 6 test decay risks, findings cited as Symptom → Source → Consequence → Remedy, a 0–100 health score and six modes. | **Optional integration (MIT, not a dependency).** Where installed, five of its six commands back the self-check and review rounds; absent, the workflow degrades along a declared fallback chain. |
|
|
146
129
|
|
|
147
|
-
|
|
130
|
+
**Fit**: flow-comet is built for long-running, multi-session development changes. The contract is the same on all three platforms — write permission, commit isolation, verification isolation and integration discipline — while the depth of testing differs per platform, and the per-platform coverage is stated in [Core Mechanisms](docs/MECHANISM.md#parallel-delegation). It is not a general CI/CD or project-management tool; other platforms (Gemini / Cursor) are not guaranteed.
|
|
148
131
|
|
|
149
|
-
|
|
132
|
+
## Recommended: brooks-lint
|
|
150
133
|
|
|
151
|
-
|
|
134
|
+
The quality checks are grounded in the decay-risk framework of [brooks-lint](https://github.com/hyhmrright/brooks-lint), a third-party (MIT) review engine that diagnoses code against twelve classic engineering books. Where it is installed, the per-task self-check, the review node's code-quality round and the test-quality check run through it, and the `health` side command folds its result into its report; where it is not, the workflow still completes along a declared fallback chain and says so. It is not a dependency and nothing needs configuring on the flow-comet side; its installer covers more platforms than this project does, with a different depth of verification per platform — the details are in [Installation](docs/INSTALLATION.md).
|
|
152
135
|
|
|
153
136
|
## Relationship to the upstream project
|
|
154
137
|
|
|
@@ -162,7 +145,7 @@ flow-comet automates the methodology of [flow-kit](https://github.com/rihebty/fl
|
|
|
162
145
|
| [Usage](docs/USAGE.md) | The 8-node workflow, the per-node lifecycle and its commands, artifacts, branch mode, execution modes, user entry points |
|
|
163
146
|
| [Core Mechanisms](docs/MECHANISM.md) | The behaviour contract, the three defense layers, guard validation, and custom protocols |
|
|
164
147
|
| [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
|
|
148
|
+
| [Versions](docs/VERSIONS.md) | Version semantics, the places that record the version, and the release checklist |
|
|
166
149
|
| [CHANGELOG](CHANGELOG.md) | Per-version history |
|
|
167
150
|
| [Contributing](CONTRIBUTING.md) | Contribution flow and the borrowing boundary |
|
|
168
151
|
| [Security](SECURITY.md) | Reporting a vulnerability |
|
|
@@ -173,13 +156,13 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
173
156
|
|
|
174
157
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
175
158
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
176
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
159
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 325 SCENARIOS PASSED`
|
|
177
160
|
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)
|
|
178
161
|
|
|
179
|
-
CI enforces the repository conventions automatically on every PR and push
|
|
162
|
+
CI enforces the repository conventions automatically on every PR and push: regression, installer reproducibility, workflow and bilingual-mirror quality, PR discipline, version consistency, and 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.
|
|
180
163
|
|
|
181
164
|
## License
|
|
182
165
|
|
|
183
166
|
[MIT](LICENSE) © 2026 baobaolaodie
|
|
184
167
|
|
|
185
|
-
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT)
|
|
168
|
+
flow-comet depends on [flow-kit](https://github.com/rihebty/flow-kit) (MIT). Its mechanism shapes were borrowed from [Comet](https://github.com/rpamis/comet) (MIT), which it does not depend on.
|
package/package.json
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-comet",
|
|
3
|
-
"version": "1.6.
|
|
3
|
+
"version": "1.6.4",
|
|
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": [
|
|
7
7
|
".flow-comet/skills",
|
|
8
8
|
".flow-comet/rules",
|
|
9
9
|
"scripts/prepare-env.mjs",
|
|
10
|
-
"scripts/dsh-bridge.mjs"
|
|
10
|
+
"scripts/dsh-bridge.mjs",
|
|
11
|
+
"scripts/lib"
|
|
11
12
|
],
|
|
12
13
|
"bin": {
|
|
13
14
|
"fcomet": "scripts/prepare-env.mjs",
|