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.
- package/.flow-comet/skills/flow-comet/GUIDANCE.md +26 -5
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +51 -2
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
- package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
- package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5499 -596
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +58 -3
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1024 -11
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +285 -227
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +6 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +515 -31
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +13 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
- package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
- package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
- package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +28 -3
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
- package/README.md +45 -119
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
|
@@ -7,6 +7,8 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 plan 节点提供 flow-kit 的 TASK 拆解流程。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/3-task.md` 并按其执行。关键步骤:
|
|
@@ -15,12 +17,14 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
15
17
|
2. **拆解原则**:
|
|
16
18
|
- 大小:fresh context 2~10 分钟可完成
|
|
17
19
|
- 粒度:按文件冲突切(垂直切片),不按层切
|
|
18
|
-
- 并行标记 `[P]
|
|
19
|
-
-
|
|
20
|
+
- 并行标记 `[P]`:只给本波确有并发同伴、且 write_files 互不重叠的任务;孤立任务一律串行——「互不冲突」只是必要条件,不等于应标 `[P]`
|
|
21
|
+
- **同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务
|
|
22
|
+
- **[P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行串行任务的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口;共享工作区以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为相互隔离纪律
|
|
23
|
+
- 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;唯一硬性拦截是依赖环(如 A→B→A,规划出口 BLOCKED 并附恢复指引——调整涉环任务的 depends_on 后重新 exit 即可通过),跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
|
|
20
24
|
- 依赖:`depends_on: <task-id>`
|
|
21
25
|
3. **每任务 7 字段**:id / name / read_files / write_files / action / verify / done
|
|
22
26
|
- **write_files 必须包含关联测试文件**:若任务修改组件/函数,且有关联测试直接 import 其本地导出(如 `src/**/__tests__/*.test.ts` 从组件文件 import),该测试文件**必须纳入该任务 write_files**。否则组件删除本地导出/改 import 后,关联测试会编译失败或断言失效(实测:改组件时破坏了关联测试文件)。
|
|
23
|
-
4.
|
|
27
|
+
4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P],孤立任务一律串行;flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
|
|
24
28
|
5. **XML 格式**:便于 AI 解析与执行
|
|
25
29
|
|
|
26
30
|
## 产物
|
|
@@ -7,6 +7,8 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 review 节点提供 flow-kit 的 5 轮测试金字塔。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/5-test.md` 并按其执行。
|
|
@@ -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
|
|
55
|
+
- Follow the「修复回路状态机路径」section below: home back to execute, run its four exit gates, then return to verify.
|
|
54
56
|
- Re-run verification after fix, then run verify's own exit gates.
|
|
55
57
|
|
|
56
58
|
4. **Auto-retry limit (R2.6)**: verify 失败自动重试 ≤ 3 次(机器计数 verifyFailures);第 4 次失败必须暂停问用户「继续修 / 停止」。Do not auto-retry beyond 3 times.
|
|
@@ -83,7 +85,7 @@ This node is truly done when:
|
|
|
83
85
|
- **Agent thought**: "Auto-retry 4th time, maybe it'll work now." **Actual risk**: On the 4th failure (R2.6 violation), the problem is likely systematic, not transient. Must pause and ask the user「继续修 / 停止」.
|
|
84
86
|
- **Agent thought**: "Fix the failure directly, no need for a fix task." **Actual risk**: Bypassing the fix-task -> execute -> re-verify cycle means the fix is not properly tracked or tested. Must go through the proper loop.
|
|
85
87
|
|
|
86
|
-
##
|
|
88
|
+
## 修复回路状态机路径
|
|
87
89
|
|
|
88
90
|
review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
|
|
89
91
|
|
|
@@ -91,10 +93,10 @@ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周
|
|
|
91
93
|
2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
|
|
92
94
|
3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
|
|
93
95
|
4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
|
|
94
|
-
- **guard exit 回源审计行语义(Fix vs RETURN
|
|
96
|
+
- **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
|
|
95
97
|
5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
|
|
96
98
|
- **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
|
|
97
|
-
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED
|
|
99
|
+
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
98
100
|
|
|
99
101
|
**由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
|
|
100
102
|
|
|
@@ -174,6 +176,6 @@ If the script prints `SKILL: flow-comet-archive`, load that Skill next.
|
|
|
174
176
|
2. Read `.specs/<change-id>/UAT.md` — check which items have results.
|
|
175
177
|
3. If UAT.md exists with all items passing, verification is done.
|
|
176
178
|
4. If UAT.md has failures, check if fix tasks were generated in TASK.md.
|
|
177
|
-
5. If fix tasks exist but have not gone through the execute lifecycle, follow the
|
|
179
|
+
5. If fix tasks exist but have not gone through the execute lifecycle, follow the「修复回路状态机路径」section below: home back to execute, run its four exit gates, then return to verify and run verify's exit gates.
|
|
178
180
|
6. Count previous auto-retries (from UAT.md / machine-counted verifyFailures) to enforce R2.6 limit.
|
|
179
181
|
7. Resume from the first incomplete verification step.
|
package/README.md
CHANGED
|
@@ -28,111 +28,70 @@
|
|
|
28
28
|
<p align="center">
|
|
29
29
|
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
30
30
|
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI" /></a>
|
|
31
|
-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.
|
|
32
|
-
</p>
|
|
33
|
-
|
|
34
|
-
<p align="center">
|
|
35
|
-
<em>The <code>comet</code> badge links to the Comet project — flow-comet itself no longer reads any Comet files (see ADR-009).</em>
|
|
31
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.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
|
-
|
|
38
|
+
Three steps, run from your project directory:
|
|
53
39
|
|
|
54
40
|
```bash
|
|
55
41
|
# 1. Install the CLI globally (Node.js 18+)
|
|
56
42
|
npm install -g flow-comet
|
|
57
43
|
|
|
58
|
-
# 2.
|
|
44
|
+
# 2. Go to your project
|
|
59
45
|
cd <your project>
|
|
46
|
+
|
|
47
|
+
# 3. Install flow-comet into it
|
|
60
48
|
fcomet init
|
|
61
49
|
```
|
|
62
50
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
On an interactive terminal, the first run prompts for the platform with a direction-key multi-select (arrow keys + space to toggle, Enter to confirm; the default is Claude Code) — `@clack/prompts` is the primary path, with an automatic readline number/comma multi-select fallback when the dependency is not installed, offline, or stdin has no raw mode (`FLOW_COMET_FORCE_READLINE=1` forces the fallback for testing); for a non-interactive pick, add `--platform codex` / `--platform dsh` / `--platform claude-code,dsh` (comma-separated) / `--platform all`.
|
|
66
|
-
|
|
67
|
-
**Updating**: a global package upgrade does not touch projects that are already installed — re-run `fcomet init` in each project to pick up the new files. And because an npm install has no git history to derive a development marker from, the version marker it writes (`<project>/.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/…` for Codex, `.dsh/skills/…` for dsh) is the release version shipped inside the package; the `<release>-<n>-g<hash>` form appears only for installs run from a repository clone that has git and tags.
|
|
51
|
+
`fcomet` and `flow-comet` are two names for the same installer. The `init` token may be omitted whenever another argument expresses the intent (`fcomet --target <dir>`), and `--target` itself defaults to the current directory; called with no arguments at all the command prints its usage and exits non-zero instead of installing. On a terminal the first run asks which platform to set up; for a non-interactive pick use `--platform claude-code`, `--platform codex`, `--platform dsh`, a comma-separated combination such as `--platform claude-code,dsh`, or `--platform all`. Re-running the same command updates an existing install and is idempotent. Upgrading the global package only replaces the CLI — run `fcomet init` in a project again to refresh that project's copy.
|
|
68
52
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
The installer also ensures `flow-kit` in the target project: when missing it clones the upstream and checks out the locked snapshot `9b5dda7`; an existing upstream clone is only inspected (current HEAD vs the locked snapshot is reported, read-only); a same-name non-clone directory is skipped with guidance; a network failure warns and continues; purge never touches it.
|
|
72
|
-
|
|
73
|
-
The same installer also runs straight from a repository clone, with no global package — that is the path this repository's own workflow and its distribution to other projects use (Option B in the installation guide):
|
|
53
|
+
**Verify**:
|
|
74
54
|
|
|
75
55
|
```bash
|
|
76
|
-
|
|
77
|
-
|
|
56
|
+
fcomet --version # the installed CLI version
|
|
57
|
+
cat .claude/skills/flow-comet/INSTALLED_VERSION # the version written into this project
|
|
78
58
|
```
|
|
79
59
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
cd <your project>
|
|
84
|
-
fcomet init --platform dsh
|
|
85
|
-
```
|
|
60
|
+
The installer writes the marker to `.claude/skills/flow-comet/INSTALLED_VERSION` for Claude Code, `.agents/skills/...` for Codex and `.dsh/skills/...` for dsh. It records the version the copy came from: the package's release version for an npm install, or the repository's `git describe` value for an install run from a clone (that form carries a `-<n>-g<hash>` suffix when the clone is ahead of its tag).
|
|
86
61
|
|
|
87
|
-
|
|
62
|
+
## Use it
|
|
88
63
|
|
|
89
|
-
|
|
90
|
-
# 3. Open your project in a new Claude Code session and run:
|
|
91
|
-
/flow-comet
|
|
92
|
-
# (Codex: invoke the skill in a Codex session — `/use flow-comet` or natural language;
|
|
93
|
-
# same workflow, see Installation → "Using flow-comet on Codex")
|
|
94
|
-
```
|
|
64
|
+
Open a session in your project and invoke the workflow:
|
|
95
65
|
|
|
96
|
-
|
|
66
|
+
- **Claude Code** — `/flow-comet`
|
|
67
|
+
- **Codex** — invoke the skill (`/use flow-comet`, or simply ask for the flow-comet workflow in natural language)
|
|
68
|
+
- **DeepSeek Harness** — invoke the `flow-comet` skill
|
|
97
69
|
|
|
98
|
-
|
|
70
|
+
The first call confirms scope, then creates the branch for the change, initializes the state and enters the first node, producing that change's `CHANGE.md` / `REQUIREMENT.md` under `.specs/`. Every later stage is routed automatically — you only answer the decision points (scope, tech stack, destructive changes, review findings, archive confirmation). On first use in a project it detects a missing project context and offers to build one from your existing documents before starting.
|
|
99
71
|
|
|
100
|
-
|
|
72
|
+
To see where it is, just ask it — or inspect it from the command line with `status` and `next` in the project (the per-platform paths are in [Installation](docs/INSTALLATION.md)).
|
|
101
73
|
|
|
102
|
-
-
|
|
103
|
-
- **[Custom protocols](docs/PROTOCOL.md)** — compose any installed skill into a custom workflow via `/flow-comet-compose`
|
|
104
|
-
- **[Core mechanisms](docs/MECHANISM.md)** — state machine, three defense layers, guard validation, execution model
|
|
105
|
-
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** — BLOCKED/WARN messages and their fixes
|
|
74
|
+
Artifacts live in `.specs/<change-id>/`; on archive they move to `.specs/archive/<date>-<change-id>/` and a row is added to `.specs/CHANGELOG.md`. The node-by-node walkthrough — including what the workflow runs underneath, and how to drive a node by hand when you need to — is in [Usage](docs/USAGE.md).
|
|
106
75
|
|
|
107
|
-
|
|
76
|
+
## Pick a platform
|
|
108
77
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
78
|
+
| Platform | Skills install to | Hook / bridge | First use |
|
|
79
|
+
|---|---|---|---|
|
|
80
|
+
| Claude Code (default) | `.claude/skills/` | `settings.local.json` → `hooks.PreToolUse` | the workspace must be trusted; headless sessions need that trust pre-accepted |
|
|
81
|
+
| Codex | `.agents/skills/` | `.codex/hooks.json`, plus a managed block in `AGENTS.md` | trust the project hook once (interactive), or pass the automation flag for scripted runs — see [Installation](docs/INSTALLATION.md) |
|
|
82
|
+
| DeepSeek Harness (dsh) | `.dsh/skills/` | global bridge loader under `$DSH_HOME`, plus a managed block in `AGENTS.md` | no hook-trust step |
|
|
113
83
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
```mermaid
|
|
117
|
-
graph LR
|
|
118
|
-
O[open] --> D[design] --> P[plan] --> E[execute]
|
|
119
|
-
E <--> SE[subagent-execute]
|
|
120
|
-
E --> R[review] --> V[verify] --> A[archive]
|
|
121
|
-
style O fill:#e8f5e9
|
|
122
|
-
style D fill:#e3f2fd
|
|
123
|
-
style P fill:#fff3e0
|
|
124
|
-
style E fill:#fce4ec
|
|
125
|
-
style SE fill:#f3e5f5
|
|
126
|
-
style R fill:#e8eaf6
|
|
127
|
-
style V fill:#e0f7fa
|
|
128
|
-
style A fill:#f1f8e9
|
|
129
|
-
```
|
|
84
|
+
Prerequisites, all four install options, the per-platform verification steps and uninstall/reset behaviour: [Installation](docs/INSTALLATION.md).
|
|
130
85
|
|
|
131
|
-
|
|
86
|
+
## Why
|
|
132
87
|
|
|
133
|
-
|
|
88
|
+
If you use skill-based disciplines like [superpowers](https://github.com/obra/superpowers), [OpenSpec](https://github.com/Fission-AI/OpenSpec), or [GSD](https://github.com/open-gsd/gsd-core), you know the pain: discipline relies on the model's compliance, and progress lives in chat history. flow-comet turns the flow-kit 9-stage process (CHANGE → REQUIREMENT → DESIGN → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE) from a discipline-dependent manual flow into a **verifiable deterministic state machine**:
|
|
134
89
|
|
|
135
|
-
|
|
90
|
+
- **Automated routing** — scripts manage stage transitions, guard validations, and hook-based write interception
|
|
91
|
+
- **Protocol-driven** — the built-in 8-node protocol is the default workflow; custom protocols composed from any installed skill run on the same engine (see [Custom Protocols](docs/MECHANISM.md#custom-protocols))
|
|
92
|
+
- **Three defense layers** — physical write interception (hook), coordinator prohibition, and exit takeover detection
|
|
93
|
+
- **Subagent-isolated execution** — implementation work is delegated to fresh-context subagents with a verifiable Return Contract
|
|
94
|
+
- **File-as-truth recovery** — state is derived from `.specs/` artifacts, so recovery never depends on conversation history
|
|
136
95
|
|
|
137
96
|
## Why flow-comet
|
|
138
97
|
|
|
@@ -191,55 +150,22 @@ processor-pipeline/ (archived change, full artifact set)
|
|
|
191
150
|
|
|
192
151
|

|
|
193
152
|
|
|
194
|
-
##
|
|
195
|
-
|
|
196
|
-
| Project | Role | Relationship to flow-comet |
|
|
197
|
-
|---------|------|---------------------------|
|
|
198
|
-
| [flow-kit](https://github.com/rihebty/flow-kit) | Methodology & artifact system (9-stage flow, `.specs/` templates, R1-R8 rules) | **Dependency** — flow-comet is its automation layer; artifacts and rules come from flow-kit |
|
|
199
|
-
| [Comet](https://github.com/rpamis/comet) | Skill Creator ecosystem (bundle authoring, hook-guard pattern, state machine) | **Mechanism source** — flow-comet borrows Comet's mechanism patterns extensively (workflow-protocol as source of truth, script-owned state, guard gates, hook interception); **runtime optional** (copy install needs no Comet CLI). Details in [Ecosystem](docs/ECOSYSTEM.md) |
|
|
200
|
-
| **Comet Classic** | Comet's classic workflow (OpenSpec + Superpowers) | **Not a dependency** — flow-comet is an independent workflow-kernel; state does not interoperate with classic (own `.flow-comet/flow-comet-state.json` + file-derived routing) |
|
|
201
|
-
|
|
202
|
-
## Directory Structure
|
|
203
|
-
|
|
204
|
-
```
|
|
205
|
-
flow-comet/
|
|
206
|
-
├── .flow-comet/ ★ authoritative source (skills/ + rules/)
|
|
207
|
-
├── scripts/ prepare-env installer (npm bin: fcomet / flow-comet)
|
|
208
|
-
├── docs/
|
|
209
|
-
│ ├── examples/ workflow artifact examples
|
|
210
|
-
│ ├── ECOSYSTEM.md roles of flow-kit & Comet, borrowing boundaries
|
|
211
|
-
│ ├── INSTALLATION.md installation guide
|
|
212
|
-
│ ├── USAGE.md usage guide
|
|
213
|
-
│ ├── PROTOCOL.md custom protocol guide
|
|
214
|
-
│ ├── MECHANISM.md core mechanisms (behavior layer)
|
|
215
|
-
│ ├── TROUBLESHOOTING.md failure diagnosis
|
|
216
|
-
│ └── VERSIONS.md versioning & compatibility
|
|
217
|
-
└── CHANGELOG.md Keep a Changelog style
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
## Tech Stack
|
|
153
|
+
## Relationship to the upstream project
|
|
221
154
|
|
|
222
|
-
|
|
223
|
-
|-------|------------|
|
|
224
|
-
| Runtime | Node.js ≥ 18 (ESM); third-party dependency: `@clack/prompts` (pinned exact version, installer TTY multi-select only — automatic readline fallback when unavailable) |
|
|
225
|
-
| Platform | Claude Code (default — skills, `.claude/` installation, hooks); Codex (`.agents/skills/`, AGENTS.md managed rules, PreToolUse write interception); DeepSeek Harness (`.dsh/skills/flow-comet` project-level skill, AGENTS.md managed rules, bridge loader + `tools/pre-execute` interception) |
|
|
226
|
-
| Methodology | [flow-kit](https://github.com/rihebty/flow-kit) (artifacts, rules, templates) |
|
|
155
|
+
flow-comet automates the methodology of [flow-kit](https://github.com/rihebty/flow-kit) — its stages, artifacts, rules and templates are inherited rather than reinvented. The two projects do not share files: flow-kit is consumed as a read-only, pinned dependency, and this repository vendors a copy only as a format baseline. What may be borrowed, and how divergences are declared, is written down in [CONTRIBUTING.md](CONTRIBUTING.md#borrowing-boundary).
|
|
227
156
|
|
|
228
157
|
## Documentation
|
|
229
158
|
|
|
230
|
-
| Document |
|
|
231
|
-
|
|
232
|
-
| [
|
|
233
|
-
| [
|
|
234
|
-
| [
|
|
235
|
-
| [
|
|
236
|
-
| [
|
|
237
|
-
| [
|
|
238
|
-
| [
|
|
239
|
-
| [
|
|
240
|
-
| [Changelog](CHANGELOG.md) | Version history (Keep a Changelog) |
|
|
241
|
-
| [Security](SECURITY.md) | How to report vulnerabilities |
|
|
242
|
-
| [Code of Conduct](CODE_OF_CONDUCT.md) | Community guidelines |
|
|
159
|
+
| Document | What it is the single place for |
|
|
160
|
+
|---|---|
|
|
161
|
+
| [Installation](docs/INSTALLATION.md) | Prerequisites, the four install options, platform choice, verification, and reset (purge is delete-and-rebuild, not uninstall) |
|
|
162
|
+
| [Usage](docs/USAGE.md) | The 8-node workflow, the per-node lifecycle and its commands, artifacts, branch mode, execution modes, user entry points |
|
|
163
|
+
| [Core Mechanisms](docs/MECHANISM.md) | The behaviour contract, the three defense layers, guard validation, and custom protocols |
|
|
164
|
+
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Symptoms grouped by where they bite: installation, first run, a stuck node, platform |
|
|
165
|
+
| [Versions](docs/VERSIONS.md) | Version semantics, the nine version surfaces, and the release checklist |
|
|
166
|
+
| [CHANGELOG](CHANGELOG.md) | Per-version history |
|
|
167
|
+
| [Contributing](CONTRIBUTING.md) | Contribution flow and the borrowing boundary |
|
|
168
|
+
| [Security](SECURITY.md) | Reporting a vulnerability |
|
|
243
169
|
|
|
244
170
|
## Contributing
|
|
245
171
|
|
|
@@ -247,7 +173,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
247
173
|
|
|
248
174
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
249
175
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
250
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
176
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 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.
|
|
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": [
|
package/scripts/dsh-bridge.mjs
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
// 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
|
|
29
29
|
// ESM 模块导出 { name, apply },ctx 由 dsh 注入。
|
|
30
30
|
//
|
|
31
|
-
// BRIDGE_VERSION: 1.6.
|
|
31
|
+
// BRIDGE_VERSION: 1.6.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.
|
|
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';
|