flow-comet 1.6.0 → 1.6.2

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.
Files changed (43) hide show
  1. package/.flow-comet/skills/flow-comet/GUIDANCE.md +26 -5
  2. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  3. package/.flow-comet/skills/flow-comet/SKILL.md +51 -2
  4. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
  5. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
  6. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
  7. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
  8. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
  10. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
  11. package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
  12. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
  13. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
  14. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5499 -596
  15. package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
  16. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
  17. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
  18. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +58 -3
  19. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1024 -11
  20. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
  21. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +285 -227
  22. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +6 -4
  23. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +515 -31
  24. package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
  25. package/.flow-comet/skills/flow-comet-change/SKILL.md +13 -1
  26. package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -2
  27. package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
  28. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
  29. package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
  30. package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
  31. package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
  32. package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
  33. package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
  34. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
  35. package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
  36. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
  37. package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
  38. package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
  39. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +28 -3
  40. package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
  41. package/README.md +45 -119
  42. package/package.json +1 -1
  43. package/scripts/dsh-bridge.mjs +2 -2
@@ -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
- - 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一连续块;唯一硬性拦截是依赖环(如 A→B→A,规划出口 BLOCKED 并附恢复指引——调整涉环任务的 depends_on 后重新 exit 即可通过),跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
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` 并按其执行。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: flow-comet-ui-design
3
- description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens + 反 AI-slop 自检。仅前端项目触发。"
3
+ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens + 反 AI-slop 自检。前端 change 触发(结构级判据见内文),非前端 change 显式跳过。"
4
4
  ---
5
5
 
6
6
  # flow-kit UI-DESIGN Protocol
@@ -21,6 +21,31 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
21
21
 
22
22
  - `.specs/<change-id>/UI-DESIGN.md`(含 design tokens frontmatter)
23
23
 
24
- ## 触发范围
24
+ ## 触发与跳过(前端判据 · 结构级)
25
25
 
26
- 仅前端项目触发。非前端项目跳过。
26
+ 判据只看 `.specs/<change-id>/CHANGE.md` 的 `## 视觉调性` 段(段名基准取自 `flow-kit/templates/CHANGE.md`),不做语义判断——判据的实现方是 design 出口的适用性门控,本表只描述契约:
27
+
28
+ | `## 视觉调性` 段 | 判定 | 本技能动作 |
29
+ |---|---|---|
30
+ | 段在场,段内出现**结构形态**的「不适用」标记 | 非前端 change | **显式跳过**:不加载、不产出;design 出口打印 `UI-DESIGN: skipped(非前端)` 与命中片段后放行 |
31
+ | 段在场,无**结构形态**的「不适用」标记 | 前端 change | 必须加载本技能并产出 `.specs/<change-id>/UI-DESIGN.md` |
32
+ | 段缺席 | 非前端 change | 同上按非前端处理——但缺席不留可读证据,故约定保留段并以结构形态标注「不适用」(见 `flow-comet-change` 的标记约定) |
33
+
34
+ **「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不关闸,仍判前端。
35
+
36
+ 上游的语义信号(`flow-kit/prompts/2a-ui-design.md` 与 `4-dev` 的判定):任务触碰 `.css` / `.scss` / `.tsx` / `.vue` / `.jsx` / `.html` / `.svelte` / 设计 token / 用户可见文案,或 `action` 含 button / 颜色 / 字体 / 卡片 / 布局 / 动画 / 主题 等关键词。
37
+
38
+ 语义上判为前端、而 `## 视觉调性` 段已按结构形态标注「不适用」时:**回 open 阶段改段**再走本阶段——判据输入只有这一个段,不在 design / execute 里就地绕开它。反向同理:非前端 change 不要为了「保险」产出 UI-DESIGN.md。
39
+
40
+ ## 强制等级(design 节点 · guarded)
41
+
42
+ `design` 节点对本技能的绑定等级 = **guarded**(见 `reference/workflow-protocol.json` 的 `requiredSkillCalls`)。前端 change 的完整动作是**先加载、再声明、后干活**:
43
+
44
+ 1. 用 Skill 工具加载本技能(只读取 SKILL.md 文件不叫加载);
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`;
46
+ 3. 把 `required-skill:design.flow-comet-ui-design` 记进 design 节点的 evidence(`record` / handoff 载荷)。
47
+
48
+ design 出口的核对口径:
49
+
50
+ - **前端 change**:evidence 缺 `required-skill:design.flow-comet-ui-design` → 出口**不再自动补写**该条目,直接拦截(加载并声明后重试);缺 `.specs/<change-id>/UI-DESIGN.md` → 新 change **BLOCKED**,恢复两条路——补齐工件,或按结构形态在 `## 视觉调性` 段标注「不适用」改判非前端;旧 change 仅 **WARN** 渐进,不阻断。
51
+ - **非前端 change**:不要求 UI-DESIGN.md,也不要求上述声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行——**显式跳过,不是静默省略**。
@@ -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「Fix 批次状态机路径」section below: home back to execute, run its four exit gates, then return to verify.
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
- ## Fix 批次状态机路径
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)**:真实修复批次二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
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(存在未归位/未跑出口的 Fix 批次),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
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「Fix 批次状态机路径」section below: home back to execute, run its four exit gates, then return to verify and run verify's exit gates.
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.0-blue.svg" alt="Version" /></a>
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.2-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
- Requires [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) and [flow-kit](https://github.com/rihebty/flow-kit) in the target project (see [Installation](docs/INSTALLATION.md)).
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. Install flow-comet into your project, from the project directory
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
- The package ships two command names pointing at the same installer — `fcomet` (primary) and `flow-comet` (alias). The `init` token is optional whenever another argument expresses the intent (`fcomet --target <dir>` is equivalent to `fcomet init --target <dir>`), and `--target <dir>` is optional too (default: the current working directory); run with no arguments at all, the command prints its usage and exits non-zero instead of installing. `fcomet --version` prints the version of the installed CLI. Re-running the same command updates an existing install and is idempotent.
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
- By default the installer targets Claude Code (unchanged behavior). For Codex: `fcomet init --platform codex` — skills install to `.agents/skills/` (auto-discovered), orchestration rules are injected into an `AGENTS.md` managed block, and the write-guard hook intercepts Bash write commands via Codex's PreToolUse (trust the hook on first use: `/hooks`). For DeepSeek Harness: `fcomet init --platform dsh` — skills install to `.dsh/skills/flow-comet` (auto-discovered at rank 100, no restart), orchestration rules are injected into an `AGENTS.md` managed block, and a thin bridge loader is mounted globally in `$DSH_HOME` (see [Installation → Option D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform)). When run on an interactive terminal (TTY) without `--platform`, the installer prompts for the target platform with a multi-select (pre-checked from existing traces — default Claude Code — press Enter to accept); without a TTY (CI/scripts) existing `.claude/` / `.codex/` / `.dsh/` in the target project is detected, falling back to Claude Code.
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
- cd <flow-comet repo>
77
- node scripts/prepare-env.mjs --target <absolute path to your project>
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
- For DeepSeek Harness (dsh), install through the same installer — a dedicated dsh platform descriptor, with no separate plugin bundle:
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
- This installs the skill tree project-locally at `<project>/.dsh/skills/flow-comet` (dsh auto-discovers skills there at rank 100 without a restart — projects without that directory cannot see the skill, which makes activation naturally project-level), injects the orchestration rules into an `AGENTS.md` managed block (non-destructive merge), and mounts a thin bridge loader globally at `$DSH_HOME/plugins/dsh-flow-comet-bridge.mjs` with a managed block in `$DSH_HOME/cordis.patch.yml` (read-merge-write, preserves existing blocks such as dsh-skin, effective for all profiles). The bridge intercepts write tools via dsh's `tools/pre-execute` event. Interception only applies while a flow is running — in an idle session, writes outside the project root are not interrupted. Each install reports the dsh loader version transition (upgrade / downgrade / consistent) by comparing the embedded version stamp with the previously installed loader, and `workflow-state.mjs bridge-check` is a read-only health check with six states (healthy / file missing / not mounted / version skew / duplicate registration / not applicable). Minimum dsh `0.1.0-rc.6`. See [Installation → Option D](docs/INSTALLATION.md#option-d--deepseek-harness-dsh-platform) for the full dsh platform section.
62
+ ## Use it
88
63
 
89
- ```bash
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
- The first call confirms scope, then automatically creates the `change/<id>` branch, initializes state, enters the open node, and produces `CHANGE.md` / `REQUIREMENT.md`. Every subsequent stage is routed automatically — you only answer decision points (scope, tech stack, destructive changes, review findings, archive confirmation).
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
- On first use in a project, the workflow automatically detects whether a project context (`CONTEXT.md`) exists and prompts to initialize it when missing — existing AI-context documents (such as `CLAUDE.md` / `AGENTS.md`) are read and integrated with source attribution, and existing files are never modified. Projects with a fresh context run silently. No separate command to remember.
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
- ## Usage
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
- - **[8-node workflow](docs/USAGE.md)** — node-by-node responsibilities, branch mode, execution modes, decision points
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
- The entry point is the `/flow-comet` command; state is inspected and advanced from the command line (paths below assume the Claude Code install `.claude/skills/`; Codex installs to `.agents/skills/`, dsh to `.dsh/skills/` — see [Installation](docs/INSTALLATION.md)):
76
+ ## Pick a platform
108
77
 
109
- ```bash
110
- node .claude/skills/flow-comet/scripts/workflow-state.mjs status # current change + node
111
- node .claude/skills/flow-comet/scripts/workflow-state.mjs next # next node + skill
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
- ## Architecture
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
- The engine routes between nodes by deriving state from `.specs/` artifacts (determineNode), gated by guard exit validations.
86
+ ## Why
132
87
 
133
- ## What is flow-kit
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
- [flow-kit](https://github.com/rihebty/flow-kit) is a pure-Markdown development methodology that fuses mainstream AI coding workflows — [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), [spec-kit](https://github.com/github/spec-kit), [GSD](https://github.com/open-gsd/gsd-core), [gstack](https://github.com/garrytan/gstack), [claude-task-master](https://github.com/eyaltoledano/claude-task-master) — into its own 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) with `.specs/` artifact templates and R1-R8 behavior rules. No runtime, no CLI — clone it into a project and it defines *what to produce and what rules to follow*, but progress relies on human (and AI) discipline.
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
  ![Verification run](images/long-run-5h.png)
193
152
 
194
- ## Ecosystem
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
- | Layer | Technology |
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 | Description |
231
- |----------|-------------|
232
- | [Ecosystem](docs/ECOSYSTEM.md) | Roles of flow-kit & Comet, what flow-comet borrows and deliberately does not |
233
- | [Installation](docs/INSTALLATION.md) | Prerequisites, install options A–D (npm / prepare-env / manual copy / dsh), installation verification |
234
- | [Usage](docs/USAGE.md) | 8-node workflow, branch mode, execution modes, decision points |
235
- | [Custom Protocols](docs/PROTOCOL.md) | Compose skills into custom workflows |
236
- | [Core Mechanisms](docs/MECHANISM.md) | State machine, defense layers, guard validation |
237
- | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common errors and fixes |
238
- | [Versions](docs/VERSIONS.md) | SemVer policy, compatibility |
239
- | [Examples](docs/examples/) | Full workflow artifact examples |
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 267 SCENARIOS PASSED`
176
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 309 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.0",
3
+ "version": "1.6.2",
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": [
@@ -28,7 +28,7 @@
28
28
  // 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
29
29
  // ESM 模块导出 { name, apply },ctx 由 dsh 注入。
30
30
  //
31
- // BRIDGE_VERSION: 1.6.0
31
+ // BRIDGE_VERSION: 1.6.2
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.0';
43
+ export const version = '1.6.2';
44
44
 
45
45
  // guard 在项目内的相对路径常量(随 skill 包分发)。
46
46
  const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';